Deploying the Red Hat Quay Operator on OpenShift Container Platform

Procedure

1. On the OpenShift Container Platform web console, click Operators → Installed Operators → Red Hat Quay.
2. On the Red Hat Quay dashboard, click Create instance.

3. On the Create QuayRegistry page, review the default settings of the QuayRegistry custom resource (CR). Here, you decide whether to to use managed or unmanaged object storage.

   1. If you are using the Multicloud Object Gateway or Red Hat OpenShift Data Foundation as your object storage, keep the following settings:

          - kind: objectstorage
            managed: true

   2. If you are using a different storage provider, such as Google Cloud Platform, AWS S3, or Nutanix, set the objectstorage component as follows:

          - kind: objectstorage
            managed: false

4. Click Create. You are redirected to the Quay Registry tab on the Operator page.

5. Click the name of the Red Hat Quay registry that you created, then click Events to view the status of creation. If you used managed storage and leveraged the Multicloud Object Gateway, the registry completes creation. If you are using Red Hat OpenShift Data Foundation or an unmanaged storage backend provider, complete the following steps:

   1. Click the Details page of the Red Hat Quay registry.
   2. Click the name of the Config Bundle Secret resource, for example, <example_registry_name_config-bundle-secret-12345>.

   3. Click Actions → Edit Secret, and pass in the following information from your backend storage provider:

      # ...
      DISTRIBUTED_STORAGE_CONFIG:
          <storage_provider>:
              - <storage_provider_name>
              - access_key: <access_key>
                bucket_name: <bucket_name>
                secret_key: <secret_key>
                storage_path: /datastorage/registry
      # ...

      Note

      Depending on your storage provider, different information is required. For more information, see see Storage object configuration fields.

   4. Click Save, and then re-navigate to the Events page of the registry to ensure successful deployment.

Procedure

1. Create a namespace, for example, quay-enterprise, by entering the following command:

   $ oc new-project quay-enterprise

2. Create the QuayRegistry custom resource (CR).

   1. If the objectstorage component is set to managed: true, complete the following steps:

      1. Create the QuayRegistry CR by entering the following command:

         $ cat <<EOF | oc create -n quay-enterprise -f -
         apiVersion: quay.redhat.com/v1
         kind: QuayRegistry
         metadata:
           name: example-registry
           namespace: quay-enterprise
         EOF

   2. If the objectstorage component is set to managed: false, complete the following steps:

      1. Create the config.yaml file for Red Hat Quay by entering the following command. You must include the information required for your backend storage provider. During this step, you can enable additional Red Hat Quay features. The following example is for a minimal configuration that includes the configuration options for automating early setup tasks:

         $ cat <<EOF > config.yaml
         ALLOW_PULLS_WITHOUT_STRICT_LOGGING: false
         AUTHENTICATION_TYPE: Database
         DEFAULT_TAG_EXPIRATION: 2w
         FEATURE_USER_INITIALIZE: true 

         1

         
         SUPER_USERS: 

         2

         
              -  <username>
         BROWSER_API_CALLS_XHR_ONLY: false 

         3

         
         FEATURE_USER_CREATION: false 

         4

         
         DISTRIBUTED_STORAGE_CONFIG:
             <storage_provider>:
                 - <storage_provider_name>
                 - access_key: <access_key>
                   bucket_name: <bucket_name>
                   secret_key: <secret_key>
                   storage_path: /datastorage/registry
         ENTERPRISE_LOGO_URL: /static/img/RH_Logo_Quay_Black_UX-horizontal.svg
         FEATURE_BUILD_SUPPORT: false
         FEATURE_DIRECT_LOGIN: true
         FEATURE_MAILING: false
         REGISTRY_TITLE: Red Hat Quay
         REGISTRY_TITLE_SHORT: Red Hat Quay
         SETUP_COMPLETE: true
         TAG_EXPIRATION_OPTIONS:
         - 2w
         TEAM_RESYNC_STALE_TIME: 60m
         TESTING: false
         EOF

         1

         Set this field to true if you plan to create the first user by using API.

         2

         Include this field and the username that you plan to leverage as a Red Hat Quay administrator.

         3

         When set to False, allows general browser-based access to the API.

         4

         When set to False, relegates the creation of new users to only superusers.

   3. Create a secret for the configuration by entering the following command:

      $ oc create secret generic <quay_config_bundle_name> \
        --from-file=config.yaml=</path/to/config.yaml> \
        -n quay-enterprise \
        --dry-run=client -o yaml | oc apply -f -

   4. Create the QuayRegistry CR by entering the following command:

      $ cat <<EOF | oc create -n quay-enterprise -f -
      apiVersion: quay.redhat.com/v1
      kind: QuayRegistry
      metadata:
        name: example-registry
        namespace: quay-enterprise
      spec:
        configBundleSecret: <quay_config_bundle_name>
        components:
          - kind: clair
            managed: true
          - kind: objectstorage
            managed: false 

      1

      
          - kind: mirror
            managed: true
          - kind: monitoring
            managed: true
      EOF

      1

      Must be set to false when providing your own storage backend.

Verification

1. Check the status of your registry by entering the following command:

   $ oc describe quayregistry <registry_name> -n quay-enterprise

   Example output

   ...
   Events:
     Type    Reason                     Age                   From                     Message
     ----    ------                     ----                  ----                     -------
     Normal  ComponentsCreationSuccess  23s (x2458 over 42h)  quayregistry-controller  All objects created/updated successfully

2. Alternatively, you can check pod statuses for your registry deployment by entering the following command:

3. Enter the following command to view the deployed components:

   $ oc get pods -n quay-enterprise

   Example output

   NAME                                                   READY   STATUS      RESTARTS   AGE
   example-registry-clair-app-5ffc9f77d6-jwr9s            1/1     Running     0          3m42s
   example-registry-clair-app-5ffc9f77d6-wgp7d            1/1     Running     0          3m41s
   example-registry-clair-postgres-54956d6d9c-rgs8l       1/1     Running     0          3m5s
   example-registry-quay-app-79c6b86c7b-8qnr2             1/1     Running     4          3m42s
   example-registry-quay-app-79c6b86c7b-xk85f             1/1     Running     4          3m41s
   example-registry-quay-app-upgrade-5kl5r                0/1     Completed   4          3m50s
   example-registry-quay-database-b466fc4d7-tfrnx         1/1     Running     2          3m42s
   example-registry-quay-mirror-6d9bd78756-6lj6p          1/1     Running     0          2m58s
   example-registry-quay-mirror-6d9bd78756-bv6gq          1/1     Running     0          2m58s
   example-registry-quay-postgres-init-dzbmx              0/1     Completed   0          3m43s
   example-registry-quay-redis-8bd67b647-skgqx            1/1     Running     0          3m42s

Procedure

1. On the OpenShift Container Platform web console, click Operators → Installed Operators → Red Hat Quay.
2. On the Red Hat Quay Operators page, click Quay Registry, and then the name of your registry.
3. On the QuayRegistry details page, click the Registry Endpoint link, for example, example-registry-quay.username-cluster-new.gcp.quaydev.org. You are navigated to the registry’s main page.
4. Click Create Account.
5. Enter the details for Username, Password, Email, and then click Create Account. After creating the first user, you are automatically logged in to the Red Hat Quay registry.

Procedure

1. On the command-line interface, generate a new user with a username, password, email, and access token by entering the following CURL command:

   $ curl -X POST -k  http:/</quay-server.example.com>/api/v1/user/initialize --header 'Content-Type: application/json' --data '{ "username": "<username>", "password":"<password>", "email": "<email>@example.com", "access_token": true}'

   If successful, the command returns an object with the username, email, and encrypted password. For example:

   {"access_token":"123456789", "email":"quayadmin@example.com","encrypted_password":"<password>","username":"quayadmin"} # gitleaks:allow

   If a user already exists in the database, an error is returned. For example:

   {"message":"Cannot initialize user in a non-empty database"}

   If your password is not at least eight characters or contains whitespace, an error is returned. For example:

   {"message":"Failed to initialize user: Invalid password, password must be at least 8 characters and contain no whitespace."}

2. You can log in to your registry by navigating to the UI or by leveraging Podman on the CLI.

   1. Log in to the registry by running the following podman command:

      $ podman login -u <username> -p <password> http://<quay-server.example.com>

      Example output

      Login Succeeded!

Procedure

1. On the OpenShift Container Platform web console, click Operators → Installed Operators.
2. Click Red Hat Quay.
3. Click Quay Registry.
4. Click the name of your Red Hat Quay registry, for example, example-registry.
5. Click YAML.
6. Adjust the managed field of the desired component to either True or False.

7. Click Save.

   Note

   Setting a component to unmanaged (managed: false) might require additional configuration. For more information about setting unmanaged components in the QuayRegistry CR, see Using unmanaged components for dependencies.

Procedure

1. Edit the QuayRegistry CR by entering the following command:

   $ oc edit quayregistry <registry_name> -n <namespace>

2. Make the desired changes to the QuayRegistry CR.

   Note

   Setting a component to unmanaged (managed: false) might require additional configuration. For more information about setting unmanaged components in the QuayRegistry CR, see Using unmanaged components for dependencies.

3. Save the changes.

Procedure

1. On the OpenShift Container Platform web console, click Operators → Installed Operators → Red Hat Quay.
2. Click Quay Registry and then the name of your registry.
3. Under Config Bundle Secret, click the name of your secret, for example, quay-config-bundle.
4. On the Secret details page, click Actions → Edit secret.
5. In the Value text box, add the new configuration fields for the features that you want to enable. For a list of all configuration fields, see Configure Red Hat Quay.
6. Click Save. The Red Hat Quay Operator automatically reconciles the changes by restarting all Quay-related pods. After all pods are restarted, the features are enabled.

Procedure

1. Describe the QuayRegistry resource by entering the following command:

   $ oc describe quayregistry -n <quay_namespace>

   Example output

   # ...
     Config Bundle Secret: example-registry-config-bundle-v123x
   # ...

2. Obtain the secret data by entering the following command:

   $ oc get secret -n <quay_namespace> <example-registry-config-bundle-v123x> -o jsonpath='{.data}'

   Example output

   {
       "config.yaml": "RkVBVFVSRV9VU0 ... MDAwMAo="
   }

3. Decode the data into a YAML file into the current directory by passing in the >> config.yaml flag. For example:

   $ echo 'RkVBVFVSRV9VU0 ... MDAwMAo=' | base64 --decode >> config.yaml

4. Make the desired changes to your config.yaml file, and then save the file as config.yaml.

5. Create a new configBundleSecret YAML by entering the following command.

   $ touch <new_configBundleSecret_name>.yaml

6. Create the new configBundleSecret resource, passing in the config.yaml file` by entering the following command:

   $ oc -n <namespace> create secret generic <secret_name> \
     --from-file=config.yaml=</path/to/config.yaml> \ 

   1

   
     --dry-run=client -o yaml > <new_configBundleSecret_name>.yaml

   1

   Where <config.yaml> is your base64 decoded config.yaml file.

7. Create the configBundleSecret resource by entering the following command:

   $ oc create -n <namespace> -f <new_configBundleSecret_name>.yaml

   Example output

   secret/config-bundle created

8. Update the QuayRegistry YAML file to reference the new configBundleSecret object by entering the following command:

   $ oc patch quayregistry <registry_name> -n <namespace> --type=merge -p '{"spec":{"configBundleSecret":"<new_configBundleSecret_name>"}}'

   Example output

   quayregistry.quay.redhat.com/example-registry patched

Verification

1. Verify that the QuayRegistry CR has been updated with the new configBundleSecret:

   $ oc describe quayregistry -n <quay_namespace>

   Example output

   # ...
     Config Bundle Secret: <new_configBundleSecret_name>
   # ...

   After patching the registry, the Red Hat Quay Operator automatically reconciles the changes.

1. Obtain a list of worker nodes in your deployment by entering the following command:

   $ oc get nodes | grep worker

   Example output

   NAME                                                              STATUS   ROLES                  AGE    VERSION
   ---
   example-cluster-new-c5qqp-worker-b-4zxx5.c.quay-devel.internal   Ready    worker                 401d   v1.31.11
   example-cluster-new-c5qqp-worker-b-kz6jn.c.quay-devel.internal   Ready    worker                 402d   v1.31.11
   example-cluster-new-c5qqp-worker-b-wrhw4.c.quay-devel.internal   Ready    worker                 401d   v1.31.11
   ---

2. Add the node-role.kubernetes.io/infra= label to the worker nodes by entering the following command. The number of infrastructure nodes required depends on your environment. Production environments should provision enough infra nodes to ensure high availability and sufficient resources for all quay-related components. Monitor CPU, memory, and storage utilization to determine if additional infra nodes are required.

   $ oc label node --overwrite <infra_node_one> <infra_node_two> <infra_node_three> node-role.kubernetes.io/infra=

3. Confirm that the node-role.kubernetes.io/infra= label has been added to the proper nodes by entering the following command:

   $ oc get node | grep infra

   ---
   example-cluster-new-c5qqp-worker-b-4zxx5.c.quay-devel.internal   Ready    infra,worker           405d   v1.32.8
   example-cluster-new-c5qqp-worker-b-kz6jn.c.quay-devel.internal   Ready    infra,worker           406d   v1.32.8
   example-cluster-new-c5qqp-worker-b-wrhw4.c.quay-devel.internal   Ready    infra,worker           405d   v1.32.8
   ---

4. When a worker node is assigned the infra role, there is a chance that user workloads could get inadvertently assigned to an infra node. To avoid this, you can apply a taint to the infra node, and then add tolerations for the pods that you want to control. Taint the worker nodes with the infra label by entering the following command:

   $ oc adm taint nodes -l node-role.kubernetes.io/infra \
     node-role.kubernetes.io/infra=reserved:NoSchedule --overwrite

   Example output

   node/example-cluster-new-c5qqp-worker-b-4zxx5.c.quay-devel.internal modified
   node/example-cluster-new-c5qqp-worker-b-kz6jn.c.quay-devel.internal modified
   node/example-cluster-new-c5qqp-worker-b-wrhw4.c.quay-devel.internal modified

Procedure

1. Add the node-selector annotation to the namespace by entering the following command:

   $ oc annotate namespace <namespace> openshift.io/node-selector='node-role.kubernetes.io/infra='

   Example output

   namespace/<namespace> annotated

2. Add the tolerations annotation to the namespace by entering the following command:

   $ oc annotate namespace <namespace> scheduler.alpha.kubernetes.io/defaultTolerations='[{"operator":"Equal","value":"reserved","effect":"NoSchedule","key":"node-role.kubernetes.io/infra"},{"operator":"Equal","value":"reserved","effect":"NoExecute","key":"node-role.kubernetes.io/infra"}]' --overwrite

   Example output

   namespace/<namespace> annotated

   Important

   The tolerations in this example are specific to two taints commonly applied to infra nodes. The taints configured in your environment might differ. You must set the tolerations accordingly to match the taints applied to your infra nodes.

Procedure

1. On the OpenShift Container Platform web console, click Operators → OperatorHub.
2. In the search box, type Red Hat Quay.
3. Click Red Hat Quay → Install.
4. Select the update channel, for example, stable-3.15 and the version.
5. Click A specific namespace on the cluster for the installation mode, and then select the namespace that you applied the node-selector and tolerations annotations to.
6. Click Install.

1. Confirm that the Operator is installed by entering the following command:

   $ oc get pods -n <annotated_namespace> -o wide | grep quay-operator

   Example output

   quay-operator.v3.15.1-858b5c5fdc-lf5kj   1/1     Running   0          29m   10.130.6.18   example-cluster-new-c5qqp-worker-f-mhngl.c.quay-devel.internal   <none>           <none>

Procedure

1. On the OpenShift Container Platform web console, click Operators → Installed Operators → Red Hat Quay.
2. On the Red Hat Quay Operator details page, click Quay Registry → Create QuayRegistry.

3. On the Create QuayRegistry page, set the monitoring and objectstorage fields to false. The monitoring component cannot be enabled when Red Hat Quay is installed in a single namespace. For example:

   # ...
       - kind: monitoring
         managed: false
       - kind: objectstorage
         managed: false
   # ...

4. Click Create.

1. Optional: Confirm that the pods are running on infra nodes.

   1. List all Quay-related pods along with the nodes that they are scheduled on by entering the following command:

      $ oc get pods -n <annotated_namespace> -o wide | grep example-registry

      Example output

      ...
      NAME                                               READY   STATUS      RESTARTS   AGE   IP             NODE                                                              NOMINATED NODE   READINESS GATES
      example-registry-clair-app-5f95d685bd-dgjf6        1/1     Running     0          52m   10.128.4.12    example-cluster-new-c5qqp-worker-b-wrhw4.c.quay-devel.internal   <none>           <none>
      ...

   2. Confirm that the nodes listed include only nodes labeled infra by running the following command:

      $ oc get nodes -l node-role.kubernetes.io/infra -o name

      Example output

      node/example-cluster-new-c5qqp-worker-b-4zxx5.c.quay-devel.internal modified
      node/example-cluster-new-c5qqp-worker-b-kz6jn.c.quay-devel.internal modified
      node/example-cluster-new-c5qqp-worker-b-wrhw4.c.quay-devel.internal modified

      Note

      If any pod appears on a non-infra node, revisit your namespace annotations and deployment patching.

2. Restart all pods for the Red Hat Quay registry by entering the following command:

   $ oc delete pod -n <annotated_namespace> --all

3. Check the status of the pods by entering the following command:

   $ oc get pods -n <annotated_namespace>

   Example output

   ...
   NAME                                               READY   STATUS      RESTARTS   AGE
   example-registry-clair-app-5f95d685bd-dgjf6        1/1     Running     0          5m4s
   ...

Procedure

1. On the OpenShift Container Platform web console, click Operators → Installed Operators → Red Hat Quay.
2. On the Red Hat Quay Operator details page, click Quay Registry.
3. Click the name of the registry → Events. On this page, events a streamed in real-time.
4. Optional: To reveal more information about deployment issues, you can click the name of the registry on the Events page to navigate to the QuayRegistry details page. On the QuayRegistry details page, you can view the condition of all QuayRegistry CR components.

Procedure

1. View the state of deployed components by entering the following command:

   $ oc get pods -n quay-enterprise

   Example output

   NAME                                                   READY   STATUS              RESTARTS   AGE
   example-registry-clair-app-86554c6b49-ds7bl            0/1     ContainerCreating   0          2s
   example-registry-clair-app-86554c6b49-hxp5s            0/1     Running             1          17s
   example-registry-clair-postgres-68d8857899-lbc5n       0/1     ContainerCreating   0          17s
   example-registry-quay-app-upgrade-h2v7h                0/1     ContainerCreating   0          9s
   example-registry-quay-database-66f495c9bc-wqsjf        0/1     ContainerCreating   0          17s
   example-registry-quay-mirror-854c88457b-d845g          0/1     Init:0/1            0          2s
   example-registry-quay-mirror-854c88457b-fghxv          0/1     Init:0/1            0          17s
   example-registry-quay-postgres-init-bktdt              0/1     Terminating         0          17s
   example-registry-quay-redis-f9b9d44bf-4htpz            0/1     ContainerCreating   0          17s

2. Return information about your deployment by entering the following command:

   $ oc get quayregistry -n <namespace> -o yaml

   Example output

   apiVersion: v1
   items:
   - apiVersion: quay.redhat.com/v1
     kind: QuayRegistry
     metadata:
       annotations:
   ...
     spec:
       components:
       - kind: clair
         managed: true
       - kind: objectstorage
         managed: false
   ...
    status:
       conditions: 

   1

   
       - lastTransitionTime: "2025-10-01T18:46:13Z"
         lastUpdateTime: "2025-10-07T13:12:54Z"
         message: Horizontal pod autoscaler found
         reason: ComponentReady
         status: "True"
         type: ComponentHPAReady
   ...
       currentVersion: v3.15.2 

   2

   
       lastUpdated: 2025-10-07 13:12:54.48811705 +0000 UTC
       registryEndpoint: https://example-registry-quay-cluster-new.gcp.quaydev.org 

   3

   1

   Shows information about the status of all QuayRegistry components.

   2

   Shows the current version that the registry is using.

   3

   Shows the publicly available hostname of the registry.