Heat Resource Plug-in Development Guide¶

Resource Status and Action¶

The base class handles reporting state of the resource back to the engine. A resource’s state is the combination of the life cycle action and the status of that action. For example, if a resource is created successfully, the state of that resource will be CREATE_COMPLETE. Alternatively, if the plug-in encounters an error when attempting to create the physical resource, the state would be CREATE_FAILED. The base class handles the reporting and persisting of resource state, so a plug-in’s handler methods only need to return data or raise exceptions as appropriate.

Resource Support Status¶

New resource should be marked from which OpenStack release it will be available with support_status option. For more details, see Heat Support Status usage Guide.

Resource description¶

An important part of future resources is a concisely written description. It should be in class docstring and contain information about the resource and how it could be useful to the end-user. The docstring description is used in documentation generation and should be always defined, if resource is designed for public use. Docstring should follows PEP 257.

class CustomResource(resource.Resource):
    """This custom resource has description.

    Now end-users could understand the meaning of the resource existing
    and will use it correctly without any additional questions.
    """

Defining Resource Properties¶

Each property that a resource supports must be defined in a schema that informs the engine and validation logic what the properties are, what type each is, and validation constraints. The schema is a dictionary whose keys define property names and whose values describe the constraints on that property. This dictionary must be assigned to the properties_schema attribute of the plug-in.

from heat.common.i18n import _
from heat.engine import constraints
from heat.engine import properties

    nested_schema = {
        "foo": properties.Schema(
            properties.Schema.STRING,
            _('description of foo field'),
            constraints=[
                constraints.AllowedPattern('(Ba[rc]?)+'),
                constraints.Length(max=10,
                                   description="don't go crazy")
            ]
        )
    }
    properties_schema = {
        "property_name": properties.Schema(
            properties.Schema.MAP,
            _('Internationalized description of property'),
            required=True,
            default={"Foo": "Bar"},
            schema=nested_schema
        )
    }

As shown above, some properties may themselves be complex and reference nested schema definitions. Following are the parameters to the Schema constructor; all but the first have defaults.

data_type:

Defines the type of the property’s value. The valid types are the members of the list properties.Schema.TYPES, currently INTEGER, STRING, NUMBER, BOOLEAN, MAP, LIST and ANY; please use those symbolic names rather than the literals to which they are equated. For LIST and MAP type properties, the schema referenced constrains the format of complex items in the list or map.

description:

A description of the property and its function; also used in documentation generation. Default is None — but you should always provide a description.

default:

The default value to assign to this property if none was supplied in the template. Default is None.

schema:

This property’s value is complex and its members must conform to this referenced schema in order to be valid. The referenced schema dictionary has the same format as the properties_schema. Default is None.

required:

True if the property must have a value for the template to be valid; False otherwise. The default is False

constraints:

A list of constraints that apply to the property’s value. See Property Constraints.

update_allowed:

True if an existing resource can be updated, False means update is accomplished by delete and re-create. Default is False.

immutable:

True means updates are not supported, resource update will fail on every change of this property. False otherwise. Default is False.

support_status:

Defines current status of the property. Read Heat Support Status usage Guide for details.

Accessing property values of the plug-in at runtime is then a simple call to:

self.properties['PropertyName']

Based on the property type, properties without a set value will return the default “empty” value for that type:

Property Constraints¶

Following are the available kinds of constraints. The description is optional and, if given, states the constraint in plain language for the end user.

AllowedPattern(regex, description):

Constrains the value to match the given regular expression; applicable to STRING.

AllowedValues(allowed, description):

Lists the allowed values. allowed must be a collections.abc.Sequence or string. Applicable to all types of value except MAP.

Length(min, max, description):

Constrains the length of the value. Applicable to STRING, LIST, MAP. Both min and max default to None.

Range(min, max, description):

Constrains a numerical value. Applicable to INTEGER and NUMBER. Both min and max default to None.

Modulo(step, offset, description):

Starting with the specified offset, every multiple of step is a valid value. Applicable to INTEGER and NUMBER.

Available from template version 2017-02-24.

CustomConstraint(name, description, environment):

This constructor brings in a named constraint class from an environment. If the given environment is None (its default) then the environment used is the global one.

Defining Resource Attributes¶

Attributes communicate runtime state of the physical resource. Note that some plug-ins do not define any attributes and doing so is optional. If the plug-in needs to expose attributes, it will define an attributes_schema similar to the properties schema described above. Each item in the schema dictionary consists of an attribute name and an attribute Schema object.

attributes_schema = {
    "foo": attributes.Schema(
        _("The foo attribute"),
        type=attribute.Schema.STRING
    ),
    "bar": attributes.Schema(
        _("The bar attribute"),
        type=attribute.Schema.STRING
    ),
    "baz": attributes.Schema(
        _("The baz attribute"),
        type=attribute.Schema.STRING
    )
}

Following are the parameters to the Schema.

description

A description of the attribute; also used in documentation generation. Default is None — but you should always provide a description.

type

Defines the type of attribute value. The valid types are the members of the list attributes.Schema.TYPES, currently STRING, NUMBER, BOOLEAN, MAP, and LIST; please use those symbolic names rather than the literals to which they are equated.

support_status

Defines current status of the attribute. Read Heat Support Status usage Guide for details.

If attributes are defined, their values must also be resolved by the plug-in. The simplest way to do this is to override the _resolve_attribute method from the Resource class:

def _resolve_attribute(self, name):
    # _example_get_physical_resource is just an example and is not
    # defined in the Resource class
    phys_resource = self._example_get_physical_resource()
    if phys_resource:
        if not hasattr(phys_resource, name):
                # this is usually not needed, but this is a simple
                # example
                raise exception.InvalidTemplateAttribute(name)
        return getattr(phys_resource, name)
    return None

If the plug-in needs to be more sophisticated in its attribute resolution, the plug-in may instead choose to override FnGetAtt. However, if this method is chosen, validation and accessibility of the attribute would be the plug-in’s responsibility.

Also, each resource has show attribute by default. The attribute uses default implementation from heat.engine.resource.Resource class, but if resource has different way of resolving show attribute, the _show_resource method from the Resource class will need to be overridden:

def _show_resource(self):
    """Default implementation; should be overridden by resources.

    :returns: the map of resource information or None
     """
    if self.entity:
        try:
            obj = getattr(self.client(), self.entity)
            resource = obj.get(self.resource_id)
            if isinstance(resource, dict):
                return resource
            else:
                return resource.to_dict()
        except AttributeError as ex:
            LOG.warning("Resolving 'show' attribute has failed : %s",
                        ex)
            return None

Property and Attribute Example¶

Assume the following simple property and attribute definition:

properties_schema = {
    'foo': properties.Schema(
        properties.Schema.STRING,
        _('foo prop description'),
        default='foo',
        required=True
    ),
    'bar': properties.Schema(
        properties.Schema.INTEGER,
        _('bar prop description'),
        required=True,
        constraints=[
            constraints.Range(5, 10)
        ]
    )
}

attributes_schema = {
    'Attr_1': attributes.Schema(
        _('The first attribute'),
        support_status=support.Status('5.0.0'),
        type=attributes.Schema.STRING
    ),
    'Attr_2': attributes.Schema(
        _('The second attribute'),
        type=attributes.Schema.MAP
    )
}

Also assume the plug-in defining the above has been registered under the template reference name ‘Resource::Foo’ (see Registering Resource Plug-ins). A template author could then use this plug-in in a stack by simply making following declarations in a template:

# ... other sections omitted for brevity ...

resources:
  resource-1:
    type: Resource::Foo
    properties:
      foo: Value of the foo property
      bar: 7

outputs:
  foo-attrib-1:
    value: { get_attr: [resource-1, Attr_1] }
    description: The first attribute of the foo resource
  foo-attrib-2:
    value: { get_attr: [resource-1, Attr_2] }
    description: The second attribute of the foo resource

Create¶

handle_create(self)¶

Create a new physical resource. This function should make the required calls to create the physical resource and return as soon as there is enough information to identify the resource. The function should return this identifying information and implement check_create_complete which will take this information in as a parameter and then periodically be polled. This allows for cooperative multi-threading between multiple resources that have had their dependencies satisfied.

Note once the native identifier of the physical resource is known, this function should call self.resource_id_set passing the native identifier of the physical resource. This will persist the identifier and make it available to the plug-in by accessing self.resource_id.

Returns:

A representation of the created physical resource

Raise:

any Exception if the create failed

check_create_complete(self, token)¶

If defined, will be called with the return value of handle_create

Parameters:

token – the return value of handle_create; used to poll the physical resource’s status.

Returns:

True if the physical resource is active and ready for use; False otherwise.

Raise:

any Exception if the create failed.

Update (Optional)¶

Note that there is a default implementation of handle_update in heat.engine.resource.Resource that simply raises an exception indicating that updates require the engine to delete and re-create the resource (this is the default behavior) so implementing this is optional.

handle_update(self, json_snippet, tmpl_diff, prop_diff)¶

Update the physical resources using updated information.

Parameters:

• json_snippet (collections.abc.Mapping) – the resource definition from the updated template

• tmpl_diff (collections.abc.Mapping) – values in the updated definition that have changed with respect to the original template definition.

• prop_diff (collections.abc.Mapping) – property values that are different between the original definition and the updated definition; keys are property names and values are the new values. Deleted or properties that were originally present but now absent have values of None

Note Before calling handle_update we check whether need to replace the resource, especially for resource in *_FAILED state, there is a default implementation of needs_replace_failed in heat.engine.resource.Resource that simply returns True indicating that updates require replacement. And we override the implementation for OS::Nova::Server, OS::Cinder::Volume and all of neutron resources. The base principle is that to check whether the resource exists underlying and whether the real status is available. So override the method needs_replace_failed for your resource plug-ins if needed.

check_update_complete(self, token)¶

If defined, will be called with the return value of handle_update

Parameters:

token – the return value of handle_update; used to poll the physical resource’s status.

Returns:

True if the update has finished; False otherwise.

Raise:

any Exception if the update failed.

Suspend (Optional)¶

These handler functions are optional and only need to be implemented if the physical resource supports suspending

handle_suspend(self)¶

If the physical resource supports it, this function should call the native API and suspend the resource’s operation. This function should return information sufficient for check_suspend_complete to poll the native API to verify the operation’s status.

Returns:

a token containing enough information for check_suspend_complete to verify operation status.

Raise:

any Exception if the suspend operation fails.

check_suspend_complete(self, token)¶

Verify the suspend operation completed successfully.

Parameters:

token – the return value of handle_suspend

Returns:

True if the suspend operation completed and the physical resource is now suspended; False otherwise.

Raise:

any Exception if the suspend operation failed.

Resume (Optional)¶

These handler functions are optional and only need to be implemented if the physical resource supports resuming from a suspended state

handle_resume(self)¶

If the physical resource supports it, this function should call the native API and resume a suspended resource’s operation. This function should return information sufficient for check_resume_complete to poll the native API to verify the operation’s status.

Returns:

a token containing enough information for check_resume_complete to verify operation status.

Raise:

any Exception if the resume operation fails.

check_resume_complete(self, token)¶

Verify the resume operation completed successfully.

Parameters:

token – the return value of handle_resume

Returns:

True if the resume operation completed and the physical resource is now active; False otherwise.

Raise:

any Exception if the resume operation failed.

Delete¶

handle_delete(self)¶

Delete the physical resource.

Returns:

a token containing sufficient data to verify the operations status

Raise:

any Exception if the delete operation failed

Note

As of the Liberty release, implementing handle_delete is optional. The parent resource class can handle the most common pattern for deleting resources:

def handle_delete(self):
    if self.resource_id is not None:
        try:
            self.client().<entity>.delete(self.resource_id)
        except Exception as ex:
            self.client_plugin().ignore_not_found(ex)
            return None
        return self.resource_id

For this to work for a particular resource, the entity and default_client_name attributes must be overridden in the resource implementation. For example, entity of Aodh Alarm should equals to “alarm” and default_client_name to “aodh”.

handle_delete_snapshot(self, snapshot)¶

Delete resource snapshot.

Parameters:

snapshot – dictionary describing current snapshot.

Returns:

a token containing sufficient data to verify the operations status

Raise:

any Exception if the delete operation failed

handle_snapshot_delete(self, state)¶

Called instead of handle_delete when the deletion policy is SNAPSHOT. Create backup of resource and then delete resource.

Parameters:

state – the (action, status) tuple of the resource to make sure that backup may be created for the current resource

Returns:

a token containing sufficient data to verify the operations status

Raise:

any Exception if the delete operation failed

check_delete_complete(self, token)¶

Verify the delete operation completed successfully.

Parameters:

token – the return value of handle_delete or handle_snapshot_delete (for deletion policy - Snapshot) used to verify the status of the operation

Returns:

True if the delete operation completed and the physical resource is deleted; False otherwise.

Raise:

any Exception if the delete operation failed.

check_delete_snapshot_complete(self, token)¶

Verify the delete snapshot operation completed successfully.

Parameters:

token – the return value of handle_delete_snapshot used to verify the status of the operation

Returns:

True if the delete operation completed and the snapshot is deleted; False otherwise.

Raise:

any Exception if the delete operation failed.