4.14 OLM 1.0 Tech Preview procedures

openshift · Oct 16, 2023 · fa7cc57 · fa7cc57
1 parent f8f64ed
commit fa7cc57
Show file tree

Hide file tree

Showing 10 changed files with 865 additions and 0 deletions.
diff --git a/_topic_maps/_topic_map.yml b/_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

diff --git a/modules/olmv1-about-catalogs.adoc b/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 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.
diff --git a/modules/olmv1-about-target-versions.adoc b/modules/olmv1-about-target-versions.adoc
@@ -0,0 +1,138 @@
+// 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 the Operator's version is not specified in the CR, then OLM 1.0 defaults to the latest 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 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 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. 
+
+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 the Operator's CR.
+
+If you want to change the installed version of an Operator, edit the Operator's CR to desired target version.
+
+.Example CR with an updated target version
+[source,yaml]
+----
+apiVersion: operators.operatorframework.io/v1alpha1
+kind: Operator
+metadata:
+  name: quay-example
+spec:
+  packageName: quay-operator
+  version: 3.9.1 <1>
+----
+<1> Updates the target version of the Operator to version 3.9.1.
+
+[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 supported versions, 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
+----
+====
diff --git a/modules/olmv1-adding-a-catalog.adoc b/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.
+
+. Run the following command to add the catalog to your cluster:
++
+[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 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:v4.14
+      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> Displays 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.
diff --git a/modules/olmv1-deleting-an-operator.adoc b/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 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
+
+* Run the following command to delete an Operator and its CRDs:
++
+[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
+----