Chapter 2. Upgrading the Red Hat Quay Operator Overview Note Currently, upgrading the Red Hat Quay Operator is not supported on IBM Power and IBM Z. The Red Hat Quay Operator follows a synchronized versioning scheme, which means that each version of the Operator is tied to the version of Red Hat Quay and the components that it manages. 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. 2.1. Operator Lifecycle Manager The Red Hat Quay Operator should be installed and upgraded using the Operator Lifecycle Manager (OLM) . When creating a Subscription with the default approvalStrategy: Automatic , OLM will automatically upgrade the Red Hat Quay Operator whenever a new version becomes available. 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. 2.2. Upgrading the Red Hat Quay Operator The standard approach for upgrading installed Operators on OpenShift Container Platform is documented at Upgrading installed Operators . In general, Red Hat Quay supports upgrades from a prior (N-1) minor version only. For example, upgrading directly from Red Hat Quay 3.0.5 to the latest version of 3.5 is not supported. Instead, users would have to upgrade as follows: 3.0.5 3.1.3 3.1.3 3.2.2 3.2.2 3.3.4 3.3.4 3.4.z 3.4.z 3.5.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.10: 3.7.z 3.10.z 3.8.z 3.10.z 3.9.z 3.10.z For users on standalone deployments of Red Hat Quay wanting to upgrade to 3.9, see the Standalone upgrade guide. 2.2.1. Upgrading Red Hat Quay To update Red Hat Quay from one minor version to the , for example, 3.9 3.10, you must change the update channel for the Red Hat Quay Operator. For z stream upgrades, for example, 3.9.1 3.9.2, updates are released in the major-minor channel that the user initially selected during install. The procedure to perform a z stream upgrade depends on the approvalStrategy as outlined above. If the approval strategy is set to Automatic , the Red Hat Quay Operator upgrades automatically to the newest z stream. This results in automatic, rolling Red Hat Quay updates to newer z streams with little to no downtime. Otherwise, the update must be manually approved before installation can begin. 2.3. Removing config editor objects on Red Hat Quay Operator The config editor has been removed from the Red Hat Quay Operator on OpenShift Container Platform deployments. As a result, the quay-config-editor pod no longer deploys, and users cannot check the status of the config editor route. Additionally, the Config Editor Endpoint no longer generates on the Red Hat Quay Operator Details page. Users with existing Red Hat Quay Operators who are upgrading from 3.7, 3.8, or 3.9 to 3.10 must manually remove the Red Hat Quay config editor by removing the pod , deployment , route, service , and secret objects. To remove the deployment , route, service , and secret objects, use the following procedure. Prerequisites You have deployed Red Hat Quay version 3.7, 3.8, or 3.9. You have a valid QuayRegistry object. Procedure Obtain the quayregistry-quay-config-editor route object by entering the following command: USD oc get route Example output --- quayregistry-quay-config-editor-c866f64c4-68gtb 1/1 Running 0 49m --- Remove the quayregistry-quay-config-editor route object by entering the following command: USD oc delete route quayregistry-quay-config-editor Obtain the quayregistry-quay-config-editor deployment object by entering the following command: USD oc get deployment Example output --- quayregistry-quay-config-editor --- Remove the quayregistry-quay-config-editor deployment object by entering the following command: USD oc delete deployment quayregistry-quay-config-editor Obtain the quayregistry-quay-config-editor service object by entering the following command: USD oc get svc | grep config-editor Example output quayregistry-quay-config-editor ClusterIP 172.30.219.194 <none> 80/TCP 6h15m Remove the quayregistry-quay-config-editor service object by entering the following command: USD oc delete service quayregistry-quay-config-editor Obtain the quayregistry-quay-config-editor-credentials secret by entering the following command: USD oc get secret | grep config-editor Example output quayregistry-quay-config-editor-credentials-mb8kchfg92 Opaque 2 52m Delete the quayregistry-quay-config-editor-credentials secret by entering the following command: USD oc delete secret quayregistry-quay-config-editor-credentials-mb8kchfg92 Obtain the quayregistry-quay-config-editor pod by entering the following command: USD USD oc get pod Example output --- quayregistry-quay-config-editor-c866f64c4-68gtb 1/1 Running 0 49m --- Delete the quayregistry-quay-config-editor pod by entering the following command: USD oc delete pod quayregistry-quay-app-6bc4fbd456-8bc9c 2.3.1. Upgrading with custom SSL/TLS certificate/key pairs without Subject Alternative Names There is an issue for customers using their own SSL/TLS certificate/key pairs without Subject Alternative Names (SANs) when upgrading from Red Hat Quay 3.3.4 to Red Hat Quay 3.6 directly. During the upgrade to Red Hat Quay 3.6, the deployment is blocked, with the error message from the Red Hat Quay Operator pod logs indicating that the Red Hat Quay SSL/TLS certificate must have SANs. If possible, you should regenerate your SSL/TLS certificates with the correct hostname in the SANs. A possible workaround involves defining an environment variable in the quay-app , quay-upgrade and quay-config-editor pods after upgrade to enable CommonName matching: The GODEBUG=x509ignoreCN=0 flag enables the legacy behavior of treating the CommonName field on X.509 certificates as a hostname when no SANs are present. However, this workaround is not recommended, as it will not persist across a redeployment. 2.3.2. Changing the update channel for the Red Hat Quay Operator The subscription of an installed Operator specifies an update channel, which is used to track and receive updates for the Operator. To upgrade the Red Hat Quay Operator to start tracking and receiving updates from a newer channel, change the update channel in the Subscription tab for the installed Red Hat Quay Operator. For subscriptions with an Automatic approval strategy, the upgrade begins automatically and can be monitored on the page that lists the Installed Operators. 2.3.3. Manually approving a pending Operator upgrade If an installed Operator has the approval strategy in its subscription set to Manual , when new updates are released in its current update channel, the update must be manually approved before installation can begin. If the Red Hat Quay Operator has a pending upgrade, this status will be displayed in the list of Installed Operators. In the Subscription tab for the Red Hat Quay Operator, you can preview the install plan and review the resources that are listed as available for upgrade. If satisfied, click Approve and return to the page that lists Installed Operators to monitor the progress of the upgrade. The following image shows the Subscription tab in the UI, including the update Channel , the Approval strategy, the Upgrade status and the InstallPlan : The list of Installed Operators provides a high-level summary of the current Quay installation: 2.4. Upgrading a QuayRegistry resource When the Red Hat Quay Operator starts, it immediately looks for any QuayRegistries it can find in the namespace(s) it is configured to watch. When it finds one, 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. 2.5. Upgrading a QuayEcosystem Upgrades are supported from versions of the Operator which used the QuayEcosystem API for a limited set of configurations. To ensure that migrations do not happen unexpectedly, a special label needs to be applied to the QuayEcosystem for it to be migrated. A new QuayRegistry will be created for the Operator to manage, but the old QuayEcosystem will remain until manually deleted to ensure that you can roll back and still access Quay in case anything goes wrong. To migrate an existing QuayEcosystem to a new QuayRegistry , use the following procedure. Procedure Add "quay-operator/migrate": "true" to the metadata.labels of the QuayEcosystem . USD oc edit quayecosystem <quayecosystemname> metadata: labels: quay-operator/migrate: "true" Wait for a QuayRegistry to be created with the same metadata.name as your QuayEcosystem . The QuayEcosystem will be marked with the label "quay-operator/migration-complete": "true" . After the status.registryEndpoint of the new QuayRegistry is set, access Red Hat Quay and confirm that all data and settings were migrated successfully. If everything works correctly, you can delete the QuayEcosystem and Kubernetes garbage collection will clean up all old resources. 2.5.1. Reverting QuayEcosystem Upgrade If something goes wrong during the automatic upgrade from QuayEcosystem to QuayRegistry , follow these steps to revert back to using the QuayEcosystem : Procedure Delete the QuayRegistry using either the UI or kubectl : USD kubectl delete -n <namespace> quayregistry <quayecosystem-name> If external access was provided using a Route , change the Route to point back to the original Service using the UI or kubectl . Note If your QuayEcosystem was managing the PostgreSQL database, the upgrade process will migrate your data to a new PostgreSQL database managed by the upgraded Operator. Your old database will not be 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 will exit and it is recommended that you continue with your database as an unmanaged component. 2.5.2. Supported QuayEcosystem Configurations for Upgrades 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.

Commands:
oc get route
--- quayregistry-quay-config-editor-c866f64c4-68gtb 1/1 Running 0 49m ---
oc delete route quayregistry-quay-config-editor
oc get deployment
--- quayregistry-quay-config-editor ---
oc delete deployment quayregistry-quay-config-editor
oc get svc | grep config-editor
quayregistry-quay-config-editor ClusterIP 172.30.219.194 <none> 80/TCP 6h15m
oc delete service quayregistry-quay-config-editor
oc get secret | grep config-editor
quayregistry-quay-config-editor-credentials-mb8kchfg92 Opaque 2 52m
oc delete secret quayregistry-quay-config-editor-credentials-mb8kchfg92
USD oc get pod
--- quayregistry-quay-config-editor-c866f64c4-68gtb 1/1 Running 0 49m ---
oc delete pod quayregistry-quay-app-6bc4fbd456-8bc9c
GODEBUG=x509ignoreCN=0
oc edit quayecosystem <quayecosystemname>
metadata: labels: quay-operator/migrate: "true"
kubectl delete -n <namespace> quayregistry <quayecosystem-name>