# kubermatic/machine-controller architecture

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

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

## Overview

##### Main components
- Machine-Controller: The centralized controller that handles the reconciliation loops for Machine, MachineDeployment, and MachineSet resources. Highlight its role in reading CRDs from the Kubernetes API.
- Webhook Component: This separate executable (located in cmd/webhook) is used for admission control and securing HTTPS endpoints for resource validation/mutation.
- Cloud Provider Abstraction Layer: Represent this as a dedicated module which encompasses all the different cloud provider integrations (e.g., Alibaba, AWS, Azure, DigitalOcean, OpenStack, etc.). Note that each provider’s implementation is arranged in subdirectories under pkg/cloudprovider/provider and also in the sdk.
- Kubernetes API Server: Show the interaction between the cluster’s API server and the machine-controller for receiving CRDs and updating cluster state.
- Operating System Manager (External): Include a link or external module for the Operating System Manager which now takes over some responsibilities (user data management) that were formerly part of machine-controller.
- Supporting Services & Utilities: Include supporting components such as:
- Admission (for validating machine deployments and machines),
- ClusterInfo (managing cluster-info ConfigMaps),
- Node Management (node CSR approval, pod deletion, eviction, etc.),
- SDK/APIs: This exposes the CRD APIs and conversion logic.

##### Relationships and Interactions
- Machine-Controller’s communication with the Cloud Provider Abstraction Layer to make API calls to external cloud services. Indicate that different providers are “plugged in” under this layer.
- Integration between the Machine-Controller and the Operating System Manager by noting that the latter is responsible for generating and managing configurations (user data) required by machines for bootstrapping.
- Test and CI/CD aspects as a cloud or separate process (e.g., from the “hack” and “test/e2e” directories) to show that continuous integration, unit tests, and end-to-end tests are an integral part of the development lifecycle.

##### Architectural Patterns and Design Principles
- The project follows a controller pattern common in Kubernetes operator development. Clearly separate concerns by showing distinct control loops (machine, machine deployment, and machineset controllers).
- It uses a multi-provider plugin style within its Cloud Provider Layer, where each provider is modularized.
- The project uses admission webhooks to intercept and validate Kubernetes object creation/updates.
- That the architecture supports extensibility (e.g., community-provided providers) and integration with external components like cert-manager and the Operating System Manager.

##### Technologies, Frameworks, and Libraries
- Go as the main programming language (as indicated by the go.mod, go.sum, and Go source files).
- Mention that the project uses Kubernetes client libraries (for CRD watching and modifying resources) and that it integrates with cert-manager for certificate management.
- That policies for node bootstrapping (via cluster-info ConfigMap) and CRD conversions (provided in the SDK) are key to the workflow.
- Recognize additional utilities in the “pkg/log”, “pkg/health”, and “pkg/migrations” layers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    K8S["Kubernetes API Server"]:::k8s
    MC["Machine Controller"]:::controller

    K8S -->|"CRD_events"| MC

    subgraph "Cloud Provider Abstraction"
        CP1["Provider Directory"]:::cp
        CP2["SDK Cloud Provider"]:::cp
    end

    subgraph "Admission Services"
        WH["Admission Webhook"]:::webhook
        AD["Admission Module"]:::admission
    end

    subgraph "Node Management"
        NM_NM["Node Manager"]:::nodeMgmt
        NM_EV["Eviction"]:::nodeMgmt
    end

    CI["ClusterInfo ConfigMap"]:::cluster
    SDK["SDK/APIs"]:::sdk
    OSM["Operating System Manager"]:::osmgmt
    CICD["CI/CD & Testing"]:::cicd

    MC -->|"calls"| CP1
    MC -->|"calls"| CP2
    MC -->|"validates"| WH
    MC -->|"validates"| AD
    MC -->|"updates"| CI
    MC -->|"manages"| NM_NM
    MC -->|"manages"| NM_EV
    MC -->|"converts"| SDK
    MC -->|"configures"| OSM
    MC -->|"triggers"| CICD

    click MC "https://github.com/kubermatic/machine-controller/blob/main/cmd/machine-controller/main.go"
    click WH "https://github.com/kubermatic/machine-controller/blob/main/cmd/webhook/main.go"
    click CP1 "https://github.com/kubermatic/machine-controller/tree/main/pkg/cloudprovider/provider"
    click CP2 "https://github.com/kubermatic/machine-controller/tree/main/sdk/cloudprovider"
    click AD "https://github.com/kubermatic/machine-controller/tree/main/pkg/admission"
    click CI "https://github.com/kubermatic/machine-controller/blob/main/pkg/clusterinfo/configmap.go"
    click NM_NM "https://github.com/kubermatic/machine-controller/blob/main/pkg/node/nodemanager/node_manager.go"
    click NM_EV "https://github.com/kubermatic/machine-controller/blob/main/pkg/node/eviction/eviction.go"
    click SDK "https://github.com/kubermatic/machine-controller/tree/main/sdk"
    click OSM "https://github.com/kubermatic/machine-controller/blob/main/examples/operating-system-manager.yaml"

    classDef k8s fill:#bbdefb,stroke:#1e88e5,stroke-width:2px,color:#000;
    classDef controller fill:#fff176,stroke:#fbc02d,stroke-width:2px,color:#000;
    classDef webhook fill:#ffab91,stroke:#ff7043,stroke-width:2px,color:#000;
    classDef cp fill:#c5e1a5,stroke:#8bc34a,stroke-width:2px,color:#000;
    classDef admission fill:#80cbc4,stroke:#4db6ac,stroke-width:2px,color:#000;
    classDef cluster fill:#ce93d8,stroke:#ab47bc,stroke-width:2px,color:#000;
    classDef nodeMgmt fill:#b0bec5,stroke:#78909c,stroke-width:2px,color:#000;
    classDef sdk fill:#f8bbd0,stroke:#f06292,stroke-width:2px,color:#000;
    classDef osmgmt fill:#dcedc8,stroke:#7cb342,stroke-width:2px,color:#000;
    classDef cicd fill:#ffe082,stroke:#ffb300,stroke-width:2px,color:#000;
```
