doc/source/devref/upgrade.rst

   1 ..
   2       Licensed under the Apache License, Version 2.0 (the "License"); you may
   3       not use this file except in compliance with the License. You may obtain
   4       a copy of the License at
   5
   6           http://www.apache.org/licenses/LICENSE-2.0
   7
   8       Unless required by applicable law or agreed to in writing, software
   9       distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  10       WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  11       License for the specific language governing permissions and limitations
  12       under the License.
  13
  14
  15       Convention for heading levels in Neutron devref:
  16       =======  Heading 0 (reserved for the title in a document)
  17       -------  Heading 1
  18       ~~~~~~~  Heading 2
  19       +++++++  Heading 3
  20       '''''''  Heading 4
  21       (Avoid deeper levels because they do not render well.)
  22
  23 .. note::
  24
  25     Much of this document discusses upgrade considerations for the Neutron
  26     reference implementation using Neutron's agents. It's expected that each
  27     Neutron plugin provides its own documentation that discusses upgrade
  28     considerations specific to that choice of backend. For example, OVN does
  29     not use Neutron agents, but does have a local controller that runs on each
  30     compute node. OVN supports rolling upgrades, but information about how that
  31     works should be covered in the documentation for networking-ovn, the OVN
  32     Neutron plugin.
  33
  34 Upgrade strategy
  35 ================
  36
  37 There are two general upgrade scenarios supported by Neutron:
  38
  39 #. All services are shut down, code upgraded, then all services are started again.
  40 #. Services are upgraded gradually, based on operator service windows.
  41
  42 The latter is the preferred way to upgrade an OpenStack cloud, since it allows
  43 for more granularity and less service downtime. This scenario is usually called
  44 'rolling upgrade'.
  45
  46 Rolling upgrade
  47 ---------------
  48
  49 Rolling upgrades imply that during some interval of time there will be services
  50 of different code versions running and interacting in the same cloud. It puts
  51 multiple constraints onto the software.
  52
  53 #. older services should be able to talk with newer services.
  54 #. older services should not require the database to have older schema
  55    (otherwise newer services that require the newer schema would not work).
  56
  57 `More info on rolling upgrades in OpenStack
  58 <http://governance.openstack.org/reference/tags/assert_supports-rolling-upgrade.html>`_.
  59
  60 Those requirements are achieved in Neutron by:
  61
  62 #. If the Neutron backend makes use of Neutron agents, the Neutron server have
  63    backwards compatibility code to deal with older messaging payloads.
  64 #. isolating a single service that accesses database (neutron-server).
  65
  66 To simplify the matter, it's always assumed that the order of service upgrades
  67 is as following:
  68
  69 #. first, all neutron-servers are upgraded.
  70 #. then, if applicable, neutron agents are upgraded.
  71
  72 This approach allows us to avoid backwards compatibility code on agent side and
  73 is in line with other OpenStack projects that support rolling upgrades
  74 (specifically, nova).
  75
  76 Server upgrade
  77 ~~~~~~~~~~~~~~
  78
  79 Neutron-server is the very first component that should be upgraded to the new
  80 code. It's also the only component that relies on new database schema to be
  81 present, other components communicate with the cloud through AMQP and hence do
  82 not depend on particular database state.
  83
  84 Database upgrades are implemented with alembic migration chains.
  85
  86 Database upgrade is split into two parts:
  87
  88 #. neutron-db-manage upgrade --expand
  89 #. neutron-db-manage upgrade --contract
  90
  91 Each part represents a separate alembic branch.
  92
  93 :ref:`More info on alembic scripts <alembic_migrations>`.
  94
  95 The former step can be executed while old neutron-server code is running. The
  96 latter step requires *all* neutron-server instances to be shut down. Once it's
  97 complete, neutron-servers can be started again.
  98
  99 Agents upgrade
 100 ~~~~~~~~~~~~~~
 101
 102 .. note::
 103
 104     This section does not apply when the cloud does not use AMQP agents to
 105     provide networking services to instances. In that case, other backend
 106     specific upgrade instructions may also apply.
 107
 108 Once neutron-server services are restarted with the new database schema and the
 109 new code, it's time to upgrade Neutron agents.
 110
 111 Note that in the meantime, neutron-server should be able to serve AMQP messages
 112 sent by older versions of agents which are part of the cloud.
 113
 114 The recommended order of agent upgrade (per node) is:
 115
 116 #. first, L2 agents (openvswitch, linuxbridge, sr-iov).
 117 #. then, all other agents (L3, DHCP, Metadata, ...).
 118
 119 The rationale of the agent upgrade order is that L2 agent is usually
 120 responsible for wiring ports for other agents to use, so it's better to allow
 121 it to do its job first and then proceed with other agents that will use the
 122 already configured ports for their needs.
 123
 124 Each network/compute node can have its own upgrade schedule that is independent
 125 of other nodes.
 126
 127 AMQP considerations
 128 +++++++++++++++++++
 129
 130 Since it's always assumed that neutron-server component is upgraded before
 131 agents, only the former should handle both old and new RPC versions.
 132
 133 The implication of that is that no code that handles UnsupportedVersion
 134 oslo.messaging exceptions belongs to agent code.
 135
 136 :ref:`More information about RPC versioning <rpc_versioning>`.
 137
 138 Interface signature
 139 '''''''''''''''''''
 140
 141 An RPC interface is defined by its name, version, and (named) arguments that
 142 it accepts. There are no strict guarantees that arguments will have expected
 143 types or meaning, as long as they are serializable.
 144
 145 Message content versioning
 146 ''''''''''''''''''''''''''
 147
 148 To provide better compatibility guarantees for rolling upgrades, RPC interfaces
 149 could also define specific format for arguments they accept. In OpenStack
 150 world, it's usually implemented using oslo.versionedobjects library, and
 151 relying on the library to define serialized form for arguments that are passed
 152 through AMQP wire.
 153
 154 Note that Neutron has *not* adopted oslo.versionedobjects library for its RPC
 155 interfaces yet (except for QoS feature).
 156
 157 :ref:`More information about RPC callbacks used for QoS <rpc_callbacks>`.
 158
 159 Networking backends
 160 ~~~~~~~~~~~~~~~~~~~
 161
 162 Backend software upgrade should not result in any data plane disruptions.
 163 Meaning, e.g. Open vSwitch L2 agent should not reset flows or rewire ports;
 164 Neutron L3 agent should not delete namespaces left by older version of the
 165 agent; Neutron DHCP agent should not require immediate DHCP lease renewal; etc.
 166
 167 The same considerations apply to setups that do not rely on agents. Meaning,
 168 f.e. OpenDaylight or OVN controller should not break data plane connectivity
 169 during its upgrade process.
 170
 171 Upgrade testing
 172 ---------------
 173
 174 `Grenade <https://github.com/openstack-dev/grenade>`_ is the OpenStack project
 175 that is designed to validate upgrade scenarios.
 176
 177 Currently, only offline (non-rolling) upgrade scenario is validated in Neutron
 178 gate. The upgrade scenario follows the following steps:
 179
 180 #. the 'old' cloud is set up using latest stable release code
 181 #. all services are stopped
 182 #. code is updated to the patch under review
 183 #. new database migration scripts are applied, if needed
 184 #. all services are started
 185 #. the 'new' cloud is validated with a subset of tempest tests
 186
 187 The scenario validates that no configuration option names are changed in one
 188 cycle. More generally, it validates that the 'new' cloud is capable of running
 189 using the 'old' configuration files. It also validates that database migration
 190 scripts can be executed.
 191
 192 The scenario does *not* validate AMQP versioning compatibility.
 193
 194 Other projects (for example Nova) have so called 'partial' grenade jobs where
 195 some services are left running using the old version of code. Such a job would
 196 be needed in Neutron gate to validate rolling upgrades for the project. Till
 197 that time, it's all up to reviewers to catch compatibility issues in patches on
 198 review.
 199
 200 Another hole in testing belongs to split migration script branches. It's
 201 assumed that an 'old' cloud can successfully run after 'expand' migration
 202 scripts from the 'new' cloud are applied to its database; but it's not
 203 validated in gate.
 204
 205 .. _upgrade_review_guidelines:
 206
 207 Review guidelines
 208 -----------------
 209
 210 There are several upgrade related gotchas that should be tracked by reviewers.
 211
 212 First things first, a general advice to reviewers: make sure new code does not
 213 violate requirements set by `global OpenStack deprecation policy
 214 <http://governance.openstack.org/reference/tags/assert_follows-standard-deprecation.html>`_.
 215
 216 Now to specifics:
 217
 218 #. Configuration options:
 219
 220    * options should not be dropped from the tree without waiting for
 221      deprecation period (currently it's one development cycle long) and a
 222      deprecation message issued if the deprecated option is used.
 223    * option values should not change their meaning between releases.
 224
 225 #. Data plane:
 226
 227    * agent restart should not result in data plane disruption (no Open vSwitch
 228      ports reset; no network namespaces deleted; no device names changed).
 229
 230 #. RPC versioning:
 231
 232    * no RPC version major number should be bumped before all agents had a
 233      chance to upgrade (meaning, at least one release cycle is needed before
 234      compatibility code to handle old clients is stripped from the tree).
 235    * no compatibility code should be added to agent side of AMQP interfaces.
 236    * server code should be able to handle all previous versions of agents,
 237      unless the major version of an interface is bumped.
 238    * no RPC interface arguments should change their meaning, or names.
 239    * new arguments added to RPC interfaces should not be mandatory. It means
 240      that server should be able to handle old requests, without the new
 241      argument specified. Also, if the argument is not passed, the old behaviour
 242      before the addition of the argument should be retained.
 243
 244 #. Database migrations:
 245
 246    * migration code should be split into two branches (contract, expand) as
 247      needed. No code that is unsafe to execute while neutron-server is running
 248      should be added to expand branch.
 249    * if possible, contract migrations should be minimized or avoided to reduce
 250      the time when API endpoints must be down during database upgrade.