Merge pull request #65963 from adellape/arch_olmv1

Author: adellape

_attributes/common-attributes.adoc

@@ -187,6 +187,9 @@ endif::[]
 :osdk_ver: 1.31.0
 //Operator SDK version that shipped with the previous OCP 4.x release
 :osdk_ver_n1: 1.28.0
+//Next-gen (OCP 4.14+) Operator Lifecycle Manager, aka "v1"
+:olmv1: OLM 1.0
+:olmv1-first: Operator Lifecycle Manager (OLM) 1.0
 :ztp-first: GitOps Zero Touch Provisioning (ZTP)
 :ztp: GitOps ZTP
 :3no: three-node OpenShift

_topic_maps/_topic_map.yml

@@ -1858,18 +1858,29 @@ Topics:
     Distros: openshift-origin
 - Name: Cluster Operators reference
   File: operator-reference
-- Name: OLM v1 (Technology Preview)
+- Name: OLM 1.0 (Technology Preview)
   Dir: olm_v1
   Distros: openshift-origin,openshift-enterprise
   Topics:
-  - Name: About OLM v1
+  - Name: About OLM 1.0
     File: index
-  - Name: Packaging format
-    File: olmv1-packaging-format
-  - Name: Managing catalogs
-    File: olmv1-managing-catalogs
+  - Name: Components and architecture
+    Dir: arch
+    Topics:
+    - Name: Components overview
+      File: olmv1-components
+    - Name: Operator Controller
+      File: olmv1-operator-controller
+    - Name: RukPak
+      File: olmv1-rukpak
+    - Name: Dependency resolution
+      File: olmv1-dependency
+    - Name: Catalogd
+      File: olmv1-catalogd
   - Name: Installing an Operator from a catalog
     File: olmv1-installing-an-operator-from-a-catalog
+  - Name: Managing plain bundles
+    File: olmv1-managing-plain-bundles
 ---
 Name: CI/CD
 Dir: cicd

modules/olm-rukpak-about.adoc

@@ -1,6 +1,7 @@
 // Module included in the following assemblies:
 //
 // * operators/understanding/olm-packaging-format.adoc
+// * operators/olm_v1/olmv1_rukpak.adoc
 
 :_content-type: CONCEPT
 [id="olm-rukpak-about_{context}"]
@@ -11,13 +12,28 @@ ifeval::["{context}" == "olm-packaging-format"]
 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.
+
+{product-title} 4.14 introduces {olmv1-first} as a Technology Preview feature, which also relies on the RukPak component.
 endif::[]
-ifeval::["{context}" == "olmv1-packaging-format"]
-= RukPak
+ifeval::["{context}" == "olmv1-rukpak"]
+= About 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.
+RukPak is a pluggable solution for packaging and distributing cloud-native content. It supports advanced strategies for installation, updates, and policy.
+
+RukPak provides a content ecosystem for installing a variety of artifacts on a Kubernetes cluster. Artifact examples include Git repositories, Helm charts, and OLM bundles. RukPak can then manage, scale, and upgrade these artifacts in a safe way to enable powerful cluster extensions.
+
+At its core, RukPak is a small set of APIs and controllers. The APIs are packaged as custom resource definitions (CRDs) that express what content to install on a cluster and how to create a running deployment of the content. The controllers watch for the APIs.
 
-A provisioner places a watch on both `Bundle` and `BundleDeployment` resources that refer to the provisioner explicitly. For a given bundle, the provisioner unpacks the contents of the `Bundle` resource onto the cluster. Then, given a `BundleDeployment` resource referring to that bundle, the provisioner installs the bundle contents and is responsible for managing the lifecycle of those resources.
+.Common terminology
 
-Two provisioners are currently implemented and bundled with RukPak: the _plain provisioner_ that sources and unpacks `plain+v0` bundles, and the _registry provisioner_ that sources and unpacks Operator Lifecycle Manager (OLM) `registry+v1` bundles.
+Bundle::
+A collection of Kubernetes manifests that define content to be deployed to a cluster
+Bundle image::
+A container image that contains a bundle within its filesystem
+Bundle Git repository::
+A Git repository that contains a bundle within a directory
+Provisioner::
+Controllers that install and manage content on a Kubernetes cluster
+Bundle deployment::
+Generates deployed instances of a bundle

modules/olm-rukpak-plain-bundle.adoc

@@ -20,13 +20,13 @@ For example, the following shows the file tree in a `plain+v0` bundle. It must h
 .Example `plain+v0` bundle file tree
 [source,terminal]
 ----
+$ tree manifests
+
 manifests
 ├── namespace.yaml
+├── service_account.yaml
 ├── cluster_role.yaml
-├── role.yaml
-├── serviceaccount.yaml
 ├── cluster_role_binding.yaml
-├── role_binding.yaml
 └── deployment.yaml
 ----
 

modules/olm-rukpak-provisioner.adoc

@@ -1,11 +1,16 @@
 // Module included in the following assemblies:
 //
 // * operators/understanding/olm-packaging-format.adoc
+// * operators/olm_v1/olmv1_rukpak.adoc
 
 :_content-type: CONCEPT
 [id="olm-rukpak-provisioner_{context}"]
-= Provisioner
+= About provisioners
 
-A RukPak provisioner is a controller that understands the `BundleDeployment` and `Bundle` APIs and can take action. Each provisioner is assigned a unique ID and is responsible for reconciling `Bundle` and `BundleDeployment` objects with a `spec.provisionerClassName` field that matches that particular ID.
+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.
 
-For example, the plain provisioner is able to unpack a given `plain+v0` bundle onto a cluster and then instantiate it, making the content of the bundle available in the cluster.
+Two provisioners are currently implemented and bundled with RukPak: the _plain provisioner_ that sources and unpacks `plain+v0` bundles, and the _registry provisioner_ that sources and unpacks Operator Lifecycle Manager (OLM) `registry+v1` bundles.
+
+Each provisioner is assigned a unique ID and is responsible for reconciling `Bundle` and `BundleDeployment` objects with a `spec.provisionerClassName` field that matches that particular ID. For example, the plain provisioner is able to unpack a given `plain+v0` bundle onto a cluster and then instantiate it, making the content of the bundle available in the cluster.
+
+A provisioner places a watch on both `Bundle` and `BundleDeployment` resources that refer to the provisioner explicitly. For a given bundle, the provisioner unpacks the contents of the `Bundle` resource onto the cluster. Then, given a `BundleDeployment` resource referring to that bundle, the provisioner installs the bundle contents and is responsible for managing the lifecycle of those resources.

modules/olmv1-about-catalogs.adoc

@@ -1,10 +1,11 @@
 // Module included in the following assemblies:
 //
 // * operators/olm_v1/olmv1-installing-an-operator-from-a-catalog.adoc
+// * operators/olm_v1/arch/olmv1-catalogd.adoc
 
 :_content-type: CONCEPT
 
 [id="olmv1-about-catalogs_{context}"]
-= About catalogs in OLM 1.0
+= About catalogs in {olmv1}
 
-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.
+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 {olmv1-first} suite of microservices. Currently, catalogd unpacks catalog content that is packaged and distributed as container images.

modules/olmv1-about-purpose.adoc

@@ -0,0 +1,14 @@
+// Module included in the following assemblies:
+//
+// * operators/olm_v1/index.adoc
+
+:_content-type: CONCEPT
+
+[id="olmv1-about-purpose_{context}"]
+= Purpose
+
+The mission of Operator Lifecycle Manager (OLM) has been to manage the lifecycle of cluster extensions centrally and declaratively on Kubernetes clusters. Its purpose has always been to make installing, running, and updating functional extensions to the cluster easy, safe, and reproducible for cluster and platform-as-a-service (PaaS) administrators throughout the lifecycle of the underlying cluster.
+
+The initial version of OLM, which launched with {product-title} 4 and is included by default, focused on providing unique support for these specific needs for a particular type of cluster extension, known as Operators. Operators are classified as one or more Kubernetes controllers, shipping with one or more API extensions, as `CustomResourceDefinition` (CRD) objects, to provide additional functionality to the cluster.
+
+After running in production clusters for many releases, the next-generation of OLM aims to encompass lifecycles for cluster extensions that are not just Operators.

modules/olmv1-about-target-versions.adoc

@@ -1,15 +1,16 @@
 // Module included in the following assemblies:
 //
 // * operators/olm_v1/olmv1-installing-an-operator-from-a-catalog.adoc
+// * operators/olm_v1/arch/olmv1-operator-controller.adoc
 
 :_content-type: CONCEPT
 
 [id="olmv1-about-operator-updates_{context}"]
-= About target versions in OLM 1.0
+= About target versions in {olmv1}
 
-In Operator Lifecycle Manager 1.0, cluster administrators set the target version of an Operator declaratively in the Operator's custom resource (CR).
+In {olmv1-first}, 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.
+If you specify a channel in the Operator's CR, {olmv1} installs the latest release from the specified channel. When updates are published to the specified channel, {olmv1} automatically updates to the latest release from the channel.
 
 .Example CR with a specified channel
 [source,yaml]
@@ -24,7 +25,7 @@ spec:
 ----
 <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 specify the Operator's target version in the CR, {olmv1} installs the specified version. When the target version is specified in the Operator's CR, {olmv1} 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.
 
@@ -45,7 +46,7 @@ If you want to change the installed version of an Operator, edit the Operator's
 
 [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.
+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, {olmv1} does not enforce upgrade edge definitions. You can specify any version of an Operator, and {olmv1} attempts to apply the update.
 ====
 
 You can inspect an Operator's catalog contents, including available versions and channels, by running the following command:
@@ -56,7 +57,7 @@ You can inspect an Operator's catalog contents, including available versions and
 $ oc get package <catalog_name>-<package_name> -o yaml
 ----
 
-After a you create or update a CR, create or configure the Operator by running the following command:
+After you create or update a CR, create or configure the Operator by running the following command:
 
 .Command syntax
 [source,terminal]
@@ -70,7 +71,7 @@ $ oc apply -f <extension_name>.yaml
 +
 [source,terminal]
 ----
-$ oc get operators.operators.operatorframework.io <operator_name> -o yaml
+$ oc get operator.operators.operatorframework.io <operator_name> -o yaml
 ----
 +
 .Example output

modules/olmv1-adding-plain-to-fbc.adoc

@@ -0,0 +1,121 @@
+// Module included in the following assemblies:
+//
+// * operators/olm_v1/olmv1-plain-bundles.adoc
+
+:_content-type: PROCEDURE
+
+[id="olmv1-adding-plain-bundle-to-fbc_{context}"]
+= Adding a plain bundle to a file-based catalog
+
+The `opm render` command does not support adding plain bundles to catalogs. You must manually add plain bundles to your file-based catalog, as shown in the following procedure.
+
+.Procedure
+
+. Verify that the `index.json` or `index.yaml` file for your catalog is similar to the following example:
++
+.Example `<catalog_dir>/index.json` file
+[source,json]
+----
+{
+    {
+     "schema": "olm.package",
+     "name": "<extension_name>",
+     "defaultChannel": ""
+    }
+}
+----
+
+. To create an `olm.bundle` blob, edit your `index.json` or `index.yaml` file, similar to the following example:
++
+.Example `<catalog_dir>/index.json` file with `olm.bundle` blob
+[source,json]
+----
+{
+   "schema": "olm.bundle",
+    "name": "<extension_name>.v<version>",
+    "package": "<extension_name>",
+    "image": "quay.io/<organization_name>/<repository_name>:<image_tag>",
+    "properties": [
+        {
+            "type": "olm.package",
+            "value": {
+            "packageName": "<extension_name>",
+            "version": "<bundle_version>"
+            }
+        },
+        {
+            "type": "olm.bundle.mediatype",
+            "value": "plain+v0"
+        }
+  ]
+}
+----
+
+. To create an `olm.channel` blob, edit your `index.json` or `index.yaml` file, similar to the following example:
++
+.Example `<catalog_dir>/index.json` file with `olm.channel` blob
+[source,json]
+----
+{
+    "schema": "olm.channel",
+    "name": "<desired_channel_name>",
+    "package": "<extension_name>",
+    "entries": [
+        {
+            "name": "<extension_name>.v<version>"
+        }
+    ]
+}
+----
+
+// Please refer to [channel naming conventions](https://olm.operatorframework.io/docs/best-practices/channel-naming/) for choosing the <desired_channel_name>. An example of the <desired_channel_name> is `candidate-v0`.
+
+.Verification
+
+. Open your `index.json` or `index.yaml` file and ensure it is similar to the following example:
++
+.Example `<catalog_dir>/index.json` file
+[source,json]
+----
+{
+    "schema": "olm.package",
+    "name": "example-extension",
+    "defaultChannel": "preview"
+}
+{
+    "schema": "olm.bundle",
+    "name": "example-extension.v0.0.1",
+    "package": "example-extension",
+    "image": "quay.io/example-org/example-extension-bundle:v0.0.1",
+    "properties": [
+        {
+            "type": "olm.package",
+            "value": {
+            "packageName": "example-extension",
+            "version": "0.0.1"
+            }
+        },
+        {
+            "type": "olm.bundle.mediatype",
+            "value": "plain+v0"
+        }
+    ]
+}
+{
+    "schema": "olm.channel",
+    "name": "preview",
+    "package": "example-extension",
+    "entries": [
+        {
+            "name": "example-extension.v0.0.1"
+        }
+    ]
+}
+----
+
+. Validate your catalog by running the following command:
++
+[source,terminal]
+----
+$ opm validate <catalog_dir>
+----

modules/olmv1-building-plain-image.adoc

@@ -0,0 +1,38 @@
+// Module included in the following assemblies:
+//
+// * operators/olm_v1/olmv1-plain-bundles.adoc
+
+:_content-type: PROCEDURE
+
+[id="olmv1-building-plain-bundle-image-source_{context}"]
+= Building a plain bundle image from an image source
+
+The Operator Controller currently supports installing plain bundles created only from a _plain bundle image_.
+
+.Procedure
+
+. At the root of your project, create a Dockerfile that can build a bundle image:
++
+.Example `plainbundle.Dockerfile`
+[source,docker]
+----
+FROM scratch <1>
+ADD manifests /manifests
+----
+<1> Use the `FROM scratch` directive to make the size of the image smaller. No other files or directories are required in the bundle image.
+
+. Build an Open Container Initiative (OCI)-compliant image by using your preferred build tool, similar to the following example:
++
+[source,terminal]
+----
+$ podman build -f plainbundle.Dockerfile -t \
+    quay.io/<organization_name>/<repository_name>:<image_tag> . <1>
+----
+<1> Use an image tag that references a repository where you have push access privileges.
+
+. Push the image to your remote registry by running the following command:
++
+[source,terminal]
+----
+$ podman push quay.io/<organization_name>/<repository_name>:<image_tag>
+----