[4.14] OLM 1.0 add catalog & install Operator procedures

_topic_maps/_topic_map.yml

@@ -1819,6 +1819,18 @@ Topics:
     Distros: openshift-origin
 - Name: Cluster Operators reference
   File: operator-reference
+- Name: OLM v1 (Technology Preview)
+  Dir: olm_v1
+  Distros: openshift-origin,openshift-enterprise
+  Topics:
+  - Name: About OLM v1
+    File: index
+  - Name: Packaging format
+    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/olm-rukpak-about.adoc

@@ -4,12 +4,17 @@
 
 :_content-type: CONCEPT
 [id="olm-rukpak-about_{context}"]
+ifeval::["{context}" == "olm-packaging-format"]
 = RukPak (Technology Preview)
 
 :FeatureName: RukPak
 include::snippets/technology-preview.adoc[]
 
 {product-title} 4.12 introduces the _platform Operator_ type as a Technology Preview feature. The platform Operator mechanism relies on the RukPak component, also introduced in {product-title} 4.12, and its resources to manage content.
+endif::[]
+ifeval::["{context}" == "olmv1-packaging-format"]
+= RukPak
+endif::[]
 
 RukPak consists of a series of controllers, known as _provisioners_, that install and manage content on a Kubernetes cluster. RukPak also provides two primary APIs: `Bundle` and `BundleDeployment`. These components work together to bring content onto the cluster and install it, generating resources within the cluster.
 

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,76 @@
+// 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 the set 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 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
+  version: <1> 
+----
+<1> Leave the target version unspecified to automatically set the version to the latest stable version.
+
+[IMPORTANT]
+====
+What about a specified channel with an unspecified version?
+====
+
+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 does not update 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. As long as the update is supported by the skip ranges defined in the catalog, you can update across channels and even downgrade 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
+----

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: PRODCEDURE
+
+[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
+----