OSDOCS-8880: OLM 1.0 Adding a catalog to a cluster

michaelryanpeter · michaelryanpeter · commit 53e98bc81074 · 2024-01-11T10:10:46.000-05:00
- Add docs for creating a namespace-scoped pull secret for catalogd
diff --git a/modules/olmv1-adding-a-catalog.adoc b/modules/olmv1-adding-a-catalog.adoc
@@ -9,6 +9,15 @@
 
 To add a catalog to a cluster, create a catalog custom resource (CR) and apply it to the cluster.
 
+.Prerequisites
+
+// https://docs.asciidoctor.org/asciidoc/latest/directives/include-list-item-content/
+* {empty}
++
+--
+include::snippets/olmv1-secure-registry-pull-secret.adoc[]
+--
+
 .Procedure
 
 . Create a catalog custom resource (CR), similar to the following example:
@@ -25,8 +34,10 @@ spec:
     type: image
     image:
       ref: registry.redhat.io/redhat/redhat-operator-index:v{product-version} <1>
+      pullSecret: <pull_secret_name> <2>
 ----
 <1> Specify the catalog's image in the `spec.source.image` field.
+<2> If your catalog is hosted on a secure registry, such as `registry.redhat.io`, you must create a pull secret scoped to the `openshift-catalog` namespace.
 
 . Add the catalog to your cluster by running the following command:
 +
@@ -63,48 +74,50 @@ redhat-operators      20s
 +
 [source,terminal]
 ----
-$ oc get catalogs.catalogd.operatorframework.io -o yaml
+$ oc describe catalog
 ----
 +
 .Example output
 [source,text,subs="attributes+"]
 ----
-apiVersion: v1
-items:
-- apiVersion: catalogd.operatorframework.io/v1alpha1
-  kind: Catalog
-  metadata:
-    annotations:
-      kubectl.kubernetes.io/last-applied-configuration: |
-        {"apiVersion":"catalogd.operatorframework.io/v1alpha1","kind":"Catalog","metadata":{"annotations":{},"name":"redhat-operators"},"spec":{"source":{"image":{"ref":"registry.redhat.io/redhat/redhat-operator-index:v4.14"},"type":"image"}}}
-    creationTimestamp: "2023-10-16T13:30:59Z"
-    generation: 1
-    name: redhat-operators
-    resourceVersion: "37304"
-    uid: cf00c68c-4312-4e06-aa8a-299f0bbf496b
-  spec:
-    source:
-      image:
-        ref: registry.redhat.io/redhat/redhat-operator-index:v{product-version}
-      type: image
-  status: <1>
-    conditions:
-    - lastTransitionTime: "2023-10-16T13:32:25Z"
-      message: successfully unpacked the catalog image "registry.redhat.io/redhat/redhat-operator-index@sha256:bd2f1060253117a627d2f85caa1532ebae1ba63da2a46bdd99e2b2a08035033f" <2>
-      reason: UnpackSuccessful <3>
-      status: "True"
-      type: Unpacked
-    phase: Unpacked <4>
-    resolvedSource:
-      image:
-        ref: registry.redhat.io/redhat/redhat-operator-index@sha256:bd2f1060253117a627d2f85caa1532ebae1ba63da2a46bdd99e2b2a08035033f <5>
-      type: image
-kind: List
-metadata:
-  resourceVersion: ""
+Name:         redhat-operators
+Namespace:
+Labels:       <none>
+Annotations:  <none>
+API Version:  catalogd.operatorframework.io/v1alpha1
+Kind:         Catalog
+Metadata:
+  Creation Timestamp:  2024-01-10T16:18:38Z
+  Finalizers:
+    catalogd.operatorframework.io/delete-server-cache
+  Generation:        1
+  Resource Version:  57057
+  UID:               128db204-49b3-45ee-bfea-a2e6fc8e34ea
+Spec:
+  Source:
+    Image:
+      Pull Secret:  redhat-cred
+      Ref:          registry.redhat.io/redhat/redhat-operator-index:v4.15
+    Type:           image
+Status: <1>
+  Conditions:
+    Last Transition Time:  2024-01-10T16:18:55Z
+    Message:
+    Reason:                UnpackSuccessful <2>
+    Status:                True
+    Type:                  Unpacked
+  Content URL:             http://catalogd-catalogserver.openshift-catalogd.svc/catalogs/redhat-operators/all.json
+  Observed Generation:     1
+  Phase:                   Unpacked <3>
+  Resolved Source:
+    Image:
+      Last Poll Attempt:  2024-01-10T16:18:51Z
+      Ref:                registry.redhat.io/redhat/redhat-operator-index:v4.15
+      Resolved Ref:       registry.redhat.io/redhat/redhat-operator-index@sha256:7b536ae19b8e9f74bb521c4a61e5818e036ac1865a932f2157c6c9a766b2eea5 <4>
+    Type:                 image
+Events:                   <none>
 ----
-<1> Stanza describing the status of the catalog.
-<2> Output message of the status of the catalog.
-<3> Displays the reason the catalog is in the current state.
-<4> Displays the phase of the installion process.
-<5> Displays the image reference of the catalog.
+<1> Describes the status of the catalog.
+<2> Displays the reason the catalog is in the current state.
+<3> Displays the phase of the installation process.
+<4> Displays the image reference of the catalog.
diff --git a/modules/olmv1-creating-a-pull-secret-for-catalogd.adoc b/modules/olmv1-creating-a-pull-secret-for-catalogd.adoc
@@ -0,0 +1,94 @@
+// Module included in the following assemblies:
+//
+// * operators/olm_v1/olmv1-installing-an-operator-from-a-catalog.adoc
+
+ifeval::["{context}" == "olmv1-installing-operator"]
+:olmv1-pullsecret-proc:
+endif::[]
+
+:_mod-docs-content-type: PROCEDURE
+
+[id="olmv1-creating-a-pull-secret-for-catalogs-secure-registry_{context}"]
+= Creating a pull secret for catalogs hosted on a secure registry
+
+include::snippets/olmv1-secure-registry-pull-secret.adoc[]
+
+.Prerequisites
+
+* Login credentials for the secure registry
+* Docker or Podman installed on your workstation
+
+.Procedure
+
+* If you already have a `.dockercfg` file with login credentials for the secure registry, create a pull secret by running the following command:
++
+[source,terminal]
+----
+$ oc create secret generic <pull_secret_name> \
+    --from-file=.dockercfg=<file_path>/.dockercfg \
+    --type=kubernetes.io/dockercfg \
+    --namespace=openshift-catalogd
+----
++
+.Example command
+[%collapsible]
+====
+[source,terminal]
+----
+$ oc create secret generic redhat-cred \
+    --from-file=.dockercfg=/home/<username>/.dockercfg \
+    --type=kubernetes.io/dockercfg \
+    --namespace=openshift-catalogd
+----
+====
+
+* If you already have a `$HOME/.docker/config.json` file with login credentials for the secured registry, create a pull secret by running the following command:
++
+[source,terminal]
+----
+$ oc create secret generic <pull_secret_name> \
+    --from-file=.dockerconfigjson=<file_path>/.docker/config.json \
+    --type=kubernetes.io/dockerconfigjson \
+    --namespace=openshift-catalogd
+----
++
+.Example command
+[%collapsible]
+====
+[source,terminal]
+----
+$ oc create secret generic redhat-cred \
+    --from-file=.dockerconfigjson=/home/<username>/.docker/config.json \
+    --type=kubernetes.io/dockerconfigjson \
+    --namespace=openshift-catalogd
+----
+====
+* If you do not have a Docker configuration file with login credentials for the secure registry, create a pull secret by running the following command:
++
+[source,terminal]
+----
+$ oc create secret docker-registry <pull_secret_name> \
+    --docker-server=<registry_server> \
+    --docker-username=<username> \
+    --docker-password=<password> \
+    --docker-email=<email> \
+    --namespace=openshift-catalogd
+----
++
+.Example command
+[%collapsible]
+====
+[source,terminal]
+----
+$ oc create secret docker-registry redhat-cred \
+    --docker-server=registry.redhat.io \
+    --docker-username=username \
+    --docker-password=password \
+    --docker-email=user@example.com \
+    --namespace=openshift-catalogd
+----
+====
+
+ifeval::["{context}" == "olmv1-installing-operator"]
+:!olmv1-pullsecret-proc:
+endif::[]
diff --git a/modules/olmv1-red-hat-catalogs.adoc b/modules/olmv1-red-hat-catalogs.adoc
@@ -10,6 +10,11 @@
 
 {olmv1-first} does not include Red Hat-provided Operator catalogs by default. If you want to add a Red Hat-provided catalog to your cluster, create a custom resource (CR) for the catalog and apply it to the cluster. The following custom resource (CR) examples show how to create a catalog resources for {olmv1}.
 
+[IMPORTANT]
+====
+include::snippets/olmv1-secure-registry-pull-secret.adoc[]
+====
+
 .Example Red Hat Operators catalog
 [source,yaml,subs="attributes+"]
 ----
@@ -22,6 +27,7 @@ spec:
     type: image
     image:
       ref: registry.redhat.io/redhat/redhat-operator-index:v{product-version}
+      pullSecret: <pull_secret_name>
 ----
 
 .Example Certified Operators catalog
@@ -36,6 +42,7 @@ spec:
     type: image
     image:
       ref: registry.redhat.io/redhat/certified-operator-index:v{product-version}
+      pullSecret: <pull_secret_name>
 ----
 
 .Example Community Operators catalog
@@ -50,6 +57,7 @@ spec:
     type: image
     image:
       ref: registry.redhat.io/redhat/community-operator-index:v{product-version}
+      pullSecret: <pull_secret_name>
 ----
 
 The following command adds a catalog to your cluster:
diff --git a/operators/olm_v1/olmv1-installing-an-operator-from-a-catalog.adoc b/operators/olm_v1/olmv1-installing-an-operator-from-a-catalog.adoc
@@ -31,30 +31,30 @@ Enabling the `TechPreviewNoUpgrade` feature set cannot be undone and prevents mi
 
 [role="_additional-resources"]
 .Additional resources
-
 * xref:../../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling[Enabling features using feature gates]
 
 include::modules/olmv1-about-catalogs.adoc[leveloffset=+1]
 [role="_additional-resources"]
 .Additional resources
 * xref:../../operators/understanding/olm-packaging-format.adoc#olm-file-based-catalogs_olm-packaging-format[File-based catalogs]
 
-include::modules/olmv1-red-hat-catalogs.adoc[leveloffset=+2]
+include::modules/olmv1-red-hat-catalogs.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
+* xref:../../operators/olm_v1/olmv1-installing-an-operator-from-a-catalog.adoc#olmv1-creating-a-pull-secret-for-catalogs-secure-registry_olmv1-installing-operator[Creating a pull secret for catalogs hosted on a secure registry]
 * xref:../../operators/olm_v1/olmv1-installing-an-operator-from-a-catalog.adoc#olmv1-adding-a-catalog-to-a-cluster_olmv1-installing-operator[Adding a catalog to a cluster]
 * xref:../../operators/understanding/olm-rh-catalogs.adoc#olm-rh-catalogs_olm-rh-catalogs[About Red Hat-provided Operator catalogs]
 
-[NOTE]
-====
-The following procedures use the Red Hat Operators catalog and the Quay Operator as examples.
-====
-
-include::modules/olmv1-about-target-versions.adoc[leveloffset=+1]
+include::modules/olmv1-creating-a-pull-secret-for-catalogd.adoc[leveloffset=+1]
 include::modules/olmv1-adding-a-catalog.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../../operators/olm_v1/olmv1-installing-an-operator-from-a-catalog.adoc#olmv1-creating-a-pull-secret-for-catalogs-secure-registry_olmv1-installing-operator[Creating a pull secret for catalogs hosted on a secure registry]
+
 include::modules/olmv1-finding-operators-to-install.adoc[leveloffset=+1]
 
-include::modules/olmv1-installing-an-operator.adoc[leveloffset=+1]
+include::modules/olmv1-about-target-versions.adoc[leveloffset=+1]
 include::modules/olmv1-updating-an-operator.adoc[leveloffset=+1]
 include::modules/olmv1-deleting-an-operator.adoc[leveloffset=+1]
diff --git a/snippets/olmv1-secure-registry-pull-secret.adoc b/snippets/olmv1-secure-registry-pull-secret.adoc
@@ -0,0 +1,8 @@
+// Text snippet included in the following modules:
+//
+// * modules/olmv1-operator-api.adoc
+
+:_mod-docs-content-type: SNIPPET
+
+If you want to use a catalog that is hosted on a secure registry, such as Red Hat-provided Operator catalogs from `registry.redhat.io`, you must have a pull secret scoped to the `openshift-catalogd` namespace.
+ifndef::olmv1-pullsecret-proc[For more information, see "Creating a pull secret for catalogs hosted on a secure registry".]
