diff --git a/doc/source/index.rst b/doc/source/index.rst index 5073e0ffbb..b36491d436 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -55,6 +55,7 @@ Developers Documentation pluginguide schedulerhints gmr + supportstatus API Documentation ======================== diff --git a/doc/source/pluginguide.rst b/doc/source/pluginguide.rst index b086c18437..d2e318976f 100644 --- a/doc/source/pluginguide.rst +++ b/doc/source/pluginguide.rst @@ -78,6 +78,13 @@ status 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 +:ref:`supportstatus`. + Properties and Attributes +++++++++++++++++++++++++ diff --git a/doc/source/supportstatus.rst b/doc/source/supportstatus.rst new file mode 100644 index 0000000000..a71d512327 --- /dev/null +++ b/doc/source/supportstatus.rst @@ -0,0 +1,254 @@ +.. + 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: + - PROTOTYPE. Prototype of object. Not supported at current time. + - 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. Object with this status is unavailable and can't be used + anywhere else. Old stacks with such object continue running. + All new stacks cannot be created with such object. HIDDEN status + notifies, that object is unavailable for using in templates, because can + be deleted later. Object with HIDDEN status is not displaying in + resource-type-show and in documentation. See below more details about + removing and deprecating process. + - UNSUPPORTED. Resources with UNSUPPORTED status are not supported by Heat + team, i.e. user can use it, but it may be broken. Not used at current + time. + +*version*: + Release name, since which current status is active. Parameter is optional, + but should be defined or changes 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 described life cycle of such objects as resource, property +and attribute. All these objects have same life cycle: + +PROTOTYPE -> SUPPORTED -> DEPRECATED -> HIDDEN + \ + -> UNSUPPORTED + +where PROTOTYPE and UNSUPPORTED are 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, some message. This parameter +allows user to understand, from which this object 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.'. + +Removing process of object +++++++++++++++++++++++++++ +After at least one full release cycle deprecated object should be hidden and +*support_status* status should equals to HIDDEN. All using of hidden object in +new stacks is prohibited, but old stacks continue running. So if template uses +removed object, StackValidationFailed exception will raised. + +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='2015.2', + 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='2015.2', + 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, `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='2015.2', + 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='2015.2', + 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='2015.2', + message=_('Some message'), + previous_status=support.SupportStatus( + status=support.DEPRECATED, + version='2015.1', + 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 was non-LIST property and LIST property, which was designed to + replace non-LIST property. + +Mechanism has rules and executes them. To define rule, ``TranslationRule`` +class called and specifies *source_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. + +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, + source_path=[self.NETWORKS, self.NETWORK_ID], + value_name=self.NETWORK_UUID)]