Merge pull request #71009 from michaelryanpeter/osdocs-8865-installing-extensions

OSDOCS#8865 Installing extensions on a cluster in OLM 1.0

Author: michaelryanpeter

modules/olmv1-installing-an-operator.adoc

@@ -5,42 +5,127 @@
 :_mod-docs-content-type: PROCEDURE
 
 [id="olmv1-installing-an-operator_{context}"]
-= Installing an Operator
+= Installing an Operator from a catalog
 
-You can install an Operator from a catalog by creating an Operator custom resource (CR) and applying it to the cluster.
+{olmv1-first} supports installing Operators and extensions scoped to the cluster. You can install an Operator from a catalog by creating an Operator custom resource (CR) and applying it to the cluster.
+
+[IMPORTANT]
+====
+Currently, {olmv1} supports the installation Operators and extensions that meet the following criteria:
+
+* The Operator or extension must use the `AllNamespaces` install mode.
+* The Operator or extension must not use webhooks.
+
+Operators and extensions that use webhooks or that target a single or specified set of namespaces cannot be installed.
+====
 
 .Prerequisite
 
 * You have added a catalog to your cluster.
-* You have inspected the details of an Operator to find what version you want to install.
+* You have downloaded a local copy of the catalog file.
 
 .Procedure
 
+. Inspect a package for channel and version information from a local copy of your catalog file by completing the following steps:
+
+.. Get a list of channels from a selected package by running the following command:
++
+[source,terminal]
+----
+$ jq -s '.[] | select( .schema == "olm.channel" ) | \
+  select( .package == "<package_name>") | \
+  .name' /<path>/<catalog_name>.json
+----
++
+.Example command
+[%collapsible]
+====
+[source,terminal]
+----
+$ jq -s '.[] | select( .schema == "olm.channel" ) | \
+  select( .package == "openshift-pipelines-operator-rh") | \
+  .name' /home/username/rhoc.json
+----
+====
++
+.Example output
+[%collapsible]
+====
+[source,text]
+----
+"latest"
+"pipelines-1.11"
+"pipelines-1.12"
+"pipelines-1.13"
+----
+====
+
+.. Get a list of the versions published in a channel by running the following command:
++
+[source,terminal]
+----
+$ jq -s '.[] | select( .package == "<package_name" ) | \
+  select( .schema == "olm.channel" ) | \
+  select( .name == "<channel_name" ) | .entries | \
+  .[] | .name' /<path>/<catalog_name>.json
+----
++
+.Example command
+[%collapsible]
+====
+[source,terminal]
+----
+$ jq -s '.[] | select( .package == "openshift-pipelines-operator-rh" ) | \
+select( .schema == "olm.channel" ) | select( .name == "latest" ) | \
+.entries | .[] | .name' /home/username/rhoc.json
+----
+====
++
+.Example output
+[%collapsible]
+====
+[source,text]
+----
+"openshift-pipelines-operator-rh.v1.11.1"
+"openshift-pipelines-operator-rh.v1.12.0"
+"openshift-pipelines-operator-rh.v1.12.1"
+"openshift-pipelines-operator-rh.v1.12.2"
+"openshift-pipelines-operator-rh.v1.13.0"
+"openshift-pipelines-operator-rh.v1.13.1"
+----
+====
+
 . Create an Operator CR, similar to the following example:
 +
-.Example `test-operator.yaml` CR
+.Example `pipelines-operator.yaml` CR
 [source,yaml]
 ----
 apiVersion: operators.operatorframework.io/v1alpha1
 kind: Operator
 metadata:
-  name: quay-example
+  name: pipelines-operator
 spec:
-  packageName: quay-operator
-  version: 3.8.12
+  packageName: openshift-pipelines-operator-rh
+  channel: <channel>
+  version: <version>
 ----
++
+where:
++
+<channel>:: Optional: Specifies the channel, such as `pipelines-1.11` or `latest`, for the package you want to install or update.
+<version>:: Optional: Specifies the specific version or version range, such as `1.11.1`, `1.12.x`, or `>=1.12.1`, of the package you want to install or update. For more information, see "About target versions in OLM 1.0" and "Support for version ranges".
 
 . Apply the Operator CR to the cluster by running the following command:
 +
 [source,terminal]
 ----
-$ oc apply -f test-operator.yaml
+$ oc apply -f pipeline-operator.yaml
 ----
 +
 .Example output
 [source,text]
 ----
-operator.operators.operatorframework.io/quay-example created
+operator.operators.operatorframework.io/pipelines-operator created
 ----
 
 .Verification
@@ -49,54 +134,113 @@ operator.operators.operatorframework.io/quay-example created
 +
 [source,terminal]
 ----
-$ oc get operator.operators.operatorframework.io/quay-example -o yaml
+$ oc get operator.operators.operatorframework.io pipelines-operator -o yaml
 ----
 +
+[NOTE]
+====
+If you specify a channel or define a version range in your Operator or extension's CR, {olmv1} does not display the resolved version installed on the cluster. Only the version and channel information specified in the CR are displayed.
+
+If you want to find the specific version that is installed, you must compare the SHA of the image of the `spec.source.image.ref` field to the image reference in the catalog.
+====
++
 .Example output
+[%collapsible]
+====
 [source,text]
 ----
 apiVersion: operators.operatorframework.io/v1alpha1
 kind: Operator
 metadata:
   annotations:
     kubectl.kubernetes.io/last-applied-configuration: |
-      {"apiVersion":"operators.operatorframework.io/v1alpha1","kind":"Operator","metadata":{"annotations":{},"name":"quay-example"},"spec":{"packageName":"quay-operator","version":"3.8.12"}}
-  creationTimestamp: "2023-10-19T18:39:37Z"
+      {"apiVersion":"operators.operatorframework.io/v1alpha1","kind":"Operator","metadata":{"annotations":{},"name":"pipelines-operator"},"spec":{"channel":"latest","packageName":"openshift-pipelines-operator-rh","version":"1.11.x"}}
+  creationTimestamp: "2024-01-30T20:06:09Z"
   generation: 1
-  name: quay-example
-  resourceVersion: "45663"
-  uid: 2558623b-8689-421c-8ed5-7b14234af166
+  name: pipelines-operator
+  resourceVersion: "44362"
+  uid: 4272d228-22e1-419e-b9a7-986f982ee588
 spec:
-  packageName: quay-operator
-  version: 3.8.12
+  channel: latest
+  packageName: openshift-pipelines-operator-rh
+  upgradeConstraintPolicy: Enforce
+  version: 1.11.x
 status:
   conditions:
-  - lastTransitionTime: "2023-10-19T18:39:37Z"
-    message: resolved to "registry.redhat.io/quay/quay-operator-bundle@sha256:bf26c7679ea1f7b47d2b362642a9234cddb9e366a89708a4ffcbaf4475788dc7"
+  - lastTransitionTime: "2024-01-30T20:06:15Z"
+    message: resolved to "registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:e09d37bb1e754db42324fd18c1cb3e7ce77e7b7fcbf4932d0535391579938280"
     observedGeneration: 1
     reason: Success
     status: "True"
     type: Resolved
-  - lastTransitionTime: "2023-10-19T18:39:46Z"
-    message: installed from "registry.redhat.io/quay/quay-operator-bundle@sha256:bf26c7679ea1f7b47d2b362642a9234cddb9e366a89708a4ffcbaf4475788dc7"
+  - lastTransitionTime: "2024-01-30T20:06:31Z"
+    message: installed from "registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:e09d37bb1e754db42324fd18c1cb3e7ce77e7b7fcbf4932d0535391579938280"
     observedGeneration: 1
     reason: Success
     status: "True"
     type: Installed
-  installedBundleResource: registry.redhat.io/quay/quay-operator-bundle@sha256:bf26c7679ea1f7b47d2b362642a9234cddb9e366a89708a4ffcbaf4475788dc7
-  resolvedBundleResource: registry.redhat.io/quay/quay-operator-bundle@sha256:bf26c7679ea1f7b47d2b362642a9234cddb9e366a89708a4ffcbaf4475788dc7
+  installedBundleResource: registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:e09d37bb1e754db42324fd18c1cb3e7ce77e7b7fcbf4932d0535391579938280
+  resolvedBundleResource: registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:e09d37bb1e754db42324fd18c1cb3e7ce77e7b7fcbf4932d0535391579938280
 ----
+====
 
-. Get information about your Operator's controller manager pod by running the following command:
+. Get information about your Operator's bundle deployment by running the following command:
 +
 [source,terminal]
 ----
-$ oc get pod -n quay-operator-system
+$ oc get bundleDeployment pipelines-operator -o yaml
 ----
 +
 .Example output
+[%collapsible]
+====
 [source,text]
 ----
-NAME                                     READY   STATUS    RESTARTS   AGE
-quay-operator.v3.8.12-6677b5c98f-2kdtb   1/1     Running   0          2m28s
+apiVersion: core.rukpak.io/v1alpha1
+kind: BundleDeployment
+metadata:
+  creationTimestamp: "2024-01-30T20:06:15Z"
+  generation: 2
+  name: pipelines-operator
+  ownerReferences:
+  - apiVersion: operators.operatorframework.io/v1alpha1
+    blockOwnerDeletion: true
+    controller: true
+    kind: Operator
+    name: pipelines-operator
+    uid: 4272d228-22e1-419e-b9a7-986f982ee588
+  resourceVersion: "44464"
+  uid: 0a0c3525-27e2-4c93-bf57-55920a7707c0
+spec:
+  provisionerClassName: core-rukpak-io-plain
+  template:
+    metadata: {}
+    spec:
+      provisionerClassName: core-rukpak-io-registry
+      source:
+        image:
+          ref: registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:e09d37bb1e754db42324fd18c1cb3e7ce77e7b7fcbf4932d0535391579938280
+        type: image
+status:
+  activeBundle: pipelines-operator-29x720cjzx8yiowf13a3j75fil2zs3mfw
+  conditions:
+  - lastTransitionTime: "2024-01-30T20:06:15Z"
+    message: Successfully unpacked the pipelines-operator-29x720cjzx8yiowf13a3j75fil2zs3mfw
+      Bundle
+    reason: UnpackSuccessful
+    status: "True"
+    type: HasValidBundle
+  - lastTransitionTime: "2024-01-30T20:06:28Z"
+    message: Instantiated bundle pipelines-operator-29x720cjzx8yiowf13a3j75fil2zs3mfw
+      successfully
+    reason: InstallationSucceeded
+    status: "True"
+    type: Installed
+  - lastTransitionTime: "2024-01-30T20:06:40Z"
+    message: BundleDeployment is healthy
+    reason: Healthy
+    status: "True"
+    type: Healthy
+  observedGeneration: 2
 ----
+====