Operator Lifecycle Manager (OLM)

Operator Lifecycle Manager (OLM) is a component of the Operator Framework that provides a declarative way to install, manage, and upgrade Operators and their dependencies in a Kubernetes cluster.

Key capabilities include:

• Over-the-Air Updates and Catalogs: Uses catalogs to provide Operators and manage granular update paths via channels.
• Dependency Model: Allows Operators to express dependencies on the platform or other Operators, ensuring stability across updates.
• Discoverability: Advertises installed Operators and services into tenant namespaces.
• Cluster Stability: Prevents conflicting Operators from owning the same APIs.
• Declarative UI controls: Uses descriptors to drive rich graphical interfaces for interacting with Operators.

A ClusterServiceVersion (CSV) combines metadata and runtime information about a service to allow OLM to manage its lifecycle.

A CSV includes:

• Metadata: name, description, version, links, labels, icon, etc.
• Install strategy: Defines the type (e.g., Deployment) and the set of service accounts, required permissions, and deployments needed.
• CRDs: Specifies which Custom Resource Definitions are Owned (managed by the service), Required (must exist for the service to run), or simply part of the Resources the operator interacts with. It also uses Descriptors to annotate CRD spec and status fields with semantic information.

A Cluster Service Version (CSV) is a metadata object that accompanies an Operator container image. It serves two primary purposes:

1. UI/UX Information: It provides metadata like logos, descriptions, and version numbers to populate user interfaces.
2. Technical Orchestration: It contains the technical requirements needed for the Operator Lifecycle Manager (OLM) to run the Operator, including RBAC rules, managed Custom Resource Definitions (CRDs), and dependencies.

When OLM parses a CSV, it automatically handles the wiring of Roles and Role Bindings and ensures the Operator is started or updated within the correct namespace.

The Catalog Registry stores CSVs, CRDs, and metadata about packages and channels.

Hierarchy

• Catalog: Contains multiple packages.
• Package: A manifest associating an identity with sets of ClusterServiceVersions. A package contains multiple Channels.
• Channel: Points to a specific ClusterServiceVersion (CSV).

Because CSVs explicitly reference the CSV they replace, the Catalog Operator can use the package manifest to step through intermediate versions to reach the latest version in a channel.

Visual Model:

Package {name}
  |
  +-- Channel {name} --> CSV {version} (--> CSV {version - 1} --> ...)
  |
  +-- Channel {name} --> CSV {version}
  |
  +-- Channel {name} --> CSV {version}

A ClusterServiceVersion (CSV) is the fundamental unit of packaging in OLM, similar to a dpkg package. It contains:

• Identity: A global name for the service (e.g., etcd).
• Metadata: Information such as maintainers and icons.
• Owned CRDs: Custom Resource Definitions directly managed by the operator (e.g., EtcdCluster is owned by the Etcd CSV).
• Required CRDs: CRDs that the operator expects to exist but does not manage (e.g., EtcdCluster is required by the Vault CSV).
• Cluster Requirements: Dependencies like pull secrets, config maps, or specific cluster features.
• Install Strategy: Instructions for OLM on how to create the resources. The current supported strategy is deployment, which creates a Kubernetes Deployment.

OLM decouples operator dependencies by expressing them as requirements for specific Custom Resource Definitions (CRDs) rather than direct operator dependencies.

Why this pattern is used:

• Decoupling: It allows operators to be updated independently. For example, Vault can depend on an EtcdCluster CRD without being strictly tied to the specific version of the Etcd operator running in the cluster.
• Automated Provisioning: When an InstallPlan is resolved, OLM identifies the required CRDs from the service catalog cache and ensures they are created in the cluster before the dependent operator starts.

Operator Lifecycle Manager (OLM) resolves upgrades by coordinating three primary resources:

1. ClusterServiceVersion (CSV): The operator's definition, which includes metadata and the replaces field used to build an update graph.
2. CatalogSource: A collection of operator metadata (CSVs) organized into packages and channels.
3. Subscription: A user-defined resource that specifies a particular Package and Channel within a CatalogSource to follow.

When a Subscription is created for a package not yet installed in the namespace, OLM installs the newest operator version available in that package/channel. For existing installations, OLM uses the replaces field in CSVs to walk the directed acyclic graph (DAG) from the current version to the channel head, performing upgrades one version at a time.

When running in an OpenShift environment, OLM automatically manages proxy settings if a global ProxyConfig object is present in the cluster.

• OLM will automatically inject HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables into the operator deployment.
• Override Behavior: If you explicitly define any of these three variables (HTTP_PROXY, HTTPS_PROXY, or NO_PROXY) in your Subscription configuration, OLM will respect your manual setting and will not automatically update the other proxy variables based on the global ProxyConfig changes.

For OLM to successfully and deterministically resolve upgrades, your CatalogSource must maintain the following invariant:

Given a (CatalogSource, Package, Channel, ClusterServiceVersion), the catalog must be able to return, unambiguously and deterministically, a single CSV that replaces the input CSV.

This ensures that regardless of the cluster's current state, there is always a clear, single path for the upgrade engine to follow.

OLM manages CRD upgrades based on ownership to ensure compatibility between running operators:

• Singular Ownership: If a CRD is owned by a single ClusterServiceVersion (CSV), OLM will upgrade the CRD immediately.
• Multiple Ownership: If a CRD is owned by multiple CSVs, OLM only upgrades the CRD when the following backward compatibility conditions are met:
  1. All existing serving versions in the current CRD are present in the new CRD.
  2. All existing Custom Resource instances associated with current serving versions remain valid when validated against the new CRD's validation schema.

When a Cluster Service Version (CSV) owns an APIService, it is responsible for describing the deployment of the extension api-server and the group-version-kinds it provides. The Lifecycle Manager automatically creates or replaces the Service and APIService resources. It also handles certificate management: a new CA key/cert pair is generated for each installation, and a serving cert is stored as a kubernetes.io/tls Secret in the deployment namespace.

To allow your deployment to use these certificates, the Lifecycle Manager automatically appends a Volume named apiservice-cert to the deployment matching the DeploymentName. The default mount path is /apiserver.local.config/certificates.