Heat/Plugins

Heat Resource Plugins

The Heat Engine now supports Resource Plugin modules, which allows operators of OpenStack clouds to provide custom Resource handlers to their users. This feature is available from the grizzly-2 release of Heat onwards.

Built-in Resources

Heat aims to include built-in resources for Core OpenStack services. Projects that are not part of Core OpenStack (including incubated projects) should maintain any Heat resource implementations as plugins outside of the Heat tree. (This is the same policy as for Horizon modules.)

The built-in resource types supplied with Heat are made available whenever their respective client libraries are present. (e.g. Quantum resources will be available if python-quantumclient is installed.)

Plugins may override built-in resource implementations by supplying another implementation for the same resource type.

Installation and Configuration

The list of directories to search for plugins can be defined with the `plugin_dirs` option in the file `/etc/heat/heat-engine.conf`. The default is to search the directories `/usr/lib64/heat` and `/usr/lib/heat`.

To install a plugin, copy the Python modules to one of the configured plugin directories. Note that heat-engine must be restarted after this in order to load the new plugins.

The configured directories are treated as the `path` entries for the package `heat.engine.plugins`. All Python modules appearing in this package will be imported and scanned for resource implementations.

Writing a plugin

If a plugin module includes a function named `resource_mapping`, it will be called to get a mapping of resource names to handler classes. The result should be a Python dictionary representing this mapping. For example:

#!highlight python
def resource_mapping():
    return {
        'AWS::EC2::Instance': Instance,
    }

Where the value part of each key-value pair is a class representing the desired resource. The class should be a subclass of the `heat.engine.resource.Resource` class.

Resource subclasses must contain an attribute named `properties_schema` that is a dictionary representing the schema of its Properties. (The schema keys and permitted types are defined in the module `heat.engine.properties`.)

They also may, and generally should, contain `handle_create`, `handle_update` and `handle_delete` methods. If present, these will be called when the resource is created, updated or deleted (respectively) to perform the main work of managing the underlying resource. The `resource_id_set` method can be used to store a handle to the underlying resource in the database. Refer to the built-in resources in Heat for detailed implementation examples.

You may also subclass one of the existing resource types in the built-in `heat.engine.resources` package. Remember that you can even override a built-in resource by publishing it in the resource mapping with the same resource type.

Stack Resources

The class `heat.engine.stack_resource.StackResource` adds convenience methods to the Resource class for managing a Heat stack as a resource. The canonical example of this is the `AWS::CloudFormation::Stack` resource type, but other resources may also be implemented behind-the-scenes as nested stacks.

To use this class, your `handle_create()` function should call `create_with_template()` with the template you want to instantiate and any parameters, and your `handle_delete()` should call `delete_nested()`. Outputs from the stack are available from the `get_output()` function.