In the Operator Lifecycle Manager (OLM) ecosystem, the following resources are used to resolve Operator installations and upgrades:
Operator metadata, defined in CSVs, can be stored in a collection called a CatalogSource. OLM uses CatalogSources, which use the Operator Registry API, to query for available Operators as well as upgrades for installed Operators.
Within a CatalogSource, Operators are organized into packages and streams of updates called channels, which should be a familiar update pattern from OpenShift Container Platform or other software on a continuous release cycle like web browsers.
A user indicates a particular package and channel in a particular CatalogSource
in a Subscription, for example an
etcd package and its
alpha channel. If a
Subscription is made to a package that has not yet been installed in the
namespace, the latest Operator for that package is installed.
OLM deliberately avoids version comparisons, so the "latest" or "newest" Operator available from a given catalog → channel → package path does not necessarily need to be the highest version number. It should be thought of more as the head reference of a channel, similar to a Git repository.
Each CSV has a
replaces parameter that indicates which Operator it replaces.
This builds a graph of CSVs that can be queried by OLM, and updates can be
shared between channels. Channels can be thought of as entry points into the
graph of updates:
packageName: example channels: - name: alpha currentCSV: example.v0.1.2 - name: beta currentCSV: example.v0.1.3 defaultChannel: alpha
For OLM to successfully query for updates, given a CatalogSource, package,
channel, and CSV, a catalog must be able to return, unambiguously and
deterministically, a single CSV that
replaces the input CSV.
For an example upgrade scenario, consider an installed Operator corresponding to
0.1.1. OLM queries the CatalogSource and detects an upgrade in the
subscribed channel with new CSV version
0.1.3 that replaces an older but
not-installed CSV version
0.1.2, which in turn replaces the older and
installed CSV version
OLM walks back from the channel head to previous versions via the
field specified in the CSVs to determine the upgrade path
0.1.1; the direction of the arrow indicates that the former replaces the
latter. OLM upgrades the Operator one version at the time until it reaches the
For this given scenario, OLM installs Operator version
0.1.2 to replace the
existing Operator version
0.1.1. Then, it installs Operator version
replace the previously installed Operator version
0.1.2. At this point, the
installed operator version
0.1.3 matches the channel head and the upgrade is
OLM’s basic path for upgrades is:
A CatalogSource is updated with one or more updates to an Operator.
OLM traverses every version of the Operator until reaching the latest version the CatalogSource contains.
However, sometimes this is not a safe operation to perform. There will be cases where a published version of an Operator should never be installed on a cluster if it has not already, for example because a version introduces a serious vulnerability.
In those cases, OLM must consider two cluster states and provide an update graph that supports both:
The "bad" intermediate Operator has been seen by the cluster and installed.
The "bad" intermediate Operator has not yet been installed onto the cluster.
By shipping a new catalog and adding a skipped release, OLM is ensured that it can always get a single unique update regardless of the cluster state and whether it has seen the bad update yet.
apiVersion: operators.coreos.com/v1alpha1 kind: ClusterServiceVersion metadata: name: etcdoperator.v0.9.2 namespace: placeholder annotations: spec: displayName: etcd description: Etcd Operator replaces: etcdoperator.v0.9.0 skips: - etcdoperator.v0.9.1
Consider the following example Old CatalogSource and New CatalogSource:
This graph maintains that:
Any Operator found in Old CatalogSource has a single replacement in New CatalogSource.
Any Operator found in New CatalogSource has a single replacement in New CatalogSource.
If the bad update has not yet been installed, it will never be.
Creating the New CatalogSource as described requires publishing CSVs that
one Operator, but can
skip several. This can be accomplished using the
<semver_range> has the version range format supported by the
When searching catalogs for updates, if the head of a channel has a
annotation and the currently installed Operator has a version field that falls
in the range, OLM updates to the latest entry in the channel.
The order of precedence is:
Channel head in the source specified by
sourceName on the Subscription, if the
other criteria for skipping are met.
The next Operator that replaces the current one, in the source specified by
Channel head in another source that is visible to the Subscription, if the other criteria for skipping are met.
The next Operator that replaces the current one in any source visible to the Subscription.
Example CSV with
apiVersion: operators.coreos.com/v1alpha1 kind: ClusterServiceVersion metadata: name: elasticsearch-operator.v4.1.2 namespace: <namespace> annotations: olm.skipRange: '>=4.1.0 <4.1.2'
A z-stream, or patch release, must replace all previous z-stream releases for the same minor version. OLM does not care about major, minor, or patch versions, it just needs to build the correct graph in a catalog.
In other words, OLM must be able to take a graph as in Old CatalogSource and, similar to before, generate a graph as in New CatalogSource: