# gardener/machine-controller-manager architecture

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

- Interactive diagram: https://gitdiagram.com/gardener/machine-controller-manager
- Repository: https://github.com/gardener/machine-controller-manager

## Overview

##### Main Components
- Controllers: There are multiple controllers, each with a distinct purpose:
- MachineDeployment Controller: Reconciles MachineDeployment objects and oversees the creation and update of MachineSet objects.
- MachineSet Controller: Ensures that the desired number of Machine objects exist.
- Machine Controller: Manages the lifecycle of individual Machine objects.
- Safety Controller: Monitors safety thresholds and freezes/unfreezes operations if cloud provider or replica inconsistencies occur.
- Custom Resource Definitions (CRDs): Represent the objects that the controllers work with. Essential CRDs include:
- MachineClass (templates for cloud provider specifics)
- Machine (the virtual machine/VM instances)
- MachineSet (grouping and scaling of Machines)
- MachineDeployment (declarative updates and roll-out of MachineSets and Machines)
- Kubernetes Resources: The system inherently interacts with the Kubernetes control plane (e.g., API Server, etcd) and secrets (for cloud credentials and configurations).

##### Understand the File Structure and Its Architectural Impact
- The top-level directories – “cmd”, “pkg”, “kubernetes”, “docs”, “hack” – clearly indicate separation between binary entry points (cmd), implementation libraries and core logic (pkg), Kubernetes manifests (kubernetes), documentation (docs) and supporting scripts (hack).
- In the “pkg” directory, you have subdirectories for “apis”, “controller”, “client”, “util”, and “metrics”. This maps directly to the various concerns of the system:
- “pkg/apis” contains API definitions and CRDs.
- “pkg/controller” houses the implementation of the controllers.
- “pkg/client” and “pkg/util” include helper functions, shared informers, workqueues, leader election logic, and rate limiting.
- The “kubernetes” folder includes manifests (CRD definitions, deployment YAMLs) that show how the machine-controller-manager is deployed and interacts with Kubernetes.
- The “.ci” directory includes pipelines and sample objects for different cloud providers (AWS, Azure, GCP, Openstack), highlighting that cloud-specific configurations are abstracted via MachineClass YAMLs and similar templates.

##### Relationships and Data Flow
- Machine-controller-manager as a collection of components (each controller) that watches over and reconciles its respective CRD:
- A hierarchical relationship between:
- MachineDeployment Controller (grandparent) → manages → MachineSet Controller (parent) → manages → Machine Controller (child)
- Safety Controller as a side component that takes input from overall machine state (Machine, MachineSet, MachineDeployment) and can “freeze” actions on these objects if defined thresholds are breached.
- External cloud providers (AWS, Azure, GCP, etc.) as separate entities that the controllers interact with indirectly through the MachineClass templates and cloud credentials (stored in Secrets).
- Incorporate integration with Prometheus for metrics reporting and leader election features that help scale the controllers for high-availability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Kubernetes Control Plane
    subgraph "Kubernetes Control Plane"
        KCP["Kubernetes API Server & etcd"]:::k8s
    end

    %% machine-controller-manager Block
    subgraph "machine-controller-manager"
        %% Controllers Subgraph
        subgraph "Controllers"
            MD["MachineDeployment Controller"]:::controller
            MS["MachineSet Controller"]:::controller
            MC["Machine Controller"]:::controller
            SC["Safety Controller"]:::controller
        end
        %% CRDs Subgraph
        subgraph "Custom Resource Definitions"
            CRD_API["CRD API Definitions"]:::crd
            CRD_YAML["CRD YAML Manifests"]:::crd
        end
        %% Deployment & Utilities Subgraph
        subgraph "Deployment & Utilities"
            DEPLOY["Deployment Manifests"]:::deployment
            MACHINE_OBJ["Machine Examples"]:::deployment
            LE["Leader Election"]:::utility
            PM["Prometheus Metrics"]:::utility
        end
    end

    %% External Systems Subgraph
    subgraph "External Systems"
        CP["Cloud Providers"]:::external
        CPConf["Cloud Provider Configurations"]:::external
    end

    %% Arrows from Kubernetes Control Plane to Controllers
    KCP -->|"watches"| MD
    KCP -->|"watches"| MS
    KCP -->|"watches"| MC
    KCP -->|"watches"| SC

    %% Hierarchical relationship among Controllers
    MD -->|"manages"| MS
    MS -->|"manages"| MC

    %% Controllers updating CRD Definitions
    MD ---|"updates"| CRD_API
    MS ---|"updates"| CRD_API
    MC ---|"updates"| CRD_API

    %% CRDs registered/applied back to Control Plane
    CRD_API -->|"registered"| KCP
    CRD_YAML -->|"applied"| KCP

    %% Safety Controller monitors other Controllers
    SC ---|"monitors"| MD
    SC ---|"monitors"| MS
    SC ---|"monitors"| MC

    %% Controllers integrating with Cloud Providers
    MD -->|"integrates"| CP
    MC -->|"integrates"| CP

    %% Cloud Providers configured externally
    CP -->|"configured_by"| CPConf

    %% Deployment resources linking to Kubernetes Control Plane
    DEPLOY ---|"deploys to"| KCP
    MACHINE_OBJ ---|"example objects"| KCP

    %% Utilities supporting Controllers
    LE ---|"supports"| MD
    LE ---|"supports"| MS
    LE ---|"supports"| MC

    PM ---|"collects from"| MD
    PM ---|"collects from"| MS
    PM ---|"collects from"| MC

    %% Click Events
    click MD "https://github.com/gardener/machine-controller-manager/blob/master/pkg/controller/deployment.go"
    click MS "https://github.com/gardener/machine-controller-manager/blob/master/pkg/controller/machineset.go"
    click MC "https://github.com/gardener/machine-controller-manager/blob/master/pkg/util/provider/machinecontroller/machine.go"
    click SC "https://github.com/gardener/machine-controller-manager/blob/master/pkg/controller/machine_safety.go"
    click CRD_API "https://github.com/gardener/machine-controller-manager/tree/master/pkg/apis/machine/v1alpha1/"
    click CRD_YAML "https://github.com/gardener/machine-controller-manager/tree/master/kubernetes/crds/"
    click DEPLOY "https://github.com/gardener/machine-controller-manager/tree/master/kubernetes/deployment/out-of-tree/"
    click MACHINE_OBJ "https://github.com/gardener/machine-controller-manager/tree/master/kubernetes/machine_objects/"
    click CPConf "https://github.com/gardener/machine-controller-manager/tree/master/.ci/sample-objects/"

    %% Styles
    classDef k8s fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef controller fill:#ffdead,stroke:#000,stroke-width:2px;
    classDef crd fill:#c1ffc1,stroke:#000,stroke-width:2px;
    classDef deployment fill:#f0e68c,stroke:#000,stroke-width:2px;
    classDef utility fill:#d3d3d3,stroke:#000,stroke-width:2px;
    classDef external fill:#e6e6fa,stroke:#000,stroke-width:2px;
```
