On this page
Summary
Red Hat Quay is the selected target registry pattern for the DC 3.0 registry capability. It provides the controlled image and artifact distribution point that lets restricted-network OpenShift clusters consume approved content without making every cluster manage direct upstream access.
The target pattern is tiered and deliberately separates platform-facing registry traffic from tenant-facing registry traffic:
- The main ACM-governed seed Quay instance curates upstream content and distributes approved platform content to the fleet.
- Each Datacenter Services cluster in AM1 and AM4 has a DCS-internal platform Quay instance for OpenShift lifecycle content, platform mirrors, marketplace/operator content, and managed cluster pull paths.
- HCP tenant clusters and tenant CI/CD systems use a separate tenant-facing Quay service per datacenter. It is platform-operated, network/API separated from DCS-internal Quay, and synchronized only through governed mirror definitions.
- Tenant-facing Quay does not receive a copy of platform mirror content by default. It stores tenant workload images and OCI artifacts only, plus selected tenant images synchronized between datacenters.
- Dedicated tenant-owned Quay instances remain exception patterns only; they require explicit ownership, IAM, backup, mirroring, scanning, logging, and admission-control evidence.
ACM and release/admission controls remain the governance and enforcement planes. Quay provides the trusted distribution path and registry evidence; it does not replace policy enforcement.
Applicable Principles
- Security by Design - registry ingress, mirroring, signing evidence, vulnerability visibility, and RBAC are designed as mandatory control surfaces.
- Least Privilege - human access uses federated identity and team roles; automation uses scoped robot accounts rather than shared credentials.
- Automation First - Quay deployment, configuration, mirroring, retention, and namespace onboarding are managed through Operator and GitOps workflows.
- Observability by Default - registry health, metrics, mirror status, garbage collection, and scan freshness are part of the platform monitoring baseline.
- Reliability and Resilience - durable state is externalized to highly available database, cache, and object-storage services.
- Data Protection - backup and restore scope includes configuration, metadata, and object blobs.
Architecture
Target Role
Quay is the tiered registry fabric between upstream registries, platform automation, DCS-internal platform registry endpoints, tenant-facing registry endpoints, and OpenShift consumers.
Red Hat generally recommends one shared Quay registry with organizations, repositories, and RBAC for separation. The RWS target intentionally uses distinct registries because the access boundary and endpoint configuration differ: DCS Quay is a platform-facing Datacenter Services dependency, while tenant-facing Quay is an externally consumable service for HCP tenant clusters and tenant pipelines. This is workable because Quay supports distinct registries with repository or organization mirroring. It is the RWS recommended target pattern for this security boundary, not a generic recommendation to deploy one Quay per cluster or per tenant.
| Flow | Target behavior |
|---|---|
| Upstream intake | Approved Red Hat, operator catalog, Quay dependency, and third-party images are mirrored into the main ACM-governed seed Quay through explicit mirror definitions. |
| Fleet seeding | AM1 and AM4 DCS-internal platform Quay instances synchronize approved platform content from the main ACM-governed seed tier on an owned cadence. |
| Tenant publishing | Build and release pipelines push workload images and OCI artifacts to tenant-facing Quay endpoints, not to DCS-internal platform Quay. |
| Cross-locality tenant sync | Tenant-facing Quay endpoints synchronize only selected repositories, tags, or promoted digests through governed repository or organization mirroring. |
| Cluster consumption | OpenShift clusters pull platform lifecycle content from the DCS-internal platform endpoint and workload content from tenant-facing Quay by digest or governed tag through ImageContentSourcePolicy or target-version mirror-set resources such as ImageDigestMirrorSet and ImageTagMirrorSet. |
| Evidence | Quay records access logs, tag history, vulnerability scan visibility, and repository metadata; policy engines enforce deployment trust gates outside Quay. |
Logical Components
| Component | Responsibility | Architecture stance |
|---|---|---|
| Main ACM-governed seed Quay | Curates upstream mirrors, Red Hat platform content, operator catalogs, Quay/Clair dependencies, and approved base images for the ACM-governed fleet. | Main upstream Quay tier for the platform; it is not the default tenant endpoint. |
| DCS-internal platform Quay | Provides local platform mirror repositories and managed cluster pull endpoints for the AM1 or AM4 Datacenter Services cluster. | One internal platform instance per datacenter; platform-facing only and not the tenant push/pull endpoint. |
| Tenant-facing Quay service | Provides tenant organizations, CI/CD push endpoints, workload image pull paths, and selected cross-datacenter repository synchronization. | One platform-operated service instance per datacenter for HCP tenants; separated from DCS-internal Quay; dedicated tenant-owned Quay remains exception-only. |
| Quay Operator | Installs and reconciles Quay, Clair, routes, services, and component configuration on OpenShift. | Target deployment mechanism for main seed, DCS-internal platform, and tenant-facing Quay instances. |
| Quay application replicas | Serve OCI registry API, UI, API, repository metadata, and authentication flows. | Horizontally scalable; treat replicas as stateless. |
| PostgreSQL | Stores users, organizations, teams, robot accounts, permissions, repositories, tags, manifests, and related metadata. | Must be highly available and backed up. |
| Redis | Supports Quay runtime functions such as events, garbage collection, and builder-related logs. | Must be treated as a service dependency with monitored health. |
| Object storage | Stores image and artifact blobs for each Quay instance. | Quay requires an S3-compatible object API for production blobs. Use ODF-provisioned object buckets backed by the dedicated Ceph platform from the accepted storage baseline; local storage or a raw block/PVC backend is not a production Quay blob store. |
| Clair | Provides vulnerability scan visibility for container images. | Enabled as registry evidence; does not replace deployment admission policy. |
| Mirror workers | Synchronize selected upstream repositories, organizations, tags, operator content, main-to-DCS platform content, and tenant-facing cross-datacenter repositories. | Mandatory for restricted-network readiness and controlled tenant image portability. |
| External route and ADC | Exposes only the intended registry endpoint for each audience: main seed, DCS-internal platform pull path, or tenant-facing service endpoint. | Runs through approved DNS, TLS, firewall, and external-load-balancing controls for the endpoint's audience. |
| Identity provider | Provides human authentication through OIDC. | Target integration is Keycloak through the federated-authentication capability. |
Deployment Topology
- The main ACM-governed seed Quay instance runs in the global hub / ACM-governed platform environment and acts as the upstream source for approved platform content.
- AM1 and AM4 each run a DCS-internal platform Quay instance in the local Datacenter Services cluster for OpenShift lifecycle content, operator content, platform base images, and managed cluster pull paths.
- AM1 and AM4 each expose a separate tenant-facing Quay service endpoint for HCP tenant clusters, tenant CI/CD publishing, and workload image pulls. The tenant-facing instance may run on platform-managed OpenShift capacity, but it is not direct exposure of DCS-internal registry services.
- Tenant-facing Quay is a shared tenant service per datacenter, not one Quay instance per tenant. Dedicated tenant-owned Quay is reserved for explicit exceptions.
- Registry endpoints are externally reachable only through approved load-balancing, DNS, TLS, and firewall paths.
- Quay application and Clair replicas scale horizontally within each instance; the HA boundary for metadata and blobs is provided by PostgreSQL, Redis, and object storage.
- Image blobs use the DC 3.0 object-storage service aligned with block-file-s3-storage, adr-001-storage-backend, and adr-009-odf-structure: an S3-compatible ODF object bucket, backed by the dedicated Ceph platform. Block or file storage can underpin the object service, but Quay consumes the object API; a raw block volume or filesystem path is not the production blob backend. A non-Ceph or non-ODF S3 endpoint is a storage exception that requires an explicit ADR.
- Main-to-DCS and tenant-facing cross-datacenter content distribution use owned mirror/synchronization definitions. They are not the same as Quay geo-replication.
- Geo-replication is not baseline. It requires a separate design for global load balancing, shared database/cache posture, object-store health, and failover runbooks.
Tenant and Platform Access Model
| Consumer | Default registry path | Exception path |
|---|---|---|
| Platform lifecycle content | Main ACM-governed seed Quay mirrors upstream content; AM1 and AM4 DCS-internal platform Quay instances synchronize the approved subset used by local clusters. | Direct upstream pulls require explicit operational approval and evidence. |
| OpenShift clusters | Pull OpenShift release, operator, platform base, and other lifecycle content from the DCS-internal platform Quay endpoint for their datacenter. | Pulling from the main seed tier is reserved for bootstrap, recovery, or approved fallback. |
| Application tenants | Push and pull workload images and OCI artifacts through tenant organizations in the local tenant-facing Quay service endpoint for the datacenter hosting their HCP tenant cluster or workload. | Dedicated tenant Quay requires an exception decision or time-bound exception record. |
| CI/CD and GitOps | Publish promoted digests and artifacts to tenant-facing repositories; only platform-owned or release-governance-approved base-image content may enter the main seed tier. | Cross-datacenter promotion without release-governance evidence is not baseline. |
| Cross-datacenter tenant image sync | Mirror only selected tenant repositories, tags, or promoted digests between AM1 and AM4 tenant-facing Quay endpoints. | Full registry duplication is not baseline; unavoidable per-instance blob copies must be justified by locality or recovery requirements. |
| Security and release tooling | Consume Quay logs, scan visibility, tag history, signatures, SBOMs, and provenance metadata where supported. | Blocking policy remains in release/admission tooling, not in Quay alone. |
Security and Supply-chain Controls
- Human access uses OIDC, Quay organizations, teams, and role-based repository permissions.
- Automation uses scoped robot accounts. A robot account is a Quay automation identity bound to a user namespace or organization; short-lived robot-account federation is preferred where the IAM integration supports it.
- Mirrored repositories are treated as controlled imports; manual pushes to mirrored repositories stay restricted to the mirror automation identity.
- Tenant-facing repositories are the controlled push/pull boundary for application teams; DCS-internal platform repositories are not tenant push targets.
- Platform mirror repositories are not copied into tenant-facing Quay. Tenant-facing Quay stores tenant workload images, tenant OCI artifacts, and selected tenant cross-datacenter mirror copies.
- Immutable tags, tag expiration, repository logs, and Clair scan results are registry evidence controls.
- Signature, SBOM, provenance, and deployment blocking are enforced by release and admission-policy tooling that consumes registry evidence; Quay is not the sole policy decision point.
- Secrets for database, object storage, robot accounts, and OIDC integration are managed through the target secrets-management service and Kubernetes secret reconciliation.
- Dedicated tenant Quay instances must not bypass central mirror catalog, IAM, backup, scanning, logging, or admission-control evidence requirements.
Operations
| Operational area | Required baseline |
|---|---|
| Backup and restore | Capture Quay config bundle, PostgreSQL dump or database backup, and object-storage blobs. Restore tests must prove image pull by digest after recovery. |
| Monitoring | Scrape Quay metrics; alert on registry API health, database/Redis connectivity, object-store errors, mirror backlog, garbage collection, Clair freshness, and certificate expiry. |
| Upgrade | Use Operator-managed lifecycle with pre-upgrade backup, mirror compatibility check, and rollback or restore evidence. |
| Capacity | Track object-storage growth, manifest count, pull traffic, mirror cadence, garbage-collection lag, and database size. |
| Tenant onboarding | Create organizations, teams, default permissions, robot accounts, retention class, and repository naming through a repeatable platform workflow. |
| Tier synchronization | Track main-to-DCS mirror cadence, tenant-facing cross-datacenter mirror cadence, failed syncs, content freshness, selected repository scope, and local override approvals. |
Scope Boundaries
- Transitional implementations that use a non-Quay registry path are outside this target Quay architecture; see openshift-ai-cluster-setup and ADR-022 OpenShift AI exception.
- Target-state Quay readiness is a cutover dependency for platform services and fleet-governed cluster consumption.
- Any future air-gapped model requires a separate ADR and design because it changes transfer logistics, catalog curation, vulnerability data movement, and operational evidence.
Decisions
- adr-005-datacenter-services-baseline selects Red Hat Quay as the Registry SBB in the Datacenter Services baseline.
- adr-011-connected-vs-disconnected keeps Phase 1 in restricted-network mode and reserves disconnected or air-gapped registry patterns for later decisions.
- adr-004-single-active-phased-rollout constrains rollout sequencing; this note defines the location-neutral target topology for the Quay tiers after each DCS locality is available.
- The architecture uses Quay Operator on OpenShift as the target deployment pattern and keeps standalone Quay out of baseline unless a future ADR changes this stance.
- The architecture treats Clair scan output as evidence and visibility, not as a complete admission-control mechanism.
- Quay image blobs use the ODF object path backed by the accepted dedicated Ceph platform baseline; any other S3 backend requires an exception ADR.
- PostgreSQL and Redis are highly available Datacenter Services dependencies with backup, monitoring, and lifecycle evidence captured during service onboarding.
- The initial mirror catalog covers Red Hat platform content, operator catalogs, OpenShift lifecycle content, Quay/Clair dependencies, and explicitly approved workload base images; additions require an owner, retention class, and review cadence.
- The target access model separates tenant-facing Quay from DCS-internal platform Quay. Tenants do not push to, or directly consume from, DCS-internal registry services; the main ACM-governed seed Quay is a platform content source, not the normal tenant endpoint.
- The tenant-facing tier is one shared platform-operated Quay service per datacenter for HCP tenant clusters, not one Quay per tenant. This deviates from Red Hat's generic preference for one shared registry only because the RWS security boundary and endpoint configuration differ between platform-facing and tenant-facing traffic.
Open Questions
No open architecture questions remain for this target Quay pattern. Remaining work is service-onboarding evidence, not architecture ambiguity:
- Record CMDB entry, support groups, service levels, recovery objectives, and cost attribution before moving the SBB from
selectedtoactive. - Publish the PostgreSQL, Redis, object bucket, backup, monitoring, tenant onboarding, main-to-DCS synchronization, tenant-facing cross-datacenter synchronization, and mirror-catalog runbooks before production cutover.
- Record the selected release-signing, SBOM, provenance, and admission-control implementation in the release-governance architecture when that adjacent control plane is selected.
- Track retirement of non-target exception registry paths through their owning workpackages, outside this Quay target architecture.