Adds Operator configuration information (quay#1342)

stevsmit · Steven Smith · web-flow · commit a5db254ce4ff · 2025-05-19T11:21:15.000-04:00
Co-authored-by: Steven Smith &lt;stevsmit@stevsmit-thinkpadt14gen4.remote.csb&gt;
diff --git a/config_quay/master.adoc b/config_quay/master.adoc
@@ -9,11 +9,22 @@ include::modules/config-intro.adoc[leveloffset=+1]
 include::modules/config-disclaimer.adoc[leveloffset=+1]
 include::modules/understanding-configuration-file.adoc[leveloffset=+1]
 
+//onprem
 include::modules/on-prem-configuration-overview.adoc[leveloffset=+1]
 include::modules/config-file-minimal.adoc[leveloffset=+2]
 include::modules/modifying-config-file-post-deployment.adoc[leveloffset=+2]
 include::modules/config-file-verification.adoc[leveloffset=+2]
 
+//operator - cross compare with quay operator docs
+include::modules/operator-components-intro.adoc[leveloffset=+1]
+include::modules/understanding-quayregistry-cr.adoc[leveloffset=+2]
+include::modules/operator-components-managed.adoc[leveloffset=+2]
+include::modules/modifying-quayregistry-cr-after-deployment.adoc[leveloffset=+2]
+include::modules/modifying-quayregistry-cr-ui.adoc[leveloffset=+3]
+include::modules/modifying-quayregistry-cr-cli.adoc[leveloffset=+3]
+include::modules/operator-config-bundle-secret.adoc[leveloffset=+3]
+include::modules/modifying-config-bundle-secret-ui.adoc[leveloffset=+4]
+include::modules/operator-config-cli-download.adoc[leveloffset=+4]
 
 include::modules/config-updates-314.adoc[leveloffset=+2]
 //include::modules/config-updates-313.adoc[leveloffset=+2]
diff --git a/modules/modifying-config-bundle-secret-ui.adoc b/modules/modifying-config-bundle-secret-ui.adoc
@@ -0,0 +1,55 @@
+:_content-type: CONCEPT
+[id="modifying-configuration-file-ocp"]
+= Modifying the configuration file by using the {ocp} web console
+
+Use the following procedure to modify the `config.yaml` file that is stored by the `configBundleSecret` by using the {ocp} web console.
+
+.Prerequisites
+
+* You are logged in to the {ocp} cluster as a user with admin privileges. 
+
+.Procedure
+
+. On the {ocp} web console, click *Operators* -> *Installed Operators* -> *Red Hat Quay*. 
+
+. Click *Quay Registry*.
+
+. Click the name of your {productname} registry, for example, *example-registry*.
+
+. On the *QuayRegistry details* page, click the name of your *Config Bundle Secret*, for example, *example-registry-config-bundle*. 
+
+. Click *Actions* -> *Edit Secret*.
+
+. In the *Value* box, add the desired key/value pair. For example, to add a superuser to your {productname-ocp} deployment, add the following reference:
++
+[source,yaml]
+----
+SUPER_USERS:
+- quayadmin
+----
+
+. Click *Save*.
+
+.Verification
+
+. Verify that the changes have been accepted:
+
+.. On the {ocp} web console, click *Operators* -> *Installed Operators* -> *Red Hat Quay*. 
+
+.. Click *Quay Registry*.
+
+.. Click the name of your {productname} registry, for example, *example-registry*.
+
+.. Click *Events*. If successful, the following message is displayed:
++
+[source,text]
+----
+All objects created/updated successfully
+----
+
+
+[NOTE]
+You must base64 encode any updated config.yaml before placing it in the Secret. Ensure the Secret name matches the value specified in spec.configBundleSecret.
+Once the Secret is updated, the Operator detects the change and automatically rolls out updates to the Red Hat Quay pods.
+
+For detailed steps, see "Updating configuration secrets through the {productname} UI."
diff --git a/modules/modifying-quayregistry-cr-after-deployment.adoc b/modules/modifying-quayregistry-cr-after-deployment.adoc
@@ -0,0 +1,17 @@
+:_content-type: CONCEPT
+[id="modifying-quayregistry-cr-after-deployment"]
+= Modifying the QuayRegistry CR after deployment
+
+After you have installed the {productname} Operator and created an initial deployment, you can modify the `QuayRegistry` custom resource (CR) to customize or reconfigure aspects of the Red Hat Quay environment.
+
+{productname} administrators might modify the QuayRegistry CR for the following reasons:
+
+* *To change component management*: Switch components from `managed: true` to `managed: false` in order to bring your own infrastructure. For example, you might set `kind: objectstorage` to unmanaged to integrate external object storage platforms such as Google Cloud Storage or Nutanix.
+
+* *To apply custom configuration*: Update or replace the `configBundleSecret` to apply new configuration settings, for example, authentication providers, external SSL/TLS settings, feature flags.
+
+* *To enable or disable features*: Toggle features like repository mirroring, Clair scanning, or horizontal pod autoscaling by modifying the `spec.components` list.
+
+* *To scale the deployment*: Adjust environment variables or replica counts for the Quay application.
+
+* *To integrate with external services*: Provide configuration for external PostgreSQL, Redis, or Clair databases, and update endpoints or credentials.
diff --git a/modules/modifying-quayregistry-cr-cli.adoc b/modules/modifying-quayregistry-cr-cli.adoc
@@ -0,0 +1,27 @@
+:_content-type: CONCEPT
+[id="modifying-quayregistry-cr-cli"]
+= Modifying QuayRegistry components CR by using the CLI
+
+The `QuayRegistry` CR can be modified by using the CLI.
+
+.Prerequisites
+
+* You are logged in to your {ocp} cluster as a user with admin privileges. 
+
+.Procedure
+
+. Edit the `QuayRegistry` CR by entering the following command:
++
+[source,terminal]
+----
+$ oc edit quayregistry <registry_name> -n <namespace>
+----
+
+. Make the desired changes to the `QuayRegistry` CR.
++
+[NOTE]
+====
+Setting a component to unmanaged (`managed: false`) might require additional configuration. For more information about setting unmanaged components in the `QuayRegistry` CR, see link:https://docs.redhat.com/en/documentation/red_hat_quay/{producty}/html-single/deploying_the_red_hat_quay_operator_on_openshift_container_platform/index#operator-components-unmanaged[Using unmanaged components for dependencies].
+====
+
+. Save the changes.
diff --git a/modules/modifying-quayregistry-cr-ui.adoc b/modules/modifying-quayregistry-cr-ui.adoc
@@ -0,0 +1,31 @@
+:_content-type: CONCEPT
+[id="modifying-quayregistry-cr-ocp-console"]
+= Modifying QuayRegistry CR components by using the {ocp} web console
+
+The `QuayRegistry` can be modified by using the {ocp} web console.
+
+.Prerequisites
+
+* You are logged into {ocp} as a user with admin privileges. 
+* You have installed the {productname} Operator.
+
+.Procedure
+
+. On the {ocp} web console, click *Operators* -> *Installed Operators*.
+
+. Click *Red Hat Quay*.
+
+. Click *Quay Registry*.
+
+. Click the name of your {productname} registry, for example, *example-registry*.
+
+. Click *YAML*.
+
+. Adjust the `managed` field of the desired component to either `true` or `false`.
+
+. Click *Save*.
++
+[NOTE]
+====
+Setting a component to unmanaged (`managed: false`) might require additional configuration. For more information about setting unmanaged components in the `QuayRegistry` CR, see link:https://docs.redhat.com/en/documentation/red_hat_quay/{producty}/html-single/deploying_the_red_hat_quay_operator_on_openshift_container_platform/index#operator-components-unmanaged[Using unmanaged components for dependencies].
+====
diff --git a/modules/operator-components-intro.adoc b/modules/operator-components-intro.adoc
@@ -1,45 +1,11 @@
 :_content-type: CONCEPT
 [id="operator-components-intro"]
-= {productname} Operator components
+= {productname} Operator configuration overview
 
-{productname} has many dependencies. These dependencies include a database, object storage, Redis, and others. The {productname} Operator manages an opinionated deployment of {productname} and its dependencies on Kubernetes. These dependencies are treated as _components_ and are configured through the `QuayRegistry` API.
+When deploying {productname} using the Operator on {ocp}, configuration is managed declaratively through the `QuayRegistry` custom resource (CR). This model allows cluster administrators to define the desired state of the {productname} deployment, including which components are enabled, storage backends, SSL/TLS configuration, and other core features.
 
-In the `QuayRegistry` custom resource, the `spec.components` field configures components. Each component contains two fields: `kind` (the name of the component), and `managed` (a boolean that addresses whether the component lifecycle is handled by the {productname} Operator). 
+After deploying {productname-ocp} with the Operator, administrators can further customize their registry by updating the `config.yaml` file and referencing it in a Kubernetes secret. This configuration bundle is linked to the `QuayRegistry` CR through the `configBundleSecret` field.
 
-By default, all components are managed and auto-filled upon reconciliation for visibility:
-
-.Example `QuayRegistry` resource
-[source,yaml]
-----
-apiVersion: quay.redhat.com/v1
-kind: QuayRegistry
-metadata:
-  name: example-registry
-  namespace: quay-enterprise
-  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: true
-----
+The Operator reconciles the state defined in the `QuayRegistry` CR and its associated configuration, automatically deploying or updating registry components as needed.
 
+This guide covers the basic concepts behind the `QuayRegistry` CR and modifying your `config.yaml` file on {productname-ocp} deployments. More advanced topics, such as using unmanaged components within the `QuayRegistry` CR, can be found in link:https://docs.redhat.com/en/documentation/red_hat_quay/3/html-single/deploying_the_red_hat_quay_operator_on_openshift_container_platform/index[Deploying {productname} Operator on {ocp}].
diff --git a/modules/operator-components-managed.adoc b/modules/operator-components-managed.adoc
@@ -1,39 +1,63 @@
 :_content-type: REFERENCE
 [id="operator-components-managed"]
-= Using managed components
-
-Unless your `QuayRegistry` custom resource specifies otherwise, the {productname} Operator uses defaults for the following managed components:
-
-* **quay:** Holds overrides for deployment of {productname-ocp}, for example, environment variables and number of replicas. This component is new as of {productname} 3.7 and cannot be set to unmanaged.
-
-* **postgres:**  For storing the registry metadata,
-ifeval::["{productname}" == "Red Hat Quay"]
-As of {productname} 3.9, uses a version of PostgreSQL 13 from link:https://www.softwarecollections.org/en/[Software Collections].
-+
-[NOTE]
-====
-When upgrading from {productname} 3.8 -> 3.9, the Operator automatically handles upgrading PostgreSQL 10 to PostgreSQL 13. This upgrade is required. PostgreSQL 10 had its final release on November 10, 2022 and is no longer supported.
-====
-endif::[]
-ifeval::["{productname}" == "Project Quay"]
-As of {productname} 3.9, uses an upstream (CentOS) version of PostgreSQL 13. 
-endif::[]
-* **clair:**  Provides image vulnerability scanning.
-
-* **redis:**  Stores live builder logs and the {productname} tutorial. Also includes the locking mechanism that is required for garbage collection.
-
-* **horizontalpodautoscaler:**  Adjusts the number of `Quay` pods depending on memory/cpu consumption.
-
-* **objectstorage:**  For storing image layer blobs,  utilizes the `ObjectBucketClaim` Kubernetes API which is provided by Noobaa or {odf}.
-
-* **route:**  Provides an external entrypoint to the {productname} registry from outside of {ocp}.
-
-* **mirror:**  Configures repository mirror workers to support optional repository mirroring.
-
-* **monitoring:** Features include a Grafana dashboard, access to individual metrics, and notifications for frequently restarting `Quay` pods.
-
-* **tls:** Configures whether {productname} or {ocp} handles SSL/TLS.
-
-* **clairpostgres:** Configures a managed Clair database. This is a separate database than the PostgreSQL database used to deploy {productname}. 
-
-The {productname} Operator handles any required configuration and installation work needed for {productname} to use the managed components. If the opinionated deployment performed by the {productname} Operator is unsuitable for your environment, you can provide the {productname} Operator with `unmanaged` resources, or overrides, as described in the following sections.
+= Managed components
+
+By default, the Operator handles all required configuration and installation needed for {productname}'s managed components. 
+
+If the opinionated deployment performed by the {productname} Operator is unsuitable for your environment, you can provide the {productname} Operator with `unmanaged` resources, or overrides, as described in link:https://docs.redhat.com/en/documentation/red_hat_quay/{producty}/html-single/deploying_the_red_hat_quay_operator_on_openshift_container_platform/index#operator-components-managed[Using unmanaged components].
+
+.QuayRegistry required fields
+[cols="2a,1a,2a",options="header"]
+|===
+| Field | Type | Description
+
+|`quay` |Boolean | Holds overrides for deployment of {productname-ocp}, such as environment variables and number of replicas. This component cannot be set to unmanaged (`managed: false`).
+|`postgres` |Boolean | Used for storing registry metadata. Currently, PostgreSQL version 13 is used.
+|`clair` |Boolean | Provides image vulnerability scanning. 
+|`redis` |Boolean | Storage live builder logs and the locking mechanism that is required for garbage collection.
+|`horizontalpodautoscaler` |Boolean | Adjusts the number of `quay` pods depending on your memory and CPU consumption.
+|`objectstorage` |Boolean | Stores image layer blobs. When set to `managed: true`, utilizes the `ObjectBucketClaim` Kubernetes API which is provided by NooBaa or {odf}. Setting this field to `managed: false` requires you to provide your own object storage.
+|`route` |Boolean | Provides an external entrypoint to the {productname} registry from outside of {ocp}.
+|`mirror` |Boolean | Configures repository mirror workers to support optional repository mirroring.
+|`monitoring` |Boolean | Features include a Grafana dashboard, access to individual metrics, and notifications for frequently restarting `quay` pods.
+|`tls` |Boolean | Configures whether SSL/TLS is automatically handled.
+|`clairpostgres` |Boolean | Configures a managed Clair database. This is a separate database than the PostgreSQL database that is used to deploy {productname}. 
+
+|===
+
+The following example shows you the default configuration for the `QuayRegistry` custom resource provided by the {productname} Operator. It is available on the {ocp} web console.
+
+.Example `QuayRegistry` custom resource
+[source,yaml]
+----
+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: true
+----
diff --git a/modules/operator-config-bundle-secret.adoc b/modules/operator-config-bundle-secret.adoc
@@ -1,7 +1,21 @@
 :_content-type: REFERENCE
 [id="operator-config-bundle-secret"]
-= Config bundle secret
+= Understanding the configBundleSecret
 
-The `spec.configBundleSecret` field is a reference to the `metadata.name` of a `Secret` in the same namespace as the `QuayRegistry` resource. This `Secret` must contain a `config.yaml` key/value pair. 
+The `spec.configBundleSecret` field is an optional reference to the name of a Secret in the same namespace as the `QuayRegistry` resource. This Secret must contain a `config.yaml` key/value pair, where the value is a {productname} configuration file.
 
-The `config.yaml` file is a {productname} `config.yaml` file. This field is optional, and is auto-filled by the {productname} Operator if not provided. If provided, it serves as the base set of config fields which are later merged with other fields from any managed components to form a final output `Secret`, which is then mounted into the {productname} application pods.
+The `configBundleSecret` stores the `config.yaml` file, which defines configuration settings for {productname}, such as:
+
+* Authentication backends (for example, OIDC, LDAP)
+* External TLS termination settings
+* Repository creation policies
+* Feature flags
+* Notification settings
+
+{productname} administrators might update this secret to:
+
+* Enable a new authentication method
+* Add custom SSL/TLS certificates
+* Modify security scanning settings
+
+If this field is omitted, the {productname} 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.
diff --git a/modules/operator-config-cli-download.adoc b/modules/operator-config-cli-download.adoc
diff --git a/modules/understanding-quayregistry-cr.adoc b/modules/understanding-quayregistry-cr.adoc
