# kubernetes-sigs/cluster-api-provider-azure architecture

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

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

## Overview

##### Main Components
- CRDs / API Definitions: Represented by the “api” directory (with versions v1alpha1 and v1beta1). These define the objects (e.g., AzureCluster, AzureManagedCluster, AzureMachinePool, etc.) that are managed declaratively.
- Controllers / Reconcilers: Found in the “controllers” directory; these are the control loops that monitor CRD state and reconcile desired against actual state.
- Azure Integration and Abstraction Layer: This includes the “azure” package and its submodules (such as converters, scopes, services, and clients) that encapsulate the interactions with the Azure APIs – managing things like virtual machines, load balancers, networks, disks, and other cloud resources.
- Kubernetes Manifests and Operator Deployment: Represented by the “config” and “templates” directories, providing deployment manifests (manager, webhook, CRDs) and various cluster templates (“flavors”) for different deployment scenarios.
- Supporting Libraries & Utilities: Under “pkg”, “util”, and “hack”, providing common functionality such as caching, logging, version handling, and reconciliation helpers.
- Testing / Mocks: Test directories and mocks (test, exp, internal/test) that support validation of controllers and integration with Azure APIs.

##### Relationships and Interactions
- The Kubernetes API Server (external to CAPZ) holds the desired state via CRDs.
- Controllers continuously watch these CRDs. When a change is detected, these controllers invoke reconciliation loops to ensure the actual state in Azure matches the declared state.
- The Controllers interact with the Azure integration layer; this layer abstracts the creation, updating, and deletion of Azure resources. It uses a set of specialized components (clients, converters, scopes) to map Kubernetes state to Azure operations.
- The Azure integration layer communicates with external Azure cloud services through REST APIs.
- In addition, there is automated observability (e.g., logging, telemetry, metrics) inside the CAPZ controllers, as seen in packages under “pkg/ot” and “util/tele”.

##### Architectural Patterns and Principles
- Reconciler Pattern: Central to the design, with dedicated controllers for different resource kinds (clusters, machine pools, etc.).
- Separation of Concerns: Clear division between CRD definitions, controller logic, and Azure service integrations.
- Modularity and Extensibility: The use of distinct directories for API, controllers, Azure-specific functions, and external templates supports a modular design and extensibility.
- Testability: The presence of mocks and a rich testing framework to consistently validate each component.

##### Relevant Technologies, Frameworks, and Libraries
- Golang as the programming language.
- Kubernetes APIs, Custom Resource Definitions (CRDs), and controller-runtime libraries.
- Azure Go SDK or custom REST client abstractions for Azure interactions.
- Standard Kubernetes configuration (YAML manifests) and kustomize for managing deployments and templates.
- Testing frameworks like Ginkgo/Gomega, and automated CI workflows (as visible in the .github/workflows directory).

##### Additional Suggestions
- Annotations explaining key responsibilities (e.g., “Reconciler updates resource state”, “Azure service client manages VM lifecycle”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Kubernetes Control Plane"
        API["Kubernetes API Server / CRDs"]:::k8s
        CONTROL["CAPZ Controllers / Reconcilers"]:::k8s
    end

    subgraph "Cloud Integration"
        AZ_INT["Azure Integration Layer"]:::azure
        AZ_SERV["Azure Services / Clients"]:::azure
        AZ_CLOUD["Azure Cloud (External Service)"]:::external
    end

    subgraph "Deployment"
        DEP_CONFIG["Manifests (config)"]:::config
        DEP_TEMPLATES["Templates (templates)"]:::config
    end

    subgraph "Supporting & Testing"
        subgraph "Libraries & Utilities"
            PKG["pkg/"]:::utility
            UTIL_NODE["util/"]:::utility
            HACK_NODE["hack/"]:::utility
        end
        subgraph "Testing / Mocks"
            TEST_NODE["test/"]:::test
            EXP_NODE["exp/"]:::test
            INTERNAL_TEST["internal/test/"]:::test
        end
    end

    API -->|"watch"| CONTROL
    CONTROL -->|"reconcile"| AZ_INT
    AZ_INT -->|"invoke"| AZ_SERV
    AZ_SERV -->|"cloud_ops"| AZ_CLOUD
    AZ_CLOUD -->|"status_update"| API

    CONTROL -->|"uses"| DEP_CONFIG
    CONTROL -->|"uses"| DEP_TEMPLATES

    CONTROL -->|"logging"| PKG
    CONTROL -->|"telemetry"| UTIL_NODE
    CONTROL -->|"testing"| TEST_NODE

    click API "https://github.com/kubernetes-sigs/cluster-api-provider-azure/tree/main/api/"
    click CONTROL "https://github.com/kubernetes-sigs/cluster-api-provider-azure/tree/main/controllers/"
    click AZ_INT "https://github.com/kubernetes-sigs/cluster-api-provider-azure/tree/main/azure/"
    click AZ_SERV "https://github.com/kubernetes-sigs/cluster-api-provider-azure/tree/main/azure/services/"
    click DEP_CONFIG "https://github.com/kubernetes-sigs/cluster-api-provider-azure/tree/main/config/"
    click DEP_TEMPLATES "https://github.com/kubernetes-sigs/cluster-api-provider-azure/tree/main/templates/"
    click PKG "https://github.com/kubernetes-sigs/cluster-api-provider-azure/tree/main/pkg/"
    click UTIL_NODE "https://github.com/kubernetes-sigs/cluster-api-provider-azure/tree/main/util/"
    click HACK_NODE "https://github.com/kubernetes-sigs/cluster-api-provider-azure/tree/main/hack/"
    click TEST_NODE "https://github.com/kubernetes-sigs/cluster-api-provider-azure/tree/main/test/"
    click EXP_NODE "https://github.com/kubernetes-sigs/cluster-api-provider-azure/tree/main/exp/"
    click INTERNAL_TEST "https://github.com/kubernetes-sigs/cluster-api-provider-azure/tree/main/internal/test/"

    classDef k8s fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef azure fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef config fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef utility fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef test fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
```
