diff --git a/_topic_map.yml b/_topic_map.yml index e4639f6c05cd..a9ca2bdeb27d 100644 --- a/_topic_map.yml +++ b/_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 diff --git a/modules/olm-catalogsource.adoc b/modules/olm-catalogsource.adoc index 586b8454cdcd..0c9d9e08bb9d 100644 --- a/modules/olm-catalogsource.adoc +++ b/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::[] diff --git a/modules/olm-cs-status-cli.adoc b/modules/olm-cs-status-cli.adoc new file mode 100644 index 000000000000..4a3061d07961 --- /dev/null +++ b/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::[] diff --git a/modules/olm-status-viewing-cli.adoc b/modules/olm-status-viewing-cli.adoc index dff52b440b9b..5892ad89f8e3 100644 --- a/modules/olm-status-viewing-cli.adoc +++ b/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 diff --git a/modules/olm-subscription.adoc b/modules/olm-subscription.adoc index 5c68202c6c2e..e1ed80e12ead 100644 --- a/modules/olm-subscription.adoc +++ b/modules/olm-subscription.adoc @@ -2,26 +2,33 @@ // // * 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. @@ -29,3 +36,10 @@ This `Subscription` object defines the name and namespace of the Operator, as we 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::[] diff --git a/operators/admin/olm-status.adoc b/operators/admin/olm-status.adoc index b88b7edf066f..ff4dcfe63453 100644 --- a/operators/admin/olm-status.adoc +++ b/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] diff --git a/operators/understanding/olm/olm-understanding-olm.adoc b/operators/understanding/olm/olm-understanding-olm.adoc index 53c227bf6a5e..747df3935751 100644 --- a/operators/understanding/olm/olm-understanding-olm.adoc +++ b/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 diff --git a/support/troubleshooting/troubleshooting-operator-issues.adoc b/support/troubleshooting/troubleshooting-operator-issues.adoc index 2eb0fd29ccb0..3a83339aa017 100644 --- a/support/troubleshooting/troubleshooting-operator-issues.adoc +++ b/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] -