×

Cluster administrators and Operator catalog maintainers can create and managing custom catalogs packaged using the bundle format on Operator Lifecycle Manager (OLM) in OpenShift Container Platform.

Kubernetes periodically deprecates certain APIs that are removed in subsequent releases. As a result, Operators are unable to use removed APIs starting with the version of OpenShift Container Platform that uses the Kubernetes version that removed the API.

If your cluster is using custom catalogs, see Controlling Operator compatibility with OpenShift Container Platform versions for more details about how Operator authors can update their projects to help avoid workload issues and prevent incompatible upgrades.

Additional resources

Prerequisites

File-based catalogs

File-based catalogs are the latest iteration of the catalog format in Operator Lifecycle Manager (OLM). It is a plain text-based (JSON or YAML) and declarative config evolution of the earlier SQLite database format, and it is fully backwards compatible.

As of OpenShift Container Platform 4.11, the default Red Hat-provided Operator catalog releases in the file-based catalog format. The default Red Hat-provided Operator catalogs for OpenShift Container Platform 4.6 through 4.10 released in the deprecated SQLite database format.

The opm subcommands, flags, and functionality related to the SQLite database format are also deprecated and will be removed in a future release. The features are still supported and must be used for catalogs that use the deprecated SQLite database format.

Many of the opm subcommands and flags for working with the SQLite database format, such as opm index prune, do not work with the file-based catalog format. For more information about working with file-based catalogs, see Operator Framework packaging format and Mirroring images for a disconnected installation using the oc-mirror plug-in.

Creating a file-based catalog image

You can create a catalog image that uses the plain text file-based catalog format (JSON or YAML), which replaces the deprecated SQLite database format. The opm CLI provides tooling that helps initialize a catalog in the file-based format, render new records into it, and validate that the catalog is valid.

Prerequisites
  • opm

  • podman version 1.9.3+

  • A bundle image built and pushed to a registry that supports Docker v2-2

Procedure
  1. Initialize a catalog for a file-based catalog:

    1. Create a directory for the catalog:

      $ mkdir <operator_name>-index
    2. Create a Dockerfile that can build a catalog image:

      Example <operator_name>-index.Dockerfile
      # The base image is expected to contain
      # /bin/opm (with a serve subcommand) and /bin/grpc_health_probe
      FROM registry.redhat.io/openshift4/ose-operator-registry:v4.9
      
      # Configure the entrypoint and command
      ENTRYPOINT ["/bin/opm"]
      CMD ["serve", "/configs"]
      
      # Copy declarative config root into image at /configs
      ADD <operator_name>-index /configs
      
      # Set DC-specific label for the location of the DC root directory
      # in the image
      LABEL operators.operatorframework.io.index.configs.v1=/configs

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

      Example directory structure
      .
      ├── <operator_name>-index
      └── <operator_name>-index.Dockerfile
    3. Populate the catalog with your package definition:

      $ opm init <operator_name> \ (1)
          --default-channel=preview \ (2)
          --description=./README.md \ (3)
          --icon=./operator-icon.svg \ (4)
          --output yaml \ (5)
          > <operator_name>-index/index.yaml (6)
      1 Operator, or package, name.
      2 Channel that subscription will default to if unspecified.
      3 Path to the Operator’s README.md or other documentation.
      4 Path to the Operator’s icon.
      5 Output format: JSON or YAML.
      6 Path for creating the catalog configuration file.

      This command generates an olm.package declarative config blob in the specified catalog configuration file.

  2. Add a bundle to the catalog:

    $ opm render <registry>/<namespace>/<bundle_image_name>:<tag> \ (1)
        --output=yaml \
        >> <operator_name>-index/index.yaml (2)
    1 Pull spec for the bundle image.
    2 Path to the catalog configuration file.

    The opm render command generates a declarative config blob from the provided catalog images and bundle images.

    Channels must contain at least one bundle.

  3. Add a channel entry for the bundle. For example, modify the following example to your specifications, and add it to your <operator_name>-index/index.yaml file:

    Example channel entry
    ---
    schema: olm.channel
    package: <operator_name>
    name: preview
    entries:
      - name: <operator_name>.v0.1.0 (1)
    1 Ensure that you include the period (.) after <operator_name> but before the v in the version. Otherwise, the entry will fail to pass the opm validate command.
  4. Validate the file-based catalog:

    1. Run the opm validate command against the catalog directory:

      $ opm validate <operator_name>-index
    2. Check that the error code is 0:

      $ echo $?
      Example output
      0
  5. Build the catalog image:

    $ podman build . \
        -f <operator_name>-index.Dockerfile \
        -t <registry>/<namespace>/<catalog_image_name>:<tag>
  6. Push the catalog image to a registry:

    1. If required, authenticate with your target registry:

      $ podman login <registry>
    2. Push the catalog image:

      $ podman push <registry>/<namespace>/<catalog_image_name>:<tag>

SQLite-based catalogs

The SQLite database format for Operator catalogs is a deprecated feature. Deprecated functionality is still included in OpenShift Container Platform and continues to be supported; however, it will be removed in a future release of this product and is not recommended for new deployments.

For the most recent list of major functionality that has been deprecated or removed within OpenShift Container Platform, refer to the Deprecated and removed features section of the OpenShift Container Platform release notes.

Creating a SQLite-based index image

You can create an index image based on the SQLite database format by using the opm CLI.

Prerequisites
  • opm

  • podman version 1.9.3+

  • A bundle image built and pushed to a registry that supports Docker v2-2

Procedure
  1. Start a new index:

    $ opm index add \
        --bundles <registry>/<namespace>/<bundle_image_name>:<tag> \(1)
        --tag <registry>/<namespace>/<index_image_name>:<tag> \(2)
        [--binary-image <registry_base_image>] (3)
    1 Comma-separated list of bundle images to add to the index.
    2 The image tag that you want the index image to have.
    3 Optional: An alternative registry base image to use for serving the catalog.
  2. Push the index image to a registry.

    1. If required, authenticate with your target registry:

      $ podman login <registry>
    2. Push the index image:

      $ podman push <registry>/<namespace>/<index_image_name>:<tag>

Updating a SQLite-based index image

After configuring OperatorHub to use a catalog source that references a custom index image, cluster administrators can keep the available Operators on their cluster up to date by adding bundle images to the index image.

You can update an existing index image using the opm index add command.

Prerequisites
  • opm

  • podman version 1.9.3+

  • An index image built and pushed to a registry.

  • An existing catalog source referencing the index image.

Procedure
  1. Update the existing index by adding bundle images:

    $ opm index add \
        --bundles <registry>/<namespace>/<new_bundle_image>@sha256:<digest> \(1)
        --from-index <registry>/<namespace>/<existing_index_image>:<existing_tag> \(2)
        --tag <registry>/<namespace>/<existing_index_image>:<updated_tag> \(3)
        --pull-tool podman (4)
    1 The --bundles flag specifies a comma-separated list of additional bundle images to add to the index.
    2 The --from-index flag specifies the previously pushed index.
    3 The --tag flag specifies the image tag to apply to the updated index image.
    4 The --pull-tool flag specifies the tool used to pull container images.

    where:

    <registry>

    Specifies the hostname of the registry, such as quay.io or mirror.example.com.

    <namespace>

    Specifies the namespace of the registry, such as ocs-dev or abc.

    <new_bundle_image>

    Specifies the new bundle image to add to the registry, such as ocs-operator.

    <digest>

    Specifies the SHA image ID, or digest, of the bundle image, such as c7f11097a628f092d8bad148406aa0e0951094a03445fd4bc0775431ef683a41.

    <existing_index_image>

    Specifies the previously pushed image, such as abc-redhat-operator-index.

    <existing_tag>

    Specifies a previously pushed image tag, such as 4.11.

    <updated_tag>

    Specifies the image tag to apply to the updated index image, such as 4.11.1.

    Example command
    $ opm index add \
        --bundles quay.io/ocs-dev/ocs-operator@sha256:c7f11097a628f092d8bad148406aa0e0951094a03445fd4bc0775431ef683a41 \
        --from-index mirror.example.com/abc/abc-redhat-operator-index:4.11 \
        --tag mirror.example.com/abc/abc-redhat-operator-index:4.11.1 \
        --pull-tool podman
  2. Push the updated index image:

    $ podman push <registry>/<namespace>/<existing_index_image>:<updated_tag>
  3. After Operator Lifecycle Manager (OLM) automatically polls the index image referenced in the catalog source at its regular interval, verify that the new packages are successfully added:

    $ oc get packagemanifests -n openshift-marketplace

Filtering a SQLite-based index image

An index image, based on the Operator bundle format, is a containerized snapshot of an Operator catalog. You can filter, or prune, an index of all but a specified list of packages, which creates a copy of the source index containing only the Operators that you want.

Prerequisites
  • podman version 1.9.3+

  • grpcurl (third-party command-line tool)

  • opm

  • Access to a registry that supports Docker v2-2

Procedure
  1. Authenticate with your target registry:

    $ podman login <target_registry>
  2. Determine the list of packages you want to include in your pruned index.

    1. Run the source index image that you want to prune in a container. For example:

      $ podman run -p50051:50051 \
          -it registry.redhat.io/redhat/redhat-operator-index:v4.11
      Example output
      Trying to pull registry.redhat.io/redhat/redhat-operator-index:v4.11...
      Getting image source signatures
      Copying blob ae8a0c23f5b1 done
      ...
      INFO[0000] serving registry                              database=/database/index.db port=50051
    2. In a separate terminal session, use the grpcurl command to get a list of the packages provided by the index:

      $ grpcurl -plaintext localhost:50051 api.Registry/ListPackages > packages.out
    3. Inspect the packages.out file and identify which package names from this list you want to keep in your pruned index. For example:

      Example snippets of packages list