openshift-docs/modules/olm-bundle-format.adoc

// Module included in the following assemblies:
//
// * operators/understanding/olm/olm-packaging-format.adoc

[id="olm-bundle-format_{context}"]
= 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 CSV.
* If a CSV owns a CRD, that CRD must exist in the bundle.

[id="olm-bundle-format-manifests_{context}"]
== Manifests

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

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

.Example Bundle Format layout
[source,terminal]
----
etcd
├── manifests
│   ├── etcdcluster.crd.yaml
│   └── etcdoperator.clusterserviceversion.yaml
│   └── secret.yaml
│   └── configmap.yaml
└── metadata
    └── annotations.yaml
    └── dependencies.yaml
----

[discrete]
[id="olm-bundle-format-manifests-optional_{context}"]
=== Optional objects

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

.Supported optional objects
* Secrets
* ConfigMaps

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.

[id="olm-bundle-format-annotations_{context}"]
== 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`
[source,yaml]
----
annotations:
  operators.operatorframework.io.bundle.mediatype.v1: "registry+v1" <1>
  operators.operatorframework.io.bundle.manifests.v1: "manifests/" <2>
  operators.operatorframework.io.bundle.metadata.v1: "metadata/" <3>
  operators.operatorframework.io.bundle.package.v1: "test-operator" <4>
  operators.operatorframework.io.bundle.channels.v1: "beta,stable" <5>
  operators.operatorframework.io.bundle.channel.default.v1: "stable" <6>
----
<1> The media type or format of the Operator bundle. The `registry+v1` format means
it contains a CSV and its associated Kubernetes objects.
<2> The 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.
<3> The 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.
<4> The package name of the bundle.
<5> The list of channels the bundle is subscribing to when added into an Operator
Registry.
<6> The default channel an Operator should be subscribed to when installed from a
registry.

[NOTE]
====
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.
====

[id="olm-bundle-format-dependencies_{context}"]
== Dependencies

The dependencies of an Operator are listed in a `dependencies.yaml` file inside
the bundle's `metadata/` folder. 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`: A package type means this is 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 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
[source,yaml]
----
dependencies:
  - type: olm.package
    value:
      packageName: prometheus
      version: ">0.27.0"
  - type: olm.gvk
    value:
      group: etcd.database.coreos.com
      kind: EtcdCluster
      version: v1beta2
----