mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-05 21:46:22 +01:00
107 lines
4.8 KiB
Plaintext
107 lines
4.8 KiB
Plaintext
// Module included in the following assemblies:
|
|
//
|
|
// * operators/understanding/olm-packaging-format.adoc
|
|
|
|
[id="olm-bundle-format_{context}"]
|
|
= Bundle format
|
|
|
|
The _bundle format_ for Operators is a 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.
|
|
|
|
[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 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
|
|
----
|
|
|
|
|
|
[id="olm-bundle-format-manifests-optional_{context}"]
|
|
=== Additionally supported objects
|
|
|
|
The following object types can also be optionally included in the `/manifests` directory of a bundle:
|
|
|
|
.Supported optional object types
|
|
[.small]
|
|
* `ClusterRole`
|
|
* `ClusterRoleBinding`
|
|
* `ConfigMap`
|
|
* `ConsoleCLIDownload`
|
|
* `ConsoleLink`
|
|
* `ConsoleQuickStart`
|
|
* `ConsoleYamlSample`
|
|
* `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.
|
|
|
|
[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.
|
|
====
|