zuul
/
zuul
Code Issues Proposed changes

Add an upgrading document 

This outlines our baseline assumptions regarding upgrading.

Change-Id: I2f63b3b3d643fc2aae4f35de8206d4081afa1494
This commit is contained in:
James E. Blair 2022-11-07 09:01:07 -08:00
parent c355adf44e
commit f90b5699dc
2 changed files with 46 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/source/admin.rst
View File

@ -5,6 +5,7 @@ Service Administration
:maxdepth: 2
installation
upgrading
components
configuration
drivers/index

45
doc/source/upgrading.rst Normal file
View File

@ -0,0 +1,45 @@
Upgrading
=========
Rolling Upgrades
----------------
If more than one of each Zuul component is present in a system, then
Zuul may be upgrading without downtime by performing a rolling
upgrade. During a rolling upgrade, components are stopped and started
one at a time until all components are upgraded. If there is a
behavior change during an upgrade, Zuul will typically wait until all
components are upgraded before changing behavior, but in some cases
when it is deemed safe, new behaviors may start to appear as soon as
the first component is upgraded. Be sure not to begin using or rely
on new behaviors until all components are upgraded.
Unless specified in the release notes, there is no specific order for
which components should be upgraded first, but the following order is
likely to produce the least disruption and delay the use of new
behaviors until closer to the end of the process:
* Gracefully restart executors (one at a time, or as many as a
system's over-allocation of resources will allow).
* Gracefully restart mergers.
* Restart schedulers.
* Restart web and finger gateways.
Skipping Versions
-----------------
Zuul versions are specified as `major.minor.micro`. In general,
skipping minor or micro versions during upgrades is considered safe.
Skipping major versions is not recommended, as backwards compatibility
code for older systems may be removed during a major upgrade. This
means that, for example, an upgrade from 5.x.y to 7.0.0 should include
at least an upgrade to 6.4.0 (the latest 6.x release) before
proceeding to 7.0.0.
If skipping major versions is required, then a rolling upgrade is not
possible, and Zuul should be completely stopped, and the ``zuul-admin
delete-state`` command should be run before restarting on the new
version.
Some versions may have unique upgrade requirements. See release notes
for additional information about specific version upgrades.