Skip to content

Commit 46c773e

Browse files
adellapeadellape
committed
Improve CatalogSource concept docs
1 parent cb979a2 commit 46c773e

File tree

8 files changed

+261
-42
lines changed

8 files changed

+261
-42
lines changed

‎_topic_map.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1221,7 +1221,7 @@ Topics:
12211221
Dir: olm
12221222
Distros: openshift-enterprise,openshift-origin
12231223
Topics:
1224-
- Name: Concepts
1224+
- Name: Concepts and resources
12251225
File: olm-understanding-olm
12261226
- Name: Architecture
12271227
File: olm-arch

‎modules/olm-catalogsource.adoc‎

Lines changed: 83 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -2,52 +2,107 @@
22
//
33
// * operators/understanding/olm/olm-understanding-olm.adoc
44

5+
ifdef::openshift-origin[]
6+
:global_ns: olm
7+
endif::[]
8+
ifndef::openshift-origin[]
9+
:global_ns: openshift-marketplace
10+
endif::[]
11+
512
[id="olm-catalogsource_{context}"]
613
= Catalog source
714

8-
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.
9-
10-
There are three primary `sourceTypes` for a `CatalogSource` object:
15+
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.
1116

12-
* `grpc` with an `image` reference: OLM pulls the image and runs the pod, which is expected to serve a compliant API.
13-
* `grpc` with an `address` field: OLM attempts to contact the gRPC API at the given address. This should not be used in most cases.
14-
* `internal` or `configmap`: OLM parses the ConfigMap data and runs a pod that can serve the gRPC API over it.
17+
[TIP]
18+
====
19+
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.
20+
====
1521

16-
The following example defines a catalog source for OperatorHub.io content:
22+
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.
1723

1824
.Example `CatalogSource` object
19-
[source,yaml]
25+
[%collapsible]
26+
====
27+
[source,yaml,subs="attributes+"]
2028
----
21-
apiVersion: operators.coreos.com/v1alpha1
29+
apiVersion: operators.coreos.com/v1alpha1
2230
kind: CatalogSource
2331
metadata:
24-
name: operatorhubio-catalog
25-
namespace: olm
32+
generation: 1
33+
name: example-catalog <.>
34+
namespace: {global_ns} <.>
2635
spec:
27-
sourceType: grpc
28-
image: quay.io/operatorhubio/catalog:latest <1>
29-
priority: -400
30-
displayName: Community Operators
31-
publisher: OperatorHub.io
32-
updateStrategy:
33-
registryPoll: <2>
34-
interval: 30m
36+
displayName: Example Catalog <.>
37+
image: quay.io/example-org/example-catalog:v1 <.>
38+
priority: -400 <.>
39+
publisher: Example Org
40+
sourceType: grpc <.>
41+
updateStrategy:
42+
registryPoll: <.>
43+
interval: 30m0s
44+
status:
45+
connectionState:
46+
address: example-catalog.{global_ns}.svc:50051
47+
lastConnect: 2021-08-26T18:14:31Z
48+
lastObservedState: READY <.>
49+
latestImageRegistryPoll: 2021-08-26T18:46:25Z <.>
50+
registryService: <.>
51+
createdAt: 2021-08-26T16:16:37Z
52+
port: 50051
53+
protocol: grpc
54+
serviceName: example-catalog
55+
serviceNamespace: {global_ns}
3556
----
36-
<1> Specify catalog image.
37-
<2> Automatically check for new versions at a given interval to keep up to date.
57+
<.> 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.
58+
<.> 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.
59+
<.> Display name for the catalog in the web console and CLI.
60+
<.> Index image for the catalog.
61+
<.> 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.
62+
<.> Source types include the following:
63+
+
64+
--
65+
* `grpc` with an `image` reference: OLM pulls the image and runs the pod, which is expected to serve a compliant API.
66+
* `grpc` with an `address` field: OLM attempts to contact the gRPC API at the given address. This should not be used in most cases.
67+
* `internal` or `configmap`: OLM parses config map data and runs a pod that can serve the gRPC API over it.
68+
--
69+
<.> Automatically check for new versions at a given interval to stay up-to-date.
70+
<.> Last observed state of the catalog connection. For example:
71+
+
72+
--
73+
* `READY`: A connection is successfully established.
74+
* `CONNECTING`: A connection is attempting to establish.
75+
* `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.
76+
--
77+
+
78+
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.
79+
<.> Latest time the container registry storing the catalog image was polled to ensure the image is up-to-date.
80+
<.> Status information for the catalog's Operator Registry service.
81+
====
3882

39-
The `name` of the `CatalogSource` object is used as input to a subscription, which instructs OLM where to look to find a requested Operator:
83+
Referencing the `name` of a `CatalogSource` object in a subscription instructs OLM where to search to find a requested Operator:
4084

4185
.Example `Subscription` object referencing a catalog source
42-
[source,yaml]
86+
[%collapsible]
87+
====
88+
[source,yaml,subs="attributes+"]
4389
----
4490
apiVersion: operators.coreos.com/v1alpha1
4591
kind: Subscription
4692
metadata:
47-
name: my-operator
48-
namespace: olm
93+
name: example-operator
94+
namespace: example-namespace
4995
spec:
50-
channel: stable
51-
name: my-operator
52-
source: operatorhubio-catalog
96+
channel: stable
97+
name: example-operator
98+
source: example-catalog
99+
sourceNamespace: {global_ns}
53100
----
101+
====
102+
103+
ifdef::openshift-origin[]
104+
:!global_ns:
105+
endif::[]
106+
ifndef::openshift-origin[]
107+
:!global_ns:
108+
endif::[]

‎modules/olm-cs-status-cli.adoc‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operators/admin/olm-status.adoc
4+
// * support/troubleshooting/troubleshooting-operator-issues.adoc
5+
6+
ifdef::openshift-origin[]
7+
:global_ns: olm
8+
endif::[]
9+
ifndef::openshift-origin[]
10+
:global_ns: openshift-marketplace
11+
endif::[]
12+
13+
[id="olm-cs-status-cli_{context}"]
14+
= Viewing Operator catalog source status by using the CLI
15+
16+
You can view the status of an Operator catalog source by using the CLI.
17+
18+
.Prerequisites
19+
20+
* You have access to the cluster as a user with the `cluster-admin` role.
21+
* You have installed the OpenShift CLI (`oc`).
22+
23+
.Procedure
24+
25+
. List the catalog sources in a namespace. For example, you can check the `{global_ns}` namespace, which is used for cluster-wide catalog sources:
26+
+
27+
[source,terminal,subs="attributes+"]
28+
----
29+
$ oc get catalogsources -n {global_ns}
30+
----
31+
+
32+
.Example output
33+
[source,terminal]
34+
----
35+
NAME DISPLAY TYPE PUBLISHER AGE
36+
certified-operators Certified Operators grpc Red Hat 55m
37+
community-operators Community Operators grpc Red Hat 55m
38+
example-catalog Example Catalog grpc Example Org 2m25s
39+
redhat-marketplace Red Hat Marketplace grpc Red Hat 55m
40+
redhat-operators Red Hat Operators grpc Red Hat 55m
41+
----
42+
43+
. Use the `oc describe` command to get more details and status about a catalog source:
44+
+
45+
[source,terminal,subs="attributes+"]
46+
----
47+
$ oc describe catalogsource example-catalog -n {global_ns}
48+
----
49+
+
50+
.Example output
51+
[source,terminal,subs="attributes+"]
52+
----
53+
Name: example-catalog
54+
Namespace: {global_ns}
55+
...
56+
Status:
57+
Connection State:
58+
Address: example-catalog.{global_ns}.svc:50051
59+
Last Connect: 2021-09-09T17:07:35Z
60+
Last Observed State: TRANSIENT_FAILURE
61+
Registry Service:
62+
Created At: 2021-09-09T17:05:45Z
63+
Port: 50051
64+
Protocol: grpc
65+
Service Name: example-catalog
66+
Service Namespace: {global_ns}
67+
----
68+
+
69+
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.
70+
71+
. List the pods in the namespace where your catalog source was created:
72+
+
73+
[source,terminal,subs="attributes+"]
74+
----
75+
$ oc get pods -n {global_ns}
76+
----
77+
+
78+
.Example output
79+
[source,terminal]
80+
----
81+
NAME READY STATUS RESTARTS AGE
82+
certified-operators-cv9nn 1/1 Running 0 36m
83+
community-operators-6v8lp 1/1 Running 0 36m
84+
marketplace-operator-86bfc75f9b-jkgbc 1/1 Running 0 42m
85+
example-catalog-bwt8z 0/1 ImagePullBackOff 0 3m55s
86+
redhat-marketplace-57p8c 1/1 Running 0 36m
87+
redhat-operators-smxx8 1/1 Running 0 36m
88+
----
89+
+
90+
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.
91+
92+
. Use the `oc describe` command to inspect a pod for more detailed information:
93+
+
94+
[source,terminal,subs="attributes+"]
95+
----
96+
$ oc describe pod example-catalog-bwt8z -n {global_ns}
97+
----
98+
+
99+
.Example output
100+
[source,terminal,subs="attributes+"]
101+
----
102+
Name: example-catalog-bwt8z
103+
Namespace: {global_ns}
104+
Priority: 0
105+
Node: ci-ln-jyryyg2-f76d1-ggdbq-worker-b-vsxjd/10.0.128.2
106+
...
107+
Events:
108+
Type Reason Age From Message
109+
---- ------ ---- ---- -------
110+
Normal Scheduled 48s default-scheduler Successfully assigned {global_ns}/example-catalog-bwt8z to ci-ln-jyryyf2-f76d1-fgdbq-worker-b-vsxjd
111+
Normal AddedInterface 47s multus Add eth0 [10.131.0.40/23] from openshift-sdn
112+
Normal BackOff 20s (x2 over 46s) kubelet Back-off pulling image "quay.io/example-org/example-catalog:v1"
113+
Warning Failed 20s (x2 over 46s) kubelet Error: ImagePullBackOff
114+
Normal Pulling 8s (x3 over 47s) kubelet Pulling image "quay.io/example-org/example-catalog:v1"
115+
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
116+
Warning Failed 8s (x3 over 47s) kubelet Error: ErrImagePull
117+
----
118+
+
119+
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.
120+
121+
ifdef::openshift-origin[]
122+
:!global_ns:
123+
endif::[]
124+
ifndef::openshift-origin[]
125+
:!global_ns:
126+
endif::[]

‎modules/olm-status-viewing-cli.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@
44
// * support/troubleshooting/troubleshooting-operator-issues.adoc
55

66
[id="olm-status-viewing-cli_{context}"]
7-
= Viewing Operator subscription status using the CLI
7+
= Viewing Operator subscription status by using the CLI
88

9-
You can view Operator subscription status using the CLI.
9+
You can view Operator subscription status by using the CLI.
1010

1111
.Prerequisites
1212

‎modules/olm-subscription.adoc‎

Lines changed: 21 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,30 +2,44 @@
22
//
33
// * operators/understanding/olm/olm-understanding-olm.adoc
44

5+
ifdef::openshift-origin[]
6+
:global_ns: olm
7+
endif::[]
8+
ifndef::openshift-origin[]
9+
:global_ns: openshift-marketplace
10+
endif::[]
11+
512
[id="olm-subscription_{context}"]
613
= Subscription
714

8-
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.
15+
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.
916

1017
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.
1118

1219
.Example `Subscription` object
13-
[source,yaml]
20+
[source,yaml,subs="attributes+"]
1421
----
1522
apiVersion: operators.coreos.com/v1alpha1
1623
kind: Subscription
1724
metadata:
18-
name: my-operator
19-
namespace: operators
25+
name: example-operator
26+
namespace: example-namespace
2027
spec:
2128
channel: stable
22-
name: my-operator
23-
source: my-catalog
24-
sourceNamespace: operators
29+
name: example-operator
30+
source: example-catalog
31+
sourceNamespace: {global_ns}
2532
----
2633

2734
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.
2835

2936
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`).
3037

3138
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.
39+
40+
ifdef::openshift-origin[]
41+
:!global_ns:
42+
endif::[]
43+
ifndef::openshift-origin[]
44+
:!global_ns:
45+
endif::[]

‎operators/admin/olm-status.adoc‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,9 @@ include::modules/olm-status-conditions.adoc[leveloffset=+1]
1313
* xref:../../operators/admin/olm-deleting-operators-from-cluster.adoc#olm-refresh-subs_olm-deleting-operators-from-a-cluster[Refreshing failing subscriptions]
1414

1515
include::modules/olm-status-viewing-cli.adoc[leveloffset=+1]
16+
include::modules/olm-cs-status-cli.adoc[leveloffset=+1]
17+
.Additional resources
18+
19+
* xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-catalogsource_olm-understanding-olm[Operator Lifecycle Manager concepts and resources -> Catalog source]
20+
* gRPC documentation: link:https://grpc.github.io/grpc/core/md_doc_connectivity-semantics-and-api.html[States of Connectivity]
21+
* 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‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
[id="olm-understanding-olm"]
2-
= Operator Lifecycle Manager concepts
2+
= Operator Lifecycle Manager concepts and resources
33
include::modules/common-attributes.adoc[]
44
:context: olm-understanding-olm
55

@@ -11,7 +11,18 @@ include::modules/olm-overview.adoc[leveloffset=+1]
1111
include::modules/olm-crds.adoc[leveloffset=+1]
1212
include::modules/olm-csv.adoc[leveloffset=+2]
1313
include::modules/olm-catalogsource.adoc[leveloffset=+2]
14+
.Additional resources
15+
16+
* xref:../../../operators/understanding/olm-understanding-operatorhub.adoc#olm-understanding-operatorhub[Understanding OperatorHub]
17+
* xref:../../../operators/understanding/olm-rh-catalogs.adoc#olm-rh-catalogs[Red Hat-provided Operator catalogs]
18+
* xref:../../../operators/understanding/olm/olm-understanding-dependency-resolution.adoc#olm-dependency-catalog-priority_olm-understanding-dependency-resolution[Catalog priority]
19+
* xref:../../../operators/admin/olm-status.adoc#olm-cs-status-cli_olm-status[Viewing Operator catalog source status by using the CLI]
20+
1421
include::modules/olm-subscription.adoc[leveloffset=+2]
22+
.Additional resources
23+
24+
* xref:../../../operators/admin/olm-status.adoc#olm-status-viewing-cli_olm-status[Viewing Operator subscription status by using the CLI]
25+
1526
include::modules/olm-installplan.adoc[leveloffset=+2]
1627
.Additional resources
1728

‎support/troubleshooting/troubleshooting-operator-issues.adoc‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,12 +13,20 @@ As a cluster administrator, you can install application Operators from the Opera
1313

1414
If you experience Operator issues, verify Operator subscription status. Check Operator pod health across the cluster and gather Operator logs for diagnosis.
1515

16-
// Operator Subscription condition types
16+
// Operator subscription condition types
1717
include::modules/olm-status-conditions.adoc[leveloffset=+1]
1818

19-
// Viewing Operator Subscription status using the CLI
19+
// Viewing Operator subscription status by using the CLI
2020
include::modules/olm-status-viewing-cli.adoc[leveloffset=+1]
2121

22+
// Viewing Operator catalog source status by using the CLI
23+
include::modules/olm-cs-status-cli.adoc[leveloffset=+1]
24+
.Additional resources
25+
26+
* xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-catalogsource_olm-understanding-olm[Operator Lifecycle Manager concepts and resources -> Catalog source]
27+
* gRPC documentation: link:https://grpc.github.io/grpc/core/md_doc_connectivity-semantics-and-api.html[States of Connectivity]
28+
* xref:../../operators/admin/olm-managing-custom-catalogs.adoc#olm-accessing-images-private-registries_olm-managing-custom-catalogs[Accessing images for Operators from private registries]
29+
2230
// Querying Operator Pod status
2331
include::modules/querying-operator-pod-status.adoc[leveloffset=+1]
2432

@@ -32,4 +40,3 @@ include::modules/troubleshooting-disabling-autoreboot-mco-cli.adoc[leveloffset=+
3240

3341
// Refreshing failing subscriptions
3442
include::modules/olm-refresh-subs.adoc[leveloffset=+1]
35-

0 commit comments

Comments
 (0)