Working with bundle images - Developing Operators | Operators

Bundling an Operator
Deploying an Operator with Operator Lifecycle Manager
Publishing a catalog containing a bundled Operator
Testing an Operator upgrade on Operator Lifecycle Manager
Controlling Operator compatibility with OpenShift Container Platform versions
Additional resources

You can use the Operator SDK to package, deploy, and upgrade Operators in the bundle format for use on Operator Lifecycle Manager (OLM).

Bundling an Operator

The Operator bundle format is the default packaging method for Operator SDK and Operator Lifecycle Manager (OLM). You can get your Operator ready for use on OLM by using the Operator SDK to build and push your Operator project as a bundle image.

Prerequisites

Operator SDK CLI installed on a development workstation
OpenShift CLI (oc) v4.11+ installed
Operator project initialized by using the Operator SDK
If your Operator is Go-based, your project must be updated to use supported images for running on OpenShift Container Platform

Procedure

Run the following make commands in your Operator project directory to build and push your Operator image. Modify the IMG argument in the following steps to reference a repository that you have access to. You can obtain an account for storing containers at repository sites such as Quay.io.

Build the image:

$ make docker-build IMG=<registry>/<user>/<operator_image_name>:<tag>

The Dockerfile generated by the SDK for the Operator explicitly references GOARCH=amd64 for go build. This can be amended to GOARCH=$TARGETARCH for non-AMD64 architectures. Docker will automatically set the environment variable to the value specified by –platform. With Buildah, the –build-arg will need to be used for the purpose. For more information, see Multiple Architectures.

Push the image to a repository:

$ make docker-push IMG=<registry>/<user>/<operator_image_name>:<tag>

Create your Operator bundle manifest by running the make bundle command, which invokes several commands, including the Operator SDK generate bundle and bundle validate subcommands:
```
$ make bundle IMG=<registry>/<user>/<operator_image_name>:<tag>
```
Bundle manifests for an Operator describe how to display, create, and manage an application. The make bundle command creates the following files and directories in your Operator project:
- A bundle manifests directory named bundle/manifests that contains a ClusterServiceVersion object
- A bundle metadata directory named bundle/metadata
- All custom resource definitions (CRDs) in a config/crd directory
- A Dockerfile bundle.Dockerfile
These files are then automatically validated by using operator-sdk bundle validate to ensure the on-disk bundle representation is correct.
Build and push your bundle image by running the following commands. OLM consumes Operator bundles using an index image, which reference one or more bundle images.
1. Build the bundle image. Set BUNDLE_IMG with the details for the registry, user namespace, and image tag where you intend to push the image:
  $ make bundle-build BUNDLE_IMG=<registry>/<user>/<bundle_image_name>:<tag>
2. Push the bundle image:
  $ docker push <registry>/<user>/<bundle_image_name>:<tag>

Deploying an Operator with Operator Lifecycle Manager

Operator Lifecycle Manager (OLM) helps you to install, update, and manage the lifecycle of Operators and their associated services on a Kubernetes cluster. OLM is installed by default on OpenShift Container Platform and runs as a Kubernetes extension so that you can use the web console and the OpenShift CLI (oc) for all Operator lifecycle management functions without any additional tools.

The Operator bundle format is the default packaging method for Operator SDK and OLM. You can use the Operator SDK to quickly run a bundle image on OLM to ensure that it runs properly.

Prerequisites

Operator SDK CLI installed on a development workstation
Operator bundle image built and pushed to a registry
OLM installed on a Kubernetes-based cluster (v1.16.0 or later if you use apiextensions.k8s.io/v1 CRDs, for example OpenShift Container Platform 4.11)
Logged in to the cluster with oc using an account with cluster-admin permissions
If your Operator is Go-based, your project must be updated to use supported images for running on OpenShift Container Platform

Procedure

Enter the following command to run the Operator on the cluster:

$ operator-sdk run bundle \(1)
    -n <namespace> \(2)
    <registry>/<user>/<bundle_image_name>:<tag> (3)

1	The `run bundle` command creates a valid file-based catalog and installs the Operator bundle on your cluster using OLM.
2	Optional: By default, the command installs the Operator in the currently active project in your `~/.kube/config` file. You can add the `-n` flag to set a different namespace scope for the installation.
3	If you do not specify an image, the command uses `quay.io/operator-framework/opm:latest` as the default index image. If you specify an image, the command uses the bundle image itself as the index image.

As of OpenShift Container Platform 4.11, the run bundle command supports the file-based catalog format for Operator catalogs by default. The deprecated SQLite database format for Operator catalogs continues to be supported; however, it will be removed in a future release. It is recommended that Operator authors migrate their workflows to the file-based catalog format.

This command performs the following actions:

Create an index image referencing your bundle image. The index image is opaque and ephemeral, but accurately reflects how a bundle would be added to a catalog in production.
Create a catalog source that points to your new index image, which enables OperatorHub to discover your Operator.
Deploy your Operator to your cluster by creating an OperatorGroup, Subscription, InstallPlan, and all other required resources, including RBAC.

Additional resources

File-based catalogs in Operator Framework packaging format
File-based catalogs in Managing custom catalogs
Bundle format

Publishing a catalog containing a bundled Operator

To install and manage Operators, Operator Lifecycle Manager (OLM) requires that Operator bundles are listed in an index image, which is referenced by a catalog on the cluster. As an Operator author, you can use the Operator SDK to create an index containing the bundle for your Operator and all of its dependencies. This is useful for testing on remote clusters and publishing to container registries.

The Operator SDK uses the opm CLI to facilitate index image creation. Experience with the opm command is not required. For advanced use cases, the opm command can be used directly instead of the Operator SDK.

Prerequisites

Operator SDK CLI installed on a development workstation
Operator bundle image built and pushed to a registry
OLM installed on a Kubernetes-based cluster (v1.16.0 or later if you use apiextensions.k8s.io/v1 CRDs, for example OpenShift Container Platform 4.11)
Logged in to the cluster with oc using an account with cluster-admin permissions

Procedure

Run the following make command in your Operator project directory to build an index image containing your Operator bundle:
```
$ make catalog-build CATALOG_IMG=<registry>/<user>/<index_image_name>:<tag>
```
where the CATALOG_IMG argument references a repository that you have access to. You can obtain an account for storing containers at repository sites such as Quay.io.

Push the built index image to a repository:

$ make catalog-push CATALOG_IMG=<registry>/<user>/<index_image_name>:<tag>

You can use Operator SDK make commands together if you would rather perform multiple actions in sequence at once. For example, if you had not yet built a bundle image for your Operator project, you can build and push both a bundle image and an index image with the following syntax:

$ make bundle-build bundle-push catalog-build catalog-push \
    BUNDLE_IMG=<bundle_image_pull_spec> \
    CATALOG_IMG=<index_image_pull_spec>

Alternatively, you can set the IMAGE_TAG_BASE field in your Makefile to an existing repository:

IMAGE_TAG_BASE=quay.io/example/my-operator

You can then use the following syntax to build and push images with automatically-generated names, such as quay.io/example/my-operator-bundle:v0.0.1 for the bundle image and quay.io/example/my-operator-catalog:v0.0.1 for the index image:

$ make bundle-build bundle-push catalog-build catalog-push

Define a CatalogSource object that references the index image you just generated, and then create the object by using the oc apply command or web console:

Example CatalogSource YAML

apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
  name: cs-memcached
  namespace: default
spec:
  displayName: My Test
  publisher: Company
  sourceType: grpc
  image: quay.io/example/memcached-catalog:v0.0.1 (1)
  updateStrategy:
    registryPoll:
      interval: 10m

1	Set `image` to the image pull spec you used previously with the `CATALOG_IMG` argument.

Check the catalog source:

$ oc get catalogsource

Example output

NAME           DISPLAY     TYPE   PUBLISHER   AGE
cs-memcached   My Test     grpc   Company     4h31m

Verification

Install the Operator using your catalog:

Define an OperatorGroup object and create it by using the oc apply command or web console:

Example OperatorGroup YAML

apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: my-test
  namespace: default
spec:
  targetNamespaces:
  - default

Define a Subscription object and create it by using the oc apply command or web console:

Example Subscription YAML

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: catalogtest
  namespace: default
spec:
  channel: "alpha"
  installPlanApproval: Manual
  name: catalog
  source: cs-memcached
  sourceNamespace: default
  startingCSV: memcached-operator.v0.0.1

Verify the installed Operator is running:

Check the Operator group:

$ oc get og

Example output

NAME             AGE
my-test           4h40m

Check the cluster service version (CSV):

$ oc get csv

Example output

NAME                        DISPLAY   VERSION   REPLACES   PHASE
memcached-operator.v0.0.1   Test      0.0.1                Succeeded

Check the pods for the Operator:

$ oc get pods

Example output

NAME                                                              READY   STATUS      RESTARTS   AGE
9098d908802769fbde8bd45255e69710a9f8420a8f3d814abe88b68f8ervdj6   0/1     Completed   0          4h33m
catalog-controller-manager-7fd5b7b987-69s4n                       2/2     Running     0          4h32m
cs-memcached-7622r                                                1/1     Running     0          4h33m

Additional resources

See Managing custom catalogs for details on direct usage of the opm CLI for more advanced use cases.

Testing an Operator upgrade on Operator Lifecycle Manager

You can quickly test upgrading your Operator by using Operator Lifecycle Manager (OLM) integration in the Operator SDK, without requiring you to manually manage index images and catalog sources.

The run bundle-upgrade subcommand automates triggering an installed Operator to upgrade to a later version by specifying a bundle image for the later version.

Prerequisites

Operator installed with OLM either by using the run bundle subcommand or with traditional OLM installation
A bundle image that represents a later version of the installed Operator

Procedure

If your Operator has not already been installed with OLM, install the earlier version either by using the run bundle subcommand or with traditional OLM installation.

If the earlier version of the bundle was installed traditionally using OLM, the newer bundle that you intend to upgrade to must not exist in the index image referenced by the catalog source. Otherwise, running the run bundle-upgrade subcommand will cause the registry pod to fail because the newer bundle is already referenced by the index that provides the package and cluster service version (CSV).

For example, you can use the following run bundle subcommand for a Memcached Operator by specifying the earlier bundle image: