Operator Lifecycle Manager – Reference

Docs: Admission Webhook Reference

Fri, 24 Apr 2020 00:00:00 +0000

After a request has been authenticated and authorized, admission webhooks intercept requests against the Kubernetes API and have an opportunity to validate or update the object before it is saved in the object store. Please refer to the following table that highlights what each webhook is capable of:

	Validating Webhooks	Mutating Webhooks
Validating Objects	x	x
Mutating Objects		x

If you are interested in learning more about admission webhooks, please review the official kubernetes documentation.

Docs: File-based Catalogs

Tue, 18 Jan 2022 00:00:00 +0000

File-based catalogs are the latest iteration of OLM’s catalog format. It is a fully plaintext-based (JSON or YAML) evolution of the previous sqlite database format that is fully backwards compatible.

Design

The primary design goal for this format is to enable catalog editing, composability, and extensibility.

Editing

With file-based catalogs, users interacting with the contents of a catalog are able to make direct changes to the catalog format and verify that their changes are valid.

Because this format is plaintext JSON or YAML, catalog maintainers can easily manipulate catalog metadata by hand or with widely known and supported JSON or YAML tooling (e.g. jq).

This editability enables features and user-defined extensions, such as:

Promoting an existing bundle to a new channel
Changing the default channel of a package
Custom algorithms for adding, updating, adding removing upgrade edges

Composability

File-based catalogs are stored in an arbitrary directory hierarchy, which enables catalog composition. If I have two separate file-based catalog directories, CatalogA and CatalogB, I can make a new combined catalog by making a new directory CatalogC and copying CatalogA and CatalogB into it.

This composability enables decentralized catalogs. The format permits operator authors to maintain operator-specific catalogs and catalog maintainers to trivially build a catalog composed of individual operator-specific catalogs.

NOTE: Duplicate packages and duplicate bundles within a package are not permitted. The opm validate command will return an error if any duplicates are found.

Since operator authors are most familiar with their operator, its dependencies, and its upgrade compatibility, they are able to maintain their own operator-specific catalog and have direct control over its contents. With file-based catalogs, operator authors own the task of building and maintaining their packages in a catalog. Composite catalog maintainers treat packages as a black box; they own the task of curating the packages in their catalog and publishing the catalog to users.

File-based catalogs can be composed by combining multiple other catalogs or by extracting subsets of one catalog, or a combination of both of these.

See the Building a composite catalog section for a simple example.

Extensibility

The final design goal is to provide extensibility around catalogs. The file-based catalog spec is a low-level representation of a catalog. While it can be maintained directly in its low-level form, we expect many catalog maintainers to build interesting extensions on top that can be used by their own custom tooling to make all sorts of mutations. For example, one could imagine a tool that translates a high-level API like (mode=semver) down to the low-level file-based catalog format for upgrade edges. Or perhaps a catalog maintainer needs to customize all of the bundle metadata by adding a new property to bundles that meet a certain criteria.

The OLM developer community will be making use of this extensibility to build more official tooling on top of the low-level APIs, but the major benefit is that catalog maintainers have this capability as well.

Specification

Structure

File-based catalogs can be stored and loaded from directory-based filesystems.

opm loads the catalog by walking the root directory and recursing into subdirectories. It attempts to load every file it finds and fails if any errors occur.

Non-catalog files can be ignored using .indexignore files, which behave identically to .gitignore files. That is, they have the same rules for patterns and precedence.

Example .gitignore file

# Ignore everything except non-object .json and .yaml files
**/*
!*.json
!*.yaml
**/objects/*.json
**/objects/*.yaml

Catalog maintainers have the flexibility to chose their desired layout, but the OLM team recommends storing each package’s file-based catalog blobs in separate sub-directories. Each individual file can be either JSON or YAML – it is not necessary for every file in a catalog to use the same format.

This layout has the property that each sub-directory in the directory hierarchy is a self-contained catalog, which makes catalog composition, discovery, and navigation as simple as trivial filesystem operations.

Basic recommended structure

catalog
├── pkgA
│ └── operator.yaml
├── pkgB
│ ├── .indexignore # to ignore README.md
│ ├── operator.yaml
│ └── README.md
└── pkgC
│ ├── package.json
│ ├── channels.yaml
└── bundles.json

This catalog could also be trivially included in a parent catalog by simply copying it into the parent catalog’s root directory.

Schema

At its core, file-based catalogs use a simple format that can be extended with arbitrary schemas. The format that all file-based catalog blobs must adhere to is the Meta schema, which consists of schema, package, name, and properties fields. The schema field is required. The package, name, and properties fields are optional, but if they are present, they must adhere to their respective field schemas. Any other field is allowed and is specified by the schema.

The combination of the schema, package, and name fields must be unique within a catalog.

See the Properties section for information about the properties field.

Here is an example of an object which adheres to the Meta schema:

### Core Meta fields
# The schema for this object (required)
schema: "example.com.my.object"

# The package this object belongs to, if applicable (optional)
package: foo

# The name of this object, if applicable (optional)
name: bar

# The properties associated with this object, if applicable (optional)
properties:
- type: my.string
 value: "my value"
- type: my.map
 value:
 key1: value1
 key2:
 - hello
 - world
 key3:
 harry: sally
- type: my.list
 value:
 - item1
 - item2

# (schema: "my.other.object")-defined, non-meta fields
myCustomMap:
 whiz: bang
myCustomList:
 - alice
 - bob

When this blob is parsed as a Meta object, the core fields are parsed to their respective types. Non-meta fields are not parsed. However, the parsed Meta object contains the full JSON representation of the blob, which enables callers to parse the object using a more specific type that maps to the “my.other.object” schema.

OLM-defined schemas

An OLM catalog currently uses the following schemas:

olm.package, olm.channel, and olm.bundle, which correspond to OLM’s existing package, channel, and bundle concepts,
olm.deprecations, which provides information for support and upgrades.

Each operator package in a catalog requires exactly one olm.package blob, at least one olm.channel blob, and one or more olm.bundle blobs.

NOTE: All olm.* schemas are reserved for OLM-defined schemas. Custom schemas must use a unique prefix (e.g. a domain that you own).

`olm.package`

An olm.package defines package-level (i.e. top level) metadata for an operator. This includes its name, description, default channel and icon.

Here is an example of an olm.package blob:

schema: olm.package
name: foo

# Description is markdown-formatted text that describes the operator.
# It may contain overviews, installation instructions, links, migration
# guides, etc. It is meant for a human audience.
description: |-
 foo-operator is a Kubernetes operator to deploy and manage Foo resources for a Kubernetes cluster.

 ## Overview

 Foo is a service that orchestrates Bar and Baz to provide a simple integrated experience.

 The goal of the **foo-operator** is to make it easy to orchestrate complex tasks that underpin the Foo
 service, including Bar and Baz upgrades, migrations, and optimizations.

# DefaultChannel is the name of the default channel for this package.
defaultChannel: candidate-v0

# Icon defines the image that UIs can use to represent this package.
icon:
 base64data: PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPHN2ZyB2ZXJzaW9uPSIxLjEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDMyMCAzMjAiPgogIDxnIGlkPSJsb2dvIiBmaWxsPSIjZmZmIj4KICAgIDxjaXJjbGUgY3g9IjE2MCIgY3k9IjE2MCIgcj0iMTAwIiBzdHJva2U9InBpbmsiIHN0cm9rZS13aWR0aD0iMyIgZmlsbD0icmVkIiAvPgogIDwvZz4KPC9zdmc+Cg==
 mediatype: image/svg+xml

`olm.channel`

An olm.channel defines a channel within a package, the bundle entries that are members of the channel, and the upgrade edges for those bundles.

A bundle can be included as an entry in multiple olm.channel blobs, but it can have only one entry per channel.

Also, it is valid for an entry’s replaces value to reference another bundle name that cannot be found in this catalog (or even another catalog) as long as other channel invariants still hold (e.g. a channel cannot have multiple heads).

Here is an example of an olm.channel blob:

schema: olm.channel
package: foo
name: candidate-v0
entries:
- # name is required. It is the name of an `olm.bundle` that
 # is present in the channel. 
 name: foo.v0.3.1

 # replaces is optional. It is the name of the bundle that is replaced
 # by this entry. It must be present in the entry list, unless this
 # entry is a channel tail. Channel tails are allowed to have replaces
 # values that are not present in the entry list.
 replaces: foo.v0.2.1

 # skips is optional. It is a list of bundle names that are skipped by
 # this entry. The skipped bundles do not have to be present in the
 # entry list.
 skips:
 - foo.v0.3.0

 # skipRange is optional. It is the semver range of bundle versions
 # that are skipped by this entry.
 skipRange: ">=0.2.0-0 <0.3.1-0"

- name: foo.v0.3.0
 replaces: v0.2.1
- name: foo.v0.2.1

For more information about defining upgrade edges, see the upgrade graph reference documentation.

`olm.bundle`

An olm.bundle defines an individually installable version of an operator within a package. It contains information necessary to locate the bundle’s contents, the related images used by the operator at runtime, and properties that can be used by clients to orchestrate lifecycling behavior, build user interfaces, provide filtering mechanisms, etc. For example, the “olm.gvk” property can be used to specify a Kubernetes group, version, and kind that this operator version provides, and the “olm.gvk.required” property can be used to specify a GVK that this operator requires. Components that understand these properties can implement dependency resolution by matching GVK providers and requirers.

See the Properties section for information about the properties understood by OLM.

Here is an example of an olm.bundle blob:

schema: olm.bundle
package: foo
name: foo.v0.3.0

# image defined the location of the bundle image. (required)
image: quay.io/example-com/foo-bundle:v0.3.0
relatedImages:
 - # name is a descriptive name for this image that helps
 # identify its purpose in the context of the operator. (optional)
 name: bundle

 # image is the location of the image. (required)
 image: quay.io/example-com/foo-bundle:v0.3.0

 - name: operator
 image: quay.io/example-com/foo-operator:v0.3.0
 - name: foo-v1
 image: quay.io/example-com/foo:v1
 - name: foo-v2
 image: quay.io/example-com/foo:v2
properties:
- type: olm.package
 value:
 packageName: foo
 version: 0.3.0
- type: olm.package.required
 value:
 packageName: bar
 versionRange: ">=1.0.0 <2.0.0-0"
- type: olm.gvk
 value:
 group: example.com
 version: v1alpha1
 kind: Foo
- type: olm.gvk.required
 value:
 group: example.com
 version: v1
 kind: Bar

`olm.deprecations`

Operator authors can provide information for support and upgrades by using the optional olm.deprecations schema.

The file-based catalog (FBC) deprecation schema consists of references to packages, bundles, and channels with a custom deprecation message.

A valid deprecation schema meets the following criteria:

There must be only one schema per package
The message must be a non-zero length
The package must exist in the catalog

The deprecation feature does not consider overlapping deprecation (package vs channel vs bundle).

	`olm.package`	`olm.channel`	`olm.bundle`
Scope	Entire Package	Single Channel	Single Bundle Version
Requirements	`name` must be empty since it is inferred from the parent `package` field	`name` is mandatory	`name` is mandatory

The following example demonstrates each of the deprecation entry types:

schema: olm.deprecations
package: deprecation-example
entries:
 - reference:
 schema: olm.bundle
 name: deprecation-example-operator.v1.68.0
 message: |
 deprecation-example-operator.v1.68.0 is deprecated. Uninstall and install deprecation-example-operator.v1.72.0 for support.
 - reference:
 schema: olm.package
 message: |
 package deprecation-example is end of life. Please use 'non-deprecated-example' package for support.
 - reference:
 schema: olm.channel
 name: alpha
 message: |
 channel alpha is no longer supported. Please switch to channel 'stable'.

Properties

Properties are arbitrary pieces of metadata that can be attached to file-based catalog schemas. The type field is a string that effectively specifies the semantic and syntactic meaning of the value field. The value can be any arbitrary JSON/YAML.

OLM defines a handful of property types, again using the reserved olm.* prefix.

`olm.package`

An olm.package property defines the package name and version. This is a required property on bundles, and there must be exactly one of these properties. The packageName must match the bundle’s first-class package field, the version must be a valid semantic version, and the package may include an optional release bundle packaging field. See the Bundle Release Property section for additional format requirements and examples.

The olm.package property cue schema is:

#PropertyPackage: {
type: "olm.package"
value: {
packageName: string & !=""
version: string & !=""
release?: string & !="" // optional release version
}
}

`olm.gvk`

An olm.gvk property defines the group, version, and kind (GVK) of a Kubernetes API that is provided by this bundle. This property is used by OLM to resolve a bundle with this property as a dependency for other bundles that list the same GVK as a required API. The GVK must adhere to Kubernetes GVK validations.

The olm.gvk property cue schema is:

#PropertyGVK: {
type: "olm.gvk"
value: {
group: string & !=""
version: string & !=""
kind: string & !=""
}
}

`olm.package.required`

An olm.package.required property defines the package name and version range of another package that this bundle requires. For every required package property a bundle lists, OLM will ensure there is an operator installed on the cluster for the listed package and in the required version range. The versionRange field must be a valid semver range.

The olm.package.required property cue schema is:

#PropertyPackageRequired: {
type: "olm.package.required"
value: {
packageName: string & !=""
versionRange: string & !=""
}
}

`olm.gvk.required`

An olm.gvk.required property defines the group, version, and kind (GVK) of a Kubernetes API that this bundle requires. For every required GVK property a bundle lists, OLM will ensure there is an operator installed on the cluster that provides it. The GVK must adhere to Kubernetes GVK validations.

The olm.gvk.required property cue schema is:

#PropertyGVKRequired: {
type: "olm.gvk.required"
value: {
group: string & !=""
version: string & !=""
kind: string & !=""
}
}

`olm.csv.metadata`

olm.csv.metadata properties are used to include informational metadata about a bundle. This property is optional, and there can be at most one of these properties per bundle. Bundles that include this property should not include any olm.bundle.object properties. This property supersedes the olm.bundle.object property.

NOTE: Core OLM does not require a olm.csv.metadata property to be included on bundles. However, the OLM Package Server (used by tooling such as the kubectl operator plugin and the OpenShift console) does require these properties to be able to serve metadata about the packages in a catalog. In order to satisfy the needs of the package server, catalog maintainers should use this property to include the CSV metadata for all bundles that are channel heads.

As of opm version 1.28.0, this property is automatically generated by when migrating SQLite catalogs with opm migrate and when rendering SQLite catalogs and registry+v1 bundles with opm render. Catalogs containing olm.csv.metadata properties must be served by opm binaries with version at least 1.28.0.

`olm.constraint`

An olm.constraint property defines a dependency constraint of a particular type. The failureMessage field is recommended but not required to be populated so readers know why a constraint was specified, and errors can contain this string. The supported types are detailed in subsections.

The olm.constraint property cue schema is:

#ConstraintValue: {
failureMessage?: string
{ gvk: #GVK } |
{ package: #Package } |
{ cel: #Cel } |
{ all: null | #CompoundConstraintValue } |
{ any: null | #CompoundConstraintValue } |
{ not: null | #CompoundConstraintValue }
}
#PropertyOLMConstraint: {
type: "olm.constraint"
value: #ConstraintValue
}

`#GVK`

#GVK is identical to the old top-level constraint olm.gvk.required value. The cue schema is:

#GVK: {
group: string & !=""
version: string & !=""
kind: string & !=""
}

Example:

#PropertyOLMConstraint & {
value: {
failureMessage: "required for ..."
gvk: #GVK & {
group: "example.com"
version: "v1"
kind: "Foo"
}
}
}

`#Package`

#Package is identical to the old top-level constraint olm.package.required value. The cue schema is:

#Package: {
packageName: string & !=""
versionRange: string & !=""
}

Example:

#PropertyOLMConstraint & {
value: {
failureMessage: "required for ..."
package: #Package & {
packageName: "foo"
versionRange: ">=1.0.0"
}
}
}

`#Cel`

The cel struct is specific to Common Expression Language (CEL) constraint type that supports CEL as the expression language. The cel struct has rule field which contains the CEL expression string that will be evaluated against operator properties at the runtime to determine if the operator satisfies the constraint.

The cel constraint cue schema is:

#Cel: {
rule: string & !=""
}

`#CompoundConstraintValue`

#CompoundConstraintValue is a compound constraint that represents either a logical conjunction, disjunction, or negation of a constraint list, some of which are concrete (ex. #GVK or #Cel), others being child compound constraints. These logical operations correspond to #ConstraintValue fields all, any, or not, respectively. The not compound constraint should only be used with an #All or #Any value, since negating without first selecting a possible set of dependencies does not make sense.

The cue schema is:

#ConstraintList: [#ConstraintValue, ...#ConstraintValue]
#CompoundConstraintValue: {
constraints: #ConstraintList
}

Example:

#PropertyOLMConstraint & {
value: #ConstraintValue & {
failureMessage: "Required for Baz because..."
any: #CompoundConstraintValue & {
constraints: #ConstraintList & [
{
failureMessage: "Pin kind Foo's version for stable versions"
all: #CompoundConstraintValue & {
constraints: #ConstraintList & [
{
package: #Package & {
packageName: "foo"
versionRange: ">=1.0.0"
}
},
{
gvk: #GVK & {
group: "foos.example.com"
version: "v1"
kind: "Foo"
}
}
]
}
},
{
failureMessage: "Pin kind Foo's version for pre-stable versions"
all: #CompoundConstraintValue & {
constraints: #ConstraintList & [
{
package: #Package & {
packageName: "foo"
versionRange: "<1.0.0"
}
},
{
gvk: #GVK & {
group: "foos.example.com"
version: "v1beta1"
kind: "Foo"
}
}
]
}
}
]
}
}
}

`olm.bundle.object` (deprecated)

olm.bundle.object properties are used to inline a bundle’s manifests directly in the catalog.

NOTE: Core OLM does not require olm.bundle.object properties to be included on bundles. However, the OLM Package Server (used by tooling such as the kubectl operator plugin and the OpenShift console) does require these properties to be able to serve metadata about the packages in a catalog. In order to satisfy the needs of the package server, catalog maintainers should use this property to include the CSV for all bundles that are channel heads.

This property is deprecated because it causes major performance issues when loading and serving file-based catalogs. The olm.csv.metadata property, which serves the exact same purpose, should be used instead.

A bundle object property can contain inlined data using the value.data field, which must be the base64-encoded string of that manifest.

The olm.bundle.object property cue schema is:


#PropertyBundleObject: {
type: "olm.bundle.object"
value: #propertyBundleObjectData
}
#propertyBundleObjectData: {
data: string & !=""
}

Bundle Release Property

`olm.package` with Release Version

The olm.package property has been extended to support an optional release field that specifies the packaging version of a bundle. This allows catalog maintainers to distinguish between different builds of the same operator version.

Use Cases for Bundle Release

Use the release field when you need to:

Republish a bundle with documentation fixes

# Original bundle
name: foo.v0.3.0
version: 0.3.0
# (no release)

# Updated bundle with fixed description
name: foo-v0.3.0-1
version: 0.3.0
release: "1"

Create environment-specific builds

# Production build
name: foo-v0.3.0-prod
version: 0.3.0
release: "prod"

# Staging build
name: foo-v0.3.0-staging
version: 0.3.0
release: "staging"

Version catalog packaging changes

# First packaging iteration
name: foo-v0.3.0-1
version: 0.3.0
release: "1"

# Second iteration with label updates
name: foo-v0.3.0-2
version: 0.3.0
release: "2"

Required Bundle Naming with Release

When the release field is present in the olm.package property, the bundle name must follow this convention:

<package-name>-v<version>-<release>

opm validate will fail if the bundle name doesn’t match this normalized format.

Valid Examples:

# Release is a number
name: foo-v0.3.0-1
properties:
- type: olm.package
 value:
 packageName: foo
 version: 0.3.0
 release: "1"

# Release is alphanumeric
name: foo-v0.3.0-alpha.1
properties:
- type: olm.package
 value:
 packageName: foo
 version: 0.3.0
 release: "alpha.1"

Invalid Example:

# ❌ INVALID - name uses dots instead of hyphens
name: foo.v0.3.0.1
properties:
- type: olm.package
 value:
 packageName: foo
 version: 0.3.0
 release: "1"

Release Format Constraints

The release field:

Must conform to semver prerelease format (alphanumerics and hyphens, dot-separated)
Cannot contain build metadata (no + character)
Has a maximum length of 20 characters

Invalid release values:

# ❌ INVALID - contains build metadata
release: "1+fffdb0e"

# ❌ INVALID - contains invalid characters
release: "1_beta"

Example Bundle with Release

schema: olm.bundle
package: foo
name: foo-v0.3.0-1 # Note: name includes release in format <pkg>-v<version>-<release>

image: quay.io/example-com/foo-bundle:v0.3.0-1
properties:
- type: olm.package
 value:
 packageName: foo
 version: 0.3.0
 release: "1" # Optional packaging version
- type: olm.gvk
 value:
 group: example.com
 version: v1alpha1
 kind: Foo

Composite Version Ordering

Bundles are compared using a composite version that combines the version and release:

flowchart LR A[Bundle A] --> AV[version: 0.3.0
release: 1] B[Bundle B] --> BV[version: 0.3.0
release: 2] AV --> C{Compare Versions} BV --> C C -->|Equal| D{Both have
release?} C -->|Not Equal| E[Order by version] D -->|Yes| F[Order by release] D -->|No| G{Which has
release?} G -->|A| H[B < A] G -->|B| I[A < B] F --> J[Bundle A < Bundle B
1 < 2] style C fill:#e1f5ff style D fill:#e1f5ff style G fill:#e1f5ff style F fill:#c3e6cb style E fill:#c3e6cb style H fill:#c3e6cb style I fill:#c3e6cb style J fill:#c3e6cb

Ordering rules:

Compare by version first (using semver comparison)
If versions are equal:
- Bundles with a release are greater than bundles without a release
- Bundles both having releases are ordered by their release version (using semver prerelease comparison)

Example ascending order sequence:

foo.v0.2.0 # v0.2.0, no release
foo.v0.3.0 # v0.3.0, no release
foo-v0.3.0-1 # v0.3.0, release "1" is greater than no release
foo-v0.3.0-2 # v0.3.0, release "2" is greater than release "1"
foo-v0.3.0-alpha # v0.3.0, release "alpha" is greater than release "2"
foo-v0.3.0-beta.1 # v0.3.0, release "beta.1" is greater than release "alpha"
foo.v0.4.0 # v0.4.0, no release

Compatibility

Catalogs produced with tooling that comprehends the release version can be consumed by tooling that does not support release versioning without impact, and vice-versa. Due to the Meta schema FBC composition combined with a general practice of allowing unknown fields when unmarshalling, FBC processing is relatively forgiving on receipt and strict on construction. The release field is not perceived by older tooling, and the absence of this field in content created by older tooling is interpreted as intentional by newer tooling.

CLI

`opm init`

Generate an olm.package declarative config blob
Usage:
opm init <packageName> [flags]
Flags:
-c, --default-channel string The channel that subscriptions will default to if unspecified
-d, --description string Path to the operator's README.md (or other documentation)
-h, --help help for init
-i, --icon string Path to package's icon
-o, --output string Output format (json|yaml) (default "json")
Global Flags:
--skip-tls skip TLS certificate verification for container image registries while pulling bundles or index

`opm render`

Generate a declarative config blob from the provided index images, bundle images, and sqlite database files
Usage:
opm render [index-image | bundle-image | sqlite-file]... [flags]
Flags:
-h, --help help for render
-o, --output string Output format (json|yaml) (default "json")
Global Flags:
--skip-tls skip TLS certificate verification for container image registries while pulling bundles or index

`opm validate`

Validate the declarative config JSON file(s) in a given directory
Usage:
opm validate <directory> [flags]
Flags:
-h, --help help for validate
Global Flags:
--skip-tls skip TLS certificate verification for container image registries while pulling bundles or index

`opm serve`

This command serves declarative configs via a GRPC server.
NOTE: The declarative config directory is loaded by the serve command at
startup. Changes made to the declarative config after the this command starts
will not be reflected in the served content.
Usage:
opm serve <source_path> [flags]
Flags:
--debug enable debug logging
-h, --help help for serve
-p, --port string port number to serve on (default "50051")
-t, --termination-log string path to a container termination log file (default "/dev/termination-log")
Global Flags:
--skip-tls skip TLS certificate verification for container image registries while pulling bundles or index

`opm alpha diff`

Diff a set of old and new catalog references ("refs") to produce a declarative config containing only packages channels, and versions not present in the old set, and versions that differ between the old and new sets. This is known as "latest" mode. These references are passed through 'opm render' to produce a single declarative config.
This command has special behavior when old-refs are omitted, called "heads-only" mode: instead of the output being that of 'opm render refs...' (which would be the case given the preceding behavior description), only the channel heads of all channels in all packages are included in the output, and dependencies. Dependencies are assumed to be provided by either an old ref, in which case they are not included in the diff, or a new ref, in which case they are included. Dependencies provided by some catalog unknown to 'opm alpha diff' will not cause the command to error, but an error will occur if that catalog is not serving these dependencies at runtime.
Usage:
opm alpha diff [old-refs]... new-refs... [flags]
Examples:
# Diff a catalog at some old state and latest state into a declarative config index.
mkdir -p catalog-index
opm alpha diff registry.org/my-catalog:abc123 registry.org/my-catalog:def456 -o yaml > ./my-catalog-index/index.yaml
# Build and push this index into an index image.
opm generate dockerfile ./my-catalog-index
docker build -t registry.org/my-catalog:latest-abc123-def456 -f index.Dockerfile .
docker push registry.org/my-catalog:latest-abc123-def456
# Create a new catalog from the heads of an existing catalog, then build and push the image like above.
opm alpha diff registry.org/my-catalog:def456 -o yaml > my-catalog-index/index.yaml
docker build -t registry.org/my-catalog:headsonly-def456 -f index.Dockerfile .
docker push registry.org/my-catalog:headsonly-def456
Flags:
--ca-file string the root Certificates to use with this command
--debug enable debug logging
-h, --help help for diff
-o, --output string Output format (json|yaml) (default "yaml")
Global Flags:
--skip-tls skip TLS certificate verification for container image registries while pulling bundles or index

`opm generate dockerfile`

Generate a Dockerfile for a declarative config index.
This command creates a Dockerfile in the same directory as the <dcRootDir>
(named <dcDirName>.Dockerfile) that can be used to build the index. If a
Dockerfile with the same name already exists, this command will fail.
When specifying extra labels, note that if duplicate keys exist, only the last
value of each duplicate key will be added to the generated Dockerfile.
Usage:
opm generate dockerfile <dcRootDir> [flags]
Flags:
-i, --binary-image string Image in which to build catalog. (default "quay.io/operator-framework/upstream-opm-builder")
-l, --extra-labels strings Extra labels to include in the generated Dockerfile. Labels should be of the form 'key=value'.
-h, --help help for dockerfile
Global Flags:
--skip-tls skip TLS certificate verification for container image registries while pulling bundles or index

Guidelines

Immutable bundles

OLM’s general advice is that bundle images and their metadata should be treated as immutable. If a broken bundle has been pushed to an index, you must assume that at least one of your users has upgraded to that bundle. Based on that assumption, you must release another bundle with an upgrade edge from the broken bundle to ensure users with the broken bundle installed receive an upgrade. OLM will not reinstall an installed bundle if the contents of that bundle are updated in the index.

However, there are some cases where a change in the index metadata is preferred. For example:

Channel promotion - if you already released a bundle and later decide that you’d like to add it to another channel, simply add an entry for your bundle in another olm.channel blob.
New upgrade edges - if you release a new 1.2.z (e.g. 1.2.4), but 1.3.0 is already released, you can update the index metadata for 1.3.0 to skip 1.2.4.

Use of source control

OLM highly recommends storing index metadata in source control and treating the source-controlled metadata as the source of truth. Updates to index images should:

Update the source-controlled index directory with a new commit.
Build and push the index image. OLM suggests using a consistent tagging taxonomy (e.g. :latest or :<targetClusterVersion> so that users can receive updates to an index as they become available.

Examples

Building a composite catalog

With file-based catalogs, catalog maintainers can focus on operator curation and compatibility. Since operator authors have already produced operator-specific catalogs for their operators, catalog maintainers can build their catalog simply by rendering each operator catalog into a subdirectory of the catalog’s root catalog directory.

There are many possible ways to build a catalog, but an extremely simple approach would be to:

Maintain a single configuration file containing image references for each operator in the catalog

name: community-operators
repo: quay.io/community-operators/catalog
tag: latest
references:
- name: etcd-operator
 image: quay.io/etcd-operator/catalog@sha256:5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03
- name: prometheus-operator
 image: quay.io/prometheus-operator/catalog@sha256:e258d248fda94c63753607f7c4494ee0fcbe92f1a76bfdac795c9d84101eb317

Run a simple script that parses this file and creates a new catalog from its references

name=$(yq eval '.name' catalog.yaml)
mkdir "$name"
yq eval '.name + "/" + .references[].name' catalog.yaml | xargs mkdir
for l in $(yq e '.name as $catalog | .references[] | .image + "|" + $catalog + "/" + .name + "/index.yaml"' catalog.yaml); do
 image=$(echo $l | cut -d'|' -f1)
 file=$(echo $l | cut -d'|' -f2)
 opm render "$image" > "$file"
done
opm generate dockerfile "$name"
indexImage=$(yq eval '.repo + ":" + .tag' catalog.yaml)
docker build -t "$indexImage" -f "$name.Dockerfile" .
docker push "$indexImage"

Note: The yq binary used in the script can be found here

Automation

Operator authors and catalog maintainers are encouraged to automate their catalog maintenance with CI/CD workflows. Catalog maintainers could further improve on this by building Git-ops automation that:

Checks that PR authors are permitted to make the requested changes (e.g. updating their package’s image reference)
Checks that the catalog updates pass opm validate
Checks that the updated bundle and/or catalog image reference(s) exist, the catalog images run successfully in a cluster, and operators from that package can be successfully installed.
Automatically merges PRs that pass these checks.
Automatically rebuilds and republishes the catalog image.

An example catalog that automates a lot of these workflows can be found at https://github.com/operator-framework/cool-catalog

Docs: Catalog Templates

Thu, 30 Jun 2022 00:00:00 +0000

Note: catalog templates are ALPHA functionality and may adopt breaking changes

Concept and Design

File-Based Catalogs (FBC) are a major improvement to the imperative update graph approaches of previous versions. FBCs give operator authors a declarative and deterministic approach to defining their update graph. However, FBCs can get complex, especially as the number of releases and dependencies scale. We introduce the concept of a catalog template (referred to as template going forward) as an approach to simplifying interacting with FBCs.

In this context, there are two components to every template:

An arbitrary API
An executable which processes #1 and produces a valid FBC.

The templates supported by opm are:

the basic template, which provides a simplified abstraction of an FBC
the semver template, which provides the capability to generate an entire upgrade graph

Basic Template

The basic template is an input schema which eliminates FBC information that can be retrieved from existing registries when we process it. Within the schema, users can add entries composed of any valid FBC schema components, but supply only the bundle image reference for any olm.bundle objects. This results in a greatly simplified, smaller document. This approach may be attractive to operator authors who maintain existing catalogs and just want to simplify the format, or for operator authors who need to retain an update graph which cannot be based on semver.

Usage

opm alpha render-template basic [flags] <filename>

Flag	Description
-h, –help	prints help/usage information
-o, –output	the output format, can be `yaml` or `json`
–skip-tls-verify	skip TLS certificate verification for container image registries while pulling bundles
–use-http	use plain HTTP for container image registries while pulling bundles

--skip-tls-verify and --use-http are mutually exclusive flags.

Example

In a very simple example, we define an olm.package and an olm.channel composed of two olm.bundle objects that have an image name attribute but no other attributes/properties.

schema: olm.template.basic
entries:
 - schema: olm.package
 name: example-operator
 defaultChannel: stable
 - schema: olm.channel
 package: example-operator
 name: stable
 entries:
 - name: example-operator.v0.1.0
 - name: example-operator.v0.2.0
 replaces: example-operator.v0.1.0
 - schema: olm.bundle
 image: docker.io/example/example-operator-bundle:0.1.0
 - schema: olm.bundle
 image: docker.io/example/example-operator-bundle:0.2.0

Using the opm alpha render-template basic command on this input generates the full FBC (skipping large bundle metadata objects):

---
defaultChannel: stable
name: example-operator
schema: olm.package
---
entries:
- name: example-operator.v0.1.0
- name: example-operator.v0.2.0
 replaces: example-operator.v0.1.0
name: stable
package: example-operator
schema: olm.channel
---
image: docker.io/example/example-operator-bundle:0.1.0
name: example-operator.v0.1.0
package: example-operator
properties:
- type: olm.gvk
 value:
 group: example.com
 kind: App
 version: v1
- type: olm.package
 value:
 packageName: example-operator
 version: 0.1.0
relatedImages:
- image: docker.io/example/example-operator-bundle:0.1.0
 name: ""
- image: docker.io/example/example-operator:0.1.0
 name: ""
schema: olm.bundle
---
image: docker.io/example/example-operator-bundle:0.2.0
name: example-operator.v0.2.0
package: example-operator
properties:
- type: olm.gvk
 value:
 group: example.com
 kind: App
 version: v1
- type: olm.package
 value:
 packageName: example-operator
 version: 0.2.0
relatedImages:
- image: docker.io/example/example-operator-bundle:0.2.0
 name: ""
- image: docker.io/example/example-operator:0.2.0
 name: ""
schema: olm.bundle

Converting from FBC to Basic Template

The opm tool provides the capability to render existing File-Based Catalogs to basic catalog templates in JSON or YAML formats.

Usage

opm alpha convert-template basic [flags] <filename>

Flag	Description
-h, –help	prints help/usage information
-o, –output	the output format, can be `yaml` or `json`
–skip-tls-verify	skip TLS certificate verification for container image registries while pulling bundles
–use-http	use plain HTTP for container image registries while pulling bundles

--skip-tls-verify and --use-http are mutually exclusive flags.

Example template in JSON format after the conversion

{
 "schema": "olm.template.basic",
 "entries": [
 {
 "schema": "olm.package",
 "name": "hello-kubernetes",
 "defaultChannel": "alpha",
 "description": "hello-kubernetes"
 },
 {
 "schema": "olm.channel",
 "name": "alpha",
 "package": "hello-kubernetes",
 "entries": [
 {
 "name": "hello-kubernetes.v0.0.1"
 }
 ]
 },
 {
 "schema": "olm.bundle",
 "image": "docker.io/test/hello-kubernetes-operator-bundle:v0.0.1"
 }
 ]
}

Using existing FBC to bootstrap a Substitutes Template

The opm tool provides the capability to generate a substitutes template from existing FBC in JSON or YAML formats.

Usage

./bin/opm alpha convert-template substitutes [flags] <fbc-location>

Flag	Description
-h, –help	prints help/usage information
-o, –output	the output format, can be `yaml` or `json`
–skip-tls-verify	skip TLS certificate verification for container image registries while pulling bundles
–use-http	use plain HTTP for container image registries while pulling bundles

--skip-tls-verify and --use-http are mutually exclusive flags.

Example template in JSON format after the conversion

Note: empty substitutions are provided, but must be filled in to be valid

{
 "schema": "olm.template.substitutes",
 "entries": [
 {
 "schema": "olm.package",
 "name": "hello-kubernetes",
 "defaultChannel": "alpha",
 "description": "hello-kubernetes"
 },
 {
 "schema": "olm.channel",
 "name": "alpha",
 "package": "hello-kubernetes",
 "entries": [
 {
 "name": "hello-kubernetes.v0.0.1"
 }
 ]
 },
 {
 "schema": "olm.bundle",
 "image": "docker.io/test/hello-kubernetes-operator-bundle:v0.0.1"
 }
 ],
 "substitutions": [
 {
 "name": "",
 "base": ""
 }
 ]
}

Semver Template

Since a catalog template is identified as an input schema which is processed to generate a valid FBC, we can define a semver template as a schema which uses channel conventions to facilitate the auto-generation of channels adhering to Semantic Versioning (semver) guidelines and consistent with best practices on channel naming. This approach may be attractive to operator authors who are defining a new upgrade graph, or are already close enough to this template’s conventions to be able to adopt it.

DISCLAIMER: since version build metadata MUST be ignored when determining version precedence (see spec #10) when using semver, if any bundles differ only by build metadata the render attempt will generate a fatal error.

This alpha version of the semver template has the following goals:

terse grammar to minimize creation/maintenance effort
idempotent output
simple channel promotion
demonstration of a common type of channel maturity model
minor-version (Y-stream) and major-version (X-stream) versioning capabilities
clear mapping between input schema and output FBC attributes

Note: The semver template depends on the optional csv.spec.version field. If you want to use the semver catalog template, you must specify a version in your extension’s CSV.

Specification

Like best practices recommended channel naming, this template supports channel names Candidate, Fast, and Stable, in order of increasing channel stability. We leverage this relationship when calculating the default channel for the package.

GenerateMajorChannels and GenerateMinorChannels dictate whether this template will generate X-stream or Y-stream channels (attributes can be set independently). If omitted, only minor (Y-stream) channels will be generated.

Under each channel are a list of bundle image references which contribute to that channel. At least one channel must have bundle images.

The olm.semver cue schema is:

#Package: {
schema: "olm.semver"
// optional flag to control generating minor-version channels, defaults to _true_ if unspecified
GenerateMinorChannels?: bool
// optional flag to control generating major-version channels, defaults to _false_ if unspecified
GenerateMajorChannels?: bool
// optional preference for major- or minor-version channels, when both are generated and identical in stability and version
DefaultChannelTypePreference?: string
// optional candidate channel
Candidate?: {
Bundles: [...#ImageEntry]
}
// optional fast channel
Fast?: {
Bundles: [...#ImageEntry]
}
// optional stable channel
Stable?: {
Bundles: [...#ImageEntry]
}
#ImageEntry: {
Image: string
}
}

Usage

opm alpha render-template semver [flags] <filename>

Flag	Description
-h, –help	prints help/usage information
-o, –output	the output format, can be `yaml` or `json`
–skip-tls-verify	skip TLS certificate verification for container image registries while pulling bundles
–use-http	use plain HTTP for container image registries while pulling bundles

--skip-tls-verify and --use-http are mutually exclusive flags.

Examples

With the following (hypothetical) example we define a mock bundle which has 11 versions, represented across each of the channel types:

Schema: olm.semver
GenerateMajorChannels: true
GenerateMinorChannels: true
Candidate:
 Bundles:
 - Image: quay.io/foo/olm:testoperator.v0.1.0
 - Image: quay.io/foo/olm:testoperator.v0.1.1
 - Image: quay.io/foo/olm:testoperator.v0.1.2
 - Image: quay.io/foo/olm:testoperator.v0.1.3
 - Image: quay.io/foo/olm:testoperator.v0.2.0
 - Image: quay.io/foo/olm:testoperator.v0.2.1
 - Image: quay.io/foo/olm:testoperator.v0.2.2
 - Image: quay.io/foo/olm:testoperator.v0.3.0
 - Image: quay.io/foo/olm:testoperator.v1.0.0
 - Image: quay.io/foo/olm:testoperator.v1.0.1
 - Image: quay.io/foo/olm:testoperator.v1.1.0
Fast:
 Bundles:
 - Image: quay.io/foo/olm:testoperator.v0.2.1
 - Image: quay.io/foo/olm:testoperator.v0.2.2
 - Image: quay.io/foo/olm:testoperator.v0.3.0
 - Image: quay.io/foo/olm:testoperator.v1.0.1
 - Image: quay.io/foo/olm:testoperator.v1.1.0
Stable:
 Bundles:
 - Image: quay.io/foo/olm:testoperator.v1.0.1

In this example, Candidate has the entire version range of bundles, Fast has a mix of older and more-recent versions, and Stable channel only has a single published entry.

Generating major-version channels

If we set the template attributes

GenerateMajorChannels: true
GenerateMinorChannels: false

we generate the following major channels (filtering out large bundle metadata):

---
defaultChannel: stable-v1
name: testoperator
schema: olm.package
---
entries:
- name: testoperator.v0.1.0
- name: testoperator.v0.1.1
- name: testoperator.v0.1.2
- name: testoperator.v0.1.3
 skips:
 - testoperator.v0.1.0
 - testoperator.v0.1.1
 - testoperator.v0.1.2
- name: testoperator.v0.2.0
- name: testoperator.v0.2.1
- name: testoperator.v0.2.2
 replaces: testoperator.v0.1.3
 skips:
 - testoperator.v0.2.0
 - testoperator.v0.2.1
- name: testoperator.v0.3.0
 replaces: testoperator.v0.2.2
name: candidate-v0
package: testoperator
schema: olm.channel
---
entries:
- name: testoperator.v1.0.0
- name: testoperator.v1.0.1
 skips:
 - testoperator.v1.0.0
- name: testoperator.v1.1.0
 replaces: testoperator.v1.0.1
name: candidate-v1
package: testoperator
schema: olm.channel
---
entries:
- name: testoperator.v0.2.1
- name: testoperator.v0.2.2
 skips:
 - testoperator.v0.2.1
- name: testoperator.v0.3.0
 replaces: testoperator.v0.2.2
name: fast-v0
package: testoperator
schema: olm.channel
---
entries:
- name: testoperator.v1.0.1
- name: testoperator.v1.1.0
 replaces: testoperator.v1.0.1
name: fast-v1
package: testoperator
schema: olm.channel
---
entries:
- name: testoperator.v1.0.1
name: stable-v1
package: testoperator
schema: olm.channel

We generated a channel for each template channel entity corresponding to each of the 0.#.#, 1.#.# major version ranges with skips to the head of the highest semver in a channel. We also generated a replaces edge to traverse across minor version transitions within each major channel. Finally, we generated an olm.package object, setting as default the most-stable channel head we created. This process will prefer Stable channel over Fast, over Candidate and then a higher bundle version over a lower version.
(Please note that the naming of the generated channels indicates the digits of significance for that channel. For example, fast-v1 is a decomposed channel of the fast type which contains only major versions of contributing bundles matching v1.)

Generating minor-version channels

For contrast, if we set the template attributes

GenerateMinorChannels: true
GenerateMajorChannels: false

we generate the following minor channels (again filtering out large bundle metadata):

---
defaultChannel: stable-v1.0
name: testoperator
schema: olm.package
---
entries:
 - name: testoperator.v0.1.0
 - name: testoperator.v0.1.1
 - name: testoperator.v0.1.2
 - name: testoperator.v0.1.3
 skips:
 - testoperator.v0.1.0
 - testoperator.v0.1.1
 - testoperator.v0.1.2
name: candidate-v0.1
package: testoperator
schema: olm.channel
---
entries:
 - name: testoperator.v0.2.0
 - name: testoperator.v0.2.1
 - name: testoperator.v0.2.2
 replaces: testoperator.v0.1.3
 skips:
 - testoperator.v0.2.0
 - testoperator.v0.2.1
name: candidate-v0.2
package: testoperator
schema: olm.channel
---
entries:
 - name: testoperator.v0.3.0
 replaces: testoperator.v0.2.2
name: candidate-v0.3
package: testoperator
schema: olm.channel
---
entries:
 - name: testoperator.v1.0.0
 - name: testoperator.v1.0.1
 skips:
 - testoperator.v1.0.0
name: candidate-v1.0
package: testoperator
schema: olm.channel
---
entries:
 - name: testoperator.v1.1.0
 replaces: testoperator.v1.0.1
name: candidate-v1.1
package: testoperator
schema: olm.channel
---
entries:
 - name: testoperator.v0.2.1
 - name: testoperator.v0.2.2
 skips:
 - testoperator.v0.2.1
name: fast-v0.2
package: testoperator
schema: olm.channel
---
entries:
 - name: testoperator.v0.3.0
 replaces: testoperator.v0.2.2
name: fast-v0.3
package: testoperator
schema: olm.channel
---
entries:
 - name: testoperator.v1.0.1
name: fast-v1.0
package: testoperator
schema: olm.channel
---
entries:
 - name: testoperator.v1.1.0
 replaces: testoperator.v1.0.1
name: fast-v1.1
package: testoperator
schema: olm.channel
---
entries:
 - name: testoperator.v1.0.1
name: stable-v1.0
package: testoperator
schema: olm.channel

Here, a channel is generated for each template channel which differs by minor version, and each channel has a replaces edge from the predecessor channel to the next-lesser minor bundle version. Please note that at no time do we transgress across major-version boundaries with the channels, to be consistent with the semver convention for major versions, where the purpose is to make incompatible API changes.

Generating both channel types, and disambiguating default channel selection

In the case that we generate both major-version and minor-version channels:

GenerateMinorChannels: true
GenerateMajorChannels: true

we can easily end up in a situation where our results yield indifferentiable results, for e.g.:

---
entries:
- name: testoperator.v1.0.1
name: stable-v1
package: testoperator
schema: olm.channel
---
entries:
- name: testoperator.v1.0.1
name: stable-v1.0
package: testoperator
schema: olm.channel

In this situation, both channels have matching channel archetypes and the channel heads have the same versions. The DefaultChannelTypePreference attribute allows us to deterministically select a single channel in this case. This attribute defaults to prefer minor-version channels (DefaultChannelTypePreference: minor), but can be overridden in the schema if the author wishes to prefer major-version channels instead (DefaultChannelTypePreference: major).

With DefaultChannelTypePreference set to major, our most-stable channels and package output would look like

---
defaultChannel: stable-v1
name: testoperator
schema: olm.package
---
entries:
- name: testoperator.v1.0.1
name: stable-v1
package: testoperator
schema: olm.channel
---
entries:
- name: testoperator.v1.0.1
name: stable-v1.0
package: testoperator
schema: olm.channel

Substitutes Template

The substitutes template provides a safe and structured way to replace bundles in an upgrade graph with newer packaging versions. This is particularly useful when you need to republish a bundle with non-functional changes (documentation fixes, label updates, etc.) and want to ensure users can upgrade to the new bundle.

Before the substitutes template, when you needed to replace a bundle in a catalog (for example, foo.v1.0.0 with a documentation fix), you had two options:

Manually edit all channel entries - Error-prone and requires updating multiple references
Use the deprecated substitutesFor CSV field - Not available in file-based catalogs

The olm.template.substitutes template solves this by automatically handling the complex graph mutations required to safely replace bundles.

Schema

schema: olm.template.substitutes
entries:
 - # Existing FBC catalog content (packages, channels, bundles)
substitutions:
 - name: <new-bundle-image>  # Bundle image to substitute
 base: <old-bundle-name>  # Bundle name to replace

How It Works

When you define a substitution:

The template validates that the substitute bundle has a higher composite version than the base bundle
For each channel containing the base bundle, the template:
- Adds the new bundle to the channel
- Moves upgrade edges (replaces, skips, skipRange) from the base to the substitute
- Adds a skip edge from substitute to base
- Updates all other entries that reference the base to reference the substitute instead

Before Substitution

graph LR A1[foo.v0.9.0] -->|replace| B1[foo.v1.0.0] B1 -->|replace| C1[foo.v1.1.0]

After Substitution

Step-by-Step Example

Step 1: Initial Catalog State

You have a catalog with three bundles in the stable channel:

---
schema: olm.channel
package: foo
name: stable
entries:
 - name: foo.v0.9.0
 - name: foo.v1.0.0
 replaces: foo.v0.9.0
 - name: foo.v1.1.0
 replaces: foo.v1.0.0
---
schema: olm.bundle
package: foo
name: foo.v1.0.0
image: quay.io/example/foo-bundle:v1.0.0
properties:
 - type: olm.package
 value:
 packageName: foo
 version: 1.0.0

Step 2: Create New Bundle with Release

You discover foo.v1.0.0 is missing a critical annotation. You:

update the bundle’s annotation in metadata/annotations.yaml
update the bundle’s CSV with spec.release set (here set to 1)
ensure that the bundle’s metadata-name follows the format required for using release versions
publish the bundle

The rendered bundle image (via opm render) would look something like this in FBC:

---
schema: olm.bundle
package: foo
name: foo-v1.0.0-1  # New name with release
image: quay.io/example/foo-bundle:v1.0.0-1
properties:
 - type: olm.package
 value:
 packageName: foo
 version: 1.0.0
 release: "1" # Added release

Step 3: Create Substitutes Template

Instead of manually updating the catalog, create a substitutes template:

Note: see Using existing FBC to bootstrap a Substitutes Template to get opm to generate this for you.

schema: olm.template.substitutes
entries:
 # Include all your existing catalog content here
 # (packages, channels, bundles - except the new foo-v1.0.0-1)
substitutions:
 - name: quay.io/example/foo-bundle:v1.0.0-1  # New bundle image
 base: foo.v1.0.0  # Old bundle name to replace

Step 4: Render the Template

Use opm to render the template:

opm alpha render-template substitutes-template.yaml -o yaml > catalog/foo/index.yaml

The rendered catalog will have:

---
schema: olm.channel
package: foo
name: stable
entries:
 - name: foo.v0.9.0
 - name: foo-v1.0.0-1  # NEW substitute bundle
 replaces: foo.v0.9.0
 skips:
 - foo.v1.0.0  # Skips the old bundle
 - name: foo.v1.1.0
 replaces: foo-v1.0.0-1  # Updated to point to new bundle
 - name: foo.v1.0.0  # OLD bundle remains in catalog
 # No upgrade edges (orphaned)

Substitution Rules and Validation

The template enforces several validation rules:

Composite version check: The substitute bundle must have a higher composite version than the base bundle

# ✅ VALID - release "1" > no release
base: foo.v1.0.0 (version 1.0.0, no release)
name: foo-v1.0.0-1 (version 1.0.0, release "1")

# ❌ INVALID - same version and release
base: foo-v1.0.0-1
name: foo-v1.0.0-1

# ❌ INVALID - lower composite version
base: foo-v1.0.0-2
name: foo-v1.0.0-1

Base bundle must exist: The base bundle name must be present in the catalog
Required fields: Both name (bundle image) and base (bundle name) are required
Name vs Base validation: The name and base cannot be the same

Multiple Substitutions

You can define multiple substitutions in a single template:

schema: olm.template.substitutes
entries:
 # ... catalog content ...
substitutions:
 - name: quay.io/example/foo-bundle:v1.0.0-1
 base: foo.v1.0.0
 - name: quay.io/example/foo-bundle:v1.1.0-1
 base: foo.v1.1.0
 - name: quay.io/example/bar-bundle:v2.0.0-alpha.2
 base: bar-v2.0.0-alpha.1

The substitutions are processed in order, and each substitution validates against the current state of the catalog.

Upgrade Path Diagram

stateDiagram-v2 [*] --> InstalledOld: User has foo.v1.0.0 [*] --> InstalledNew: New user installs InstalledOld --> UpgradeToSubstitute: Catalog updated with
substitution InstalledNew --> UseSubstitute: Directly installs
foo-v1.0.0-1 UpgradeToSubstitute --> foo_v1_0_0_1: OLM sees substitute
skips old bundle UseSubstitute --> foo_v1_0_0_1: Gets latest bundle foo_v1_0_0_1 --> [*]: Up to date note right of UpgradeToSubstitute Skip relationship ensures users upgrade to the new packaging version end note

Best Practices

Use for packaging changes only: The substitute bundle should be functionally equivalent to the base bundle
Validate composite versions: Ensure your substitute bundle has a higher composite version (typically by adding a release field)
Test before deploying: Use opm validate to verify the rendered catalog:
```
opm alpha render-template template.yaml | opm validate -
```
Keep base bundles: The old bundle remains in the catalog but becomes unreachable through normal upgrade paths (it’s still accessible for historical reference)

Document substitutions: Add comments in your template explaining why each substitution was made

substitutions:
 # Fixed typo in operator description
 - name: quay.io/example/foo-bundle:v1.0.0-1
 base: foo.v1.0.0

Complete Working Example

---
schema: olm.template.substitutes

# Your existing catalog content
entries:
 - schema: olm.package
 name: foo
 defaultChannel: stable

 - schema: olm.channel
 package: foo
 name: stable
 entries:
 - name: foo.v0.9.0
 - name: foo.v1.0.0
 replaces: foo.v0.9.0
 - name: foo.v1.1.0
 replaces: foo.v1.0.0

 - schema: olm.bundle
 package: foo
 name: foo.v0.9.0
 image: quay.io/example/foo-bundle:v0.9.0
 properties:
 - type: olm.package
 value:
 packageName: foo
 version: 0.9.0

 - schema: olm.bundle
 package: foo
 name: foo.v1.0.0
 image: quay.io/example/foo-bundle:v1.0.0
 properties:
 - type: olm.package
 value:
 packageName: foo
 version: 1.0.0

 - schema: olm.bundle
 package: foo
 name: foo.v1.1.0
 image: quay.io/example/foo-bundle:v1.1.0
 properties:
 - type: olm.package
 value:
 packageName: foo
 version: 1.1.0

# Define the substitution
substitutions:
 - name: quay.io/example/foo-bundle:v1.0.0-1  # New bundle with fixed docs
 base: foo.v1.0.0  # Old bundle to replace

Render with:

opm alpha render-template substitutes-template.yaml -o yaml > catalog/foo/index.yaml

Operator Lifecycle Manager – Reference

Docs: Admission Webhook Reference

Docs: File-based Catalogs

Design

Editing

Composability

Extensibility

Specification

Structure

Schema

OLM-defined schemas

olm.package

olm.channel

olm.bundle

olm.deprecations

Properties

olm.package

olm.gvk

olm.package.required

olm.gvk.required

olm.csv.metadata

olm.constraint

#GVK

#Package

#Cel

#CompoundConstraintValue

olm.bundle.object (deprecated)

Bundle Release Property

olm.package with Release Version

Use Cases for Bundle Release

Required Bundle Naming with Release

Release Format Constraints

Example Bundle with Release

Composite Version Ordering

Compatibility

CLI

opm init

opm render

opm validate

opm serve

opm alpha diff

opm generate dockerfile

Guidelines

Immutable bundles

Use of source control

Examples

Building a composite catalog

Automation

Docs: Catalog Templates

Concept and Design

Basic Template

Usage

Example

Converting from FBC to Basic Template

Usage

Example template in JSON format after the conversion

Using existing FBC to bootstrap a Substitutes Template

Usage

Example template in JSON format after the conversion

Semver Template

Specification

Usage

Examples

Generating major-version channels

Generating minor-version channels

Generating both channel types, and disambiguating default channel selection

Substitutes Template

Schema

How It Works

Step-by-Step Example

Step 1: Initial Catalog State

Step 2: Create New Bundle with Release

Step 3: Create Substitutes Template

Step 4: Render the Template

Substitution Rules and Validation

Multiple Substitutions

Upgrade Path Diagram

Best Practices

Complete Working Example

`olm.package`

`olm.channel`

`olm.bundle`

`olm.deprecations`

`olm.package`

`olm.gvk`

`olm.package.required`

`olm.gvk.required`

`olm.csv.metadata`

`olm.constraint`

`#GVK`

`#Package`

`#Cel`

`#CompoundConstraintValue`

`olm.bundle.object` (deprecated)

`olm.package` with Release Version

`opm init`

`opm render`

`opm validate`

`opm serve`

`opm alpha diff`

`opm generate dockerfile`