From 07d8ec9fdf53ff2c73ec08b36153217c3651f992 Mon Sep 17 00:00:00 2001 From: Gabriel McGoldrick Date: Mon, 20 Jun 2022 11:41:22 +0100 Subject: [PATCH] PROJQUAY-2018 Architecture guide tidy up - part 1 --- architecture/images | 1 + architecture/master.adoc | 36 ++++----- modules/access-control-intro.adoc | 4 +- modules/arch-core-intro.adoc | 11 --- modules/arch-intro.adoc | 77 ++++++++++++++++--- modules/arch-prereqs.adoc | 10 +++ modules/clair-analyses.adoc | 6 +- modules/clair-intro.adoc | 2 +- modules/clairv2-to-v4.adoc | 2 +- modules/clairv4-arch.adoc | 4 +- modules/clairv4-limitations.adoc | 2 +- modules/content-distrib-intro.adoc | 2 +- modules/core-distinct-registries.adoc | 40 ++++++---- modules/core-example-deployment.adoc | 2 +- modules/core-infrastructure.adoc | 59 +++++++------- modules/core-prereqs-db.adoc | 12 +-- modules/core-prereqs-redis.adoc | 2 +- modules/core-prereqs-storage.adoc | 13 ++-- modules/core-prereqs.adoc | 10 --- modules/core-sample-quay-on-prem.adoc | 2 +- .../fine-grained-access-control-intro.adoc | 4 +- modules/georepl-arch-operator.adoc | 6 +- modules/georepl-arch-standalone.adoc | 4 +- modules/georepl-arch.adoc | 6 ++ modules/georepl-intro.adoc | 4 +- modules/georepl-mixed-storage.adoc | 8 +- modules/mirroring-api-intro.adoc | 2 +- modules/mirroring-intro.adoc | 4 +- modules/mirroring-recommend.adoc | 8 +- modules/mirroring-using.adoc | 8 +- modules/mirroring-versus-georepl.adoc | 9 ++- modules/public-cloud-azure.adoc | 4 +- modules/public-cloud-intro.adoc | 8 +- modules/quay-super-users-intro.adoc | 2 +- modules/role-based-access-control-intro.adoc | 2 +- modules/security-intro.adoc | 2 +- modules/sizing-intro.adoc | 2 +- modules/sizing-sample.adoc | 4 +- 38 files changed, 222 insertions(+), 162 deletions(-) create mode 120000 architecture/images delete mode 100644 modules/arch-core-intro.adoc create mode 100644 modules/arch-prereqs.adoc delete mode 100644 modules/core-prereqs.adoc create mode 100644 modules/georepl-arch.adoc diff --git a/architecture/images b/architecture/images new file mode 120000 index 000000000..5e6757319 --- /dev/null +++ b/architecture/images @@ -0,0 +1 @@ +../images \ No newline at end of file diff --git a/architecture/master.adoc b/architecture/master.adoc index a7459c0e4..e6319447d 100644 --- a/architecture/master.adoc +++ b/architecture/master.adoc @@ -7,28 +7,27 @@ include::modules/attributes.adoc[] include::modules/arch-intro.adoc[leveloffset=+1] -include::modules/arch-core-intro.adoc[leveloffset=+1] -include::modules/core-infrastructure.adoc[leveloffset=+2] -include::modules/core-distinct-registries.adoc[leveloffset=+3] +include::modules/arch-prereqs.adoc[leveloffset=+1] +include::modules/core-prereqs-storage.adoc[leveloffset=+2] +include::modules/core-prereqs-db.adoc[leveloffset=+2] +include::modules/core-prereqs-redis.adoc[leveloffset=+2] -include::modules/core-prereqs.adoc[leveloffset=+2] -include::modules/core-prereqs-storage.adoc[leveloffset=+3] -include::modules/core-prereqs-db.adoc[leveloffset=+3] -include::modules/core-prereqs-redis.adoc[leveloffset=+3] +include::modules/core-infrastructure.adoc[leveloffset=+1] +include::modules/core-distinct-registries.adoc[leveloffset=+2] -include::modules/core-sample-quay-on-prem.adoc[leveloffset=+2] -include::modules/core-example-deployment.adoc[leveloffset=+2] -include::modules/deployment-topology.adoc[leveloffset=+2] -include::modules/deployment-topology-with-storage-proxy.adoc[leveloffset=+2] -include::modules/public-cloud-intro.adoc[leveloffset=+2] -include::modules/public-cloud-aws.adoc[leveloffset=+3] -include::modules/public-cloud-azure.adoc[leveloffset=+3] +include::modules/core-sample-quay-on-prem.adoc[leveloffset=+1] +include::modules/core-example-deployment.adoc[leveloffset=+2] +include::modules/deployment-topology.adoc[leveloffset=+2] +include::modules/deployment-topology-with-storage-proxy.adoc[leveloffset=+2] +include::modules/public-cloud-intro.adoc[leveloffset=+1] +include::modules/public-cloud-aws.adoc[leveloffset=+2] +include::modules/public-cloud-azure.adoc[leveloffset=+2] include::modules/security-intro.adoc[leveloffset=+1] include::modules/clair-intro.adoc[leveloffset=+2] @@ -57,6 +56,7 @@ include::modules/georepl-mixed-storage.adoc[leveloffset=+3] include::modules/mirroring-versus-georepl.adoc[leveloffset=+2] include::modules/airgap-intro.adoc[leveloffset=+2] include::modules/airgap-clair.adoc[leveloffset=+3] + //access control include::modules/access-control-intro.adoc[leveloffset=+1] include::modules/tenancy-model.adoc[leveloffset=+2] @@ -70,18 +70,18 @@ include::modules/fine-grained-access-control-intro.adoc[leveloffset=+3] include::modules/ldap-binding-groups-intro.adoc[leveloffset=+4] include::modules/ldap-filtering-intro.adoc[leveloffset=+4] include::modules/quay-sso-keycloak-intro.adoc[leveloffset=+4] + //sizing include::modules/sizing-intro.adoc[leveloffset=+1] include::modules/sizing-sample.adoc[leveloffset=+2] include::modules/subscription-intro.adoc[leveloffset=+2] - include::modules/quay-internal-registry-intro.adoc[leveloffset=+2] -include::modules/scalability-intro.adoc[leveloffset=+1] +//include::modules/scalability-intro.adoc[leveloffset=+1] -include::modules/build-automation-intro.adoc[leveloffset=+1] +//include::modules/build-automation-intro.adoc[leveloffset=+1] -include::modules/integration-intro.adoc[leveloffset=+1] +//include::modules/integration-intro.adoc[leveloffset=+1] diff --git a/modules/access-control-intro.adoc b/modules/access-control-intro.adoc index 8e5fe2001..d5121d368 100644 --- a/modules/access-control-intro.adoc +++ b/modules/access-control-intro.adoc @@ -1,6 +1,6 @@ [[access-control-intro]] -= Access control += Access control in {productname} -{productname} provides both Role Based Access Control (RBAC) and Fine-Grained Access Control, and has team features that allow for limited access control of repositories, organizations, and user privileges. {productname} access control features also provide support for dispersed organizations. +{productname} provides both role-based access control (RBAC) and fine-grained access control, and has team features that allow for limited access control of repositories, organizations, and user privileges. {productname} access control features also provide support for dispersed organizations. diff --git a/modules/arch-core-intro.adoc b/modules/arch-core-intro.adoc deleted file mode 100644 index 9bc4270ee..000000000 --- a/modules/arch-core-intro.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[[arch-core-intro]] -= Core functionality - - - -* High availability -* Full standards / spec support (Docker v2-2) -* Long-term protocol support -* OCI compatibility through test suite compliance -* Enterprise grade support -* Regular updates diff --git a/modules/arch-intro.adoc b/modules/arch-intro.adoc index 38e4a37b2..39dd1c8ca 100644 --- a/modules/arch-intro.adoc +++ b/modules/arch-intro.adoc @@ -1,19 +1,74 @@ [[arch-intro]] -= {productname} features - - -{productname} is a trusted, open source container registry platform that runs everywhere, but runs best on Red Hat OpenShift. It scales without limits, from a developer laptop to a container host or Kubernetes, and can be deployed on-premise or on public cloud. It provides global governance and security controls, with features including image vulnerability scanning, access controls, geo-replication and repository mirroring. += {productname} overview +{productname} is a trusted, open source container registry platform that runs everywhere, but runs best on Red Hat OpenShift. It scales without limits, from a developer laptop to a container host or Kubernetes, and can be deployed on-prem or on public cloud. {productname} provides global governance and security controls, with features including image vulnerability scanning, access controls, geo-replication and repository mirroring. image:178_Quay_architecture_0821_features.png[Quay features] This guide provides an insight into architectural patterns to use when deploying {productname}. It contains sizing guidance and deployment prerequisites, along with best practices for ensuring high availability for your {productname} registry. -* xref:arch-core-intro[Core functionality] -* xref:security-intro[Security] -* xref:content-distrib-intro[Content distribution] -* xref:access-control-intro[Access control] -* xref:build-automation-intro[Build automation] -* xref:scalability-intro[Scalability] -* xref:integration-intro[Integration] + +== Scalability and high availability (HA) + +The code base for the private {productname} offering is substantially the same as that used for link:https::/quay.io[quay.io], the highly available container image registry hosted by Red Hat which provides a multi-tenant SaaS solution. As a result, you can be confident that {productname} can deliver at scale with high availability, whether you deploy on-prem or on public cloud. + +== Security + +{productname} is built for real enterprise use cases where content governance and security are two major focus areas. {productname} content governance and security includes built-in vulnerability scanning via Clair. + +== Content distribution + +Content distribution features in {productname} include: + +Repository mirroring:: {productname} repository mirroring lets you mirror images from external container registries (or another local registry) into your {productname} cluster. Using repository mirroring, you can synchronize images to {productname} based on repository names and tags. + +Geo-replication:: {productname} geo-replication allows multiple, geographically distributed Quay deployments to work as a single registry from the perspective of a client or user. It significantly improves push and pull performance in a globally-distributed {productname} setup. Image data is asynchronously replicated in the background with transparent failover / redirect for clients. + +Deployment in disconnected or air-gapped environments:: {productname} can be deployed in a disconnected environment in two ways: ++ +* {productname} and Clair connected to the internet, with an air-gapped OpenShift cluster accessing the Quay registry through an explicit, white-listed hole in the firewall. +* {productname} and Clair running inside the firewall, with image and CVE data transferred to the target system using offline media. The data is exported from a separate Quay and Clair deployment that is connected to the internet. + +== Access control + +{productname} provides both role-based access control (RBAC) and fine-grained access control, and has team features that allow for limited access control of repositories, organizations, and user privileges. {productname} access control features also provide support for dispersed organizations. + +== Build automation + +{productname} supports building Dockerfiles using a set of worker nodes on OpenShift or Kubernetes. Build triggers, such as GitHub webhooks, can be configured to automatically build new versions of your repositories when new code is committed. + +Prior to {productname} 3.7, Quay ran podman commands in virtual machines launched by pods. Running builds on virtual platforms requires enabling nested virtualization, which is not featured in Red Hat Enterprise Linux or OpenShift Container Platform. As a result, builds had to run on bare-metal clusters, which is an inefficient use of resources. + +With {productname} 3.7, the bare-metal constraint required to run builds has been removed by adding an additional build option which does not contain the virtual machine layer. As a result, builds can be run on virtualized platforms. Backwards compatibility to run previous build configurations is also available. + +== Integration + +Integration with popular source code management and versioning systems like GitHub, GitLab or BitBucket allows {productname} to continuously build and serve your containerized software. + +== REST API + +{productname} provides a full OAuth 2, RESTful API that: + +* Is available from endpoints of each {productname} instance from the URL https:///api/v1 +* Lets you connect to endpoints, via a browser, to get, delete, post, and put {productname} settings by enabling the Swagger UI +* Can be accessed by applications that make API calls and use OAuth tokens +* Sends and receives data as JSON + +== Recently added features + +Storage Quota on Organizations:: Control and contain storage growth of your container registry with reporting and enforcement. + +Transparent pull-thru cache proxy (Tech preview):: Use {productname} as a transparent cache for other registry for improved performance and resiliency. + +Geo-replication with the Operator:: Deploy a geographically dispersed container registry across two or more OpenShift clusters. + +{productname} container builds on OpenShift:: Build your container images right inside Quay running on top of OpenShift. + +== Other features + +* Full standards / spec support (Docker v2-2) +* Long-term protocol support +* OCI compatibility through test suite compliance +* Enterprise grade support +* Regular updates diff --git a/modules/arch-prereqs.adoc b/modules/arch-prereqs.adoc new file mode 100644 index 000000000..23c36889f --- /dev/null +++ b/modules/arch-prereqs.adoc @@ -0,0 +1,10 @@ +[[arch-prereqs]] += {productname} prerequisites + +Before deploying {productname}, you will need to provision the following: + +* xref:core-prereqs-storage[Image storage] +* xref:core-prereqs-db[Database] +* xref:core-prereqs-redis[Redis] + + diff --git a/modules/clair-analyses.adoc b/modules/clair-analyses.adoc index 84fdf43b0..fd368ddf9 100644 --- a/modules/clair-analyses.adoc +++ b/modules/clair-analyses.adoc @@ -11,17 +11,17 @@ Once a `Manifest` is indexed, the `IndexReport` is persisted for later retrieval - **Matching**: Matching is taking an `IndexReport` and correlating vulnerabilities affecting the `Manifest` the report represents. + -Clair continuously ingests new security data and a request to the matcher will always provide users with the most to date vulnerability analysis of an `IndexReport`. +Clair continuously ingests new security data and a request to the matcher will always provide users with the most up to date vulnerability analysis of an `IndexReport`. - **Notifications**: Clair implements a notification service. When new vulnerabilities are discovered, the notifier service will determine if these vulnerabilities affect any indexed `Manifests`. The notifier will then take action according to its configuration. == Notifications for vulnerabilities found by Clair -{productname} 3.4 triggers different notifications for various repository events. These notifications vary based on enabled features. +Since {productname} 3.4, different notifications are triggered for various repository events. These notifications vary based on enabled features. [NOTE] ==== -This include the event type `Package Vulnerability Found` +This includes the event type `Package Vulnerability Found` ==== `Additional Filter` can be applied for `Security Level`, and there are various notification methods. Custom notification titles are also optional. diff --git a/modules/clair-intro.adoc b/modules/clair-intro.adoc index 17a75c748..3338ac0fb 100644 --- a/modules/clair-intro.adoc +++ b/modules/clair-intro.adoc @@ -1,7 +1,7 @@ [[clair-intro]] = {productname} vulnerability scanning using Clair -Clair is equipped with three types of scanners, a matcher, and an updater: +Clair is equipped with three types of scanners, and a matcher and an updater: - **Distribution Scanner**: This scanner discovers `Distribution` information, which is typically the base operator system the layer demonstrates features of. diff --git a/modules/clairv2-to-v4.adoc b/modules/clairv2-to-v4.adoc index ac79c2cad..e13c0d4ce 100644 --- a/modules/clairv2-to-v4.adoc +++ b/modules/clairv2-to-v4.adoc @@ -1,7 +1,7 @@ [[clairv2-to-v4]] = Migrating from Clair v2 to Clair v4 -Starting with {productname} 3.4, Clair v4 is used by default. It will also be the only version of Clair continually supported, as older {productname} versions are not supported with Clair v4 in production. Users should continue using Clair v2 if using a version of {productname} earlier than 3.4. +Starting with {productname} 3.4, Clair v4 is used by default. It will also be the only version of Clair continually supported, as older versions of {productname} are not supported with Clair v4 in production. Users should continue using Clair v2 if using a version of {productname} earlier than 3.4. Existing {productname} 3.3 deployments will be upgraded to Clair v4 when managed via the {productname} Operator. Manually upgraded {productname} deployments can install Clair v4 side-by-side, which will cause the following: diff --git a/modules/clairv4-arch.adoc b/modules/clairv4-arch.adoc index f608b352b..5927e469b 100644 --- a/modules/clairv4-arch.adoc +++ b/modules/clairv4-arch.adoc @@ -1,11 +1,11 @@ [[clairv4-arch]] = Clair v4 architecture -Clair v4 utilizes the ClairCore library as its engine for examining contents and reporting vulnerabilities. At a high level you can consider Clair a service wrapper to the functionality provided in the ClairCore library. +Clair v4 utilizes the ClairCore library as its engine for examining contents and reporting vulnerabilities. At a high level, you can consider Clair as a service wrapper to the functionality provided in the ClairCore library. == ClairCore -ClairCore is the engine behind Clair v4's container security solution. The ClairCore package exports our domain models, interfaces necessary to plug into our business logic, and a default set of implementations. This default set of implementations defines our support matrix. +ClairCore is the engine behind Clair v4's container security solution. The ClairCore package exports domain models, interfaces that are necessary to plug into the business logic, and a default set of implementations. This default set of implementations defines the support matrix. ClairCore relies on Postgres for its persistence and the library will handle migrations if configured to do so. diff --git a/modules/clairv4-limitations.adoc b/modules/clairv4-limitations.adoc index 7a63940d7..a8a657120 100644 --- a/modules/clairv4-limitations.adoc +++ b/modules/clairv4-limitations.adoc @@ -9,4 +9,4 @@ The following limitations are currently being addressed by the development team: * Clair v4 does not currently support MSFT Windows images. -* Clair v4 does not currently support slim/scratch container images. \ No newline at end of file +* Clair v4 does not currently support slim / scratch container images. \ No newline at end of file diff --git a/modules/content-distrib-intro.adoc b/modules/content-distrib-intro.adoc index c9f2e64be..03703877d 100644 --- a/modules/content-distrib-intro.adoc +++ b/modules/content-distrib-intro.adoc @@ -1,5 +1,5 @@ [[content-distrib-intro]] -= Content distribution += Content distribution with {productname} Content distribution features in {productname} include: diff --git a/modules/core-distinct-registries.adoc b/modules/core-distinct-registries.adoc index 6181e010e..5135072ba 100644 --- a/modules/core-distinct-registries.adoc +++ b/modules/core-distinct-registries.adoc @@ -1,28 +1,40 @@ [[core-distinct-registries]] = Single versus multiple registries -Many users consider running multiple, distinct registries while the preferred approach with Quay is to have a single, shared registry. The following table addresses the reasons why a user might want to run multiple registries and how these requirements are addressed in Quay: +Many users consider running multiple, distinct registries whereas the preferred approach with {productname} is to have a single, shared registry. The following table addresses the reasons why a user might want to run multiple registries and how these requirements are addressed in {productname}: [cols="2a,2a",options="header"] |=== -| Multiple registries | Quay approach -| Clear separation between Dev and Prod | Use organizations and repositories instead + RBAC -Clear separation by content origin + -(internal/external) | Use organizations and repositories instead + RBAC -Required to test registry upgrades given the criticality of the registry for running apps | -Quay Operator automates updates, both patch releases as well as minor or major updates that require an ordered sequence of steps to complete -| Separate registry in each datacenter (DC) | Quay can serve content to multiple physically close DCs + + +| Multiple registries | {productname} approach +| Clear separation between development and production | Use organizations and repositories instead + RBAC + +| Clear separation by content origin + +(internal/external) +| Use organizations and repositories instead + RBAC + +| Required to test registry upgrades given the criticality of the registry for running apps +| {productname} Operator automates updates, both patch releases as well as minor or major updates that require an ordered sequence of steps to complete + +| Separate registry in each datacenter (DC) +| {productname} can serve content to multiple physically close DCs + + HA can stretch across DCs (requires load balancers) + + -Quay Geo-Replication can stretch across physically distant DCs (requires global load balancer or DNS-based geo-aware load-balancing) -| Separate registry for each cluster | Quay can serve content to thousands of clusters -| Scalability concerns over single registry | Quay scales nearly without limits + +{productname} Geo-replication can stretch across physically distant DCs (requires global load balancer or DNS-based geo-aware load-balancing) + +| Separate registry for each cluster +| {productname} can serve content to thousands of clusters + +| Scalability concerns over single registry +| {productname} scales nearly without limits + (The underlying code base is proven to work at scale at Quay.io) -| Distinct registry configurations | In this scenario it might make sense to run two distinct registries + +| Distinct registry configurations +| In this scenario it might make sense to run two distinct registries + |=== **Recommendation:** -Running a shared registry helps you to save storage, infrastructure and operational costs. -A dedicated registry would be really needed in very specific circumstances. +Running a shared registry helps you to save storage, infrastructure and operational costs but a dedicated registry may be needed in very specific circumstances. diff --git a/modules/core-example-deployment.adoc b/modules/core-example-deployment.adoc index 1e51cb62a..d8a0950ed 100644 --- a/modules/core-example-deployment.adoc +++ b/modules/core-example-deployment.adoc @@ -1,7 +1,7 @@ [[core-example-deployment]] = {productname} example deployments -The following image shows two {productname} example deployments: +The following image shows three possible deployments for {productname}: * Proof of concept, single node * Highly available, multi-node in single data center diff --git a/modules/core-infrastructure.adoc b/modules/core-infrastructure.adoc index e1f39ca02..5fbf8412e 100644 --- a/modules/core-infrastructure.adoc +++ b/modules/core-infrastructure.adoc @@ -1,48 +1,53 @@ -= Infrastructure += {productname} infrastructure -Quay runs on any physical or virtual infrastructure, both on-premise or public cloud. Deployments range from simple to massively scaled, including: +{productname} runs on any physical or virtual infrastructure, both on-premise or public cloud. Deployments range from simple to massively scaled, including: * All-in-one setup on a developer laptop * Highly available on Virtual Machines or on OpenShift -* Geographically dispersed setup across multiple availability zones and regions +* Geographically dispersed across multiple availability zones and regions -== Running Quay on standalone hosts - -* Poof-of-concept deployment, where Quay runs on a machine with image storage and containerized database, Redis and optionally, Clair security scanning (scanning only works with object storage) -* Highly available setups running Quay and Clair in containers across multiple hosts, using `systemd` to ensure restart on failure/reboot -* High availability setups on standalone hosts require customer-provided load balancers, either low-level TCP load balancers or Application Load Balancers capable of terminating TLS +== Running {productname} on standalone hosts Standalone deployment is a manual process, but it can easily be automated by the customer, for example, using Ansible. All standalone hosts require valid RHEL subscriptions. -== Running Quay on OpenShift - -* Automated deployment and Day 2 management of Red Hat Quay with customization options -* Quay Operator can manage Quay and all dependencies -* Automated scaling and updates -* Integration with existing OpenShift processes like GitOps, monitoring, alerting, logging -* Can provide out-of-the-box object storage with limited availability, backed by the Multi-Cloud Object Gateway (NooBaa), as part of the ODF Operator (no additional subscription required) -* Can leverage scale-out, high availability object storage provided by the ODF Operator (additional subscription required) - -Quay can run on OpenShift infra nodes, meaning no further subscriptions are required. +Poof-of-concept deployment:: {productname} runs on a machine with image storage, containerized database, Redis, and optionally, Clair security scanning (scanning only works with object storage). -== Running Quay outside OpenShift +Highly available setups:: {productname} and Clair run in containers across multiple hosts, using `systemd` to ensure restart on failure/reboot. ++ +High availability setups on standalone hosts require customer-provided load balancers, either low-level TCP load balancers or application load balancers capable of terminating TLS. -While the Quay Operator ensures seamless deployment and management of Quay running on OpenShift, it is also possible to run Quay in standalone mode (see above) and then serve content to one or many OpenShift clusters, wherever they are running. -image:178_Quay_architecture_0821_deployment_ex2.png[Quay outside OpenShift] -A number of operators are available to help integrate standalone Quay with OpenShift: +== Running {productname} on OpenShift -* **Quay Cluster Security Operator:** relays Quay vulnerability scanning results into the OpenShift Console -* **Quay Bridge Operator:** ensures seamless integration and user experience for using Quay with OpenShift in conjunction with OpenShift Builds and ImageStreams +The {productname} Operator for OpenShift provides the following features: +* Automated deployment and Day 2 management of {productname}with customization options +* Management of {productname} and all its dependencies +* Automated scaling and updates +* Integration with existing OpenShift processes like GitOps, monitoring, alerting, logging +* Provision of out-of-the-box object storage with limited availability, backed by the Multi-Cloud Object Gateway (NooBaa), as part of the ODF Operator (no additional subscription required) +* Scaled-out, high availability object storage provided by the ODF Operator (additional subscription required) -== Benefits of running Quay on OpenShift +{productname} can run on OpenShift infrastructure nodes, meaning no further subscriptions are required. Benefits of running {productname} on OpenShift include: -* **Zero to Hero:** Simplified deployment of Quay and associated components means that you can start using the product immediately +* **Zero to Hero:** Simplified deployment of {productname} and associated components means that you can start using the product immediately * **Scalability:** Leverage cluster compute capacity to manage demand via automated scaling, based on actual load * **Simplified Networking:** Automated provisioning of load balancers and traffic ingress secured via HTTPS using OpenShift TLS certificates and Routes * **Declarative configuration management:** Configurations stored in in CustomResource objects for GitOps-friendly lifecycle management -* **Repeatability:** Consistency regardless of the number of replicas of Quay / Clair +* **Repeatability:** Consistency regardless of the number of replicas of {productname} / Clair * **OpenShift integration:** Additional services to leverage OpenShift Monitoring and Alerting facilities to manage multiple Quay deployments on a single cluster +== Running {productname} outside OpenShift + +While the {productname} Operator ensures seamless deployment and management of {productname} running on OpenShift, it is also possible to run {productname} in standalone mode and then serve content to one or many OpenShift clusters, wherever they are running. + +image:178_Quay_architecture_0821_deployment_ex2.png[Quay outside OpenShift] + +A number of Operators are available to help integrate standalone Quay with OpenShift: + +{productname} Cluster Security Operator:: Relays Quay vulnerability scanning results into the OpenShift Console +{productname} Bridge Operator:: Ensures seamless integration and user experience for using {productname} with OpenShift in conjunction with OpenShift Builds and ImageStreams + + + diff --git a/modules/core-prereqs-db.adoc b/modules/core-prereqs-db.adoc index 5f786f068..e7e34116d 100644 --- a/modules/core-prereqs-db.adoc +++ b/modules/core-prereqs-db.adoc @@ -1,16 +1,12 @@ [[core-prereqs-db]] = Database backend -Quay stores most of its configuration and all metadata and logs inside its database backend. Logs can be pushed into ElasticSearch instead +{productname} stores most of its configuration and all metadata and logs inside its database backend, although logs can be pushed to ElasticSearch if required. PostgreSQL is the preferred database backend since it can be used for both Quay and Clair. -PostgreSQL is the preferred database backend since it can be used for both Quay and Clair +Since the {productname} 3.6 release, using MySQL/MariaDB as the database backend for {productname} is deprecated, and going forward, support will eventually be removed. Until then, MySQL is still supported as per the link:https://access.redhat.com/articles/4067991[support matrix] but will not receive additional features or explicit testing coverage. The Red Hat Quay Operator only supports PostgreSQL as a managed database since {productname} 3.4. External MySQL/MariaDB databases can still be leveraged (setting the database to `unmanaged` in the Operator in the process) until support is removed. -Quay works fine with MySQL too (5.7+) but Clair requires PostgreSQL +Deploying {productname} in a highly available (HA) configuration requires that your database is provisioned for high availablity. If {productname} is running on public cloud infrastructure, it is recommended that you use the PostgreSQL services provided by your cloud provider. -Quay HA requires an HA database setup - -If Quay is running on public cloud infrastructure, we recommend the use of the PostgreSQL services provided by your cloud provider. - -Geo-replication requires a single, shared database that is accessible from all regions +Geo-replication requires a single, shared database that is accessible from all regions. diff --git a/modules/core-prereqs-redis.adoc b/modules/core-prereqs-redis.adoc index 0e306e500..b6c1d3810 100644 --- a/modules/core-prereqs-redis.adoc +++ b/modules/core-prereqs-redis.adoc @@ -1,6 +1,6 @@ [[core-prereqs-redis]] = Redis -Quay stores builder logs inside a Redis cache. The data stored is ephemeral in nature and as such, Redis does not need to be HA even though it is stateful. if Redis does fail, you will only lose access to build logs. +{productname} stores builder logs inside a Redis cache. The data stored is ephemeral in nature and as such, Redis does not need to be HA even though it is stateful. If Redis does fail, you will only lose access to build logs. You can use a Redis image from the Red Hat Software Collections or from any other source you prefer. diff --git a/modules/core-prereqs-storage.adoc b/modules/core-prereqs-storage.adoc index 0f49ec60d..cb58888b1 100644 --- a/modules/core-prereqs-storage.adoc +++ b/modules/core-prereqs-storage.adoc @@ -5,20 +5,19 @@ {productname} Quay stores all binary blobs in its storage backend. The following conditions apply to image storage: -* Local storage and NFS should only be used for PoC / test setups -* Quay HA requires an HA storage setup -* Geo-replication requires object storage and does not work with local storage +* Local storage and NFS should only be used for proof of concept or test setups. +* Quay HA requires an HA storage setup. +* Geo-replication requires object storage and does not work with local storage. -== Supported on-premise storage types +== Supported on-prem storage types -{productname} Quay supports the following on-premise storage types: +{productname} Quay supports the following on-prem storage types: * Ceph Rados RGW * OpenStack Swift * RHODF 4 (via NooBaa) -// TODO 36 Is RHOCS 3 supported? -// * RHOCS 3 (via NooBaa) + == Supported public cloud storage types diff --git a/modules/core-prereqs.adoc b/modules/core-prereqs.adoc deleted file mode 100644 index 8349fa758..000000000 --- a/modules/core-prereqs.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[[core-prereqs]] -= Quay prerequisites - -Before deploying Quay, you will need to provision the following: - -* xref:core-prereqs-storage[Image storage] -* xref:core-prereqs-db[Database] -* xref:core-prereqs-redis[Redis] - - diff --git a/modules/core-sample-quay-on-prem.adoc b/modules/core-sample-quay-on-prem.adoc index 6ae69e54b..456acb09a 100644 --- a/modules/core-sample-quay-on-prem.adoc +++ b/modules/core-sample-quay-on-prem.adoc @@ -1,5 +1,5 @@ [[sample-quay-on-prem-intro]] -= Sample {productname} on-premise configuration += Deploying {productname} on-prem The following image shows examples for on-premise configuration, including: diff --git a/modules/fine-grained-access-control-intro.adoc b/modules/fine-grained-access-control-intro.adoc index 7645b0e0a..cd824d84e 100644 --- a/modules/fine-grained-access-control-intro.adoc +++ b/modules/fine-grained-access-control-intro.adoc @@ -1,11 +1,11 @@ [[fine-grained-access-control]] -= Fine Grained Access Control += Fine-grained access control {productname} allow users to integrate their existing identity infrastructure and use a fine-grained permissions system to map their organizational structure and grant access to whole teams to manage specific repositories. {productname} is supported by the following authentication providers: -* Built-in Database Authentication +* Built-in database authentication * Lightweight Directory Access Protocol (LDAP) authentication and _sync * External OpenID Connect (OIDC) provider * OpenStack Keystone diff --git a/modules/georepl-arch-operator.adoc b/modules/georepl-arch-operator.adoc index 378f24eff..91336bafe 100644 --- a/modules/georepl-arch-operator.adoc +++ b/modules/georepl-arch-operator.adoc @@ -1,10 +1,8 @@ [[georepl-arch-operator]] -= Geo-replication - Quay Operator - -== Geo-replication architecture - Quay Operator += Geo-replication using the {productname} Operator image:178_Quay_architecture_0821_georeplication_openshift-temp.png[Georeplication architecture] -In the example shown above, Quay Operator is deployed in two separate regions, with a common database and a common Redis instance. Localized image storage is provided in each region and image pulls are served from the closest available storage engine. Container image pushes are written to the preferred storage engine for the Quay instance, and will then be replicated, in the background, to the other storage engines. +In the example shown above, the {productname} Operator is deployed in two separate regions, with a common database and a common Redis instance. Localized image storage is provided in each region and image pulls are served from the closest available storage engine. Container image pushes are written to the preferred storage engine for the Quay instance, and will then be replicated, in the background, to the other storage engines. Because the Operator now manages the Clair security scanner and its database separately, geo-replication setups can be leveraged so that they do not manage the Clair database. Instead, an external shared database would be used. {productname} and Clair support several providers and vendors of PostgreSQL, which can be found in the Quay Enterprise 3.x link:https://access.redhat.com/articles/4067991[test matrix]. Additionally, the Operator also supports custom Clair configurations that can be injected into the deployment, which allows users to configure Clair with the connection credentials for the external database. diff --git a/modules/georepl-arch-standalone.adoc b/modules/georepl-arch-standalone.adoc index b03b00d99..b7a542ff9 100644 --- a/modules/georepl-arch-standalone.adoc +++ b/modules/georepl-arch-standalone.adoc @@ -1,7 +1,5 @@ [[georepl-arch-standalone]] -= Geo-replication - standalone Quay - -== Geo-replication architecture - standalone Quay += Geo-replication using standalone {productname} image:178_Quay_architecture_0821_georeplication.png[Georeplication] diff --git a/modules/georepl-arch.adoc b/modules/georepl-arch.adoc new file mode 100644 index 000000000..f8e24c53c --- /dev/null +++ b/modules/georepl-arch.adoc @@ -0,0 +1,6 @@ +[[georepl-arch]] += Geo-replication architecture for standalone {productname} + +image:178_Quay_architecture_0821_georeplication.png[Georeplication] + +In the example shown above, {productname} is running in two separate regions, with a common database and a common Redis instance. Localized image storage is provided in each region and image pulls are served from the closest available storage engine. Container image pushes are written to the preferred storage engine for the Quay instance, and will then be replicated, in the background, to the other storage engines. diff --git a/modules/georepl-intro.adoc b/modules/georepl-intro.adoc index 202dcbe71..73f662c29 100644 --- a/modules/georepl-intro.adoc +++ b/modules/georepl-intro.adoc @@ -1,13 +1,13 @@ [[georepl-intro]] = Geo-replication -Geo-replication allows multiple, geographically distributed Quay deployments to work as a single registry from the perspective of a client or user. It significantly improves push and pull performance in a globally-distributed Quay setup. Image data is asynchronously replicated in the background with transparent failover / redirect for clients. +Geo-replication allows multiple, geographically distributed {productname} deployments to work as a single registry from the perspective of a client or user. It significantly improves push and pull performance in a globally-distributed {productname} setup. Image data is asynchronously replicated in the background with transparent failover / redirect for clients. With {productname} 3.7, deployments of {productname} with geo-replication is supported by standalone and Operator deployments. == Geo-replication features -* When geo-replication is configured, container image pushes will be written to the preferred storage engine for that Red Hat Quay instance (typically the nearest storage backend within the region). +* When geo-replication is configured, container image pushes will be written to the preferred storage engine for that {productname} instance (typically the nearest storage backend within the region). * After the initial push, image data will be replicated in the background to other storage engines. * The list of replication locations is configurable and those can be different storage backends. * An image pull will always use the closest available storage engine, to maximize pull performance. diff --git a/modules/georepl-mixed-storage.adoc b/modules/georepl-mixed-storage.adoc index b6e35b039..9c87dfc13 100644 --- a/modules/georepl-mixed-storage.adoc +++ b/modules/georepl-mixed-storage.adoc @@ -1,12 +1,12 @@ [[georepl-mixed-storage]] = Mixed storage for geo-replication -Quay geo-replication supports the use of different, and multiple, replication targets for example, using AWS S3 storage on public cloud and using Ceph storage on-prem. -This complicates the key requirement of granting access to all storage backends from all Quay pods and cluster nodes. As a result, it is recommended that you: +{productname} geo-replication supports the use of different and multiple replication targets, for example, using AWS S3 storage on public cloud and using Ceph storage on-prem. +This complicates the key requirement of granting access to all storage backends from all {productname} pods and cluster nodes. As a result, it is recommended that you: * Use a VPN to prevent visibility of the internal storage _or_ * Use a token pair that only allows access to the specified bucket used by Quay -This will result in the public cloud instance of Quay having access to on-prem storage but the network will be encrypted, protected, and will use ACLs, thereby meeting security requirements. +This will result in the public cloud instance of {productname} having access to on-prem storage but the network will be encrypted, protected, and will use ACLs, thereby meeting security requirements. -If you cannot implement these security measures, it may be preferable to deploy two distinct Quay registries and to use repository mirroring as an alternative to geo-replication. +If you cannot implement these security measures, it may be preferable to deploy two distinct {productname} registries and to use repository mirroring as an alternative to geo-replication. diff --git a/modules/mirroring-api-intro.adoc b/modules/mirroring-api-intro.adoc index 453319df8..063d2bd87 100644 --- a/modules/mirroring-api-intro.adoc +++ b/modules/mirroring-api-intro.adoc @@ -1,7 +1,7 @@ [[mirroring-api-intro]] = Mirroring API -You can use the Quay API to configure repository mirroring: +You can use the {productname} API to configure repository mirroring: image:swagger-mirroring.png[Mirroring API] diff --git a/modules/mirroring-intro.adoc b/modules/mirroring-intro.adoc index c95e61bc7..8c9b1ff26 100644 --- a/modules/mirroring-intro.adoc +++ b/modules/mirroring-intro.adoc @@ -16,9 +16,9 @@ From your {productname} cluster with repository mirroring enabled, you can: To use the mirroring functionality, you need to: -* Enable Repository Mirroring in the {productname} configuration +* Enable repository mirroring in the {productname} configuration * Run a repository mirroring worker * Create mirrored repositories -All repository mirroring configuration can be performed using the configuration tool UI or via the Quay API +All repository mirroring configuration can be performed using the configuration tool UI or via the {productname} API diff --git a/modules/mirroring-recommend.adoc b/modules/mirroring-recommend.adoc index 13bf07013..b9b117e69 100644 --- a/modules/mirroring-recommend.adoc +++ b/modules/mirroring-recommend.adoc @@ -1,11 +1,13 @@ [[mirroring-recommend]] = Repository mirroring recommendations -* Repository mirroring pods can run on any node including other nodes where Quay is already running -* Repository mirroring is scheduled in the database and run in batches. As a result, more workers could mean faster mirroring, since more batches will be processed. +Best practices for repository mirroring include: + +* Repository mirroring pods can run on any node. This means you can even run mirroring on nodes where {productname} is already running. +* Repository mirroring is scheduled in the database and runs in batches. As a result, more workers should mean faster mirroring, since more batches will be processed. * The optimal number of mirroring pods depends on: ** The total number of repositories to be mirrored ** The number of images and tags in the repositories and the frequency of changes ** Parallel batches * You should balance your mirroring schedule across all mirrored repositories, so that they do not all start up at the same time. -* For a mid-size deployment, with approximately 1000 users and 1000 repositories, and with roughly 100 mirrored repositories, it is expected that you would use 3-5 mirroring pods, scaling up to 10 if required. +* For a mid-size deployment, with approximately 1000 users and 1000 repositories, and with roughly 100 mirrored repositories, it is expected that you would use 3-5 mirroring pods, scaling up to 10 pods if required. diff --git a/modules/mirroring-using.adoc b/modules/mirroring-using.adoc index 1653421e9..c341103ab 100644 --- a/modules/mirroring-using.adoc +++ b/modules/mirroring-using.adoc @@ -11,16 +11,16 @@ regular expressions. * Once a repository is set as mirrored, you cannot manually add other images to that repository. * Because the mirrored repository is based on the repository and tags you set, -it will hold only the content represented by the repo/tag pair. In other words, if you change +it will hold only the content represented by the repo / tag pair. In other words, if you change the tag so that some images in the repository no longer match, those images will be deleted. * Only the designated robot can push images to a mirrored repository, superseding any role-based access control permissions set on the repository. * With a mirrored repository, a user can pull images (given read permission) -from the repository but not push images to the repository. +from the repository but can not push images to the repository. -* Changing settings on your mirrored repository is done from the Mirrors tab -on the Repositories page for the mirrored repository you create. +* Changing settings on your mirrored repository can be performed in the {productname} UI, using the Repositories -> Mirrors tab +for the mirrored repository you create. * Images are synced at set intervals, but can also be synced on demand. \ No newline at end of file diff --git a/modules/mirroring-versus-georepl.adoc b/modules/mirroring-versus-georepl.adoc index 631c1edda..b86838451 100644 --- a/modules/mirroring-versus-georepl.adoc +++ b/modules/mirroring-versus-georepl.adoc @@ -1,15 +1,15 @@ [[mirroring-versus-georepl]] = Repository mirroring versus geo-replication -Quay geo-replication mirrors the entire image storage backend data between 2 or more different storage backends while the database is shared (one Quay registry with two different blob storage endpoints). The primary use cases for geo-replication are: +{productname} geo-replication mirrors the entire image storage backend data between 2 or more different storage backends while the database is shared (one {productname} registry with two different blob storage endpoints). The primary use cases for geo-replication are: * Speeding up access to the binary blobs for geographically dispersed setups * Guaranteeing that the image content is the same across regions -Repository mirroring synchronizes selected repositories (or subsets of repositories) from one registry to another. The registries are distinct, with registry is separate database and image storage. The primary use cases for mirroring are: +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 are: * Independent registry deployments in different datacenters or regions, where a certain subset of the overall content is supposed to be shared across the datacenters / regions -* Automatic synchronization or mirroring of selected (whitelisted) upstream repositories from external registries into a local Quay deployment +* Automatic synchronization or mirroring of selected (whitelisted) upstream repositories from external registries into a local {productname} deployment [NOTE] ==== @@ -26,6 +26,7 @@ Repository mirroring and geo-replication can be used simultaneously. | Is access to all storage backends in both regions required? | Yes (all {productname} nodes) | No (distinct storage) | Can users push images from both sites to the same repository? | Yes | No | Is all registry content and configuration identical across all regions (shared database) | Yes | No -| Can users select individual namespaces or repositories to be mirrored? | No,by default | Yes +| Can users select individual namespaces or repositories to be mirrored? | No | Yes | Can users apply filters to synchronization rules? | No | Yes +| Are individual / different RBAC configurations allowed in each region | No | Yes |=== diff --git a/modules/public-cloud-azure.adoc b/modules/public-cloud-azure.adoc index 5380f1c7b..03fd6c71a 100644 --- a/modules/public-cloud-azure.adoc +++ b/modules/public-cloud-azure.adoc @@ -1,8 +1,8 @@ -= Running Red Hat Quay on Microsoft Azure += Running {porductname} on Microsoft Azure image:178_Quay_architecture_0821_on_Azure.png[Red Hat Quay on Microsoft Azure] -If Quay is running on Microsoft Azure, you can use: +If {porductname} is running on Microsoft Azure, you can use: * Azure managed services such as HA PostgreSQL * Azure Blob Storage must be hot storage (not Azure Cool Blob Storage) diff --git a/modules/public-cloud-intro.adoc b/modules/public-cloud-intro.adoc index fb20bca19..00ea09a18 100644 --- a/modules/public-cloud-intro.adoc +++ b/modules/public-cloud-intro.adoc @@ -1,9 +1,7 @@ -= Quay on public cloud += Deploying {productname} on public cloud -Quay can run on public clouds, either in standalone mode or where OpenShift itself has been deployed on public cloud. +{productname} can run on public clouds, either in standalone mode or where OpenShift itself has been deployed on public cloud. A full list of tested and supported configurations can be found in the {productname} Tested Integrations Matrix at link:https://access.redhat.com/articles/4067991[]. -Recommendation: If Quay is running on public cloud, then you should use the public cloud services for Quay backend services to ensure proper HA and scalability - -A full list of tested and supported configurations can be found in the Red Hat Quay Tested Integrations Matrix at link:https://access.redhat.com/articles/4067991[] +**Recommendation:** If {productname} is running on public cloud, then you should use the public cloud services for {productname} backend services to ensure proper HA and scalability. diff --git a/modules/quay-super-users-intro.adoc b/modules/quay-super-users-intro.adoc index 5683a4055..cfd64f779 100644 --- a/modules/quay-super-users-intro.adoc +++ b/modules/quay-super-users-intro.adoc @@ -1,5 +1,5 @@ [[quay-super-users]] -= {productname} Super users += {productname} super users `Super users` are a group of {productname} users with enhanced access and privileges, including: diff --git a/modules/role-based-access-control-intro.adoc b/modules/role-based-access-control-intro.adoc index 478d81615..ae41696e2 100644 --- a/modules/role-based-access-control-intro.adoc +++ b/modules/role-based-access-control-intro.adoc @@ -1,5 +1,5 @@ [[role-based-access-control]] -= Role Based Access Control (RBAC) += Role-based access control (RBAC) {productname} offers three types of permissions: diff --git a/modules/security-intro.adoc b/modules/security-intro.adoc index 1644855bc..ad40c3830 100644 --- a/modules/security-intro.adoc +++ b/modules/security-intro.adoc @@ -1,5 +1,5 @@ [[security-intro]] -= Security Overview += {productname} security overview {productname} is built for real enterprise use cases where content governance and security are two major focus areas. {productname} content governance and security includes a built-in vulnerability scanning via Clair. diff --git a/modules/sizing-intro.adoc b/modules/sizing-intro.adoc index f9c5cb9bb..710dc8928 100644 --- a/modules/sizing-intro.adoc +++ b/modules/sizing-intro.adoc @@ -1,5 +1,5 @@ [[sizing-intro]] -= Sizing and subscriptions += {productname} sizing and subscriptions Scalability of {productname} is one of its key strengths, with a single code base supporting a broad spectrum of deployment sizes, including: diff --git a/modules/sizing-sample.adoc b/modules/sizing-sample.adoc index ce54f786a..32bc320f6 100644 --- a/modules/sizing-sample.adoc +++ b/modules/sizing-sample.adoc @@ -1,5 +1,5 @@ [[sizing-sample]] -= {productname} Sample Sizings += {productname} sample sizings The following table shows typical sizing for three deployment sizes: proof of concept, mid-size, and high-end. Whether a deployment runs appropriately with the same metrics will depend on many other factors not shown below. @@ -46,7 +46,7 @@ Clair: + For further details on sizing & related recommendations for mirroring, see the section on xref:mirroring-intro[repository mirroring]. -The sizing for the Redis cache is only relevant if you use Quay builders. otherwise it is not significant. +The sizing for the Redis cache is only relevant if you use Quay builders, otherwise it is not significant.