Heat Support Status usage Guide¶

Support Status option and its parameters¶

Support status of object may be specified by using class SupportStatus, which has follow options:

status:

Current status of object. Allowed values:

• SUPPORTED. Default value of status parameter. All objects with this status are available and can be used.

• DEPRECATED. Object with this status is available, but using it in code or templates is undesirable. As usual, can be reference in message to new object, which can be used instead of deprecated resource.

• HIDDEN. The last step in the deprecation process. Old stacks containing resources in this status will continue functioning. Certain functionality is disabled for resources in this status (resource-type-list, resource-type-show, and resource-type-template). Resources in HIDDEN status are not included in the documentation. A known limitation is that new stacks can be created with HIDDEN resources. See below for more details about the removal and deprecation process.

• UNSUPPORTED. Resources with UNSUPPORTED status are not supported by Heat team, i.e. user can use it, but it may be broken.

substitute_class:

Assign substitute class for object. If replacing the object with new object which inherited (or extended) from the substitute class will transfer the object to new class type gracefully (without calling update replace).

version:

Release name, since which current status is active. Parameter is optional, but should be defined or changed any time SupportStatus is specified or status changed. It used for better understanding from which release object in current status. .. note:

Since Liberty release mark looks like 5.0.0 instead of 2015.2.

message:

Any additional information about object’s state, e.g. 'Use property new_property instead.'.

previous_status:

Option, which allows to display object’s previous status, if any. This is helpful for displaying full life cycle of object. Type of previous_status is SupportStatus.

Life cycle of resource, property, attribute¶

This section describes life cycle of such objects as resource, property and attribute. All these objects have same life cycle:

UNSUPPORTED -> SUPPORTED -> DEPRECATED -> HIDDEN
                                      \
                                       -> UNSUPPORTED

where UNSUPPORTED is optional.

Using Support Status during code writing¶

When adding new objects or adding objects instead of some old (e.g. property subnet instead of subnet_id in OS::Neutron::RouterInterface), there is some information about time of adding objects (since which release it will be available or unavailable). This section described SupportStatus during creating/deprecating/removing resources and properties and attributes. Note, that SupportStatus locates in support.py, so you need to import support. For specifying status, use support constant names, e.g. support.SUPPORTED. All constant names described in section above.

class ResourceWithType(resource.Resource):

    support_status=support.SupportStatus(
        version='5.0.0',
        message=_('Optional message')
    )

PROPERTY: properties.Schema(
    ...
    support_status=support.SupportStatus(
        version='5.0.0',
        message=_('Optional message')
    )
)

class ResourceWithType(resource.Resource):

    support_status=support.SupportStatus(
        status=support.DEPRECATED,
        version='5.0.0',
        substitute_class=SubstituteResourceWithType,
        message=_('Optional message'),
        previous_status=support.SupportStatus(version='2014.2')
    )

ATTRIBUTE: attributes.Schema(
    ...
    support_status=support.SupportStatus(
        status=support.DEPRECATED,
        version='5.0.0',
        message=_('Optional message like: Use attribute new_attr'),
        previous_status=support.SupportStatus(
            version='2014.2',
            message=_('Feature available since 2014.2'))
    )
)

support.SupportStatus(
    status=support.HIDDEN,
    version='6.0.0',
    message=_('Some message'),
    previous_status=support.SupportStatus(
        status=support.DEPRECATED,
        version='2015.1',
        substitute_class=SubstituteResourceWithType,
        previous_status=support.SupportStatus(version='2014.2')
    )
)

Translating mechanism for hidden properties¶

Sometimes properties become deprecated and replaced by another. There is translation mechanism for that. Mechanism used for such cases:

1. If there are two properties in properties_schema, which have STRING, INTEGER, NUMBER or BOOLEAN type.

2. If there are two properties: one in LIST or MAP property sub-schema and another on the top schema.

3. If there are two properties in LIST property.

4. If there are non-LIST property and LIST property, which is designed to replace non-LIST property.

5. If there is STRING property, which contains name or ID of some entity, e.g. subnet, and should be resolved to entity’s ID.

Mechanism has rules and executes them. To define rule, TranslationRule class called and specifies translation_path - list with path in properties_schema for property which will be affected; value - value, which will be added to property, specified by previous parameter; value_name - name of old property, used for case 4; value_path - list with path in properties_schema for property which will be used for getting value. TranslationRule supports next rules:

• ADD. This rule allows to add some value to LIST-type properties. Only LIST-type values can be added to such properties. Using for other cases is prohibited and will be returned with error.

• REPLACE. This rule allows to replace some property value to another. Used for all types of properties. Note, that if property has list type, then value will be replaced for all elements of list, where it needed. If element in such property must be replaced by value of another element of this property, value_name must be defined.

• DELETE. This rule allows to delete some property. If property has list type, then deleting affects value in all list elements.

• RESOLVE - This rule allows to resolve some property using client and the finder function. Finders may require an additional entity key.

Each resource, which has some hidden properties, which can be replaced by new, must overload translation_rules method, which should return a list of TranslationRules, for example:

def translation_rules(self, properties):
     rules = [
       translation.TranslationRule(
         properties,
         translation.TranslationRule.REPLACE,
         translation_path=[self.NETWORKS, self.NETWORK_ID],
         value_name=self.NETWORK_UUID),
       translation.TranslationRule(
         properties,
         translation.TranslationRule.RESOLVE,
         translation_path=[self.FLAVOR],
         client_plugin=self.client_plugin('nova'),
         finder='find_flavor_by_name_or_id')]
     return rules