Red Hat Quay architecture

Red Hat Quay uses the same codebase as Quay.io, Red Hat’s highly available container image registry. You can deploy at scale with high availability on-prem or in the cloud, with multitenant operation supported.

The code base used for Red Hat Quay is the same as the code base used for Quay.io, which is the highly available container image registry hosted by Red Hat. Quay.io and Red Hat Quay offer a multitenant SaaS solution. As a result, users can be confident that their deployment can deliver at scale with high availability, whether their deployment is on-prem or on a public cloud.

Red Hat Quay content distribution covers repository mirroring, geo-replication, and disconnected or air-gapped deployment. You can sync images from other registries, present multiple geo-distributed deployments as one registry, or run in air-gapped environments.

Red Hat Quay build automation builds Dockerfiles on worker nodes on OpenShift Container Platform or Kubernetes. You can configure build triggers such as GitHub webhooks to build new image versions when code is committed.

Red Hat Quay enhanced build architecture uses a build manager that creates Job objects and unprivileged pods running the quay-builder image.

The following image shows the expected design flow and architecture of the enhanced build features:

With this enhancement, the build manager first creates the Job Object. Then, the Job Object then creates a pod using the quay-builder-image. The quay-builder-image contains the quay-builder binary and the Podman service. The created pod runs as unprivileged. The quay-builder binary then builds the image while communicating status and retrieving build information from the Build Manager.

Red Hat Quay integrates with Git-compatible systems such as GitHub, GitLab, and Bitbucket and provides a full OAuth 2 REST API. You can configure continuous builds from your repositories and manage Red Hat Quay through the API.

Red Hat Quay security includes vulnerability scanning with Clair, TLS configuration, isolated builds, and role-based access by organization and team. You can configure encryption, HTTPS, and fine-grained read, write, and administrative access.

The latest Red Hat Quay features, enhancements, deprecations, and known issues are documented in the release notes. You can refer to the release notes for current product capabilities and changes.

See the Red Hat Quay Release Notes for information about the latest features, enhancements, deprecations, and known issues.

Image storage for Red Hat Quay holds all binary blobs and can be local, highly available, or geo-replicated. You can use local storage for proof of concept or choose supported object storage such as Ceph, Red Hat OpenShift Data Foundation, or cloud providers for production.

The Red Hat Quay database backend stores registry metadata such as users, organizations, images, and tags. PostgreSQL is the preferred database for Red Hat Quay and Clair.

Red Hat Quay stores all of its configuration information in the config.yaml file. Logs can be pushed to ElasticSearch and Splunk if required.

A future version of Red Hat Quay will remove support for using MySQL and MariaDB as the database backend, which has been deprecated since the Red Hat Quay 3.6 release. Until then, MySQL is still supported according to the support matrix, but will not receive additional features or explicit testing coverage. The Red Hat Quay Operator supports only PostgreSQL deployments when the database is managed. If you want to use MySQL, you must deploy it manually and set the database component to managed: false.

Deploying Red Hat Quay in a highly available (HA) configuration requires that your database services are provisioned for high availability. If Red Hat Quay is running on public cloud infrastructure, it is recommended that you use the PostgreSQL services provided by your cloud provider, however MySQL is also supported.

Geo-replication requires a single, shared database that is accessible from all regions.

Red Hat Quay uses Redis for ephemeral builder logs. You do not need high availability for Redis because the data is not persistent.

If Redis fails, you will lose access to build logs, builders, and the garbage collector service. Additionally, user events will be unavailable.

You can use a Redis image from the Red Hat Software Collections or from any other source you prefer.

You can automate the standalone deployment process by using Ansible or another automation suite. All standalone hosts require valid a Red Hat Enterprise Linux (RHEL) subscription.

The Red Hat Quay Operator for OpenShift Container Platform provides the following features:

Red Hat Quay can run on OpenShift Container Platform infrastructure nodes. As a result, no further subscriptions are required. Running Red Hat Quay on OpenShift Container Platform has the following benefits:

While the Red Hat Quay Operator ensures seamless deployment and management of Red Hat Quay running on OpenShift Container Platform, it is also possible to run Red Hat Quay in standalone mode and then serve content to one or many OpenShift Container Platform clusters, wherever they are running.

The following figure shows integrating standalone Red Hat Quay with OpenShift Container Platform:

Several Operators are available to help integrate standalone and Operator based deployments ofRed Hat Quay with OpenShift Container Platform, like the following:

The mirror registry for OpenShift Container Platform is a small-scale Red Hat Quay deployment for disconnected cluster installation. You can use it to mirror OpenShift Container Platform release images before deploying a production-grade registry.

The mirror registry for Red Hat OpenShift is small-scale version of Red Hat Quay that you can use as a target for mirroring the required container images of OpenShift Container Platform for disconnected installations.

For disconnected deployments of OpenShift Container Platform, a container registry is required to execute the installation of the clusters. To run a production-grade registry service on such a cluster, you must create a separate registry deployment to install the first cluster. The mirror registry for Red Hat OpenShift addresses this need and is included in every OpenShift Container Platform subscription. It is available for download on the OpenShift console Downloads page.

The mirror registry for Red Hat OpenShift allows users to install a small-scale version of Red Hat Quay and its required components using the mirror-registry command line interface (CLI) tool. The mirror registry for Red Hat OpenShift is deployed automatically with pre-configured local storage and a local database. It also includes auto-generated user credentials and access permissions with a single set of inputs and no additional configuration choices to get started.

The mirror registry for Red Hat OpenShift provides a pre-determined network configuration and reports deployed component credentials and access URLs upon success. A limited set of optional configuration inputs like fully qualified domain name (FQDN) services, superuser name and password, and custom TLS certificates are also provided. This provides users with a container registry so that they can easily create an offline mirror of all OpenShift Container Platform release content when running OpenShift Container Platform in restricted network environments.

The mirror registry for Red Hat OpenShift is limited to hosting images that are required to install a disconnected OpenShift Container Platform cluster, such as release images or Operator images. It uses local storage. Content built by customers should not be hosted by the mirror registry for Red Hat OpenShift.

Unlike Red Hat Quay, the mirror registry for Red Hat OpenShift is not a highly-available registry. Only local file system storage is supported. Using the mirror registry for Red Hat OpenShift with more than one cluster is discouraged, because multiple clusters can create a single point of failure when updating your cluster fleet. It is advised to use the mirror registry for Red Hat OpenShift to install a cluster that can host a production-grade, highly available registry such as Red Hat Quay, which can serve OpenShift Container Platform content to other clusters.

More information is available at Creating a mirror registry with mirror registry for Red Hat OpenShift.

A single shared Red Hat Quay registry can serve many clusters and data centers with organizations, RBAC, and geo-replication. You can avoid multiple distinct registries and reduce storage, infrastructure, and operational costs in most scenarios.

Many users consider running multiple, distinct registries. The preferred approach with Red Hat Quay is to have a single, shared registry:

In summary, running a shared registry helps you to save storage, infrastructure and operational costs, but a dedicated registry might be needed in specific circumstances.

Example Red Hat Quay deployments include proof of concept on a single node, highly available in a single data center, and highly available across multiple data centers. You can reference these examples when planning your deployment.

The following image shows three possible deployments for Red Hat Quay:

Red Hat Quay deployment topology sends pushes, UI, and API traffic to public endpoints and serves pulls from object storage. You can use this overview to understand traffic flow in your deployment.

The following image provides a high level overview of a Red Hat Quay deployment topology:

In this deployment, all pushes, user interface, and API requests are received by public Red Hat Quay endpoints. Pulls are served directly from object storage.

Red Hat Quay deployment topology with storage proxy routes all traffic, including pulls, through the public endpoint. You can use this topology when clients cannot access object storage directly or when you need a single entry point.

The following image provides a high level overview of a Red Hat Quay deployment topology with storage proxy configured:

With storage proxy configured, all traffic passes through the public Red Hat Quay endpoint.

When you run Red Hat Quay on Amazon Web Services, you can use AWS Elastic Load Balancer, S3 storage, RDS, and ElastiCache Redis for backend services. You can reference the overview and EC2 instance recommendations when planning your AWS deployment.

If Red Hat Quay is running on Amazon Web Services (AWS), you can use the following features:

The following image provides a high level overview of Red Hat Quay running on AWS:

When you run Red Hat Quay on Microsoft Azure, you can use Azure managed PostgreSQL, Blob Storage (hot), and Azure Cache for Redis for backend services. You can reference the overview when planning your Azure deployment.

The following image provides a high level overview of Red Hat Quay running on Microsoft Azure:

To mirror images from external registries into your Red Hat Quay cluster and synchronize by repository names and tags, you can use repository mirroring.

From your Red Hat Quay cluster with repository mirroring enabled, you can perform the following:

To use the mirroring functionality, you need to perform the following actions:

All repository mirroring configurations can be performed using the configuration tool UI or by the Red Hat Quay API.

Geo-replication lets multiple geographically distributed Red Hat Quay deployments work as a single registry from the client perspective. This improves push and pull performance in globally distributed setups and provides transparent failover and redirect for clients.

Geo-replication is supported on standalone and Operator-based deployments.

Red Hat Quay geo-replication mirrors the entire image storage backend data between 2 or more different storage backends while the database is shared, for example, one Red Hat Quay registry with two different blob storage endpoints. The primary use cases for geo-replication include the following:

Repository mirroring synchronizes selected repositories, or subsets of repositories, from one registry to another. The registries are distinct, with each registry having a separate database and separate image storage.

The primary use cases for mirroring include the following:

Red Hat Quay supports air-gapped and disconnected deployments with internet-connected registries and firewall access, or fully disconnected installations with offline media transfer. You can choose the pattern that matches your network constraints.

In the following diagram, the upper deployment in the diagram shows Red Hat Quay and Clair connected to the internet, with an air-gapped OpenShift Container Platform cluster accessing the Red Hat Quay registry through an explicit, allowlisted hole in the firewall.

The lower deployment in the diagram shows Red Hat Quay and Clair running inside of the firewall, with image and CVE data transferred to the target system using offline media. The data is exported from a separate Red Hat Quay and Clair deployment that is connected to the internet.

Sample Red Hat Quay sizing tables list approximate resources for proof of concept, mid-size, and high-end deployments. You can use these figures as a starting point and adjust based on your workload.

The following table shows approximate sizing for Proof of Concept, mid-size, and high-end deployments. Whether a deployment runs appropriately with the same metrics depends on many factors not shown below.

For further details on sizing & related recommendations for mirroring, see the section on repository mirroring.

The sizing for the Redis cache is only relevant if you use Quay builders, otherwise it is not significant.

Red Hat Quay subscriptions are based on deployments and include Standard or Premium support. You can review subscription models and entitlements when planning your registry deployment.

With a Red Hat Quay subscription, the following options are available:

For more information about purchasing a Red Hat Quay subscription, see Red Hat Quay.

You can run Red Hat Quay as an external registry in front of multiple OpenShift Container Platform clusters that use internal registries, or rely on cluster-internal registries alone. You can choose the approach that fits your image governance and distribution needs.

The required coordination of Secrets and ImageStreams is automated by the Quay Bridge Operator, which can be launched from the OperatorHub for OpenShift Container Platform.

The namespaceautoprunepolicy database table holds the policy configuration for a single namespace. There is only one entry per namespace, but there is support for multiple rows per namespace_id. The policy field holds the policy details, such as {method: "creation_date", olderThan: "2w"} or {method: "number_of_tags", numTags: 100}.

The autoprunetaskstatus table registers tasks to be executed by the auto-prune worker. Tasks are executed within the context of a single namespace. Only one task per namespace exists.

The following sections detail information about the auto-prune worker.

The auto-pruning worker is an asynchronous job that executes configured policies. Its workflow is based on values in the autoprunetask table. When a task begins, the following occurs: