Revision as of 16:32, 17 March 2014

Upgrading Major Versions of RPC APIs in OpenStack

RPC APIs exposed between services in OpenStack components such as Nova are versioned. Generally changes much be backwards compatible and are accompanied by a minor version increase to reflect the change. We will occasionally make major version increases to allow us to drop code that provides backwards compatibility. This is done over a major release boundary. For example, support for a new API version is added just before the release of Icehouse and support for the old version is dropped once Juno development opens.

The details of these changes fall into two categories. In most cases, we do not allow a mixed version environment of services exposing an RPC interface. In Nova, the one case where we *do* allow a mixed version environment is with the compute service. We support doing rolling upgrades of the compute service. In that case, the update must be handled a bit differently than the rest.

Non-mixed version environments (most cases)

The update is made over 2 changes.

Change #1:

• Merged just before a major release.
• Add support for rpc major version N+1 to the manager (server) side.
• Update rpcapi (client) side to send N+1 messages.
• Retain support for version N on the manager side.
• Examples:
  • https://review.openstack.org//79100
  • https://review.openstack.org/81008

Change #2:

• Merged once development opens up for the next major release.
• Remove support for version N on the manager side.
• Tag commit with "UpgradeImpact". Note that the deployment *must* have already been upgraded to include change #1.
• Examples:
  • https://review.openstack.org/#/c/54493/

Mixed version environments (nova-compute)

This case is very similar to what is done for non-mixed version environments. Follow that procedure with the following exceptions:

• In change #1, you must retain rpcapi (client) side support for the old rpcapi version (N). Deployments need to be able to pin the client version to the older version until the upgrade has been completed. Once the upgrade has been completed, the client side version pin can be removed and the clients can start sending the new messages (N+1).
• Examples:
  • https://review.openstack.org/#/c/53944/