To upgrade Project Quay, follow the procedure that matches your installation type. You can use the Operator with the Operator Lifecycle Manager (OLM) for Operator-based installations, or the standalone procedure for proof of concept or highly available setups.

Operator upgrade versioning

The Project Quay Operator uses synchronized versioning: each Operator version deploys a single, matching version of Project Quay and its components. You can use this scheme to plan upgrades and keep components compatible.

Note

There is no field on the QuayRegistry custom resource which sets the version of Project Quay to deploy; the Operator can only deploy a single version of all components. This scheme was chosen to ensure that all components work well together and to reduce the complexity of the Operator needing to know how to manage the lifecycles of many different versions of Project Quay on Kubernetes.

Operator Lifecycle Manager

Operator Lifecycle Manager (OLM) installs and upgrades the Project Quay Operator. You can use automatic or manual approval in the Subscription to control when new Operator versions are applied.

Warning

When the Project Quay Operator is installed by Operator Lifecycle Manager, it might be configured to support automatic or manual upgrades. This option is shown on the OperatorHub page for the Project Quay Operator during installation. It can also be found in the Project Quay Operator Subscription object by the approvalStrategy field. Choosing Automatic means that your Project Quay Operator will automatically be upgraded whenever a new Operator version is released. If this is not desirable, then the Manual approval strategy should be selected.

Upgrading the Project Quay Operator

To upgrade the Project Quay Operator, use the standard OpenShift Container Platform process for installed Operators and follow N-1 minor version paths.

In general, Project Quay supports upgrades from a prior (N-1) minor version only. For example, upgrading directly from Project Quay 3.9 to the latest version of {producty} is not supported. Instead, users would have to upgrade as follows:

  1. 3.9.z → 3.10.z

  2. 3.10.z → 3.11.z

  3. 3.11.z → 3.14.z

  4. 3.14.z → 3.16.z

  5. 3.16.z → 3.17.z

  6. 3.17.z → 3.18.z

  7. 3.18.z → 5.0.z

This is required to ensure that any necessary database migrations are done correctly and in the right order during the upgrade.

In some cases, Project Quay supports direct, single-step upgrades from prior (N-2, N-3) minor versions. This simplifies the upgrade procedure for customers on older releases. The following upgrade paths are supported for Project Quay {productmin}:

  • 3.16.z → {productmin}

  • 3.17.z → {productmin}

  • 3.18.z → {productmin}

Important

After you install the Project Quay Operator {producty} on a cluster, you cannot install a 3.x version of the Project Quay Operator from OperatorHub on that cluster. This restriction applies to OperatorHub installation of the Operator. It does not prevent you from creating or managing QuayRegistry resources with an already installed Operator.

Preparing a custom data model cache configuration before upgrading to Project Quay {producty}

Project Quay {producty} adds a cache component to the QuayRegistry custom resource for Operator-managed Redis data model caching. If you use a customized DATA_MODEL_CACHE_CONFIG with managed Redis, you must prepare that configuration so the Operator upgrade is not blocked.

By default, previous releases used a per-pod Memcached instance for data model caching. Customers could already configure a shared Redis or Redis Cluster backend through DATA_MODEL_CACHE_CONFIG. Starting in Project Quay {producty}, the Operator can manage Redis-backed data model caching through the new cache component. Operator-managed Redis caching reduces database pressure and helps prevent stale cache scenarios across pods.

On upgrade, the Operator defaults the new cache component based on the Redis management state:

  • If redis is managed: true, the Operator implicitly sets cache to managed: true.

  • If redis is managed: false, the Operator sets cache to managed: false, and Project Quay falls back to the default Memcached instance unless you provide caching configuration through the config bundle.

If your config bundle already contains a customized DATA_MODEL_CACHE_CONFIG and Redis is managed by the Operator, the upgrade is blocked with RolloutBlocked=True, reason ConfigInvalid, unless you complete one of the preparation or recovery procedures. The 3.18 QuayRegistry CRD does not include the cache component, so you cannot set cache.managed: false until the {producty} Operator and CRD are installed.

Important

Making Redis unmanaged is not required. To retain a customized DATA_MODEL_CACHE_CONFIG with managed Redis, set only cache to managed: false after the {producty} Operator and CRD are available.

Choose one of the following procedures based on your goal and upgrade state:

  • Retain your customized cache configuration after the {producty} CRD is installed

  • Remove the custom configuration and use Operator-managed defaults before upgrading

  • Recover a registry that is already blocked after the Operator upgrade

  • Confirm that the registry advanced successfully

Optional: Set your Operator subscription to approvalStrategy: Manual so that you can prepare the registry before approving the {producty} InstallPlan.

Keep your customized cache configuration after the {producty} CRD is installed

To retain a customized DATA_MODEL_CACHE_CONFIG during a Project Quay {producty} upgrade with managed Redis, you can set the cache component to unmanaged after the {producty} Operator and CRD are installed. The 3.18 CRD rejects kind: cache.

Prerequisites
Procedure
  1. Upgrade the Project Quay Operator to {producty}. If your subscription uses automatic approval, the Operator installs immediately. If it uses manual approval, approve the InstallPlan when you are ready.

  2. After the {producty} Operator and CRD are installed, inspect the QuayRegistry status. The registry might temporarily remain at the previous version with RolloutBlocked=True and reason ConfigInvalid while cache is implicitly managed.

  3. Edit the existing QuayRegistry custom resource. Preserve all other component entries and overrides, retain redis.managed: true, leave the custom config bundle unchanged, and set only the cache component to unmanaged:

    apiVersion: quay.redhat.com/v1
    kind: QuayRegistry
    metadata:
      name: <example_registry>
      namespace: <namespace>
    spec:
      components:
      - kind: redis
        managed: true
      - kind: cache
        managed: false
      # Preserve all other existing component entries and overrides
  4. Apply the updated QuayRegistry resource. The Operator resumes normal reconciliation automatically. Another Operator upgrade is not required.

Use Operator-managed cache defaults before upgrading

To use Operator-managed cache defaults during a Project Quay {producty} upgrade, you can remove the customized DATA_MODEL_CACHE_CONFIG from your config bundle before you upgrade. You can complete these steps on the 3.18 CRD.

Prerequisites
Procedure
  1. Remove the customized DATA_MODEL_CACHE_CONFIG field from the config.yaml file in your configBundleSecret.

  2. Update the configBundleSecret with the modified config.yaml file.

  3. Proceed with the Operator upgrade. The Operator sets cache to managed: true and applies safe default caching configuration for the managed Redis instance.

Recover a registry that is already blocked after the {producty} Operator upgrade

To recover a Project Quay registry blocked after a {producty} Operator upgrade by a customized DATA_MODEL_CACHE_CONFIG with managed Redis, you can set cache to unmanaged on the existing QuayRegistry resource. The Operator resumes reconciliation without another Operator upgrade.

Prerequisites
Procedure
  1. Confirm the blocked state:

    $ oc get quayregistry <example_registry> -n <namespace> -o jsonpath='{.status.currentVersion}{"\n"}{.status.conditions[?(@.type=="RolloutBlocked")]}{"\n"}'

    A blocked registry typically reports a previous status.currentVersion, such as v3.18.2, with RolloutBlocked=True, reason ConfigInvalid, and a message that the cache component is marked as managed while the config bundle contains required cache fields. The existing registry can remain available while the upgrade is blocked, so availability alone does not indicate a successful upgrade.

  2. Edit the existing QuayRegistry custom resource. Preserve all other component entries and overrides, retain redis.managed: true, leave the custom config bundle unchanged, and set only cache to managed: false.

  3. Apply the updated QuayRegistry resource. The Operator resumes reconciliation automatically. You do not need to reinstall or re-approve the Operator upgrade.

Verify that the registry upgrade completed

To confirm that a Project Quay registry advanced after a {producty} Operator upgrade that involves the cache component, you can check the registry version, availability, and rollout block conditions. Do not rely on availability alone.

Procedure
  1. Confirm that the registry advanced to the Operator version, that the registry remains available, and that the rollout block is cleared:

    $ oc get quayregistry <example_registry> -n <namespace> -o jsonpath='{.status.currentVersion}{"\n"}{.status.conditions[?(@.type=="Available")]}{"\n"}{.status.conditions[?(@.type=="RolloutBlocked")]}{"\n"}'

    status.currentVersion must match the {producty} Operator version. RolloutBlocked must not remain True with reason ConfigInvalid. Do not rely on availability alone, because a blocked registry can still report that the previous deployment is available.

Preserve TLS settings before upgrading Red Hat Quay on OpenShift Container Platform

The Project Quay Operator can inherit the cluster-wide TLS security profile. Before upgrading, review your cluster profile and set SSL_PROTOCOLS and SSL_CIPHERS if you need to preserve your current TLS behavior.

The Operator inherits the cluster-wide TLS security profile from the OpenShift APIServer configuration when neither SSL_PROTOCOLS nor SSL_CIPHERS is set in the configBundleSecret resource.

When the tls component is set to managed, the OpenShift Route already enforces the cluster TLS profile, and no action is required.

When the tls component is set to unmanaged, Project Quay terminates TLS directly and inherits the cluster profile after the upgrade unless you override it in the config bundle. If you have already set both SSL_PROTOCOLS and SSL_CIPHERS, no additional TLS configuration is required before upgrading. Setting only one field disables cluster-profile inheritance for both fields.

Prerequisites
  • You have cluster administrator access to review the OpenShift Container Platform APIServer configuration.

  • You can edit the configBundleSecret referenced by your QuayRegistry custom resource (CR).

Procedure
  1. Review the cluster TLS security profile:

    $ oc get apiserver cluster -o jsonpath='{.spec.tlsSecurityProfile}{"\n"}'
  2. If you must preserve your current TLS settings, add SSL_PROTOCOLS and SSL_CIPHERS to the config.yaml file in your configBundleSecret before upgrading. For example:

    # ...
    SSL_PROTOCOLS:
      - TLSv1.2
      - TLSv1.3
    SSL_CIPHERS:
      - ECDHE-RSA-AES128-GCM-SHA256
      - ECDHE-ECDSA-AES128-GCM-SHA256
      - ECDHE-RSA-AES256-GCM-SHA384
      - ECDHE-ECDSA-AES256-GCM-SHA384
      # Add other required ciphers
    # ...
    Note

    Include every cipher suite your clients require. To fully override cluster-profile inheritance, set both SSL_PROTOCOLS and SSL_CIPHERS. Setting either field disables inheritance for both fields.

  3. Update the configBundleSecret with the modified config.yaml file. You can edit the secret in the OpenShift Container Platform web console or recreate it from a local file. For example:

    $ oc create secret generic <config_bundle_secret_name> \
      --from-file config.yaml=./config.yaml \
      --dry-run=client -o yaml | oc apply -f -
  4. Proceed with the Project Quay Operator upgrade. If the cluster TLS profile is acceptable and neither SSL_PROTOCOLS nor SSL_CIPHERS is set, no additional TLS configuration is required.

Upgrade Project Quay to version {productmin}

To upgrade Project Quay to the next version, change the Operator update channel in the OpenShift Container Platform Web Console and wait for the upgrade pods to complete. You can then verify the database images and access your registry.

Procedure
  1. In the OpenShift Container Platform Web Console, navigate to Operators → Installed Operators.

  2. Click on the Project Quay Operator.

  3. Navigate to the Subscription tab.

  4. Under Subscription details click Update channel.

  5. Select stable-5 → Save.

  6. Check the progress of the new installation under Upgrade status. Wait until the upgrade status changes to 1 installed before proceeding.

  7. In your OpenShift Container Platform cluster, navigate to Workloads → Pods. Existing pods should be terminated, or in the process of being terminated.

  8. Wait for the following pods, which are responsible for upgrading the database and alembic migration of existing data, to spin up: clair-postgres-upgrade, quay-postgres-upgrade, and quay-app-upgrade.

  9. After the clair-postgres-upgrade, quay-postgres-upgrade, and quay-app-upgrade pods are marked as Completed, the remaining pods for your Project Quay deployment spin up. This takes approximately ten minutes.

  10. Verify that the quay-database uses the postgresql-13 image, and clair-postgres pods now uses the postgresql-15 image.

  11. After the quay-app pod is marked as Running, you can reach your Project Quay registry.

Upgrading to the next minor release version

Z-stream upgrades, for example, 3.13.1 → 3.13.2, for Project Quay use your existing channel and approval strategy. With Automatic approval, the Operator applies new z-stream updates with little or no downtime; with Manual approval, you approve each update first.

Manually approving a pending Operator upgrade

To approve a pending Project Quay Operator upgrade when using Manual approval, open the Subscription tab, review the install plan and resources, and click Approve. You can then monitor the upgrade progress on the Installed Operators page.

If you are upgrading to Project Quay {producty} and your config bundle contains a customized DATA_MODEL_CACHE_CONFIG with managed Redis, prepare the cache configuration before or after approving the InstallPlan, depending on the option that you choose. Removing the custom configuration can happen before approval. Setting cache.managed: false requires the {producty} Operator and CRD and cannot be applied to the 3.18 CRD.

The following image shows the Subscription tab in the UI, including the update Channel, the Approval strategy, the Upgrade status and the InstallPlan:

Subscription tab including upgrade Channel and Approval strategy

The list of Installed Operators provides a high-level summary of the current Quay installation:

Installed Operators

Upgrading a QuayRegistry resource

The Project Quay Operator reconciles QuayRegistry resources and upgrades them when the Operator version differs from the current version. When an upgrade is supported, the Operator applies it and updates status; when not, it returns an error and leaves the QuayRegistry unchanged.

The following logic is used:

  • If status.currentVersion is unset, reconcile as normal.

  • If status.currentVersion equals the Operator version, reconcile as normal.

  • If status.currentVersion does not equal the Operator version, check if it can be upgraded. If it can, perform upgrade tasks and set the status.currentVersion to the Operator’s version once complete. If it cannot be upgraded, return an error and leave the QuayRegistry and its deployed Kubernetes objects alone.

Migrate QuayEcosystem to QuayRegistry

To migrate an existing QuayEcosystem to a QuayRegistry managed by the Project Quay Operator, add the migration label to the QuayEcosystem custom resource and wait for the new QuayRegistry to start. You can then verify the migration and delete the old QuayEcosystem.

Procedure
  1. Add "quay-operator/migrate": "true" to the metadata.labels of the QuayEcosystem.

    $ oc edit quayecosystem <quayecosystem_name>
    metadata:
      labels:
        quay-operator/migrate: "true"
  2. Wait for a QuayRegistry CR to be created with the same metadata.name as your QuayEcosystem. The QuayEcosystem CR is marked with the label "quay-operator/migration-complete": "true".

  3. After the status.registryEndpoint of the new QuayRegistry is set, access Project Quay and confirm that all data and settings were migrated successfully.

  4. If everything works correctly, you can delete the QuayEcosystem. Kubernetes garbage collection cleans up all old resources.

Revert QuayEcosystem migration

To revert to the QuayEcosystem when migration to QuayRegistry fails or causes issues, delete the QuayRegistry and restore the Route to the original Service. You can then use the Project Quay deployment managed by the QuayEcosystem.

Note

If your QuayEcosystem was managing the PostgreSQL database, the migration process moves your data to a new PostgreSQL database managed by the Operator. Your old database is not changed or removed but Project Quay will no longer use it once the migration is complete. If there are issues during the data migration, the migration process exits and it is recommended that you continue with your database as an unmanaged component.

Procedure
  1. Delete the QuayRegistry using either the UI or kubectl:

    $ kubectl delete -n <namespace> quayregistry <quayecosystem-name>
  2. If external access was provided using a Route, change the Route to point back to the original Service using the UI or kubectl.

Supported QuayEcosystem configurations for migration

The Project Quay Operator reports errors in its logs and in status.conditions if migrating a QuayEcosystem component fails or is unsupported.

All unmanaged components should migrate successfully because no Kubernetes resources need to be adopted and all the necessary values are already provided in Project Quay’s config.yaml file.

Database

Ephemeral database not supported (volumeSize field must be set).

Redis

Nothing special needed.

External Access

Only passthrough Route access is supported for automatic migration. Manual migration required for other methods.

  • LoadBalancer without custom hostname: After the QuayEcosystem is marked with label "quay-operator/migration-complete": "true", delete the metadata.ownerReferences field from existing Service before deleting the QuayEcosystem to prevent Kubernetes from garbage collecting the Service and removing the load balancer. A new Service will be created with metadata.name format <QuayEcosystem-name>-quay-app. Edit the spec.selector of the existing Service to match the spec.selector of the new Service so traffic to the old load balancer endpoint will now be directed to the new pods. You are now responsible for the old Service; the Quay Operator will not manage it.

  • LoadBalancer/NodePort/Ingress with custom hostname: A new Service of type LoadBalancer will be created with metadata.name format <QuayEcosystem-name>-quay-app. Change your DNS settings to point to the status.loadBalancer endpoint provided by the new Service.

Clair

Nothing special needed.

Object Storage

QuayEcosystem did not have a managed object storage component, so object storage will always be marked as unmanaged. Local storage is not supported.

Repository Mirroring

Nothing special needed.

Supported standalone upgrade paths

To upgrade a standalone Project Quay and Clair deployment, follow the procedure for your current version in sequential order. You stop the containers, back up the database and storage, then start the new Clair and Project Quay images.

In general, single-step upgrades from prior (N-2, N-3) minor versions. This helps simplify the upgrade procedure for customers on older releases. The following upgrade paths are supported for Project Quay {productmin}:

  • 3.16.z → {productmin}

  • 3.17.z → {productmin}

  • 3.18.z → {productmin}

Upgrading to {producty} from releases older than those listed above is unsupported. This helps ensure that any necessary database migrations are done correctly and in the right order during the upgrade.

For Operator-based upgrades, see Operator upgrade versioning and the OpenShift Container Platform upgrade procedures in this guide.

Determine your current version and follow the upgrade steps in sequential order, starting with your current version and working up to your desired target version. Upgrade procedures are available for 3.16.z, 3.17.z, and 3.18.z to {productmin}.

For information on features in individual releases, see the Project Quay Release Notes.

The general procedure for a manual upgrade consists of the following steps:

  1. Stop the Quay and Clair containers.

  2. Backup the database and image storage (optional but recommended).

  3. Start Clair using the new version of the image.

  4. Wait until Clair is ready to accept connections before starting the new version of Project Quay.

Accessing images

To access Project Quay and Clair images for standalone upgrades, pull from registry.redhat.io or registry.access.redhat.com and configure authentication as described in Red Hat Container Registry Authentication.

Project Quay images from version 3.4.0 and later are available from registry.redhat.io and registry.access.redhat.com. Configure authentication before pulling images.

Upgrade to {productminv} from 3.18.z

  • Quay: {productrepo}/{quayimage}:{productminv}

  • Clair: {productrepo}/{clairimage}:{productminv}

  • PostgreSQL: {postgresimage}

  • Redis: {redisimage}

  • Clair-PostgreSQL: {postgresimage}

Upgrade to {productminv} from 3.17.z

  • Quay: {productrepo}/{quayimage}:{productminv}

  • Clair: {productrepo}/{clairimage}:{productminv}

  • PostgreSQL: {postgresimage}

  • Redis: {redisimage}

  • Clair-PostgreSQL: {postgresimage}

Upgrade to {productminv} from 3.16.z

  • Quay: {productrepo}/{quayimage}:{productminv}

  • Clair: {productrepo}/{clairimage}:{productminv}

  • PostgreSQL: {postgresimage}

  • Redis: {redisimage}

  • Clair-PostgreSQL: {postgresimage}

Upgrade standalone geo-replication

To upgrade a geo-replication deployment of standalone Project Quay, stop operations on all instances, back up the deployment, then follow the procedure to upgrade each system. Expect intermittent downtime when upgrading to the next y-stream release.

Important
  • When upgrading geo-replication Project Quay deployments to the next y-stream release (for example, Project Quay 3.7 → Project Quay 3.8), or geo-replication deployments, you must stop operations before upgrading.

  • There is intermittent downtime down upgrading from one y-stream release to the next.

  • It is highly recommended to back up your Project Quay deployment before upgrading.

Note

This procedure assumes that you are running Project Quay services on three (or more) systems. For more information, see Preparing for Project Quay high availability.

Prerequisites
  • You have logged into registry.redhat.io

Procedure
  1. Obtain a list of all Project Quay instances on each system running a Project Quay instance.

    1. Enter the following command on System A to reveal the Project Quay instances:

      $ sudo podman ps
      Example output
      CONTAINER ID  IMAGE                                      COMMAND         CREATED        STATUS            PORTS                                        NAMES
      ec16ece208c0  registry.redhat.io/quay/quay-rhel8:v{producty-n1}  registry        6 minutes ago  Up 6 minutes ago  0.0.0.0:80->8080/tcp, 0.0.0.0:443->8443/tcp  quay01
    2. Enter the following command on System B to reveal the Project Quay instances:

      $ sudo podman ps
      Example output
      CONTAINER ID  IMAGE                                      COMMAND         CREATED        STATUS            PORTS                                        NAMES
      7ae0c9a8b37d  registry.redhat.io/quay/quay-rhel8:v{producty-n1}  registry        5 minutes ago   Up 2 seconds ago   0.0.0.0:82->8080/tcp, 0.0.0.0:445->8443/tcp  quay02
    3. Enter the following command on System C to reveal the Project Quay instances:

      $ sudo podman ps
      Example output
      CONTAINER ID  IMAGE                                      COMMAND         CREATED        STATUS            PORTS                                        NAMES
      e75c4aebfee9  registry.redhat.io/quay/quay-rhel8:v{producty-n1}  registry        4 seconds ago   Up 4 seconds ago   0.0.0.0:84->8080/tcp, 0.0.0.0:447->8443/tcp  quay03
  2. Temporarily shut down all Project Quay instances on each system.

    1. Enter the following command on System A to shut down the Project Quay instance:

      $ sudo podman stop ec16ece208c0
    2. Enter the following command on System B to shut down the Project Quay instance:

      $ sudo podman stop 7ae0c9a8b37d
    3. Enter the following command on System C to shut down the Project Quay instance:

      $ sudo podman stop e75c4aebfee9
  3. Obtain the latest Project Quay version, for example, Project Quay {producty}, on each system.

    1. Enter the following command on System A to obtain the latest Project Quay version:

      $ sudo podman pull registry.redhat.io/quay/quay-rhel8:{productminv}
    2. Enter the following command on System B to obtain the latest Project Quay version:

      $ sudo podman pull registry.redhat.io/quay/quay-rhel8:v{producty}
    3. Enter the following command on System C to obtain the latest Project Quay version:

      $ sudo podman pull registry.redhat.io/quay/quay-rhel8:{productminv}
  4. On System A of your highly available Project Quay deployment, run the new image version, for example, Project Quay {producty}:

    # sudo podman run --restart=always -p 443:8443 -p 80:8080 \
       --sysctl net.core.somaxconn=4096 \
       --name=quay01 \
       -v /mnt/quay/config:/conf/stack:Z \
       -v /mnt/quay/storage:/datastorage:Z \
       -d registry.redhat.io/quay/quay-rhel8:{productminv}
  5. Wait for the new Project Quay container to become fully operational on System A. You can check the status of the container by entering the following command:

    $ sudo podman ps
    Example output
    CONTAINER ID  IMAGE                                      COMMAND         CREATED        STATUS            PORTS                                        NAMES
    70b9f38c3fb4  registry.redhat.io/quay/quay-rhel8:v{producty} registry        2 seconds ago   Up 2 seconds ago   0.0.0.0:82->8080/tcp, 0.0.0.0:445->8443/tcp  quay01
  6. Optional: Ensure that Project Quay is fully operation by navigating to the Project Quay UI.

  7. After ensuring that Project Quay on System A is fully operational, run the new image versions on System B and on System C.

    1. On System B of your highly available Project Quay deployment, run the new image version, for example, Project Quay {producty}:

      # sudo podman run --restart=always -p 443:8443 -p 80:8080 \
         --sysctl net.core.somaxconn=4096 \
         --name=quay02 \
         -v /mnt/quay/config:/conf/stack:Z \
         -v /mnt/quay/storage:/datastorage:Z \
         -d registry.redhat.io/quay/quay-rhel8:{productminv}
    2. On System C of your highly available Project Quay deployment, run the new image version, for example, Project Quay {producty}:

      # sudo podman run --restart=always -p 443:8443 -p 80:8080 \
         --sysctl net.core.somaxconn=4096 \
         --name=quay03 \
         -v /mnt/quay/config:/conf/stack:Z \
         -v /mnt/quay/storage:/datastorage:Z \
         -d registry.redhat.io/quay/quay-rhel8:{productminv}
  8. You can check the status of the containers on System B and on System C by entering the following command:

    $ sudo podman ps

Upgrade Operator geo-replication

To upgrade your geo-replicated Red Hat Quay on OpenShift Container Platform deployment, you must stop operations, scale down secondary systems, upgrade the primary system, then upgrade secondary systems. This ensures a safe upgrade process with minimal downtime across your geo-replicated registry.

Important
  • When upgrading geo-replicated Red Hat Quay on OpenShift Container Platform deployment to the next y-stream release (for example, Project Quay {producty-n1} → Project Quay {producty}), you must stop operations before upgrading.

  • There is intermittent downtime down upgrading from one y-stream release to the next.

  • It is highly recommended to back up your Red Hat Quay on OpenShift Container Platform deployment before upgrading.

The following procedure assumes that you are running the Project Quay registry on three or more systems. For this procedure, three systems named System A, System B, and System C are used. System A serves as the primary system in which the Project Quay Operator is deployed.

Procedure
  1. On System B and System C, scale down your Project Quay registry. This is done by disabling auto scaling and overriding the replica county for Project Quay, mirror workers, and Clair if it is managed. Note that you must keep the Project Quay registry running on System A. Do not update the quayregistry.yaml file on System A.

    Use the following quayregistry.yaml file as a reference:

    apiVersion: quay.redhat.com/v1
    kind: QuayRegistry
    metadata:
      name: registry
      namespace: ns
    spec:
      components:
        …
        - kind: horizontalpodautoscaler
          managed: false
        - kind: quay
          managed: true
          overrides:
            replicas: 0
        - kind: clair
          managed: true
          overrides:
            replicas: 0
        - kind: mirror
          managed: true
          overrides:
            replicas: 0
        …

    where:

    managed: false

    Disables auto scaling of Quay, Clair and Mirroring workers

    overrides

    Sets the replica count to 0 for components accessing the database and objectstorage

  2. Wait for the registry-quay-app, registry-quay-mirror, and registry-clair-app pods to disappear. Enter the following command to check their status:

    oc get pods -n <quay-namespace>
    Example output
    quay-operator.v3.7.1-6f9d859bd-p5ftc               1/1     Running     0             12m
    quayregistry-clair-postgres-7487f5bd86-xnxpr       1/1     Running     1 (12m ago)   12m
    quayregistry-quay-app-upgrade-xq2v6                0/1     Completed   0             12m
    quayregistry-quay-redis-84f888776f-hhgms           1/1     Running     0             12m
  3. On System A, initiate a Project Quay upgrade to the latest y-stream version. This is a manual process. For more information about upgrading installed Operators, see Upgrading installed Operators. For more information about Project Quay upgrade paths, see Upgrading the Project Quay Operator.

  4. After the new Project Quay registry is installed, the necessary upgrades on the cluster are automatically completed. Afterwards, new Project Quay pods are started with the latest y-stream version. Additionally, new Quay pods are scheduled and started.

  5. Confirm that the update has properly worked by navigating to the Project Quay UI:

    1. In the OpenShift console, navigate to Operators → Installed Operators, and click the Registry Endpoint link.

      Important

      Do not execute the following step until the Project Quay UI is available. Do not upgrade the Project Quay registry on System B and on System C until the UI is available on System A.

  6. Confirm that the update has properly worked on System A, initiate the Project Quay upgrade on System B and on System C. The Operator upgrade results in an upgraded Project Quay installation, and the pods are restarted.

    Note

    Because the database schema is correct for the new y-stream installation, the new pods on System B and on System C should quickly start.

  7. After updating, revert the changes made in step 1 of this procedure by removing overrides for the components. For example:

    apiVersion: quay.redhat.com/v1
    kind: QuayRegistry
    metadata:
      name: registry
      namespace: ns
    spec:
      components:
        …
        - kind: horizontalpodautoscaler
          managed: true
        - kind: quay
          managed: true
        - kind: clair
          managed: true
        - kind: mirror
          managed: true
        …

    where:

    kind: horizontalpodautoscaler:: Set this resource to True if the horizontalpodautoscaler resource was set to True before the upgrade procedure, or if you want Project Quay to scale in case of a resource shortage.

Change the Quay Bridge Operator update channel

To receive the latest Project Quay upgrades and features, you can upgrade the Quay Bridge Operator by changing the update channel in the operator subscription.

Prerequisites
  • You have installed Project Quay.

  • You are logged in to OpenShift Container Platform as a cluster administrator.

Procedure
  1. On the OpenShift Container Platform web console, click Operators → Installed Operators → Quay Bridge Operator.

  2. Click the Subscription tab.

  3. Under Update channel, click stable-3.15 → Save.

Downgrade and rollback limits

Project Quay only supports rolling back, or downgrading, to previous z-stream versions, for example, 3.12.3 → 3.12.2.

Rolling back to previous y-stream versions ({producty} → {producty-n1}) is not supported. This is because Project Quay updates might contain database schema upgrades that are applied when upgrading to a new version of Project Quay. Database schema upgrades are not considered backwards compatible.

Important
  • Downgrading to previous z-streams is neither recommended nor supported by either Operator based deployments or virtual machine based deployments. Downgrading should only be done in extreme circumstances. The decision to rollback your Project Quay deployment must be made in conjunction with the Project Quay support and development teams. For more information, contact Project Quay support.

  • After you install the Project Quay Operator {producty} on a cluster, you cannot install a 3.x version of the Project Quay Operator from OperatorHub on that cluster. This restriction applies to OperatorHub installation of the Operator. It does not prevent you from creating or managing QuayRegistry resources with an already installed Operator.