OSDOCS-2602: Improve CatalogSource concept docs

_topic_map.yml

@@ -1221,7 +1221,7 @@ Topics:
     Dir: olm
     Distros: openshift-enterprise,openshift-origin
     Topics:
-    - Name: Concepts
+    - Name: Concepts and resources
       File: olm-understanding-olm
     - Name: Architecture
       File: olm-arch

modules/olm-catalogsource.adoc

@@ -2,52 +2,107 @@
 //
 // * operators/understanding/olm/olm-understanding-olm.adoc
 
+ifdef::openshift-origin[]
+:global_ns: olm
+endif::[]
+ifndef::openshift-origin[]
+:global_ns: openshift-marketplace
+endif::[]
+
 [id="olm-catalogsource_{context}"]
 = Catalog source
 
-A catalog source represents a store of metadata that OLM can query to discover and install Operators and their dependencies. The spec of a `CatalogSource` object indicates how to construct a pod or how to communicate with a service that serves the Operator Registry gRPC API.
-
-There are three primary `sourceTypes` for a `CatalogSource` object:
+A _catalog source_ represents a store of metadata, typically by referencing an _index image_ stored in a container registry. Operator Lifecycle Manager (OLM) queries catalog sources to discover and install Operators and their dependencies. The OperatorHub in the {product-title} web console also displays the Operators provided by catalog sources.
 
-* `grpc` with an `image` reference: OLM pulls the image and runs the pod, which is expected to serve a compliant API.
-* `grpc` with an `address` field: OLM attempts to contact the gRPC API at the given address. This should not be used in most cases.
-* `internal` or `configmap`: OLM parses the ConfigMap data and runs a pod that can serve the gRPC API over it.
+[TIP]
+====
+Cluster administrators can view the full list of Operators provided by an enabled catalog source on a cluster by using the *Administration* -> *Cluster Settings* -> *Configuration* -> *OperatorHub* page in the web console.
+====
 
-The following example defines a catalog source for OperatorHub.io content:
+The `spec` of a `CatalogSource` object indicates how to construct a pod or how to communicate with a service that serves the Operator Registry gRPC API.
 
 .Example `CatalogSource` object
-[source,yaml]
+[%collapsible]
+====
+[source,yaml,subs="attributes+"]
 ----
-apiVersion: operators.coreos.com/v1alpha1
+apiVersion: operators.coreos.com/v1alpha1
 kind: CatalogSource
 metadata:
- name: operatorhubio-catalog
- namespace: olm
+  generation: 1
+  name: example-catalog <.>
+  namespace: {global_ns} <.>
 spec:
- sourceType: grpc
- image: quay.io/operatorhubio/catalog:latest <1>
- priority: -400
- displayName: Community Operators
- publisher: OperatorHub.io
- updateStrategy:
-  registryPoll: <2>
-    interval: 30m
+  displayName: Example Catalog <.>
+  image: quay.io/example-org/example-catalog:v1 <.>
+  priority: -400 <.>
+  publisher: Example Org
+  sourceType: grpc <.>
+  updateStrategy:
+    registryPoll: <.>
+      interval: 30m0s
+status:
+  connectionState:
+    address: example-catalog.{global_ns}.svc:50051
+    lastConnect: 2021-08-26T18:14:31Z
+    lastObservedState: READY <.>
+  latestImageRegistryPoll: 2021-08-26T18:46:25Z <.>
+  registryService: <.>
+    createdAt: 2021-08-26T16:16:37Z
+    port: 50051
+    protocol: grpc
+    serviceName: example-catalog
+    serviceNamespace: {global_ns}
 ----
-<1> Specify catalog image.
-<2> Automatically check for new versions at a given interval to keep up to date.
+<.> Name for the `CatalogSource` object. This value is also used as part of the name for the related pod that is created in the requested namespace.
+<.> Namespace to create the catalog available. To make the catalog available cluster-wide in all namespaces, set this value to `{global_ns}`. The default Red Hat-provided catalog sources also use the `{global_ns}` namespace. Otherwise, set the value to a specific namespace to make the Operator only available in that namespace.
+<.> Display name for the catalog in the web console and CLI.
+<.> Index image for the catalog.
+<.> Weight for the catalog source. OLM uses the weight for prioritization during dependency resolution. A higher weight indicates the catalog is preferred over lower-weighted catalogs.
+<.> Source types include the following:
++
+--
+* `grpc` with an `image` reference: OLM pulls the image and runs the pod, which is expected to serve a compliant API.
+* `grpc` with an `address` field: OLM attempts to contact the gRPC API at the given address. This should not be used in most cases.
+* `internal` or `configmap`: OLM parses config map data and runs a pod that can serve the gRPC API over it.
+--
+<.> Automatically check for new versions at a given interval to stay up-to-date.
+<.> Last observed state of the catalog connection. For example:
++
+--
+* `READY`: A connection is successfully established.
+* `CONNECTING`: A connection is attempting to establish.
+* `TRANSIENT_FAILURE`: A temporary problem has occurred while attempting to establish a connection, such as a timeout. The state will eventually switch back to `CONNECTING` and try again.
+--
++
+See link:https://grpc.github.io/grpc/core/md_doc_connectivity-semantics-and-api.html[States of Connectivity] in the gRPC documentation for more details.
+<.> Latest time the container registry storing the catalog image was polled to ensure the image is up-to-date.
+<.> Status information for the catalog's Operator Registry service.
+====
 
-The `name` of the `CatalogSource` object is used as input to a subscription, which instructs OLM where to look to find a requested Operator:
+Referencing the `name` of a `CatalogSource` object in a subscription instructs OLM where to search to find a requested Operator:
 
 .Example `Subscription` object referencing a catalog source
-[source,yaml]
+[%collapsible]
+====
+[source,yaml,subs="attributes+"]
 ----
 apiVersion: operators.coreos.com/v1alpha1
 kind: Subscription
 metadata:
- name: my-operator
- namespace: olm
+  name: example-operator
+  namespace: example-namespace
 spec:
- channel: stable
- name: my-operator
- source: operatorhubio-catalog
+  channel: stable
+  name: example-operator
+  source: example-catalog
+  sourceNamespace: {global_ns}
 ----
+====
+
+ifdef::openshift-origin[]
+:!global_ns:
+endif::[]
+ifndef::openshift-origin[]
+:!global_ns:
+endif::[]

modules/olm-cs-status-cli.adoc

@@ -0,0 +1,126 @@
+// Module included in the following assemblies:
+//
+// * operators/admin/olm-status.adoc
+// * support/troubleshooting/troubleshooting-operator-issues.adoc
+
+ifdef::openshift-origin[]
+:global_ns: olm
+endif::[]
+ifndef::openshift-origin[]
+:global_ns: openshift-marketplace
+endif::[]
+
+[id="olm-cs-status-cli_{context}"]
+= Viewing Operator catalog source status by using the CLI
+
+You can view the status of an Operator catalog source by using the CLI.
+
+.Prerequisites
+
+* You have access to the cluster as a user with the `cluster-admin` role.
+* You have installed the OpenShift CLI (`oc`).
+
+.Procedure
+
+. List the catalog sources in a namespace. For example, you can check the `{global_ns}` namespace, which is used for cluster-wide catalog sources:
++
+[source,terminal,subs="attributes+"]
+----
+$ oc get catalogsources -n {global_ns}
+----
++
+.Example output
+[source,terminal]
+----
+NAME                  DISPLAY               TYPE   PUBLISHER   AGE
+certified-operators   Certified Operators   grpc   Red Hat     55m
+community-operators   Community Operators   grpc   Red Hat     55m
+example-catalog       Example Catalog       grpc   Example Org 2m25s
+redhat-marketplace    Red Hat Marketplace   grpc   Red Hat     55m
+redhat-operators      Red Hat Operators     grpc   Red Hat     55m
+----
+
+. Use the `oc describe` command to get more details and status about a catalog source:
++
+[source,terminal,subs="attributes+"]
+----
+$ oc describe catalogsource example-catalog -n {global_ns}
+----
++
+.Example output
+[source,terminal,subs="attributes+"]
+----
+Name:         example-catalog
+Namespace:    {global_ns}
+...
+Status:
+  Connection State:
+    Address:              example-catalog.{global_ns}.svc:50051
+    Last Connect:         2021-09-09T17:07:35Z
+    Last Observed State:  TRANSIENT_FAILURE
+  Registry Service:
+    Created At:         2021-09-09T17:05:45Z
+    Port:               50051
+    Protocol:           grpc
+    Service Name:       example-catalog
+    Service Namespace:  {global_ns}
+----
++
+In the preceding example output, the last observed state is `TRANSIENT_FAILURE`. This state indicates that there is a problem establishing a connection for the catalog source.
+
+. List the pods in the namespace where your catalog source was created:
++
+[source,terminal,subs="attributes+"]
+----
+$ oc get pods -n {global_ns}
+----
++
+.Example output
+[source,terminal]
+----
+NAME                                    READY   STATUS             RESTARTS   AGE
+certified-operators-cv9nn               1/1     Running            0          36m
+community-operators-6v8lp               1/1     Running            0          36m
+marketplace-operator-86bfc75f9b-jkgbc   1/1     Running            0          42m
+example-catalog-bwt8z                   0/1     ImagePullBackOff   0          3m55s
+redhat-marketplace-57p8c                1/1     Running            0          36m
+redhat-operators-smxx8                  1/1     Running            0          36m
+----
++
+When a catalog source is created in a namespace, a pod for the catalog source is created in that namespace. In the preceding example output, the status for the `example-catalog-bwt8z` pod is `ImagePullBackOff`. This status indicates that there is an issue pulling the catalog source's index image.
+
+. Use the `oc describe` command to inspect a pod for more detailed information:
++
+[source,terminal,subs="attributes+"]
+----
+$ oc describe pod example-catalog-bwt8z -n {global_ns}
+----
++
+.Example output
+[source,terminal,subs="attributes+"]
+----
+Name:         example-catalog-bwt8z
+Namespace:    {global_ns}
+Priority:     0
+Node:         ci-ln-jyryyg2-f76d1-ggdbq-worker-b-vsxjd/10.0.128.2
+...
+Events:
+  Type     Reason          Age                From               Message
+  ----     ------          ----               ----               -------
+  Normal   Scheduled       48s                default-scheduler  Successfully assigned {global_ns}/example-catalog-bwt8z to ci-ln-jyryyf2-f76d1-fgdbq-worker-b-vsxjd
+  Normal   AddedInterface  47s                multus             Add eth0 [10.131.0.40/23] from openshift-sdn
+  Normal   BackOff         20s (x2 over 46s)  kubelet            Back-off pulling image "quay.io/example-org/example-catalog:v1"
+  Warning  Failed          20s (x2 over 46s)  kubelet            Error: ImagePullBackOff
+  Normal   Pulling         8s (x3 over 47s)   kubelet            Pulling image "quay.io/example-org/example-catalog:v1"
+  Warning  Failed          8s (x3 over 47s)   kubelet            Failed to pull image "quay.io/example-org/example-catalog:v1": rpc error: code = Unknown desc = reading manifest v1 in quay.io/example-org/example-catalog: unauthorized: access to the requested resource is not authorized
+  Warning  Failed          8s (x3 over 47s)   kubelet            Error: ErrImagePull
+----
++
+In the preceding example output, the error messages indicate that the catalog source's index image is failing to pull successfully because of an authorization issue. For example, the index image might be stored in a registry that requires login credentials.
+
+ifdef::openshift-origin[]
+:!global_ns:
+endif::[]
+ifndef::openshift-origin[]
+:!global_ns:
+endif::[]

modules/olm-status-viewing-cli.adoc

@@ -4,9 +4,9 @@
 // * support/troubleshooting/troubleshooting-operator-issues.adoc
 
 [id="olm-status-viewing-cli_{context}"]
-= Viewing Operator subscription status using the CLI
+= Viewing Operator subscription status by using the CLI
 
-You can view Operator subscription status using the CLI.
+You can view Operator subscription status by using the CLI.
 
 .Prerequisites
 

modules/olm-subscription.adoc

@@ -2,30 +2,44 @@
 //
 // * operators/understanding/olm/olm-understanding-olm.adoc
 
+ifdef::openshift-origin[]
+:global_ns: olm
+endif::[]
+ifndef::openshift-origin[]
+:global_ns: openshift-marketplace
+endif::[]
+
 [id="olm-subscription_{context}"]
 = Subscription
 
-A subscription, defined by a `Subscription` object, represents an intention to install an Operator. It is the custom resource that relates an Operator to a catalog source.
+A _subscription_, defined by a `Subscription` object, represents an intention to install an Operator. It is the custom resource that relates an Operator to a catalog source.
 
 Subscriptions describe which channel of an Operator package to subscribe to, and whether to perform updates automatically or manually. If set to automatic, the subscription ensures Operator Lifecycle Manager (OLM) manages and upgrades the Operator to ensure that the latest version is always running in the cluster.
 
 .Example `Subscription` object
-[source,yaml]
+[source,yaml,subs="attributes+"]
 ----
 apiVersion: operators.coreos.com/v1alpha1
 kind: Subscription
 metadata:
-  name: my-operator
-  namespace: operators
+  name: example-operator
+  namespace: example-namespace
 spec:
   channel: stable
-  name: my-operator
-  source: my-catalog
-  sourceNamespace: operators
+  name: example-operator
+  source: example-catalog
+  sourceNamespace: {global_ns}
 ----
 
 This `Subscription` object defines the name and namespace of the Operator, as well as the catalog from which the Operator data can be found. The channel, such as `alpha`, `beta`, or `stable`, helps determine which Operator stream should be installed from the catalog source.
 
 The names of channels in a subscription can differ between Operators, but the naming scheme should follow a common convention within a given Operator. For example, channel names might follow a minor release update stream for the application provided by the Operator (`1.2`, `1.3`) or a release frequency (`stable`, `fast`).
 
 In addition to being easily visible from the {product-title} web console, it is possible to identify when there is a newer version of an Operator available by inspecting the status of the related subscription. The value associated with the `currentCSV` field is the newest version that is known to OLM, and `installedCSV` is the version that is installed on the cluster.
+
+ifdef::openshift-origin[]
+:!global_ns:
+endif::[]
+ifndef::openshift-origin[]
+:!global_ns:
+endif::[]

operators/admin/olm-status.adoc

@@ -13,3 +13,9 @@ include::modules/olm-status-conditions.adoc[leveloffset=+1]
 * xref:../../operators/admin/olm-deleting-operators-from-cluster.adoc#olm-refresh-subs_olm-deleting-operators-from-a-cluster[Refreshing failing subscriptions]
 
 include::modules/olm-status-viewing-cli.adoc[leveloffset=+1]
+include::modules/olm-cs-status-cli.adoc[leveloffset=+1]
+.Additional resources
+
+* xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-catalogsource_olm-understanding-olm[Operator Lifecycle Manager concepts and resources -> Catalog source]
+* gRPC documentation: link:https://grpc.github.io/grpc/core/md_doc_connectivity-semantics-and-api.html[States of Connectivity]
+* xref:../../operators/admin/olm-managing-custom-catalogs.adoc#olm-accessing-images-private-registries_olm-managing-custom-catalogs[Accessing images for Operators from private registries]

operators/understanding/olm/olm-understanding-olm.adoc

@@ -1,5 +1,5 @@
 [id="olm-understanding-olm"]
-= Operator Lifecycle Manager concepts
+= Operator Lifecycle Manager concepts and resources
 include::modules/common-attributes.adoc[]
 :context: olm-understanding-olm
 
@@ -11,7 +11,18 @@ include::modules/olm-overview.adoc[leveloffset=+1]
 include::modules/olm-crds.adoc[leveloffset=+1]
 include::modules/olm-csv.adoc[leveloffset=+2]
 include::modules/olm-catalogsource.adoc[leveloffset=+2]
+.Additional resources
+
+* xref:../../../operators/understanding/olm-understanding-operatorhub.adoc#olm-understanding-operatorhub[Understanding OperatorHub]
+* xref:../../../operators/understanding/olm-rh-catalogs.adoc#olm-rh-catalogs[Red Hat-provided Operator catalogs]
+* xref:../../../operators/understanding/olm/olm-understanding-dependency-resolution.adoc#olm-dependency-catalog-priority_olm-understanding-dependency-resolution[Catalog priority]
+* xref:../../../operators/admin/olm-status.adoc#olm-cs-status-cli_olm-status[Viewing Operator catalog source status by using the CLI]
+
 include::modules/olm-subscription.adoc[leveloffset=+2]
+.Additional resources
+
+* xref:../../../operators/admin/olm-status.adoc#olm-status-viewing-cli_olm-status[Viewing Operator subscription status by using the CLI]
+
 include::modules/olm-installplan.adoc[leveloffset=+2]
 .Additional resources
 

support/troubleshooting/troubleshooting-operator-issues.adoc

@@ -13,12 +13,20 @@ As a cluster administrator, you can install application Operators from the Opera
 
 If you experience Operator issues, verify Operator subscription status. Check Operator pod health across the cluster and gather Operator logs for diagnosis.
 
-// Operator Subscription condition types
+// Operator subscription condition types
 include::modules/olm-status-conditions.adoc[leveloffset=+1]
 
-// Viewing Operator Subscription status using the CLI
+// Viewing Operator subscription status by using the CLI
 include::modules/olm-status-viewing-cli.adoc[leveloffset=+1]
 
+// Viewing Operator catalog source status by using the CLI
+include::modules/olm-cs-status-cli.adoc[leveloffset=+1]
+.Additional resources
+
+* xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-catalogsource_olm-understanding-olm[Operator Lifecycle Manager concepts and resources -> Catalog source]
+* gRPC documentation: link:https://grpc.github.io/grpc/core/md_doc_connectivity-semantics-and-api.html[States of Connectivity]
+* xref:../../operators/admin/olm-managing-custom-catalogs.adoc#olm-accessing-images-private-registries_olm-managing-custom-catalogs[Accessing images for Operators from private registries]
+
 // Querying Operator Pod status
 include::modules/querying-operator-pod-status.adoc[leveloffset=+1]
 
@@ -32,4 +40,3 @@ include::modules/troubleshooting-disabling-autoreboot-mco-cli.adoc[leveloffset=+
 
 // Refreshing failing subscriptions
 include::modules/olm-refresh-subs.adoc[leveloffset=+1]
-