267 lines
11 KiB
ReStructuredText
267 lines
11 KiB
ReStructuredText
..
|
|
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
|
not use this file except in compliance with the License. You may obtain
|
|
a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
|
License for the specific language governing permissions and limitations
|
|
under the License.
|
|
|
|
.. _supportstatus:
|
|
|
|
===============================
|
|
Heat Support Status usage Guide
|
|
===============================
|
|
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 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.
|
|
|
|
Creating process of object
|
|
++++++++++++++++++++++++++
|
|
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.
|
|
|
|
Deprecating process of object
|
|
+++++++++++++++++++++++++++++
|
|
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.
|
|
|
|
Removing process of 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 :code:`resource-type-list` CLI
|
|
command, if object is resource. Also, :code:`resource-type-show` command with
|
|
such resource will raise `NotSupported` exception.
|
|
|
|
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.
|
|
|
|
Using Support Status during creation
|
|
++++++++++++++++++++++++++++++++++++
|
|
Option *support_status* may be used for whole resource:
|
|
|
|
.. code-block:: python
|
|
|
|
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:
|
|
|
|
.. code-block:: python
|
|
|
|
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.
|
|
|
|
Using Support Status during deprecation and hiding
|
|
++++++++++++++++++++++++++++++++++++++++++++++++++
|
|
When time of deprecation or hiding resource/property/attribute comes, follow
|
|
next steps:
|
|
|
|
1. If there is some support_status in object, add `previous_status` parameter
|
|
with current ``SupportStatus`` value and change all other parameters for
|
|
current `status`, `version` and, maybe, `substitute_class` or `message`.
|
|
|
|
2. If there is no support_status option, add new one with parameters status
|
|
equals to current status, `version` equals to current release note and,
|
|
optionally, some message.
|
|
|
|
Using Support Status during resource deprecating looks like:
|
|
|
|
.. code-block:: python
|
|
|
|
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:
|
|
|
|
.. code-block:: python
|
|
|
|
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.:
|
|
|
|
.. code-block:: python
|
|
|
|
support.SupportStatus(
|
|
status=support.HIDDEN,
|
|
version='5.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.
|
|
|
|
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:
|
|
|
|
.. code-block:: python
|
|
|
|
def translation_rules(self):
|
|
return [properties.TranslationRule(
|
|
self.properties,
|
|
properties.TranslationRule.REPLACE,
|
|
translation_path=[self.NETWORKS, self.NETWORK_ID],
|
|
value_name=self.NETWORK_UUID)]
|