Managing plain bundles in OLM 1.0 (Technology Preview)

Managing plain bundles in OLM 1.0 (Technology Preview)

In Operator Lifecycle Manager (OLM) 1.0, 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.

OLM 1.0 is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

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.

Additional resources

RukPak component and packaging format

Prerequisites

Access to an OKD cluster using an account with cluster-admin permissions

For OKD 4.14, documented procedures for OLM 1.0 are CLI-based only. Alternatively, administrators can create and view related objects in the web console by using normal methods, such as the Import YAML and Search pages. However, the existing OperatorHub and Installed Operators pages do not yet display OLM 1.0 components.

The TechPreviewNoUpgrades feature set enabled on the cluster

Enabling the TechPreviewNoUpgrade feature set cannot be undone and prevents minor version updates. These feature sets are not recommended on production clusters.
The OpenShift CLI (oc) installed on your workstation
The opm CLI installed on your workstation
Docker or Podman installed on your workstation
Push access to a container registry, such as Quay

Kubernetes manifests for your bundle in a flat directory at the root of your project similar to the following structure:

Example directory structure

manifests
├── namespace.yaml
├── service_account.yaml
├── cluster_role.yaml
├── cluster_role_binding.yaml
└── deployment.yaml

Additional resources

Enabling features using feature gates

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
```
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:
```
$ 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:
```
$ podman push quay.io/<organization_name>/<repository_name>:<image_tag>
```

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:
```
$ 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:

$ opm generate dockerfile <catalog_dir>

The generated Dockerfile must be in the same parent directory as the catalog directory that you created in the previous step:

Example directory structure

.
├── <catalog_dir>
└── <catalog_dir>.Dockerfile

Populate the catalog with the package definition for your extension by running the opm init command:
```
$ 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.

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
```
{
    {
     "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

{
   "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

{
    "schema": "olm.channel",
    "name": "<desired_channel_name>",
    "package": "<extension_name>",
    "entries": [
        {
            "name": "<extension_name>.v<version>"
        }
    ]
}

Verification

Open your index.json or index.yaml file and ensure it is similar to the following example:

Example <catalog_dir>/index.json file

{
    "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:
```
$ opm validate <catalog_dir>
```

Building and publishing a file-based catalog

Procedure

Build your file-based catalog as an image by running the following command:

$ podman build -f <catalog_dir>.Dockerfile -t \
    quay.io/<organization_name>/<repository_name>:<image_tag> .

Push your catalog image by running the following command:

$ podman push quay.io/<organization_name>/<repository_name>:<image_tag>