Chapter 10. Upgrading Red Hat Quay

For the purpose of ensuring a smooth upgrade, it is important to ensure you have all available configuration details before deleting your existing deployment. In the case that you must work with Red Hat Support, this information will aid them with the details needed to bring your cluster back to its original state. At minimum, the following information should be gathered:

Ensure a backup is created of your original Custom Resource (CR) before making any changes.

If your deployment does not specify any specific network-related configuration values, this step may not be necessary. Please refer to the documentation to ensure that the configuration options in your current CR are still accurate for the Quay Operator v3.3.4.

In the case that you have specified options related to the management of networking, such as using a LoadBalancer or specifying a custom hostname, please reference the latest documentation to update them with the schema changes included in Quay Operator v3.3.4.

If you have overridden the image used for Quay or Clair, please keep in mind that Quay Operator v3.3.4 specifically supports Quay v3.3.4 and Clair v3.3.4. It is advisable to remove those image overrides to use the latest, supported releases of Quay and Clair in your deployment. Any other images may not be supported.

The Quay Operator v3.3.4 is now distributed using the official Red Hat channels. Previously, Quay Operator v1.0.2 (and below) were provided using "Community" channels. Additionally, Red Hat Quay v3.3.4 offers no automatic upgrade path which requires your Red Hat Quay deployment and the Quay Operator to be completely removed and replaced.

Fortunately, the important data is stored in your Postgres database and your storage backend, so it is advisable to ensure you have proper backups for both.

Once you are ready, remove your existing deployment by issuing the following command:

$ oc delete -f deployment.yaml

All Quay and Clair pods will be removed as well as the Redis pod. At this point, your Red Hat Quay cluster will be completely down and inaccessible. It is suggested to inform your users of a maintenance window as they will not be able to access their images during this time.

When Red Hat Quay pods start, they will look at the database to determine whether all required database schema changes are applied. If the schema changes are not applied, which is more than likely going to be the case when upgrading from Red Hat Quay v3.2 to v3.3.4, then the Quay pod will automatically begin running all migrations. If multiple Red Hat Quay instances are running simultaneously, they may all attempt to update or modify the database at the same time which may result in unexpected issues.

To ensure that the migrations are run correctly, do not specify more than a single Quay replica to be started. Note that the default quantity of Quay pod replicas is 1, so unless you changed it, there is no work to be done here.

Verify that all Red Hat Quay-related deployments and pods no longer exist within your namespace. Ensure that no other Red Hat Quay deployments depend upon the installed Quay Operator v1.0.2 (or earlier). Type oc get pod and oc get deployment to make sure they are gone.

Using OpenShift, navigate to the Operators > Installed Operators page. The UI will present you with the option to delete the operator.

Previously, the Quay Operator (v1.0.2 and prior) were provided using the "community" Operator Hub catalog. In the latest release, the Quay Operator is released through official Red Hat channels.

In the OpenShift console, navigate to Operators > OperatorHub and then simply search for Quay. Ensure you are choosing the correct Quay Operator v3.3.4 in the event that you encounter multiple, similar results. Simply click install and choose the correct namespace/project to install the operator.

At this point, the following assumptions are made based upon the previous steps documented in this upgrade process:

Once you are ready, simply create your QuayEcosystem by executing the command:

$ oc create -f new_deployment.yaml

At this point, the Quay Operator will begin to deploy Redis, the Quay Config Application, and finally your (single) Quay Pod.

Assuming that you are upgrading from Quay v3.2 to Quay v3.3, it will be necessary for Quay to perform schema updates to your database. These can be viewed in your Quay pod’s logs.

Do not proceed with any additional steps until you are sure that the database migrations are complete.

Assuming that you are upgrading from Red Hat Quay v3.2 to Red Hat Quay v3.3, it will be necessary for Quay to perform schema updates to your database. These can be viewed in your Quay pod’s logs.

Do not proceed with any additional steps until you are sure that the database migrations are complete.

Now that the latest release of Red Hat Quay, and optionally Clair, have been deployed to your Openshift cluster, it is time to verify your configuration and scale as needed.

You can compare the results of the current configuration with the previous configuration referencing the documentation gathered in the first step of this

process. It is recommended to pay close attention to your hostname(s) and glance at all logs to look for any issues that may not have been obvious or caught by the Quay Operator.

It is also recommended to perform a quick "smoke test" on your environment to ensure that the major functionality is working as expected. One example test may include performing pushes and pulls from the registry on existing, and new, images. Another example may be accessing the Red Hat Quay UI as a registered user and

ensuring that the expected TLS certificate is used. If you rely on the Quay Operator to generate a self-signed TLS certificate then keep in mind that a new certificate may have been created by this process.

If multiple replicas are needed to scale your Red Hat Quay registry, it is now safe to change the replica count to your desired quantity. For example, to scale out the quay pod, your might run oc edit quayecosystem demo-quayecosystem, then change replicas: 1 to replicas: 2, or other desired number.

Finally, it would be highly recommended to ensure you store your configuration

and any relevant OpenShift secrets in a safe, preferably encrypted, backup.