OSDOCS#6673: Add initial OLM v1 subdir

_topic_maps/_topic_map.yml

@@ -1865,6 +1865,16 @@ 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: 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-catalog-plain.adoc

@@ -0,0 +1,244 @@
+// Module included in the following assemblies:
+//
+// * operators/olm_v1/olmv1-managing-catalogs.adoc
+
+ifdef::openshift-origin[]
+:registry-image: quay.io/operator-framework/opm:latest
+endif::[]
+ifndef::openshift-origin[]
+:registry-image: registry.redhat.io/openshift4/ose-operator-registry:v{product-version}
+endif::[]
+
+:_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_.
+
+.Prequisites
+
+* You have Kubernetes manifests for your bundle in a flat directory at the root of your project similar to the following structure:
++
+.Example directory structure
+[source,terminal]
+----
+manifests
+├── namespace.yaml
+├── service_account.yaml
+├── cluster_role.yaml
+├── cluster_role_binding.yaml
+└── deployment.yaml
+----
+
+.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 OCI-compliant image 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:
++
+[source,terminal]
+----
+$ podman push quay.io/<organization_name>/<repository_name>:<image_tag>
+----
+
+[id="olmv1-creating-fbc_{context}"]
+= Creating a file-based catalog
+
+If you do not have a file-based catalog, you must perform the following steps to initialize the catalog.
+
+.Procedure
+
+. Create a directory for the catalog by running the following command:
++
+[source,terminal]
+----
+$ mkdir <catalog_dir>
+----
+
+. Generate a Dockerfile that can build a catalog image by running the `opm generate dockerfile` command in the same directory level as the previous step:
++
+[source,terminal,subs="attributes+"]
+----
+ifdef::openshift-origin[]
+$ opm generate dockerfile <catalog_dir>
+endif::[]
+ifndef::openshift-origin[]
+$ opm generate dockerfile <catalog_dir> \
+    -i {registry-image} <1>
+endif::[]
+----
+ifndef::openshift-origin[]
+<1> Specify the official Red Hat base image by using the `-i` flag, otherwise the Dockerfile uses the default upstream image.
+endif::[]
++
+[NOTE]
+====
+The generated Dockerfile must be in the same parent directory as the catalog directory that you created in the previous step:
+
+.Example directory structure
+[source,terminal]
+----
+.
+├── <catalog_dir>
+└── <catalog_dir>.Dockerfile
+----
+====
+
+. Populate the catalog with the package definition for your extension by running the `opm init` command:
++
+[source,terminal]
+----
+$ opm init <extension_name> \
+    --output json \
+    > <catalog_dir>/index.json
+----
++
+This command generates an `olm.package` declarative config blob in the specified catalog configuration file.
+
+[id="olmv1-adding-plain-bundle-to-fbc_{context}"]
+= Adding a plain bundle to a file-based catalog
+
+Currently, 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 your catalog's `index.json` or `index.yaml` file 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",
+}
+{
+    "schema": "olm.bundle",
+    "name": "example-extension.v0.0.1",
+    "package": "example-extension",
+    "image": "quay.io/rashmigottipati/example-extension-bundle:v0.0.1",
+    "properties": [
+        {
+            "type": "olm.package",
+            "value": {
+            "packageName": "example-extension",
+            "version": "v0.0.1"
+            }
+        },
+        {
+            "type": "olm.bundle.mediatype",
+            "value": "plain+v0"
+        }
+    ]
+}
+{
+    "schema": "olm.channel",
+    "name": "preview",
+    "package": "example-extension",
+    "entries": [
+        {
+            "name": "example-extension.v0.0.1"
+        }
+    ]
+}
+----
+
+[id="olmv1-publishing-fbc_{context}"]
+= Building and publishing a file-based catalog
+
+.Procedure
+
+. Build your file-bsaed catalog as an image by running the following command:
++
+[source,terminal]
+----
+$ podman build -f <catalog_dir>.Dockerfile -t \
+    quay.io/<organization_name>/<repository_name>:<image_tag> .
+----
+
+. Push your catalog image by running the following command:
++
+[source,terminal]
+----
+$ podman push quay.io/<organization_name>/<repository_name>:<image_tag>
+----
+
+:!registry-image:

operators/olm_v1/_attributes

@@ -0,0 +1 @@
+../../_attributes/

operators/olm_v1/images

@@ -0,0 +1 @@
+../../images/

operators/olm_v1/index.adoc

@@ -0,0 +1,32 @@
+:_content-type: ASSEMBLY
+[id="olmv1-about"]
+= About Operator Lifecycle Manager v1 (Technology Preview)
+include::_attributes/common-attributes.adoc[]
+:context: olmv1-about
+
+toc::[]
+
+{product-title} 4.14 introduces components for a next-generation iteration of Operator Lifecycle Manager (OLM) as a Technology Preview feature. Known during this phase as OLM v1, the updated framework evolves many of the concepts that have been part of the version of OLM included since the release of {product-title} 4.
+
+:FeatureName: OLM v1
+include::snippets/technology-preview.adoc[]
+
+During this Technology Preview phase of OLM v1 in {product-title} 4.14, administrators can use file-based catalogs to install and manage the following:
+
+* OLM-based Operators, similar to the existing OLM experience
+* Plain bundles, which are static collections of arbitrary Kubernetes manifests
+
+[id="olmv1-about-purpose"]
+== 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 administrators and platform-as-a-service (PaaS) administrators, throughout the lifecycle of the underlying cluster.
+
+The existing version of OLM, which launched with {product-title} 4 and is included by default, was focused on providing unique support for these specific needs for a particular type of cluster extension, which have been referred as Operators. Operators are classified as one or more Kubernetes controllers, shipping with one or more API extensions (`CustomResourceDefinition` objects) to provide additional functionality to the cluster.
+
+After running OLM in production clusters for many releases, it became apparent that there is a desire to deviate from this coupling of CRDs and controllers to encompass the lifecycling of extensions that are not just Operators.
+
+Some of the goals of OLM v1 over the upcoming releases include improving Operator and extension lifecycle management in the following areas:
+
+* Tenant isolation
+* Dependencies and constraints
+* Simplified packaging models

operators/olm_v1/modules

@@ -0,0 +1 @@
+../../modules/

operators/olm_v1/olmv1-managing-catalogs.adoc

@@ -0,0 +1,51 @@
+:_content-type: ASSEMBLY
+[id="olmv1-managing-catalogs"]
+= Managing catalogs for OLM v1 (Technology Preview)
+include::_attributes/common-attributes.adoc[]
+:context: olmv1-managing-catalogs
+
+toc::[]
+
+In OLM v1, a _plain bundle_ is a static collection of arbitrary Kubernetes manifests in YAML format. The experimental `olm.bundle.mediatype` property of the `olm.bundle` schema object differentiates a plain bundle (`plain+v0`) from a regular (`registry+v1`) bundle.
+
+:FeatureName: OLM v1
+include::snippets/technology-preview.adoc[]
+
+// For more information, see the [Plain Bundle Specification](https://github.com/operator-framework/rukpak/blob/main/docs/bundles/plain.md) in the RukPak repository.
+
+As a cluster administrator, you can build and publish a file-based catalog that includes a plain bundle image by completing the following procedures:
+
+. Build a plain bundle image.
+. Create a file-based catalog.
+. Add the plain bundle image to your file-based catalog.
+. Build your catalog as an image.
+. Publish your catalog image.
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../operators/olm_v1/olmv1-packaging-format.adoc#olmv1-packaging-format[RukPak component and packaging format]
+
+[id="prerequisites_olmv1-plain-bundles"]
+== Prerequisites
+
+- Access to an {product-title} cluster using an account with `cluster-admin` permissions
+- The `TechPreviewNoUpgrades` feature set enabled on the cluster
++
+[WARNING]
+====
+Enabling the `TechPreviewNoUpgrade` feature set cannot be undone and prevents minor version updates. These feature sets are not recommended on production clusters.
+====
+- The `oc` command installed on your workstation
+- `opm` CLI tool
+- Docker or Podman
+- Push access to a container registry, such as link:https://quay.io[Quay]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling[Enabling features using feature gates]
+
+// - Only the `redhat-operators` catalog source enabled on the cluster. This is a restriction during the Technology Preview release.
+
+include::modules/olmv1-catalog-plain.adoc[leveloffset=+1]