# openshift/cluster-version-operator architecture

> Architecture diagram of the GitHub repository openshift/cluster-version-operator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openshift/cluster-version-operator
- Repository: https://github.com/openshift/cluster-version-operator

## Overview

##### Project Type & Purpose
- This is a Kubernetes cluster operator that orchestrates cluster upgrades by monitoring the custom “ClusterVersion” resource.
- The operator downloads, validates, and applies release payload manifests to update the cluster components.
- Key functionality includes fetching available updates, reconciling the desired cluster state with the actual state, and managing status conditions.

##### Core Components of the Architecture
a. ClusterVersion API Resource:
- Kubernetes Custom Resource “ClusterVersion” (with its spec and status fields) that acts as both input and output.
- That administrators use tools like “oc adm upgrade” or web console, which indirectly modify this resource.
b. Operator Controllers and Main Process:
- Primary CVO application (found in cmd/cluster-version-operator) that handles manifest reconciliation.
- Update status controller (e.g., cmd/cluster-version-operator/updatestatuscontroller.go) that manages the cluster’s upgrade progress.
c. Release Payload Processing:
- Component that downloads and validates the release payload image.
- How the operator reads the payload (using functionalities in pkg/payload, pkg/cvo, etc.) and extracts Kubernetes resource manifests.
d. Reconciliation & Resource Application:
- Reconciliation loop that compares the desired state (specified in the payload) and the observed state in the cluster.
e. Auxiliary Components:
- Additional modules like pkg/autoupdate, pkg/clusterconditions, pkg/updatestatus, and pkg/version. These support core operations such as periodic update checking, computing conditions, and status reporting.
- Mention integration with external systems (e.g., OpenShift Update Service), which provides available updates.

##### Relationships & Interactions
- Operator’s watcher mechanism – it monitors the “ClusterVersion” resource for changes (desired update, status conditions).
- Flow: release payload image → payload extraction (pkg/payload) → reconciliation (main process and reconciliation loop) → resource application (using lib modules) → update of cluster state.
- Internal communication between different modules such as the main operator process and the update status controller.

##### Architectural Patterns & Design Principles
- Standard Kubernetes reconciliation loop pattern (desired vs. actual state).
- Modular design: separate directories for cmd binaries, library functions (lib/), and logical grouping of operational code under pkg/.
- Use dependency injection and interface abstractions to enable testing (as seen with many *_test.go files scattered across pkg and lib directories).

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Components
    Admin["Admin (CLI/Web Console)"]:::external
    API["Kubernetes API Server"]:::external
    CVR["ClusterVersion API Resource"]:::external

    %% Operator Core Subgraph
    subgraph "Operator Core"
        MOP["Main Operator Process"]:::operator
        USC["Update Status Controller"]:::operator
        RPP["Release Payload Processor"]:::payload
        subgraph "Reconciliation & Application"
            RA["Resource Applier"]:::reconcile
            RM["Resource Merger"]:::reconcile
            RR["Resource Reader"]:::reconcile
        end
    end

    %% Auxiliary Modules Subgraph
    subgraph "Auxiliary Modules"
        AU["Auto Update Module"]:::aux
        CCM["Cluster Conditions Manager"]:::aux
        USM["Update Status Manager"]:::aux
        VH["Version Handler"]:::aux
    end

    %% External Update Service
    ExtUS["OpenShift Update Service"]:::external

    %% Relationships
    Admin -->|"triggers updates"| API
    API -->|"manages"| CVR
    CVR -->|"notifies"| MOP
    MOP -->|"invokes"| RPP
    RPP -->|"provides payload"| MOP
    MOP -->|"starts reconciliation"| RA
    MOP -->|"starts reconciliation"| RM
    MOP -->|"starts reconciliation"| RR
    RA --- RM
    RA --- RR
    RM --- RR
    MOP ---> USC
    USC ---> USM
    ExtUS -->|"supplies update info"| AU
    AU --> MOP
    %% Operator updates cluster resources
    RA -->|"updates"| API
    RM -->|"merges"| API
    RR -->|"reads manifests"| CVR

    %% Click Events
    click CVR "https://github.com/openshift/cluster-version-operator/tree/main/pkg/cvo/testdata/manifests"
    click MOP "https://github.com/openshift/cluster-version-operator/tree/main/cmd/cluster-version-operator"
    click USC "https://github.com/openshift/cluster-version-operator/blob/main/cmd/cluster-version-operator/updatestatuscontroller.go"
    click RPP "https://github.com/openshift/cluster-version-operator/tree/main/pkg/payload"
    click RA "https://github.com/openshift/cluster-version-operator/tree/main/lib/resourceapply"
    click RM "https://github.com/openshift/cluster-version-operator/tree/main/lib/resourcemerge"
    click RR "https://github.com/openshift/cluster-version-operator/blob/main/lib/resourceread/resourceread.go"
    click AU "https://github.com/openshift/cluster-version-operator/blob/main/pkg/autoupdate/autoupdate.go"
    click CCM "https://github.com/openshift/cluster-version-operator/tree/main/pkg/clusterconditions"
    click USM "https://github.com/openshift/cluster-version-operator/tree/main/pkg/updatestatus/api"
    click VH "https://github.com/openshift/cluster-version-operator/blob/main/pkg/version/version.go"

    %% Styles
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef operator fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef payload fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef reconcile fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef aux fill:#d6d8d9,stroke:#1b1e21,stroke-width:2px;
```
