📖 Document how to configure global pull secrets

Closes operator-framework#1409

docs/howto/configure-global-pull-secrets.md

@@ -0,0 +1,51 @@
+---
+tags:
+  - alpha
+---
+
+# Configure global pull secrets for allowing components to pull private images
+
+To configure `catalogd` and `operator-controller` to use authentication information for pulling private images (catalog/bundle images etc), the components can be informed about a kubernetes `Secret` object that contains the relevant auth information. The `Secret` must be of type `kubernetes.io/dockerconfigjson`. 
+
+Once the `Secret` is created, `catalogd` and `operator-controller` needs to be redeployed with an additional field, `--global-pull-secret=<secret-namespace>/<secret-name>` passed to the respective binaries.
+
+For eg, create a `Secret` using locally available `config.json`: 
+
+```sh
+$ kubectl create secret docker-registry test-secret \
+  --from-file=.dockerconfigjson=$HOME/.docker/config.json \
+  --namespace olmv1-system
+secret/test-secret created
+```
+
+Verify that the Secret is created: 
+
+```sh
+$ kubectl get secret test-secret -n olmv1-system -o yaml 
+apiVersion: v1
+data:
+  .dockerconfigjson: ewogICJh....
+kind: Secret
+metadata:
+  creationTimestamp: "2024-10-25T12:05:46Z"
+  name: test-secret
+  namespace: olmv1-system
+  resourceVersion: "237734"
+  uid: 880138f1-5d98-4bb0-9e45-45e8ebaff647
+type: kubernetes.io/dockerconfigjson
+```
+
+Modify the `config/base/manager/manager.yaml` file for `catalogd` and `operator-controller` to include the new field in the binary args: 
+
+```yaml
+ - command:
+        - ./manager
+        args:
+        - ...
+        - ...
+        - ...
+        - --global-pull-secret=olmv1-system/test-secret
+```
+
+With the above configuration, creating a `ClusterCatalog` or a `ClusterExention` whose content is packaged in a private container image hosted in an image registry, will become possible.
+

docs/tutorials/install-extension.md

@@ -14,6 +14,8 @@ After you add a catalog to your cluster, you can install an extension by creatin
 * The name, and optionally version, or channel, of the [supported extension](../project/olmv1_limitations.md) to be installed
 * An existing namespace in which to install the extension
 
+**Note** To install ClusterExentions that are shipped as private container images hosted in an image registry, please see [How to conifgure global pull secrets](../howto/configure-global-pull-secrets.md).
+
 ### ServiceAccount for ClusterExtension Installation and Management
 
 Adhering to OLM v1's "Secure by Default" tenet, OLM v1 does not have the permissions

mkdocs.yml

@@ -36,6 +36,7 @@ nav:
     - Uninstall an Extension: tutorials/uninstall-extension.md
   - How-To Guides:
     - Catalog queries: howto/catalog-queries.md
+    - Configure Global pull secrets: howto/configure-global-pull-secrets.md
     - Channel-Based Upgrades: howto/how-to-channel-based-upgrades.md
     - Version Pinning: howto/how-to-pin-version.md
     - Version Range Upgrades: howto/how-to-version-range-upgrades.md