OLM Integration Bundle Quickstart

The Operator Lifecycle Manager (OLM) is a set of cluster resources that manage the lifecycle of an Operator. The Operator SDK supports both creating manifests for OLM deployment, and testing your Operator on an OLM-enabled Kubernetes cluster.

This document succinctly walks through getting an Operator OLM-ready with bundles, and glosses over explanations of certain steps for brevity. The following documents contain more detail on these steps:

If you are working with package manifests, see the package manifests quickstart once you have completed the Setup section below.

Important: this guide assumes your project was scaffolded with operator-sdk init --project-version=3-alpha. These features are unavailable to projects of version 2 or less; this information can be found by inspecting your PROJECT file’s version value.

Setup

Let’s first walk through creating an Operator for memcached, a distributed key-value store.

Follow one of the user guides to develop the memcached-operator in either Go, Ansible, or Helm, depending on which Operator type you are interested in. This guide assumes memcached-operator is on version 0.0.1, which is set in the Makefile variable VERSION.

Enabling OLM

Ensure OLM is enabled on your cluster before following this guide. operator-sdk olm has several subcommands that can install, uninstall, and check the status of particular OLM versions in a cluster.

Note: Certain cluster types may already have OLM enabled, but under a non-default ("olm") namespace, which can be configured by setting --olm-namespace=[non-default-olm-namespace] for operator-sdk olm status|uninstall subcommands.

You can check if OLM is already installed by running the following command, which will detect the installed OLM version automatically (0.15.1 in this example):

  1. $ operator-sdk olm status
  2. INFO[0000] Fetching CRDs for version "0.15.1"
  3. INFO[0002] Fetching resources for version "0.15.1"
  4. INFO[0002] Successfully got OLM status for version "0.15.1"
  6. NAME                                            NAMESPACE    KIND                        STATUS
  7. olm                                                          Namespace                   Installed
  8. operatorgroups.operators.coreos.com                          CustomResourceDefinition    Installed
  9. catalogsources.operators.coreos.com                          CustomResourceDefinition    Installed
  10. subscriptions.operators.coreos.com                           CustomResourceDefinition    Installed
  11. ...

All resources listed should have status Installed.

If OLM is not already installed, go ahead and install the latest version:

  1. $ operator-sdk olm install
  2. INFO[0000] Fetching CRDs for version "latest"
  3. INFO[0001] Fetching resources for version "latest"
  4. INFO[0007] Creating CRDs and resources
  5. INFO[0007]   Creating CustomResourceDefinition "clusterserviceversions.operators.coreos.com"
  6. INFO[0007]   Creating CustomResourceDefinition "installplans.operators.coreos.com"
  7. INFO[0007]   Creating CustomResourceDefinition "subscriptions.operators.coreos.com"
  8. ...
  9. NAME                                            NAMESPACE    KIND                        STATUS
  10. clusterserviceversions.operators.coreos.com                  CustomResourceDefinition    Installed
  11. installplans.operators.coreos.com                            CustomResourceDefinition    Installed
  12. subscriptions.operators.coreos.com                           CustomResourceDefinition    Installed
  13. catalogsources.operators.coreos.com                          CustomResourceDefinition    Installed
  14. ...

Note: By default, olm status and olm uninstall auto-detect the OLM version installed in your cluster. This can fail if the installation is broken in some way, so the version of OLM can be overridden using the --version flag provided with these commands.

Creating a bundle

If working with package manifests, see the package manifests quickstart.

We will now create bundle manifests by running make bundle in the root of the memcached-operator project.

  1. $ make bundle
  2. /home/user/go/bin/controller-gen "crd:trivialVersions=true" rbac:roleName=manager-role webhook paths="./..." output:crd:artifacts:config=config/crd/bases
  3. operator-sdk generate kustomize manifests -q
  4. kustomize build config/manifests | operator-sdk generate bundle -q --overwrite --version 0.0.1  
  5. INFO[0000] Building annotations.yaml                    
  6. INFO[0000] Writing annotations.yaml in /home/user/go/src/github.com/test-org/memcached-operator/bundle/metadata
  7. INFO[0000] Building Dockerfile                          
  8. INFO[0000] Writing bundle.Dockerfile in /home/user/go/src/github.com/test-org/memcached-operator
  9. operator-sdk bundle validate ./bundle
  10. INFO[0000] Found annotations file                        bundle-dir=bundle container-tool=docker
  11. INFO[0000] Could not find optional dependencies file     bundle-dir=bundle container-tool=docker
  12. INFO[0000] All validation tests have completed successfully

A bundle manifests directory bundle/manifests containing a CSV and all CRDs in config/crds, a bundle metadata directory bundle/metadata, and a Dockerfile bundle.Dockerfile have been created in the Operator project. These files have been statically validated by operator-sdk bundle validate to ensure the on-disk bundle representation is correct.

Deploying an Operator with OLM

At this point in development we’ve generated all files necessary to build the memcached-operator bundle. Now we’re ready to test and deploy the Operator with OLM.

Testing bundles

Coming soon.

Deploying bundles in production

OLM and Operator Registry consumes Operator bundles via an index image, which are composed of one or more bundles. To build a memcached-operator bundle, run:

  1. make bundle-build BUNDLE_IMG=<some-registry>/memcached-operator-bundle:<tag>
  2. docker push <some-registry>/memcached-operator-bundle:<tag>

Although we’ve validated on-disk manifests and metadata, we also must make sure the bundle itself is valid:

  1. $ operator-sdk bundle validate <some-registry>/memcached-operator-bundle:<tag>
  2. INFO[0000] Unpacked image layers                         bundle-dir=/tmp/bundle-716785960 container-tool=docker
  3. INFO[0000] running docker pull                           bundle-dir=/tmp/bundle-716785960 container-tool=docker
  4. INFO[0002] running docker save                           bundle-dir=/tmp/bundle-716785960 container-tool=docker
  5. INFO[0002] All validation tests have completed successfully  bundle-dir=/tmp/bundle-716785960 container-tool=docker

The SDK does not build index images; instead, use the Operator package manager tool opm to build one. Once one has been built, follow the index image usage docs to add an index to a cluster catalog, and the catalog discovery docs to tell OLM about your cataloged Operator.

Last modified October 7, 2020: update bundle image name in examples to denote this is a bundle image (#3992) (59899ddf)