Overview of upgrade

Before beginning your {productname} 2.y.z to 3.0 upgrade, please note the following:

Synchronous upgrade: For a synchronous upgrade, expect less than one hour of total downtime for small installations. Consider a small installation to contain a few thousand container image tags or fewer. For that size installation, you could probably get by with just a couple hours of scheduled downtime. The entire {productname} service is down for the duration, so if you were to try a synchronous upgrade on a registry with millions of tags, you could potentially be down for several days.
Background upgrade: For a background upgrade (also called a compatibility mode upgrade), after a short shutdown your {productname} cluster upgrade runs in the background. For large {productname} registries, this could take weeks to complete, but the cluster continues to operate in v2 mode for the duration of the upgrade. As a point of reference, one {productname} v3 upgrade took four days to process approximately 30 million tags across six machines.
Full features on completion: Before you have access to features associated with Docker version 2, schema 2 changes (such as support for containers of different architectures), the entire migration must complete. Other v3 features are immediately available when you switch over.
Upgrade complete: When the upgrade is complete, you need to set V3_UPGRADE_MODE: complete in the {productname} config.yaml file for the new features to be available. All new {productname} v3 installations automatically have that set.

Prerequisites

To assure the best results, we recommend the following prerequisites:

Back up your {productname} database before starting the upgrade (doing regular backups is a general best practice). A good time to do this is right after you have taken down the {productname} cluster to do the upgrade.
Back up your storage (also a general best practice).
Upgrade your current {productname} 2.y.z setup to the latest 2.9.z version (currently 2.9.5) before starting the v3 upgrade. To do that:
- While the {productname} cluster is still running, take one node and change the Quay container on that system to a Quay container that is running the latest 2.9.z version.
- Wait for all the database migrations to run, bringing the database up to the latest 2.9.z version. This should only take a few minutes to a half an hour.
- Once that is done, replace the Quay container on all the existing nodes with the same latest 2.9.z version. With the entire {productname} cluster on the new version, you can proceed to the v3 upgrade.