Heat allows to use for each resource, property, attribute special option named support_status, which describes current state of object: current status, since what time this status is actual, any additional information about object’s state. This guide describes a detailed state life cycle of resources, properties and attributes.
Support status of object may be specified by using class SupportStatus
,
which has follow options:
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.
'Use property new_property instead.'
.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.
During creating object there is a reason to add support status. So new
object should contains support_status parameter equals to SupportStatus
class with defined version of object and, maybe, substitute_class or some
message. This parameter allows user to understand, from which OpenStack
release this object is available and can be used.
When some object becomes obsolete, user should know about that, so there is
need to add information about deprecation in support_status of object.
Status of SupportStatus
must equals to DEPRECATED. If there is no version
parameter, need to add one with current release otherwise move current status
to previous_status and add to version current release as value. If some new
object replaces old object, it will be good decision to add some information
about new object to support_status message of old object, e.g. ‘Use property
new_property instead.’. If old object is directly replaceable by new object,
we should add substitute_class to support_status in old object.
After at least one full release cycle deprecated object should be hidden and
support_status status should equals to HIDDEN. HIDDEN status means hiding
object from documentation and from result of resource-type-list
CLI
command, if object is resource. Also, resource-type-show
command with
such resource will raise NotSupported exception.
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.
Option support_status may be used for whole resource:
class ResourceWithType(resource.Resource):
support_status=support.SupportStatus(
version='5.0.0',
message=_('Optional message')
)
To define support_status for property or attribute, follow next steps:
PROPERTY: properties.Schema(
...
support_status=support.SupportStatus(
version='5.0.0',
message=_('Optional message')
)
)
Same support_status definition for attribute schema.
Note, that in this situation status parameter of SupportStatus
uses default
value, equals to SUPPORTED.
When time of deprecation or hiding resource/property/attribute comes, follow next steps:
SupportStatus
value and change all other parameters for
current status, version and, maybe, substitute_class or message.Using Support Status during resource deprecating looks like:
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')
)
Using Support Status during attribute (or property) deprecating looks like:
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'))
)
)
Same support_status defining for property schema.
Note, that during hiding object status should be equal support.HIDDEN instead of support.DEPRECATED. Besides that, SupportStatus with DEPRECATED status should be moved to previous_status, e.g.:
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')
)
)
During hiding properties, if some hidden property has alternative, use translation mechanism for translating properties from old to new one. See below, how to use this mechanism.
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.