4.14 OLM 1.0 Tech Preview procedures

_topic_maps/_topic_map.yml

@@ -1879,6 +1879,8 @@ Topics:
     File: olmv1-packaging-format
   - Name: Managing catalogs
     File: olmv1-managing-catalogs
+  - Name: Installing an Operator from a catalog
+    File: olmv1-installing-an-operator-from-a-catalog
 ---
 Name: CI/CD
 Dir: cicd

modules/olmv1-about-catalogs.adoc

@@ -0,0 +1,12 @@
+// Module included in the following assemblies:
+//
+// * operators/olm_v1/olmv1-installing-an-operator-from-a-catalog.adoc
+
+:_content-type: CONCEPT
+
+[id="olmv1-about-catalogs_{context}"]
+= About catalogs in OLM 1.0
+
+Operator Lifecycle Manager (OLM) 1.0 introduces the catalogd component to the OLM suite of microservices. Catalogd is a Kubernetes extension that unpacks file-based catalog content for on-cluster clients. Currently, catalogd unpacks catalog content that is packaged and distributed as container images. 
+
+Catalogd helps customers discover installable content by hosting catalog metadata for Kubernetes extensions, such as Operators and controllers.

modules/olmv1-about-target-versions.adoc

@@ -0,0 +1,116 @@
+// Module included in the following assemblies:
+//
+// * operators/olm_v1/olmv1-installing-an-operator-from-a-catalog.adoc
+
+:_content-type: CONCEPT
+
+[id="olmv1-about-operator-updates_{context}"]
+= About target versions in OLM 1.0
+
+In Operator Lifecycle Manager 1.0, cluster administrators set the target version of an Operator in the Operator's custom resource (CR).
+
+If the Operator's version is not specified in the CR, then OLM 1.0 defaults to the latest stable version in the catalog as the target version. When updates to the Operator are published to the catalog, the Operator automatically updates to the latest stable version.
+
+.Example CR without a specified target version
+[source,yaml]
+----
+apiVersion: operators.operatorframework.io/v1alpha1
+kind: Operator
+metadata:
+  name: quay-example
+spec:
+  packageName: quay-operator
+----
+
+If you specify the Operator's target version in the CR, OLM 1.0 installs the specified version. When the target version is specified in the Operator's CR, OLM 1.0 does not change the target version.
+
+.Example CR with the target version specified
+[source,yaml]
+----
+apiVersion: operators.operatorframework.io/v1alpha1
+kind: Operator
+metadata:
+  name: quay-example
+spec:
+  packageName: quay-operator
+  channel: stable-3.8
+  version: 3.8.12
+----
+
+Edit the target version to change the installed version of an Operator. Provided that the update is supported by the skip ranges defined in the catalog, you can update across channels and to an earlier version an Operator.
+
+.Example CR with an updated target version
+[source,yaml]
+----
+apiVersion: operators.operatorframework.io/v1alpha1
+kind: Operator
+metadata:
+  name: quay-example
+spec:
+  packageName: quay-operator
+  channel: stable-3.9
+  version: 3.9.1
+----
+
+You can inspect an Operator's catalog contents, including supported versions and skip ranges, by running the following command:
+
+.Command syntax
+[source,terminal]
+----
+$ oc get package <catalog_name>-<operator_name> -o yaml
+----
+
+After a CR is created or updated, run the following command to create or configure the Operator:
+
+.Command syntax
+[source,terminal]
+----
+$ oc apply -f <extension_name>.yaml
+----
+
+[NOTE]
+====
+If you make a mistake and update to a target version or channel that does not exist, you can run the following command to check the status of your Operator:
+
+[source,terminal]
+----
+$ oc get operators.operators.operatorframework.io <operator_name> -o yaml
+----
+
+.Example output
+[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":{"anno
+tations":{},"name":"quay-example"},"spec":{"channel":"stable-3.9","packageName":"quay-operator","
+version":"999.99.9"}}
+  creationTimestamp: "2023-10-12T20:20:40Z"
+  generation: 2
+  name: quay-example
+  resourceVersion: "45505"
+  uid: 01ba4dd6-4eaa-4e62-bff1-233770915f7b
+spec:
+  channel: stable-3.9
+  packageName: quay-operator
+  version: 999.99.9
+status:
+  conditions:
+  - lastTransitionTime: "2023-10-12T20:20:40Z"
+    message: installation has not been attempted as resolution failed
+    observedGeneration: 2
+    reason: InstallationStatusUnknown
+    status: Unknown
+    type: Installed
+  - lastTransitionTime: "2023-10-12T20:20:40Z"
+    message: package 'quay-operator' at version '999.99.9' in channel 'stable-3.9'
+      not found 
+    observedGeneration: 2
+    reason: ResolutionFailed
+    status: "False"
+    type: Resolved
+----
+====

modules/olmv1-adding-a-catalog.adoc

@@ -0,0 +1,75 @@
+// Module included in the following assemblies:
+//
+// * operators/olm_v1/olmv1-installing-an-operator-from-a-catalog.adoc
+
+:_content-type: PROCEDURE
+
+[id="olmv1-adding-a-catalog-to-a-cluster_{context}"]
+= Adding a catalog to a cluster
+
+To add a catalog to a cluster, create a catalog custom resource (CR) and apply it to the cluster.
+
+.Procedure
+
+. Create a catalog custom resource (CR), similar to the following example:
++
+.Example `redhat-operators.yaml`
+[source,yaml]
+----
+apiVersion: catalogd.operatorframework.io/v1alpha1
+kind: Catalog
+metadata:
+  name: redhat-operators
+spec:
+  source:
+    type: image
+    image:
+      ref: registry.redhat.io/redhat/redhat-operator-index:v{product-version} <1>
+----
+<1> Specify the catalog's image in the `spec.source.image` field.
+
+. Run the following command to add the catalog to your cluster. By default, your catalog is installed in the `openshift-catalogd` namespace.
++
+[source,terminal]
+----
+$ oc apply -f redhat-operators.yaml
+----
++
+.Example output
+[source,text]
+----
+catalog.catalogd.operatorframework.io/redhat-operators created
+----
+
+.Verification
+
+* Run the following commands to verify the status of your catalog:
+
+.. Run the following command to check if your catalog is available:
++
+[source,terminal]
+----
+$ oc get catalog
+----
++
+.Example output
+[source,text]
+----
+NAME                  AGE
+redhat-operators      20s
+----
+
+.. Run the following command to check the status of your catalog pods:
++
+[source,terminal]
+----
+$ oc get pod -n openshift-catalogd
+----
++
+.Example output
+[source,text]
+----
+NAME                                           READY   STATUS      RESTARTS   AGE
+catalogd-controller-manager-5b8844bbc4-ps76j   2/2     Running     0          60m
+redhat-operators                               0/1     Completed   0          47s
+----

modules/olmv1-deleting-an-operator.adoc

@@ -0,0 +1,50 @@
+// Module included in the following assemblies:
+//
+// * operators/olm_v1/olmv1-installing-an-operator-from-a-catalog.adoc
+
+:_content-type: PROCEDURE
+
+[id="olmv1-deleting-an-operator_{context}"]
+= Deleting an Operator
+
+You can delete an Operator by deleting the Operator's custom resource (CR).
+
+.Prerequisites
+
+* You have a catalog installed.
+* You have an Operator installed.
+
+.Procedure
+
+* Run the following command to delete an Operator:
++
+[source,terminal]
+----
+$ oc delete operator.operators.operatorframework.io quay-example
+----
++
+.Example output
+[source,text]
+----
+operator.operators.operatorframework.io "quay-example" deleted
+----
+
+.Verification
+
+* Run the following commands to verify that your Operator was deleted:
++
+[source,terminal]
+----
+$ oc get operator.operators.operatorframework.io
+----
++
+[source,terminal]
+----
+$ oc get pod -n quay-operator-system
+----
++
+.Example output
+[source,text]
+----
+No resources found
+----