# kubernetes-sigs/cluster-api architecture

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

- Interactive diagram: https://gitdiagram.com/kubernetes-sigs/cluster-api
- Repository: https://github.com/kubernetes-sigs/cluster-api

## Overview

##### Main Components
- API & CRD Layer: Represent the custom resource definitions defined in the “api”, “internal/apis”, and “exp/api” directories. This layer is the interface for the cluster, machine, clusterclass, and add-on objects.
- Controllers and Control Loops: Highlight the various controllers found in directories like “controllers”, “internal/controllers”, “controlplane”, “controllers/external”, and the migration or topology reconcilers. These components implement the reconciliation loops that ensure the desired state of clusters.
- Webhooks: Include the webhook components (under “webhooks” and “internal/webhooks”) that enforce validations, conversions, and admission control.
- Providers & Extensions: Show the extension points for infrastructure, bootstrap, and control plane providers. These are built on top of core APIs and include provider-specific implementations (e.g., in “bootstrap”, “cmd/clusterctl”, and “internal/contract”) that enable integration with AWS, Azure, vSphere, or other environments.
- Configuration & Deployment: Illustrate the manifest management and deployment configurations from directories such as “config”, “docs”, and “hack” that support environment setup, release generation, and CI/CD workflows.
- Testing & Observability: Optionally include the test directories (like “test”, “internal/test”, “hack/observability”) and utility packages that provide integration tests, logging, and metrics for the controllers.

##### Relationships and Interactions
- Connections between webhooks and the API layer for validation and conversion, ensuring data consistency.
- How provider-specific modules (bootstrap, control plane, infrastructure providers) interact with the controllers to manage external underlying systems (like VMs, load balancers, networking resources).
- If desired, include a feedback loop where monitoring/observability components gather data from controllers and infrastructure to feed back into higher-level dashboards or logging.

##### Architectural Patterns and Design Principles
- The architecture follows a declarative model where the desired state (expressed as CRDs) is continuously reconciled by controllers. Emphasize this control loop approach.
- The layered design – splitting API definitions, controllers, tooling, and provider integrations – should be clearly visible.
- That extensibility is key: multiple “provider” integrations and experimental (exp/) components mean the ecosystem is pluggable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI / Tooling Layer
    subgraph "CLI / Tooling"
        CLI["clusterctl CLI"]:::cli
    end

    %% API & CRD Layer
    subgraph "API & CRD Layer"
        API1["CRD: api"]:::api
        API2["CRD: internal/apis"]:::api
        API3["CRD: exp/api"]:::api
    end

    %% Controllers & Reconciliation Layer
    subgraph "Controllers & Reconciliation"
        CTRL1["Controller: controllers"]:::controllers
        CTRL2["Control Plane: kubeadm"]:::controllers
        CTRL3["Experimental Controller: exp/controllers"]:::controllers
        CTRL4["Experimental Controller: exp/internal/controllers"]:::controllers
    end

    %% Webhooks Layer
    subgraph "Webhooks"
        WH1["Webhook: webhooks"]:::webhooks
        WH2["Webhook: internal/webhooks"]:::webhooks
        WH3["Provider Webhook: bootstrap/kubeadm/internal/webhooks"]:::webhooks
        WH4["Provider Webhook: controlplane/kubeadm/webhooks"]:::webhooks
        WH5["Experimental Webhook: exp/internal/webhooks"]:::webhooks
        WH6["Experimental Webhook: exp/webhooks"]:::webhooks
    end

    %% Providers & Extensions Layer
    subgraph "Providers & Extensions"
        PROV1["Provider Module: bootstrap"]:::providers
        PROV2["Provider Contract: internal/contract"]:::providers
    end

    %% Configuration & Deployment Layer
    subgraph "Configuration & Deployment"
        CONF1["Config: config"]:::config
        CONF2["Documentation: docs"]:::config
        CONF3["Deployment Scripts: hack"]:::config
    end

    %% Testing & Observability Layer
    subgraph "Testing & Observability"
        TEST1["Test Suite: test"]:::test
        TEST2["Observability: hack/observability"]:::test
    end

    %% Connections
    CLI -->|"triggers"| API1
    API1 -->|"watches"| CTRL1
    CTRL1 -->|"manages"| PROV1
    API1 -->|"validation"| WH1
    WH1 -->|"approves"| API1
    CTRL1 -->|"metrics"| TEST1
    CLI -->|"usesConfig"| CONF3
    CONF3 -->|"deploysTo"| PROV1

    %% Click Events for API & CRD Layer
    click API1 "https://github.com/kubernetes-sigs/cluster-api/tree/main/api"
    click API2 "https://github.com/kubernetes-sigs/cluster-api/tree/main/internal/apis"
    click API3 "https://github.com/kubernetes-sigs/cluster-api/tree/main/exp/api"

    %% Click Events for Controllers & Control Loops
    click CTRL1 "https://github.com/kubernetes-sigs/cluster-api/tree/main/controllers"
    click CTRL2 "https://github.com/kubernetes-sigs/cluster-api/tree/main/controlplane/kubeadm"
    click CTRL3 "https://github.com/kubernetes-sigs/cluster-api/tree/main/exp/controllers"
    click CTRL4 "https://github.com/kubernetes-sigs/cluster-api/tree/main/exp/internal/controllers"

    %% Click Events for Webhooks
    click WH1 "https://github.com/kubernetes-sigs/cluster-api/tree/main/webhooks"
    click WH2 "https://github.com/kubernetes-sigs/cluster-api/tree/main/internal/webhooks"
    click WH3 "https://github.com/kubernetes-sigs/cluster-api/tree/main/bootstrap/kubeadm/internal/webhooks"
    click WH4 "https://github.com/kubernetes-sigs/cluster-api/tree/main/controlplane/kubeadm/webhooks"
    click WH5 "https://github.com/kubernetes-sigs/cluster-api/tree/main/exp/internal/webhooks"
    click WH6 "https://github.com/kubernetes-sigs/cluster-api/tree/main/exp/webhooks"

    %% Click Events for Providers & Extensions
    click PROV1 "https://github.com/kubernetes-sigs/cluster-api/tree/main/bootstrap"
    click PROV2 "https://github.com/kubernetes-sigs/cluster-api/tree/main/internal/contract"

    %% Click Event for CLI / Tooling
    click CLI "https://github.com/kubernetes-sigs/cluster-api/tree/main/cmd/clusterctl"

    %% Click Events for Configuration & Deployment
    click CONF1 "https://github.com/kubernetes-sigs/cluster-api/tree/main/config"
    click CONF2 "https://github.com/kubernetes-sigs/cluster-api/tree/main/docs"
    click CONF3 "https://github.com/kubernetes-sigs/cluster-api/tree/main/hack"

    %% Click Events for Testing & Observability
    click TEST1 "https://github.com/kubernetes-sigs/cluster-api/tree/main/test"
    click TEST2 "https://github.com/kubernetes-sigs/cluster-api/tree/main/hack/observability"

    %% Styles
    classDef cli fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef api fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef controllers fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef webhooks fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef providers fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef config fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef test fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
