Deployment Guide
metal-stack is a Metal-as-a-Service (MaaS) platform that turns on-premises bare-metal servers into an elastic, self-managed cloud infrastructure. At its core, metal-stack consists of two components:
- Control Plane — The central management layer (APIs, databases, scheduling)
- Partitions — The data center infrastructure (servers, leaf switches, BMCs)
These two components alone provide a fully functional Bare-Metal as a Service (MaaS) platform. You can allocate machines, manage networks, configure firewalls, and operate servers via REST/gRPC APIs and the metalctl CLI — without any Kubernetes cluster lifecycle management.
Kubernetes Cluster Lifecycle Management
If you need to provision Kubernetes clusters on top of your bare-metal infrastructure, metal-stack integrates with KCLM solutions like Gardener or Cluster-API. These are optional layers built on top of the MaaS foundation — not prerequisites.
You can use metal-stack as a pure MaaS platform without any KCLM integration. The KCLM layer is only needed if you want to automate Kubernetes cluster provisioning on your bare-metal infrastructure.
Deployment Approaches
We are bootstrapping the metal control plane as well as our partitions with Ansible through CI.
We recommend using the same Ansible roles that we use to deploy metal-stack in our own environments. They are available in the metal-roles repository.
To simplify dependency management, we provide a dedicated deployment base image on GitHub Container Registry. This Docker image bundles all required tools and libraries, keeping your deployment environment lean and easy to maintain.
The remainder of this guide assumes you are using our Ansible roles and the deployment base image. Make sure you have Docker installed. Every deployment environment is unique, so this guide describes how we set up metal-stack in our own infrastructure. You will need to adapt the steps to match your specific requirements.
Probably you need to learn writing Ansible playbooks if you want to be able to deploy the metal-stack as presented in this documentation. However, even when starting without any knowledge about Ansible it should be possible to follow these docs. In case you need further explanations regarding Ansible please refer to docs.ansible.com.
If you do not want to use Ansible for deployment, you need to come up with a deployment mechanism by yourself. You can still learn from our metal-roles repository and Helm charts — but be aware that the Ansible roles tie everything together (variable management, dependency ordering, environment-specific configurations), so building an equivalent from scratch will require significant effort.
You can use the mini-lab as a template project for your own deployment. It uses the same approach as described in this document.