DOCSEARCHbyAlgolia
Submit Docs

Operator Controller

repository·main·Indexed 42 days ago

https://github.com/operator-framework/operator-controller

The core of OLM v1, providing the APIs and controllers necessary to manage the installation and lifecycle of Kubernetes extensions via declarative GitOps patterns. It includes tools for ClusterCatalog and ClusterExtension configuration, OPA policy validation for NetworkPolicies, and a CRD generator using opcon tags to manage standard and experimental versions.

Tokens
60.2K
Snippets
155
Records
273
Agent score
52%

What's inside Operator Controller

  1. What is the Operator Lifecycle Manager (OLM)?

    main

    The Operator Lifecycle Manager (OLM) is a CNCF open-source project used to centralize and simplify the management of Kubernetes cluster extensions. It automates the packaging, distribution, installation, updating, and removal of these extensions.

    While originally focused on Operators (controllers paired with Kubernetes API extensions and CustomResourceDefinitions), OLM is evolving to support a wider range of Kubernetes applications.

    Key capabilities introduced in OLM v0 include:

    • Dependency Model: Delegating non-essential tasks to other dependencies.
    • Constraint Model: Defining compatibility constraints (e.g., conflicting extensions or minimum Kubernetes versions).
    • Namespace-Based Multi-Tenancy: Managing multiple extensions without requiring namespace-scoped CRDs.
    • Packaging Model: Distributing extensions via catalogs for discovery and installation.

  2. Overview of OLM v1 and operator-controller

    main

    The operator-controller is the central component of Operator Lifecycle Manager (OLM) v1. It extends Kubernetes with an API that allows users to install extensions.

    OLM v1 is designed to support the packaging, distribution, and lifecycling of Kubernetes extensions using declarative GitOps concepts. It consists of two primary components:

    • operator-controller: The central controller managing the extension lifecycle.
    • catalogd: The service responsible for serving catalog content.

    For detailed design decisions and differences between OLM v0 and v1, refer to the OLM v1 design decisions documentation.

  3. Identify the OLM v1 Public API surface

    main

    The public API for OLM v1 consists of two primary components. Only these components are guaranteed to follow Semantic Versioning (SemVer). Any interaction with the system outside of these defined surfaces is subject to breaking changes without notice.

    1. Kubernetes APIs: The custom resources and controllers exposed via the Kubernetes API server.
    2. Catalogd web server: The web server interface used for catalog operations.

  4. What is a ClusterObjectSet?

    main

    A ClusterObjectSet is a cluster-scoped Kubernetes API used to manage a versioned, ordered set of Kubernetes resources. It enables safe, phased rollouts by grouping resources into sequential phases and enforcing readiness checks between them.

    Key characteristics include:

    • Immutable Revision Content: Once created, the revision number, collisionProtection strategy, and phases (including all objects) cannot be changed, providing an auditable deployment record.
    • Lifecycle States: A set is either Active (being reconciled) or Archived (inactive). Transitions from Active to Archived are one-way.
    • Phased Rollout: Resources are applied in ordered groups. A phase only progresses once all its objects pass their readiness probes.
    • Single Ownership: Each Kubernetes resource can only be managed by one ClusterObjectSet at a time to prevent conflicts.
    • Large Bundle Support: Supports both inline manifests and externalized references to Secrets to bypass etcd size limits.

  5. Identify OLM Producer roles

    main

    The OLM ecosystem relies on several producer roles to create and distribute content. These roles form a pipeline from initial creation to final catalog publication:

    • Extension Author: Creates, builds, releases, and validates extensions. They generate catalog contributions (e.g., bundle images and upgrade graphs in FBC) to make extensions available to Cluster Extension Admins.
    • Contribution Curator: Validates contributions from Extension Authors and publishes them to a registry. This role often acts as a bridge between authors and catalog curators.
    • Catalog Curator: Aggregates contributions, validates the aggregate catalog, and publishes the final catalog index image used by consumers.
    • Catalog Manipulator: Consumes published catalogs and re-publishes them for specific use cases, such as restricting versions, providing services for disconnected environments, or reducing catalog size.

  6. Understand Semver upgrade limitations in OLM 1.0

    main

    OLM 1.0 uses Semver to assume compatibility within a major version. However, there are specific limitations and manual requirements:

    Major Version Upgrades

    OLM 1.0 does not support automatic upgrades to the next major version. Major version upgrades must be manually verified and performed.

    Upgrades within Major Version Zero (v0.x.x)

    Because major version zero releases are for initial development, automatic upgrades are restricted:

    • Patch to Patch: You cannot automatically upgrade between patch versions if both major and minor versions are 0 (e.g., no automatic upgrade from 0.0.1 to 0.0.2).
    • Minor to Minor: You cannot automatically upgrade from one minor version to another within major version zero (e.g., no automatic upgrade from 0.1.0 to 0.2.0).
    • Allowed: Upgrades are permitted within specific patch ranges (e.g., >= 0.1.0 <0.2.0).

  7. Define a ClusterCatalog resource

    main

    A ClusterCatalog makes File-Based Catalog (FBC) data available to your cluster. It uses the olm.operatorframework.io/v1 API version.

    Key components:

    • spec: A required field defining the desired state (e.g., which packages and versions to make available).
    • status: Contains information about whether the catalog is being served via the HTTP server, if it is progressing, and a reference to its source.

  8. Customize extension runtime configuration

    main

    Extensions often require runtime modifications to function correctly within specific environments (e.g., networking, placement, or resource constraints). OLM supports Extension Overrides, allowing users to provide customizations that are applied to underlying objects like Deployments, StatefulSets, or ReplicaSets.

    Supported Customization Fields:

    • Volume mounts
    • Annotations and Labels
    • Environment variables
    • Taints and Tolerations
    • Node selectors and Affinity
    • Resource requests/limits

  9. Understand the OLM 1.0 API design principles

    main

    OLM 1.0 is designed around several core behavioral principles that dictate how users and automation interact with extensions:

    • Single API Control Surface: A single, cluster-level API represents an installed extension, providing high-level controls for the entire lifecycle.
    • GitOps-friendly & Declarative: The API is designed for declarative workflows (e.g., via GitOps pipelines). It mandates continuous reconciliation and eventual consistency. Operations should not require manual cleanup of failed attempts or conditional lookups of other cluster objects.
    • Event-driven Auditing: OLM uses Kubernetes events to provide an audit trail. Administrators should rely on events and status conditions for debugging rather than controller logs.
    • Force Overrides: OLM provides mechanisms to force-override safety decisions during installation, removal, or updates when a user has specific knowledge that contradicts OLM's automated checks.
    • Scalability: API controls are designed to scale linearly with cluster size and namespace count to protect API server stability and system memory.

  10. Understand GraphQL field naming conventions

    main

    GraphQL field names are automatically generated from catalog schema names using a specific transformation process. This is important for constructing valid queries.

    Transformation Rules:

    1. Remove dots and special characters (e.g., olm.bundle → olmbundle).
    2. Convert to lowercase (e.g., OLM.Bundle → olmbundle).
    3. Append 's' for pluralization (e.g., olmbundle → olmbundles).

    Common Mappings:

    Schema NameGraphQL Field Name
    olm.bundleolmbundles
    olm.packageolmpackages
    olm.channelolmchannels
    helm.charthelmcharts

    Warning: Pluralization is a simple 's' suffix. It may not be grammatically correct (e.g., index becomes indexs). When creating custom schemas, use singular nouns that pluralize well with an 's'.