# openshift/hypershift architecture

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

- Interactive diagram: https://gitdiagram.com/openshift/hypershift
- Repository: https://github.com/openshift/hypershift

## Overview

##### Major Components
- API Layer and CRDs:
– The “api” directory shows that HyperShift defines several custom resource types (for certificates, hostedclusters, hypershift configurations, scheduling, etc.). These CRDs are the backbone of the system’s declarative management.
- Operators and Controllers:
– There are multiple operator components (such as “control-plane-operator”, “hypershift-operator”, “control-plane-pki-operator”, “karpenter-operator”, “ignition-server”, etc.). Each operator encapsulates a set of controllers dedicated to reconciling a portion of the cluster’s state (for example, hosted control plane setup, nodepool management, cloud provider integration, healthchecks, and k8s proxy configurations).
- CLI/Client Interfaces:
– Directories such as “product-cli”, “client”, and “cmd” indicate that users interact with HyperShift using a CLI to create, manage, or upgrade clusters.
- Supporting Infrastructure & Tools:
– Additional folders for “etcd-backup”, “dnsresolver”, “support”, “hack”, “docs”, and “test” showcase a comprehensive tooling layer for testing, documentation, and maintenance.
- Cloud Provider Integrations:
– Within operator directories (for example in the “control-plane-operator/controllers/hostedcontrolplane/cloud” folder) you see separate integrations for AWS, Azure, OpenStack, IBMCloud, Powervs, and Kubevirt. These integrations are essential for provisioning and managing the underlying resources.

##### Relationships and Data Flow
- User or CLI (Product CLI) interacting with the Kubernetes API server of the management cluster by submitting CRD-based requests.
- CRDs represent the desired state (for hosted clusters, certificates, node pools, etc.).
- Operators and controllers that “watch” these CRDs:
– For example, the Control Plane Operator reconciles hosted control plane resources.
– The Hypershift Operator might coordinate tasks such as deploying the ignition server and ensuring proper network routing.
– A dedicated PKI operator manages certificate lifecycles.
– Other operators (like karpenter for autoscaling, nodepool controllers, etc.) ensure that infrastructure is adjusted according to the state defined in the CRDs.
- Optionally, add secondary paths for telemetry, logging, or backup processes (represented by directories like “etcd-backup” and “support”).

##### Architectural Patterns and Design Principles
- The system is designed on a controller–reconciler pattern intrinsic to Kubernetes operators.
- Clear separation between the control plane and workload clusters is maintained through the CRD definitions and the management of hosted control planes.
- Each operator encapsulates its own concerns and leverages common libraries (as seen in “pkg”, “support”, and “hack”) to reduce duplication and ensure consistency.

– From the CLI to the Management API server.
– From the API server (CRDs) to the respective Operators.
– From Operators to external cloud/provider services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI/Client Interfaces
    subgraph "CLI/Client Interfaces"
        A1["Product CLI"]:::cli
        A2["Client"]:::cli
        A3["CMD"]:::cli
    end

    %% Management Cluster containing API & CRDs
    subgraph "Management Cluster"
        B1["API & CRDs"]:::api
    end

    %% Operators and Controllers
    subgraph "Operators"
        C1["Control Plane Operator"]:::operator
        C2["Hypershift Operator"]:::operator
        C3["PKI Operator"]:::operator
        C4["Karpenter Operator"]:::operator
    end

    %% Cloud Provider Integrations
    subgraph "Cloud Providers"
        D1["AWS"]:::cloud
        D2["Azure"]:::cloud
        D3["OpenStack"]:::cloud
        D4["Powervs"]:::cloud
        D5["Kubevirt"]:::cloud
    end

    %% Supporting Infrastructure & Tools
    subgraph "Supporting Infrastructure & Tools"
        E1["Hack"]:::infra
        E2["Docs"]:::infra
        E3["Test"]:::infra
        E4["ETCD Backup"]:::infra
        E5["DNS Resolver"]:::infra
        E6["Support"]:::infra
    end

    %% Data Flow Connections
    %% CLI to API
    A1 -->|"sendsRequest"| B1
    A2 -->|"sendsRequest"| B1
    A3 -->|"sendsRequest"| B1

    %% API to Operators (reconciliation)
    B1 -->|"reconciles"| C1
    B1 -->|"reconciles"| C2
    B1 -->|"reconciles"| C3
    B1 -->|"reconciles"| C4

    %% Operators to Cloud Providers
    C1 -->|"provisions"| D1
    C1 -->|"provisions"| D2
    C1 -->|"provisions"| D3
    C1 -->|"provisions"| D4
    C1 -->|"provisions"| D5

    C2 -->|"supports"| D1
    C2 -->|"supports"| D2
    C2 -->|"supports"| D3
    C2 -->|"supports"| D4
    C2 -->|"supports"| D5

    %% Operators to Supporting Infrastructure (backup example)
    C1 -->|"backup"| E4
    C2 -->|"backup"| E4

    %% Click Events
    click B1 "https://github.com/openshift/hypershift/tree/main/api"
    click C1 "https://github.com/openshift/hypershift/tree/main/control‐plane‐operator"
    click C2 "https://github.com/openshift/hypershift/tree/main/hypershift-operator"
    click C3 "https://github.com/openshift/hypershift/tree/main/control-plane-pki-operator"
    click C4 "https://github.com/openshift/hypershift/tree/main/karpenter-operator"
    click A1 "https://github.com/openshift/hypershift/tree/main/product-cli"
    click A2 "https://github.com/openshift/hypershift/tree/main/client"
    click A3 "https://github.com/openshift/hypershift/tree/main/cmd"
    click E1 "https://github.com/openshift/hypershift/tree/main/hack"
    click E2 "https://github.com/openshift/hypershift/tree/main/docs"
    click E3 "https://github.com/openshift/hypershift/tree/main/test"
    click E4 "https://github.com/openshift/hypershift/tree/main/etcd-backup"
    click E5 "https://github.com/openshift/hypershift/tree/main/dnsresolver"
    click E6 "https://github.com/openshift/hypershift/tree/main/support"
    click D1 "https://github.com/openshift/hypershift/tree/main/control‐plane‐operator/controllers/hostedcontrolplane/cloud/aws"
    click D2 "https://github.com/openshift/hypershift/tree/main/control‐plane‐operator/controllers/hostedcontrolplane/cloud/azure"
    click D3 "https://github.com/openshift/hypershift/tree/main/control‐plane‐operator/controllers/hostedcontrolplane/cloud/openstack"
    click D4 "https://github.com/openshift/hypershift/tree/main/control‐plane‐operator/controllers/hostedcontrolplane/cloud/powervs"
    click D5 "https://github.com/openshift/hypershift/tree/main/control‐plane‐operator/controllers/hostedcontrolplane/cloud/kubevirt"

    %% Styles
    classDef api fill:#f9c,stroke:#333,stroke-width:2px;
    classDef operator fill:#ccf,stroke:#333,stroke-width:2px;
    classDef cli fill:#cfc,stroke:#333,stroke-width:2px;
    classDef infra fill:#fcf,stroke:#333,stroke-width:2px;
    classDef cloud fill:#ff9,stroke:#333,stroke-width:2px;
```
