Operator Framework packaging formats

This guide outlines the packaging formats for Operators supported by Operator Lifecycle Manager (OLM) in OKD.

Bundle Format

The Bundle Format for Operators is a new packaging format introduced by the Operator Framework. To improve scalability and to better enable upstream users hosting their own catalogs, the Bundle Format specification simplifies the distribution of Operator metadata.

An Operator bundle represents a single version of an Operator. On-disk bundle manifests are containerized and shipped as a bundle image, which is a non-runnable container image that stores the Kubernetes manifests and Operator metadata. Storage and distribution of the bundle image is then managed using existing container tools like podman and docker and container registries such as Quay.

Operator metadata can include:

  • Information that identifies the Operator, for example its name and version.

  • Additional information that drives the UI, for example its icon and some example custom resources (CRs).

  • Required and provided APIs.

  • Related images.

When loading manifests into the Operator Registry database, the following requirements are validated:

  • The bundle must have at least one channel defined in the annotations.

  • Every bundle has exactly one cluster service version (CSV).

  • If a CSV owns a custom resource definition (CRD), that CRD must exist in the bundle.

Manifests

Bundle manifests refer to a set of Kubernetes manifests that define the deployment and RBAC model of the Operator.

A bundle includes one CSV per directory and typically the CRDs that define the owned APIs of the CSV in its /manifests directory.

Example Bundle Format layout

  1. etcd
  2. ├── manifests
  3. │   ├── etcdcluster.crd.yaml
  4. │   └── etcdoperator.clusterserviceversion.yaml
  5. │   └── secret.yaml
  6. │   └── configmap.yaml
  7. └── metadata
  8.     └── annotations.yaml
  9.     └── dependencies.yaml

Additionally supported objects

The following object types can also be optionally included in the /manifests directory of a bundle:

Supported optional object types

  • ClusterRole

  • ClusterRoleBinding

  • ConfigMap

  • PodDisruptionBudget

  • PriorityClass

  • PrometheusRule

  • Role

  • RoleBinding

  • Secret

  • Service

  • ServiceAccount

  • ServiceMonitor

  • VerticalPodAutoscaler

When these optional objects are included in a bundle, Operator Lifecycle Manager (OLM) can create them from the bundle and manage their lifecycle along with the CSV:

Lifecycle for optional objects

  • When the CSV is deleted, OLM deletes the optional object.

  • When the CSV is upgraded:

    • If the name of the optional object is the same, OLM updates it in place.

    • If the name of the optional object has changed between versions, OLM deletes and recreates it.

Annotations

A bundle also includes an annotations.yaml file in its /metadata directory. This file defines higher level aggregate data that helps describe the format and package information about how the bundle should be added into an index of bundles:

Example annotations.yaml

  1. annotations:
  2.   operators.operatorframework.io.bundle.mediatype.v1: "registry+v1" (1)
  3.   operators.operatorframework.io.bundle.manifests.v1: "manifests/" (2)
  4.   operators.operatorframework.io.bundle.metadata.v1: "metadata/" (3)
  5.   operators.operatorframework.io.bundle.package.v1: "test-operator" (4)
  6.   operators.operatorframework.io.bundle.channels.v1: "beta,stable" (5)
  7.   operators.operatorframework.io.bundle.channel.default.v1: "stable" (6)
1The media type or format of the Operator bundle. The registry+v1 format means it contains a CSV and its associated Kubernetes objects.
2The path in the image to the directory that contains the Operator manifests. This label is reserved for future use and currently defaults to manifests/. The value manifests.v1 implies that the bundle contains Operator manifests.
3The path in the image to the directory that contains metadata files about the bundle. This label is reserved for future use and currently defaults to metadata/. The value metadata.v1 implies that this bundle has Operator metadata.
4The package name of the bundle.
5The list of channels the bundle is subscribing to when added into an Operator Registry.
6The default channel an Operator should be subscribed to when installed from a registry.

In case of a mismatch, the annotations.yaml file is authoritative because the on-cluster Operator Registry that relies on these annotations only has access to this file.

Dependencies file

The dependencies of an Operator are listed in a dependencies.yaml file in the metadata/ folder of a bundle. This file is optional and currently only used to specify explicit Operator-version dependencies.

The dependency list contains a type field for each item to specify what kind of dependency this is. There are two supported types of Operator dependencies:

  • olm.package: This type indicates a dependency for a specific Operator version. The dependency information must include the package name and the version of the package in semver format. For example, you can specify an exact version such as 0.5.2 or a range of versions such as >0.5.1.

  • olm.gvk: With a gvk type, the author can specify a dependency with group/version/kind (GVK) information, similar to existing CRD and API-based usage in a CSV. This is a path to enable Operator authors to consolidate all dependencies, API or explicit versions, to be in the same place.

In the following example, dependencies are specified for a Prometheus Operator and etcd CRDs:

Example dependencies.yaml file

  1. dependencies:
  2.   - type: olm.package
  3.     value:
  4.       packageName: prometheus
  5.       version: ">0.27.0"
  6.   - type: olm.gvk
  7.     value:
  8.       group: etcd.database.coreos.com
  9.       kind: EtcdCluster
  10.       version: v1beta2

Additional resources

About opm

The opm CLI tool is provided by the Operator Framework for use with the Operator Bundle Format. This tool allows you to create and maintain catalogs of Operators from a list of bundles, called an index, that are similar to software repositories. The result is a container image, called an index image, which can be stored in a container registry and then installed on a cluster.

An index contains a database of pointers to Operator manifest content that can be queried through an included API that is served when the container image is run. On OKD, Operator Lifecycle Manager (OLM) can use the index image as a catalog by referencing it in a CatalogSource object, which polls the image at regular intervals to enable frequent updates to installed Operators on the cluster.

  • See CLI tools for steps on installing the opm CLI.

Package Manifest Format

The Package Manifest Format for Operators is the legacy packaging format introduced by the Operator Framework. While this format is deprecated in OKD 4.5, it is still supported and Operators provided by Red Hat are currently shipped using this method.

In this format, a version of an Operator is represented by a single cluster service version (CSV) and typically the custom resource definitions (CRDs) that define the owned APIs of the CSV, though additional objects may be included.

All versions of the Operator are nested in a single directory:

Example Package Manifest Format layout

  1. etcd
  2. ├── 0.6.1
  3. │   ├── etcdcluster.crd.yaml
  4. │   └── etcdoperator.clusterserviceversion.yaml
  5. ├── 0.9.0
  6. │   ├── etcdbackup.crd.yaml
  7. │   ├── etcdcluster.crd.yaml
  8. │   ├── etcdoperator.v0.9.0.clusterserviceversion.yaml
  9. │   └── etcdrestore.crd.yaml
  10. ├── 0.9.2
  11. │   ├── etcdbackup.crd.yaml
  12. │   ├── etcdcluster.crd.yaml
  13. │   ├── etcdoperator.v0.9.2.clusterserviceversion.yaml
  14. │   └── etcdrestore.crd.yaml
  15. └── etcd.package.yaml

It also includes a <name>.package.yaml file that is the package manifest that defines the package name and channels details:

Example package manifest

  1. packageName: etcd
  2. channels:
  3. - name: alpha
  4.   currentCSV: etcdoperator.v0.9.2
  5. - name: beta
  6.   currentCSV: etcdoperator.v0.9.0
  7. - name: stable
  8.   currentCSV: etcdoperator.v0.9.2
  9. defaultChannel: alpha

When loading package manifests into the Operator Registry database, the following requirements are validated:

  • Every package has at least one channel.

  • Every CSV pointed to by a channel in a package exists.

  • Every version of an Operator has exactly one CSV.

  • If a CSV owns a CRD, that CRD must exist in the directory of the Operator version.

  • If a CSV replaces another, both the old and the new must exist in the package.

Additional resources

See the upstream operator-framework/operator-registry project repository for more information on the Operator Bundle Format:

See the project Releases page for opm CLI downloads: