OLM and Bundle CLI Overview

This document gives an overview of using operator-sdk to work with Operator manifests related to OLM, namely bundles and package manifests. See the manifests generation doc for an in-depth discussion of these commands.

OLM installation

The following operator-sdk subcommands manage an OLM installation:

  • olm install: install a particular version of OLM.
  • olm status: check the status of a particular version of OLM running in a cluster. This command can infer the version of an error-free OLM installation.
  • olm uninstall: uninstall a particular version of OLM running in a cluster. This command can infer the version of an error-free OLM installation.

Manifests and metadata

The following make recipes and operator-sdk subcommands create or interact with Operator package manifests and bundles:

Bundles

  • make bundle: runs the following commands:
    • generate kustomize manifests: see above.
    • generate bundle: creates a new or updates an existing bundle in the <project-root>/bundle directory. This command generates both manifests and metadata.
    • bundle validate: validates an Operator bundle image or unpacked manifests and metadata.
  • make bundle-build: builds a bundle image using the bundle.Dockerfile generated by make bundle.
  • run bundle: runs the given Operator’s bundle image with an existing OLM installation.
  • run bundle-upgrade: upgrades the Operator bundle to a specified newer version.

Private bundle and catalog image registries

By default, projects are configured to push to and pull from a docker.io registry with namespace being the value passed to operator-sdk init --domain=<value>. Modify this value to push/pull bundle and catalog images with a different registry host or namespace.

All bundle and catalog image-related commands invoke opm (except for bundle image builds, for which docker is used directly). opm leverages the host’s image build/pull tools indirectly to perform various image tasks, so if your image registry is private or has a custom CA you must ensure the in-use build tool is able to push to/pull from the registry:

The run bundle or run bundle-upgrade commands use the none image tool, described above, in-cluster. These commands accept the names of secrets available in the deployment namespace that contain configuration file data. Ideally a cluster admin will provision a namespace and service account for bundle testing, such that they include and reference these secrets:

Once the above secrets have been created, run the either command with --pull-secret-name=<image pull secret> and --ca-secret-name=<certificate secret>:

  1. operator-sdk run bundle private-custom-ca-reg.com/memcached-operator-bundle:v0.0.2 \
  2. --index-image private-custom-ca-reg.com/memcached-operator-catalog:v0.0.1 \
  3. --pull-secret-name foo-pull-sec \
  4. --ca-secret-name foo-cert-sec

You may have to set --namespace=<provisioned namespace> if the namespace encoded in your kubeconfig’s current context was not provisioned with these secrets.

Package Manifests

The operator-framework is removing support for the packagemanifests format in the near future, and migration efforts are currently underway. Therefore generate packagemanifests and run packagemanifests commands have been deprecated. For more details on bundle format refer here. To migrate from packagemanifests to the bundle format, use the operator-sdk pkgman-to-bundle command.

Last modified July 21, 2021: docs/olm-integration: Fix misspelling (#5079) (5f6c16c7)