From 76312313d4ab43a84a9069108bbce5befabcc689 Mon Sep 17 00:00:00 2001 From: Ruby Loo Date: Wed, 8 Nov 2017 22:59:57 -0500 Subject: [PATCH] Update docs to include API version pinning This updates the documentation to include API version pinning during the rolling upgrade process. Change-Id: I493cd6229a8bd68720da4d5c25983a3662f4f35a Closes-Bug: #1708549 --- doc/source/admin/upgrade-guide.rst | 31 +++++++---- doc/source/contributor/rolling-upgrades.rst | 57 +++++++++++---------- 2 files changed, 51 insertions(+), 37 deletions(-) diff --git a/doc/source/admin/upgrade-guide.rst b/doc/source/admin/upgrade-guide.rst index a874db41d3..14e3834d41 100644 --- a/doc/source/admin/upgrade-guide.rst +++ b/doc/source/admin/upgrade-guide.rst @@ -115,13 +115,13 @@ Concepts 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 * graceful service shutdown * 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 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 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 ~~~~~~~~~~~~~~~~~~~~~~ @@ -191,10 +199,6 @@ services that have not yet been upgraded. 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 ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -214,7 +218,7 @@ Before maintenance window N+1) releases can perform operations against the same schema. .. 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 advisable to automate the deployment of changes in configuration 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 the version you are upgrading from (that is, the old version). Based on 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 ``ocata``. * restart the service @@ -262,8 +270,9 @@ During maintenance window After upgrading all the ironic-api services, the Bare Metal service is running in the new version but with downgraded RPC communication and - database object storage formats. New features can fail when objects are in - the downgraded object formats and some internal RPC API functions may still + database object storage formats. New features (in new API versions) are + 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. #. For all the ironic-conductor services, one at a time: diff --git a/doc/source/contributor/rolling-upgrades.rst b/doc/source/contributor/rolling-upgrades.rst index d2b5b7052c..8777f893e4 100644 --- a/doc/source/contributor/rolling-upgrades.rst +++ b/doc/source/contributor/rolling-upgrades.rst @@ -55,10 +55,11 @@ and ``ToVer`` releases in this order: 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 - versions in ``ToVer``. This is done via updating the new configuration - option described below in `RPC and object version pinning`_ and then - restarting the services. ironic-conductor services should be restarted +3. Unpin API, RPC and object versions so that the services can now use the + latest versions in ``ToVer``. This is done via updating the + configuration option described below in `API, RPC and object version + 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 functionality is exposed on the unpinned API service (via API micro 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 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 -during a rolling upgrade, the services need to be able to handle different RPC -versions and object versions. +during a rolling upgrade, the services need to be able to handle different API, +RPC and object versions. This versioning is handled via the configuration option: -``[DEFAULT]/pin_release_version``. It is used to pin the RPC and IronicObject -(e.g., Node, Conductor, Chassis, Port, and Portgroup) versions for +``[DEFAULT]/pin_release_version``. It is used to pin the API, RPC and +IronicObject (e.g., Node, Conductor, Chassis, Port, and Portgroup) versions for all the ironic services. 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 -releases, named (e.g. ``ocata``) or sem-versioned (e.g. ``7.0``). +will use the latest versions of API, RPC and IronicObjects. Its possible values +are releases, named (e.g. ``ocata``) or sem-versioned (e.g. ``7.0``). Internally, in `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 maintained manually. 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. -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 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 --------------------- @@ -312,19 +322,14 @@ So the new, pinned ironic-api service needs to act like it was the older service: * New features should not be made available, unless they are somehow totally - supported in the old and new releases. As a `future enhancement - `_, since new features or - 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. + supported in the old and new releases. Pinning the API version is in place + to handle this. -* For requests that cannot or should not be handled, the response should be - HTTP 406 (Not Acceptable). This is the same response to requests that have - an incorrect (old) version specified. - - * This includes accessing a new field of an object. For example, if a - "new_field" field was added to Node, any requests pertaining to - Node.new_field should not be processed. + * If, for whatever reason, the API version pinning doesn't prevent a request + from being handled that cannot or should not be handled, it should be + 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 + specified. Ironic RPC versions -------------------