Red Hat SummitChapter 1. Introduction to the Red Hat Quay Operator
The Red Hat Quay Operator is designed to simplify the installation, deployment, and management of the Red Hat Quay container registry on OpenShift Container Platform. By leveraging the Operator framework, you can treat Quay as a native OpenShift Container Platform application, automating common tasks and managing its full lifecycle.
This chapter provides a conceptual overview of the Red Hat Quay Operator’s architecture and configuration model. It covers the following information:
- A configuration overview of Red Hat Quay when deployed on OpenShift Container Platform.
- How the Operator manages Quay’s components, or managed components.
- When and why to use external, or unmanaged, components for dependencies like the database and object storage.
-
The function and structure of the
configBundleSecret, which handles Quay’s configuration. - The prerequisites required before installation.
1.1. Red Hat Quay on OpenShift Container Platform configuration overview
When deploying Red Hat Quay on OpenShift Container Platform, the registry configuration is managed declaratively through two primary mechanisms: the QuayRegistry custom resource (CR) and the configBundleSecret resource.
1.1.1. Understanding the QuayRegistry CR
The QuayRegistry custom resource (CR) is the interface for defining the desired state of your Quay deployment. This resource focuses on managing the core components of the registry, such as the database, cache, and stroage.
The QuayRegistry CR is used to determine whether a component is managed, or automatically handled by the Operator, or unmanaged, or provided externally by the user.
By default, the QuayRegistry CR contains the following key fields:
-
configBundleSecret: The name of a Kubernetes Secret containing theconfig.yamlfile which defines additional configuration parameters. -
name: The name of your Red Hat Quay registry. -
namespace: The namespace, or project, in which the registry was created. spec.components: A list of component that the Operator automatically manages. Eachspec.componentfield contains two fields:-
kind: The name of the component -
managed: A boolean that addresses whether the component lifecycle is handled by the Red Hat Quay Operator. Settingmanaged: trueto a component in theQuayRegistryCR means that the Operator manages the component.
-
All QuayRegistry components are automatically managed and auto-filled upon reconciliation for visibility unless specified otherwise. The following sections highlight the major QuayRegistry components and provide an example YAML file that shows the default settings.
1.1.1.1. Managed components
By default, the Operator handles all required configuration and installation needed for Red Hat Quay’s managed components.
| Field | Type | Description |
|---|---|---|
|
| Boolean |
Holds overrides for deployment of Red Hat Quay on OpenShift Container Platform, such as environment variables and number of replicas. This component cannot be set to unmanaged ( |
|
| Boolean | Used for storing registry metadata. Currently, PostgreSQL version 13 is used. |
|
| Boolean | Provides image vulnerability scanning. |
|
| Boolean | Storage live builder logs and the locking mechanism that is required for garbage collection. |
|
| Boolean |
Adjusts the number of |
|
| Boolean |
Stores image layer blobs. When set to |
|
| Boolean | Provides an external entrypoint to the Red Hat Quay registry from outside of OpenShift Container Platform. |
|
| Boolean | Configures repository mirror workers to support optional repository mirroring. |
|
| Boolean |
Features include a Grafana dashboard, access to individual metrics, and notifications for frequently restarting |
|
| Boolean | Configures whether SSL/TLS is automatically handled. |
|
| Boolean | Configures a managed Clair database. This is a separate database than the PostgreSQL database that is used to deploy Red Hat Quay. |
The following example shows you the default configuration for the QuayRegistry custom resource provided by the Red Hat Quay Operator. It is available on the OpenShift Container Platform web console.
Example QuayRegistry custom resource
apiVersion: quay.redhat.com/v1
kind: QuayRegistry
metadata:
name: <example_registry>
namespace: <namespace>
spec:
configBundleSecret: config-bundle-secret
components:
- kind: quay
managed: true
- kind: postgres
managed: true
- kind: clair
managed: true
- kind: redis
managed: true
- kind: horizontalpodautoscaler
managed: true
- kind: objectstorage
managed: true
- kind: route
managed: true
- kind: mirror
managed: true
- kind: monitoring
managed: true
- kind: tls
managed: true
- kind: clairpostgres
managed: true1.1.1.2. Using unmanaged components for dependencies
Although the Red Hat Quay Operator provides an opinionated deployment by automatically managing all required dependencies, this approach might not be suitable for every environment. If you need to integrate existing infrastructure or require specific configurations, you can leverage the Operator to use external, or unmanaged, resources instead. An unmanaged component is any core dependency—such as PostgreSQL, Redis, or object storage—that you deploy and maintain outside of the Operator’s control.
If you are using an unmanaged PostgreSQL database, and the version is PostgreSQL 10, it is highly recommended that you upgrade to PostgreSQL 13. PostgreSQL 10 had its final release on November 10, 2022 and is no longer supported. For more information, see the PostgreSQL Versioning Policy.
For more information about unmanaged components, see "Advanced configurations".
1.1.2. Understanding the configBundleSecret
The spec.configBundleSecret field is an optional reference to the name of a Secret in the same namespace as the QuayRegistry resource. This Secret must contain a config.yaml key/value pair, where the value is a Red Hat Quay configuration file.
The configBundleSecret stores the config.yaml file. Red Hat Quay administrators can define the following settings through the config.yaml file:
- Authentication backends (for example, OIDC, LDAP)
- External TLS termination settings
- Repository creation policies
- Feature flags
- Notification settings
Red Hat Quay administrators might update this secret for the following reasons:
- Enable a new authentication method
- Add custom SSL/TLS certificates
- Enable features
- Modify security scanning settings
If this field is omitted, the Red Hat Quay Operator automatically generates a configuration secret based on default values and managed component settings. If the field is provided, the contents of the config.yaml are used as the base configuration and are merged with values from managed components to form the final configuration, which is mounted into the quay application pods.
1.2. Prerequisites for Red Hat Quay on OpenShift Container Platform
Before deploying the Red Hat Quay Operator, ensure that your environment meets the following prerequisites. These requirements cover the minimum cluster version, administrative access, resource capacity, and storage configuration necessary for a successful installation.
1.2.1. OpenShift Container Platform cluster
To deploy and manage the Red Hat Quay Operator, you must meet the following requirements:
- An OpenShift Container Platform cluster running version 4.5 or later.
- An administrative account with sufficient permissions to perform cluster-scoped actions, including the ability to create namespaces.
1.2.2. Resource Requirements
Red Hat Quay requires dedicated compute resources to function effectively. You must ensure that your OpenShift Container Platform cluster has sufficient capacity to accommodate the following requirements for each Red Hat Quay application pod:
| Resource type | Requirement |
|---|---|
| Memory | 8 Gi |
| CPU | 2000 millicores (2 vCPUs) |
The Operator creates at least one main application pod per Red Hat Quay deployment that it manages. Plan your cluster capacity accordingly.
1.2.3. Object Storage
Red Hat Quay requires object storage to store all container image layer blobs. You have two options for providing this storage: managed (automated by the Operator) or unmanaged (using an existing external service).
1.2.3.1. Managed storage overview
By default, the Red Hat Quay Operator handles storage provisioning by consuming the ObjectBucketClaim Kubernetes API. Using the ObjectBucketClaim API is the preferred method because it decouples the Red Hat Quay Operator from vendor-specific storage implementations, allowing it to integrate seamlessly with various providers.
If you are using managed object storage, the Red Hat Quay Operator can provision it for you using this ObjectBucketClaim mechanism. The NooBaa component of Red Hat OpenShift Data Foundation is a common provider that implements the ObjectBucketClaim API.
There are two supported managed options available through Red Hat OpenShift Data Foundation: using the Multicloud Object Gateway, or a production-grade deployment of Red Hat OpenShift Data Foundation. The differences between the two are summarized in the following tables.
| Aspect | Description | Benefit |
|---|---|---|
| Component |
A standalone instance of the Multicloud Object Gateway backed by a local Kubernetes | Allows you to quickly deploy a Red Hat Quay registry without procuring an external service. |
| High availability | The Multicloud Object Gateway is not highly available. If the node fails, storage is temporarily inaccessible. | Depending on your use case, it should not be substituted for high availability needs. |
| Subscription | Included in the Red Hat Quay subscription. | Reduces complexity and avoids purchasing separate products. |
| Aspect | Description | Benefit |
|---|---|---|
| Component | A production deployment of Red Hat OpenShift Data Foundation with scale-out Object Service and Ceph. | Provides reliability and data redundancy. |
| High availability | Highly available, meaning that object storage layer can withstand node failures. | Beneficial for production environments where uptime is essential. |
| Subscription | Requires a separate subscription for Red Hat OpenShift Data Foundation. | Ensures enterprise-level support and stability for your storage layer. |
1.2.3.1.1. About the Multicloud Object Gateway component
As part of a Red Hat Quay subscription, users are entitled to use the Multicloud Object Gateway component of the Red Hat OpenShift Data Foundation Operator (formerly known as OpenShift Container Storage Operator). The following table describes some of the benefits to using the Multicloud Object Gateway:
The Multicloud Object Gateway gateway component allows you to provide an S3-compatible object storage interface to Red Hat Quay backed by Kubernetes PersistentVolume-based block storage. The usage is limited to a Red Hat Quay deployment managed by the Operator and to the exact specifications of the Multicloud Object Gateway instance as documented below.
Since Red Hat Quay does not support local filesystem storage, users can leverage the gateway in combination with Kubernetes PersistentVolume storage instead, to provide a supported deployment. A PersistentVolume is directly mounted on the gateway instance as a backing store for object storage and any block-based StorageClass is supported.
By the nature of PersistentVolume, this is not a scale-out, highly available solution and does not replace a scale-out storage system like Red Hat OpenShift Data Foundation. Only a single instance of the gateway is running. If the pod running the gateway becomes unavailable due to rescheduling, updates or unplanned downtime, this will cause temporary degradation of the connected Red Hat Quay instances.
Deploying Red Hat Quay on OpenShift Container Platform using Red Hat OpenShift Data Foundation requires you to download the Local Storage Operator, the Red Hat OpenShift Data Foundation Operator, and then Multicloud Object Gateway using the OpenShift Container Platform UI. See the following Red Hat OpenShift Data Foundation documentation for these steps:
1.2.3.1.2. About Red Hat OpenShift Data Foundation
Red Hat OpenShift Data Foundation is a provider of agnostic persistent storage for OpenShift Container Platform supporting file, block, and object storage, either in-house or in hybrid clouds. As a Red Hat storage solution, Red Hat OpenShift Data Foundation is completely integrated with OpenShift Container Platform for deployment, management, and monitoring. For more information, see the Red Hat OpenShift Data Foundation documentation.
1.2.3.2. Unmanaged storage overview
When your environment requires a connection to a storage provider that you manage, for example, AWS S3, Google Cloud Storage, or a self-hosted S3-compatible service, you can leverage unmanaged storage. Red Hat Quay supports the following major cloud and on-premises object storage providers:
- Amazon Web Services (AWS) S3
- AWS STS S3 (Security Token Service)
- AWS CloudFront (CloudFront S3Storage)
- Google Cloud Storage
- Microsoft Azure Blob Storage
- Swift Storage
- Nutanix Object Storage
- IBM Cloud Object Storage
- NetApp ONTAP S3 Object Storage
- Hitachi Content Platform (HCP) Object Storage
For a complete list of object storage providers, the Quay Enterprise 3.x support matrix.
For example configurations of external object storage, see Storage object configuration fields, which provides the required YAML configuration examples, credential formatting, and full field descriptions for all supported external storage providers.
1.2.4. StorageClass
The Red Hat Quay Operator automatically deploys dedicated PostgreSQL databases for both the main Quay registry and the Clair vulnerability scanner. Both of these databases require persistent storage to ensure data integrity and availability.
To enable the Operator to provision this storage seamlessly, your cluster must have a default StorageClass configured. The Operator uses this default StorageClass to create the Persistent Volume Claims (PVCs) required by the Quay and Clair databases. These PVCs ensure that your registry metadata and vulnerability data persist across pod restarts, node failures, and upgrades.
Before proceeding with the installation, verify that a default StorageClass is configured in your cluster to ensure that the Quay and Clair components can successfully provision their required persistent volumes.
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}