mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-06 06:46:26 +01:00
122 lines
4.5 KiB
Plaintext
122 lines
4.5 KiB
Plaintext
// 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.
|
|
====
|