Red Hat Summit Red Hat SummitSupportConsoleDéveloppeursCommencer un essaiContact

Ce contenu n'est pas disponible dans la langue sélectionnée.

Chapter 1. Upgrading the Red Hat Quay Operator Overview

The Red Hat Quay Operator uses synchronized versioning: each Operator version deploys a single, matching version of Red Hat 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 Red Hat 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 Red Hat Quay on Kubernetes.

1.1. Operator Lifecycle Manager
Copier lien

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

Warning

When the Red Hat 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 Red Hat Quay Operator during installation. It can also be found in the Red Hat Quay Operator Subscription object by the approvalStrategy field. Choosing Automatic means that your Red Hat 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.

1.2. Upgrading the Red Hat Quay Operator
Copier lien

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

In general, Red Hat Quay supports upgrades from a prior (N-1) minor version only. For example, upgrading directly from Red Hat Quay 3.9 to the latest version of 3.16 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

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

In some cases, Red Hat 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 Red Hat Quay 3.16.1:

  • 3.13.z 3.16.1
  • 3.14.z 3.16.1
  • 3.15.z 3.16.1

1.3. Upgrading Red Hat Quay to version 3.16.1
Copier lien

To upgrade Red Hat 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 Red Hat Quay Operator.
  3. Navigate to the Subscription tab.
  4. Under Subscription details click Update channel.
  5. Select stable-3.16 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 Red Hat 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 Red Hat Quay registry.

1.4. Upgrading to the next minor release version
Copier lien

Z-stream upgrades, for example, 3.13.1 3.13.2, for Red Hat 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.

1.5. Manually approving a pending Operator upgrade
Copier lien

To approve a pending Red Hat 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.

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

1.6. Upgrading a QuayRegistry resource
Copier lien

The Red Hat 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.

1.7. Upgrading a QuayEcosystem
Copier lien

To migrate an existing QuayEcosystem to a QuayRegistry managed by the Red Hat 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>
    Copy to Clipboard Toggle word wrap 
    metadata:
  labels:
    quay-operator/migrate: "true"
    Copy to Clipboard Toggle word wrap
  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 Red Hat 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.

1.8. Reverting QuayEcosystem Upgrade
Copier lien

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

Note

If your QuayEcosystem was managing the PostgreSQL database, the upgrade process migrates your data to a new PostgreSQL database managed by the upgraded Operator. Your old database is not changed or removed but Red Hat Quay will no longer use it once the migration is complete. If there are issues during the data migration, the upgrade 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>
    Copy to Clipboard Toggle word wrap
  2. If external access was provided using a Route, change the Route to point back to the original Service using the UI or kubectl.

1.9. Supported QuayEcosystem Configurations for Upgrades
Copier lien

The Red Hat 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 Red Hat 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.
Red Hat logoGithubredditYoutubeTwitter

Apprendre

Essayez, achetez et vendez

Communautés

À propos de la documentation Red Hat

Nous aidons les utilisateurs de Red Hat à innover et à atteindre leurs objectifs grâce à nos produits et services avec un contenu auquel ils peuvent faire confiance. Découvrez nos récentes mises à jour.

Rendre l’open source plus inclusif

Red Hat s'engage à remplacer le langage problématique dans notre code, notre documentation et nos propriétés Web. Pour plus de détails, consultez le Blog Red Hat.

À propos de Red Hat

Nous proposons des solutions renforcées qui facilitent le travail des entreprises sur plusieurs plates-formes et environnements, du centre de données central à la périphérie du réseau.

Theme

© 2026 Red HatRetour au début