Red Hat SummitChapter 1. Introduction to the Red Hat Quay Operator
The Red Hat Quay Operator simplifies installation, deployment, and management of the Red Hat Quay container registry on OpenShift Container Platform. You can use the Operator to treat Quay as a native OpenShift Container Platform application and manage 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. You use these mechanisms to configure and manage your registry deployment.
1.1.1. Understanding the QuayRegistry CR
The QuayRegistry custom resource (CR) defines the desired state of your Quay deployment. You use this resource to specify which components the Operator manages and which components you provide externally.
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
Managed components are Red Hat Quay registry components that the Operator automatically configures and installs. By using managed components, you simplify deployment and reduce manual configuration tasks.
| 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.
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
Unmanaged components are Red Hat Quay dependencies such as PostgreSQL, Redis, or object storage that you deploy and maintain outside of the Operator’s control. You use unmanaged components to integrate existing infrastructure or meet specific configuration requirements.
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 configBundleSecret is a Kubernetes Secret that stores the config.yaml file for Red Hat Quay. You use this secret to configure authentication backends, feature flags, and other registry settings. For example:
- 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
The prerequisites for Red Hat Quay on OpenShift Container Platform include minimum cluster version, administrative access, resource capacity, and storage configuration. Ensure your environment meets these requirements before deployment.
1.2.1. OpenShift Container Platform cluster
To deploy and manage the Red Hat Quay Operator, you need an OpenShift Container Platform cluster running version 4.5 or later and an administrative account with sufficient permissions to perform cluster-scoped actions.
1.2.2. Resource Requirements
The Red Hat Quay Operator requires dedicated compute resources for each application pod. Ensure that your OpenShift Container Platform cluster meets the following minimum requirements for sufficient capacity.
| 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 can provide this storage through managed storage that the Operator configures automatically, or through unmanaged storage using an existing external service.
1.2.3.1. Managed storage overview
Managed storage is object storage that the Red Hat Quay Operator provisions automatically using the ObjectBucketClaim Kubernetes API. This approach decouples the Operator from vendor-specific storage implementations and enables integration with various storage 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
Unmanaged storage is Red Hat Quay object storage that you provide and manage externally, such as AWS S3, Google Cloud Storage, or self-hosted S3-compatible services. You use unmanaged storage when you need to connect to a specific storage provider that you manage yourself.
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 uses the default StorageClass in your cluster to provision persistent storage for the Quay and Clair PostgreSQL databases. Ensure that your cluster has a default StorageClass configured before installation so that the Operator can create the required Persistent Volume Claims.
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}