openstack/ironic
Code Issues Proposed changes

Merge "Update docs to include API version pinning"

Browse Source
This commit is contained in:
Zuul 2017-12-07 11:01:25 +00:00 committed by Gerrit Code Review
commit cb31471aae
2 changed files with 51 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
doc/source/admin/upgrade-guide.rst
View File

@ -115,13 +115,13 @@ Concepts
There are four aspects of the rolling upgrade process to keep in mind: There are four aspects of the rolling upgrade process to keep in mind:
* RPC version pinning and versioned object backports * API and RPC version pinning, and versioned object backports
* online data migrations * online data migrations
* graceful service shutdown * graceful service shutdown
* API load balancer draining * API load balancer draining
RPC version pinning and versioned object backports API & RPC version pinning and versioned object backports
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Through careful RPC versioning, newer services are able to talk to older Through careful RPC versioning, newer services are able to talk to older
services (and vice-versa). The ``[DEFAULT]/pin_release_version`` configuration services (and vice-versa). The ``[DEFAULT]/pin_release_version`` configuration
@ -133,6 +133,14 @@ incorrect or unspecified ``[DEFAULT]/pin_release_version`` configuration value.
For example, when ``[DEFAULT]/pin_release_version`` is not set to the older For example, when ``[DEFAULT]/pin_release_version`` is not set to the older
release version, no conversion will happen during the upgrade. release version, no conversion will happen during the upgrade.
For the ironic-api service, the API version is pinned via the same
``[DEFAULT]/pin_release_version`` configuration option as above. When pinned,
the new ironic-api services will not service any API requests with Bare Metal
API versions that are higher than what the old ironic-api services support.
HTTP status code 406 is returned for such requests. This prevents new features
(available in new API versions) from being used until after the upgrade
has been completed.
Online data migrations Online data migrations
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~
@ -191,10 +199,6 @@ services that have not yet been upgraded.
Rolling upgrade process Rolling upgrade process
----------------------- -----------------------
.. warning::
New features and/or new API versions should not be used until after the upgrade
has been completed.
Before maintenance window Before maintenance window
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
@ -214,7 +218,7 @@ Before maintenance window
N+1) releases can perform operations against the same schema. N+1) releases can perform operations against the same schema.
.. note:: .. note::
Ironic bases its RPC and object storage format versions on the Ironic bases its API, RPC and object storage format versions on the
``[DEFAULT]/pin_release_version`` configuration option. It is ``[DEFAULT]/pin_release_version`` configuration option. It is
advisable to automate the deployment of changes in configuration advisable to automate the deployment of changes in configuration
files to make the process less error prone and repeatable. files to make the process less error prone and repeatable.
@ -254,7 +258,11 @@ During maintenance window
* set the ``[DEFAULT]/pin_release_version`` configuration option value to * set the ``[DEFAULT]/pin_release_version`` configuration option value to
the version you are upgrading from (that is, the old version). Based on the version you are upgrading from (that is, the old version). Based on
this setting, the new ironic-api services will downgrade any RPC this setting, the new ironic-api services will downgrade any RPC
communication and data objects to conform to the old service. communication and data objects to conform to the old service. In addition,
the new services will return HTTP status code 406 for any requests with
newer API versions that the old services did not support. This prevents
new features (available in new API versions) from being used until after
the upgrade has been completed.
For example, if you are upgrading from Ocata to Pike, set this value to For example, if you are upgrading from Ocata to Pike, set this value to
``ocata``. ``ocata``.
* restart the service * restart the service
@ -262,8 +270,9 @@ During maintenance window
After upgrading all the ironic-api services, the Bare Metal service is After upgrading all the ironic-api services, the Bare Metal service is
running in the new version but with downgraded RPC communication and running in the new version but with downgraded RPC communication and
database object storage formats. New features can fail when objects are in database object storage formats. New features (in new API versions) are
the downgraded object formats and some internal RPC API functions may still not supported, because they could fail when objects are in the
downgraded object formats and some internal RPC API functions may still
not be available. not be available.
#. For all the ironic-conductor services, one at a time: #. For all the ironic-conductor services, one at a time:

57
doc/source/contributor/rolling-upgrades.rst
View File

@ -55,10 +55,11 @@ and ``ToVer`` releases in this order:
2. Upgrade code and restart ironic-api services, one at a time. 2. Upgrade code and restart ironic-api services, one at a time.
3. Unpin RPC and object versions so that the services can now use the latest 3. Unpin API, RPC and object versions so that the services can now use the
versions in ``ToVer``. This is done via updating the new configuration latest versions in ``ToVer``. This is done via updating the
option described below in `RPC and object version pinning`_ and then configuration option described below in `API, RPC and object version
restarting the services. ironic-conductor services should be restarted pinning`_ and then restarting the services.
ironic-conductor services should be restarted
first, followed by the ironic-api services. This is to ensure that when new first, followed by the ironic-api services. This is to ensure that when new
functionality is exposed on the unpinned API service (via API micro functionality is exposed on the unpinned API service (via API micro
version), it is available on the backend. version), it is available on the backend.
@ -113,34 +114,43 @@ The policy for changes to the DB model is as follows:
accessed and/or store a large dataset), these cases must be mentioned in the accessed and/or store a large dataset), these cases must be mentioned in the
release notes. release notes.
RPC and object version pinning API, RPC and object version pinning
------------------------------ -----------------------------------
For the ironic services to be running old and new releases at the same time For the ironic services to be running old and new releases at the same time
during a rolling upgrade, the services need to be able to handle different RPC during a rolling upgrade, the services need to be able to handle different API,
versions and object versions. RPC and object versions.
This versioning is handled via the configuration option: This versioning is handled via the configuration option:
``[DEFAULT]/pin_release_version``. It is used to pin the RPC and IronicObject ``[DEFAULT]/pin_release_version``. It is used to pin the API, RPC and
(e.g., Node, Conductor, Chassis, Port, and Portgroup) versions for IronicObject (e.g., Node, Conductor, Chassis, Port, and Portgroup) versions for
all the ironic services. all the ironic services.
The default value of empty indicates that ironic-api and ironic-conductor The default value of empty indicates that ironic-api and ironic-conductor
will use the latest versions of RPC and IronicObjects. Its possible values are will use the latest versions of API, RPC and IronicObjects. Its possible values
releases, named (e.g. ``ocata``) or sem-versioned (e.g. ``7.0``). are releases, named (e.g. ``ocata``) or sem-versioned (e.g. ``7.0``).
Internally, in `common/release_mappings.py Internally, in `common/release_mappings.py
<https://git.openstack.org/cgit/openstack/ironic/tree/ironic/common/release_mappings.py>`_, <https://git.openstack.org/cgit/openstack/ironic/tree/ironic/common/release_mappings.py>`_,
ironic maintains a mapping that indicates the RPC and ironic maintains a mapping that indicates the API, RPC and
IronicObject versions associated with each release. This mapping is IronicObject versions associated with each release. This mapping is
maintained manually. maintained manually.
During a rolling upgrade, the services using the new release will set the During a rolling upgrade, the services using the new release will set the
configuration option value to be the name (or version) of the old release. configuration option value to be the name (or version) of the old release.
This will indicate to the services running the new release, which RPC and This will indicate to the services running the new release, which API, RPC and
object versions that they should be compatible with, in order to communicate object versions that they should be compatible with, in order to communicate
with the services using the old release. with the services using the old release.
Handling API versions
---------------------
When the (newer) service is pinned, the maximum API version it supports
will be the pinned version -- which the older service supports (as described
above at `API, RPC and object version pinning`_). The ironic-api
service returns HTTP status code 406 for any requests with API versions that
are higher than this maximum version.
Handling RPC versions Handling RPC versions
--------------------- ---------------------
@ -312,19 +322,14 @@ So the new, pinned ironic-api service needs to act like it was the older
service: service:
* New features should not be made available, unless they are somehow totally * New features should not be made available, unless they are somehow totally
supported in the old and new releases. As a `future enhancement supported in the old and new releases. Pinning the API version is in place
<https://bugs.launchpad.net/ironic/+bug/1708549>`_, since new features or to handle this.
new REST APIs are associated with new API microversions, we should enhance
the ``[DEFAULT]/pin_release_version`` configuration option to also include
pinning the API microversion.
* For requests that cannot or should not be handled, the response should be * If, for whatever reason, the API version pinning doesn't prevent a request
HTTP 406 (Not Acceptable). This is the same response to requests that have from being handled that cannot or should not be handled, it should be
an incorrect (old) version specified. coded so that the response has HTTP status code 406 (Not Acceptable).
This is the same response to requests that have an incorrect (old) version
* This includes accessing a new field of an object. For example, if a specified.
"new_field" field was added to Node, any requests pertaining to
Node.new_field should not be processed.
Ironic RPC versions Ironic RPC versions
------------------- -------------------