4.14 OLM 1.0 Tech Preview procedures

_topic_maps/_topic_map.yml

@@ -1885,6 +1885,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,10 @@
+// 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
+
+You can discover installable content by querying a catalog for Kubernetes extensions, such as Operators and controllers, by using the catalogd component. Catalogd is a Kubernetes extension that unpacks catalog content for on-cluster clients and is part of the OLM 1.0 suite of microservices. Currently, catalogd unpacks catalog content that is packaged and distributed as container images.

modules/olmv1-about-target-versions.adoc

@@ -0,0 +1,111 @@
+// 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 declaratively in the Operator's custom resource (CR).
+
+If you specify a channel in the Operator's CR, OLM 1.0 installs the latest release from the specified channel. When updates are published to the specified channel, OLM 1.0 automatically updates to the latest release from the channel.
+
+.Example CR with a specified channel
+[source,yaml]
+----
+apiVersion: operators.operatorframework.io/v1alpha1
+kind: Operator
+metadata:
+  name: quay-example
+spec:
+  packageName: quay-operator
+  channel: stable-3.8 <1>
+----
+<1> Installs the latest release published to the specified channel. Updates to the channel are automatically installed.
+
+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 when updates are published to the catalog.
+
+If you want to update the version of the Operator that is installed on the cluster, you must manually update the Operator's CR. Specifying a Operator's target version pins the Operator's version to the specified release.
+
+.Example CR with the target version specified
+[source,yaml]
+----
+apiVersion: operators.operatorframework.io/v1alpha1
+kind: Operator
+metadata:
+  name: quay-example
+spec:
+  packageName: quay-operator
+  version: 3.8.12 <1>
+----
+<1> Specifies the target version. If you want to update the version of the Operator that is installed on the cluster, you must manually update this field the Operator's CR to the desired target version.
+
+If you want to change the installed version of an Operator, edit the Operator's CR to the desired target version.
+
+[WARNING]
+====
+In previous versions of OLM, Operator authors could define upgrade edges to prevent you from updating to unsupported versions. In its current state of development, OLM 1.0 does not enforce upgrade edge definitions. You can specify any version of an Operator, and OLM 1.0 attempts to apply the update.
+====
+
+You can inspect an Operator's catalog contents, including available versions and channels, by running the following command:
+
+.Command syntax
+[source,terminal]
+----
+$ oc get package <catalog_name>-<operator_name> -o yaml
+----
+
+After a you create or update a CR, create or configure the Operator by running the following command:
+
+.Command syntax
+[source,terminal]
+----
+$ oc apply -f <extension_name>.yaml
+----
+
+.Troubleshooting
+
+* If you specify 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,110 @@
+// 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,subs="attributes+"]
+----
+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.
+
+. Add the catalog to your cluster by running the following command:
++
+[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:
+
+.. Check if you catalog is available by running the following command:
++
+[source,terminal]
+----
+$ oc get catalog
+----
++
+.Example output
+[source,text]
+----
+NAME                  AGE
+redhat-operators      20s
+----
+
+.. Check the status of your catalog by running the following command:
++
+[source,terminal]
+----
+$ oc get catalogs.catalogd.operatorframework.io -o yaml
+----
++
+.Example output
+[source,text,subs="attributes+"]
+----
+apiVersion: v1
+items:
+- apiVersion: catalogd.operatorframework.io/v1alpha1
+  kind: Catalog
+  metadata:
+    annotations:
+      kubectl.kubernetes.io/last-applied-configuration: |
+        {"apiVersion":"catalogd.operatorframework.io/v1alpha1","kind":"Catalog","metadata":{"annotations":{},"name":"redhat-operators"},"spec":{"source":{"image":{"ref":"registry.redhat.io/redhat/redhat-operator-index:v4.14"},"type":"image"}}}
+    creationTimestamp: "2023-10-16T13:30:59Z"
+    generation: 1
+    name: redhat-operators
+    resourceVersion: "37304"
+    uid: cf00c68c-4312-4e06-aa8a-299f0bbf496b
+  spec:
+    source:
+      image:
+        ref: registry.redhat.io/redhat/redhat-operator-index:v{product-version}
+      type: image
+  status: <1>
+    conditions:
+    - lastTransitionTime: "2023-10-16T13:32:25Z"
+      message: successfully unpacked the catalog image "registry.redhat.io/redhat/redhat-operator-index@sha256:bd2f1060253117a627d2f85caa1532ebae1ba63da2a46bdd99e2b2a08035033f" <2>
+      reason: UnpackSuccessful <3>
+      status: "True"
+      type: Unpacked
+    phase: Unpacked <4>
+    resolvedSource:
+      image:
+        ref: registry.redhat.io/redhat/redhat-operator-index@sha256:bd2f1060253117a627d2f85caa1532ebae1ba63da2a46bdd99e2b2a08035033f <5>
+      type: image
+kind: List
+metadata:
+  resourceVersion: ""
+----
+<1> Stanza describing the status of the catalog.
+<2> Output message of the status of the catalog.
+<3> Displays the reason the catalog is in the current state.
+<4> Displays the phase of the installion process.
+<5> Displays the image reference of the catalog.

modules/olmv1-deleting-an-operator.adoc

@@ -0,0 +1,60 @@
+// 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 and its custom resource definitions (CRDs) by deleting the Operator's custom resource (CR).
+
+.Prerequisites
+
+* You have a catalog installed.
+* You have an Operator installed.
+
+.Procedure
+
+* Delete an Operator and its CRDs by running the following command:
++
+[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 and its resources were deleted:
+
+** Verify the Operator is deleted by running the following command:
++
+[source,terminal]
+----
+$ oc get operator.operators.operatorframework.io
+----
++
+.Example output
+[source,text]
+----
+No resources found
+----
+
+** Verify that the Operator's system namespace is deleted by running the following command:
++
+[source,terminal]
+----
+$ oc get ns quay-operator-system
+----
++
+.Example output
+[source,text]
+----
+Error from server (NotFound): namespaces "quay-operator-system" not found
+----