# metal3-io/metal3-dev-env architecture

> Architecture diagram of the GitHub repository metal3-io/metal3-dev-env, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/metal3-io/metal3-dev-env
- Repository: https://github.com/metal3-io/metal3-dev-env

## Overview

##### Project Type and Purpose
- This is an automation/orchestration toolkit for standing up a Metal³ development environment.
- It combines shell scripts, Ansible roles, and Kubernetes-based control-plane components to:
- Prepare and configure the host OS
- Bootstrap a “management cluster” (Minikube or Kind) running Cluster API (CAPI), Cluster API Provider Metal³ (CAPM3), Baremetal Operator (BMO), and IPAM
- Provision and pivot to a “target cluster” of bare-metal VMs via Ironic and the Metal³ operator
- Run integration tests and PoCs

A. Host Layer
- Physical or VM host OS
- Hypervisor: KVM (default) or QEMU
- Networking: bridge, libvirt
B. Preparation & Configuration Scripts
- 01_prepare_host.sh → 02_configure_host.sh
- Ansiblized host setup under `vm-setup/`
C. Management Cluster
- Kubernetes control plane (Minikube or Kind)
- CAPI controllers
- CAPM3 controllers
- BMO controllers
- IPAM controllers
- Ironic containers (bare-metal provisioning service)
D. Provisioning Pipeline
- `03_launch_mgmt_cluster.sh`
- `tests/scripts/provision/*.sh`
- `clusterctl` based cluster and machine templates
E. Target Cluster
- Metal³-provisioned control plane
- Worker nodes (bare-metal VMs managed by Ironic)
F. Pivot Operation
- `tests/scripts/provision/pivot.sh`
- Switch CAPI management from Minikube to target cluster
G. Testing & PoCs
- Integration tests under `tests/`
- PoC scenarios under `PoCs/`

##### Interactions & Flows
- Host Layer → Scripts/Ansible: set up virtualization, networking, dependencies
- Scripts → Management Cluster: install Kubernetes control plane and controllers
- Management Cluster → Ironic containers: provision bare-metal nodes
- Provisioning Pipeline → Target Cluster: apply Cluster API resources to boot real nodes
- Pivot script: re-point CLI to target cluster
- Tests → Management & Target Clusters: validate cluster and machine states

##### Architectural Patterns & Principles
- Layered orchestration: Scripts (shell/Ansible) at the bottom → Kubernetes controllers at the middle → target VMs at the top
- Infrastructure as code: all steps codified in scripts, playbooks, kustomize
- Controller pattern: CAPI/CAPM3/BMO/IPAM run as controllers inside the management cluster
- Immutable clusters: provision via templated YAML, tear down and recreate

##### Putting It All Together
- Above/Right: “Target Metal³ Cluster” – control plane + worker VMs
- Optional overlay: show the Tilt workflow (under `tilt-setup/`) branching off management cluster for local development

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers and Components

    subgraph "Host Layer"
        Host["Physical/VM Host\nKVM/QEMU\nbridge, libvirt"]:::host
    end

    subgraph "Bootstrap Scripts & Ansible Roles"
        Prepare["01_prepare_host.sh"]:::scripts
        Configure["02_configure_host.sh"]:::scripts
        CleanupHost["host_cleanup.sh"]:::scripts
        Ansible["vm-setup/"]:::scripts
    end

    subgraph "Management Kubernetes Cluster"
        MCPlane["Minikube / Kind Control Plane"]:::k8s
        subgraph "Controllers"
            CAPI["CAPI Controllers"]:::k8s
            CAPM3["CAPM3 Controllers"]:::k8s
            BMO["BMO Controllers"]:::k8s
            IPAM["IPAM Controllers"]:::k8s
        end
        Ironic["Ironic Service"]:::metal3
    end

    subgraph "Provisioning Pipeline"
        LaunchMgmt["03_launch_mgmt_cluster.sh"]:::scripts
        FetchManifests["tests/scripts/fetch_manifests.sh"]:::scripts
        ClusterProv["tests/scripts/provision/cluster.sh"]:::scripts
        ControlPlaneProv["tests/scripts/provision/controlplane.sh"]:::scripts
        WorkerProv["tests/scripts/provision/worker.sh"]:::scripts
        PivotProv["tests/scripts/provision/pivot.sh"]:::scripts
        Verify["04_verify.sh"]:::scripts
    end

    subgraph "Target Metal³ Cluster"
        TargetPlane["Metal³ Provisioned Control Plane"]:::k8s
        Workers["Bare-metal VMs"]:::metal3
    end

    subgraph "Tests & PoCs"
        TestsSuite["tests/"]:::tests
        PoCs["PoCs/"]:::tests
    end

    %% Flows
    Host --> Prepare
    Host --> Configure
    Host --> CleanupHost
    Prepare --> MCPlane
    Configure --> MCPlane
    Ansible --> MCPlane

    MCPlane --> FetchManifests --> CAPI
    MCPlane --> LaunchMgmt --> ClusterProv --> ControlPlaneProv --> WorkerProv --> TargetPlane
    ControlPlaneProv --> TargetPlane
    WorkerProv --> Workers
    PivotProv --> TargetPlane
    MCPlane --> Ironic

    TestsSuite --> MCPlane
    TestsSuite --> TargetPlane
    PoCs --> MCPlane
    PoCs --> TargetPlane

    %% Click Events
    click Prepare "https://github.com/metal3-io/metal3-dev-env/blob/main/01_prepare_host.sh"
    click Configure "https://github.com/metal3-io/metal3-dev-env/blob/main/02_configure_host.sh"
    click CleanupHost "https://github.com/metal3-io/metal3-dev-env/blob/main/host_cleanup.sh"
    click Ansible "https://github.com/metal3-io/metal3-dev-env/tree/main/vm-setup/"
    click LaunchMgmt "https://github.com/metal3-io/metal3-dev-env/blob/main/03_launch_mgmt_cluster.sh"
    click FetchManifests "https://github.com/metal3-io/metal3-dev-env/blob/main/tests/scripts/fetch_manifests.sh"
    click ClusterProv "https://github.com/metal3-io/metal3-dev-env/blob/main/tests/scripts/provision/cluster.sh"
    click ControlPlaneProv "https://github.com/metal3-io/metal3-dev-env/blob/main/tests/scripts/provision/controlplane.sh"
    click WorkerProv "https://github.com/metal3-io/metal3-dev-env/blob/main/tests/scripts/provision/worker.sh"
    click PivotProv "https://github.com/metal3-io/metal3-dev-env/blob/main/tests/scripts/provision/pivot.sh"
    click Verify "https://github.com/metal3-io/metal3-dev-env/blob/main/04_verify.sh"
    click TestsSuite "https://github.com/metal3-io/metal3-dev-env/tree/main/tests/"
    click PoCs "https://github.com/metal3-io/metal3-dev-env/tree/main/PoCs/"

    %% Styles
    classDef host fill:#d3d3d3,stroke:#333;
    classDef scripts fill:#ffa500,stroke:#333;
    classDef k8s fill:#add8e6,stroke:#333;
    classDef metal3 fill:#90ee90,stroke:#333;
    classDef tests fill:#dda0dd,stroke:#333;
```
