// 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}"]
=== Additionally supported objects

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

.Supported optional objects
* Secrets
* ConfigMaps
* Services
* PodDisruptionBudget
* PriorityClass
* 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.

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