RpcMajorVersionUpdates

= Upgrading Major Versions of RPC APIs in OpenStack =

RPC APIs exposed between services in OpenStack components such as Nova are versioned. Generally changes must 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

The support for both N and N+1 on the manager side is important for upgrades. Consider nova-conductor as an example. It's a non-mixed environment service because we expect that all running instances of nova-conductor are the same version. However, the Nova deployment may contain old nova-compute services that do not know how to send "N+1" messages yet. To support the full deployment, nova-conductor must retail the ability to *receive* N and N+1 messages until the entire deployment has been upgraded.

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 sending messages using the old rpcapi version (N).
 * Examples:
 * https://review.openstack.org/#/c/53944/

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). Consider the nova-compute service. When doing rolling upgrades of nova-compute, we must send the message version that all services understand. Once they have all been upgraded, the new messages can be sent instead.