How metal3-io/metal3-dev-env works
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