From 760b34c495fab2eb220eb9b27416e6a78942b6ae Mon Sep 17 00:00:00 2001 From: Benjamin Ritter Date: Wed, 10 Jun 2026 09:48:26 +0000 Subject: [PATCH 1/5] feat: rework flavors explanation Signed-off-by: Benjamin Ritter --- docs/02-General/04-flavors-of-metalstack.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/02-General/04-flavors-of-metalstack.md b/docs/02-General/04-flavors-of-metalstack.md index 97767a7..1e14aa0 100644 --- a/docs/02-General/04-flavors-of-metalstack.md +++ b/docs/02-General/04-flavors-of-metalstack.md @@ -6,24 +6,28 @@ sidebar_position: 4 # Flavors of metal-stack -While metal-stack itself provides access to manage resources like machines, networks and ip addresses, it does not provide any higher abstractions on top when used on its own. +metal-stack bare metal provisioning offers machines, networks, firewalls and floating IPs. That`s it. -As modern infrastructure and cloud native applications are designed with Kubernetes in mind, we provide two different layers on top of metal-stack to provide provisioning of clusters. +You can consume it as-is... -> [Plain Flavor](#plain) + +... or use it as foundation for an orchestrator. We offer two K8s Flavors -> [Gardener](#gardener) and [Cluster API](#cluster-api) ## Plain -Regardless which flavor of metal-stack you use, it is always possible to manually provision machines, networks and ip addresses. This is the most basic way of using metal-stack and is very similar to how traditional bare metal infrastructures are managed. +All flavors start with this. This is what you get if you set up metal-stack and stop there. + +Using plain metal-stack without additional layer was not a focus in the past. Therefore firewall features and role management are quite basic. If There is ongoing work on [improved RBAC in MEP-4](/community/MEP-4-multi-tenancy-for-the-metal-api) and [firewall configuration via metal-api in MEP-16](/community/MEP-16-metal-api-as-an-alternative-configuration-source-for-the-firewall-controller). -Using plain metal-stack without additional layer was not a focus in the past. Therefore firewall and role management might be premature. These will be addressed by [MEP-4](/community/MEP-14-independence-from-external-sources) and [MEP-16](/community/MEP-16-metal-api-as-an-alternative-configuration-source-for-the-firewall-controller) in the future. +If you want more features, keep reading. ## Gardener -We recommend using metal-stack with our [Gardener integration](../05-Concepts/04-Kubernetes/01-gardener.md), which allows to manage Kubernetes clusters at scale. This integration is battle proof, well documented, used by many organizations in production and build on top of the open-source project [Gardener](https://gardener.cloud/). +[Gardener](https://gardener.cloud/) is an open-source managed Kubernetes service. It provides a good "batteries-included" developer experience and should be your first choice for a Kubernetes-as-a-service solution. -When compared to our Cluster API integration, this is more and provides a lot more features and stability. Clusters can more easily be created and managed. +We recommend using metal-stack with our [Gardener integration](../05-Concepts/04-Kubernetes/01-gardener.md), which allows to manage Kubernetes clusters at scale. This integration is production-hardened, well documented, used by many organizations in production and build on top of the open-source project [Gardener](https://gardener.cloud/). ## Cluster API Our [Cluster API integration](https://github.com/metal-stack/cluster-api-provider-metal-stack) is a more experimental approach to provide Kubernetes clusters with metal-stack. It is based on the [Cluster API](https://cluster-api.sigs.k8s.io/) project. -Resulting clusters are as minimal as possible and need to be configured manually after creation. With this approach there is no concept of service clusters. Each cluster is manually created and managed. +Configuring Cluster API is more verbose then Gardener and will be basically unusable for end users. Cluster API will give you building blocks to build a Kubernetes-as-a-service platform on top of it, but no more. If you need KaaS, use Gardener. From 51d2d0f3972eeecc16f48bed76fcf51f48cc0212 Mon Sep 17 00:00:00 2001 From: Benjamin Ritter <7373184+l0wl3vel@users.noreply.github.com> Date: Thu, 11 Jun 2026 11:39:55 +0200 Subject: [PATCH 2/5] Update docs/02-General/04-flavors-of-metalstack.md Co-authored-by: Simon Mayer <49491825+simcod@users.noreply.github.com> --- docs/02-General/04-flavors-of-metalstack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/02-General/04-flavors-of-metalstack.md b/docs/02-General/04-flavors-of-metalstack.md index 1e14aa0..ad27b2a 100644 --- a/docs/02-General/04-flavors-of-metalstack.md +++ b/docs/02-General/04-flavors-of-metalstack.md @@ -16,7 +16,7 @@ You can consume it as-is... -> [Plain Flavor](#plain) All flavors start with this. This is what you get if you set up metal-stack and stop there. -Using plain metal-stack without additional layer was not a focus in the past. Therefore firewall features and role management are quite basic. If There is ongoing work on [improved RBAC in MEP-4](/community/MEP-4-multi-tenancy-for-the-metal-api) and [firewall configuration via metal-api in MEP-16](/community/MEP-16-metal-api-as-an-alternative-configuration-source-for-the-firewall-controller). +Using plain metal-stack without additional layer was not a focus in the past. Therefore firewall features and role management are quite basic. There is ongoing work on [improved RBAC in MEP-4](/community/MEP-4-multi-tenancy-for-the-metal-api) and [firewall configuration via metal-api in MEP-16](/community/MEP-16-metal-api-as-an-alternative-configuration-source-for-the-firewall-controller). If you want more features, keep reading. From d49bed1a6f0a4f9d14a550c9c019483ffeb899d7 Mon Sep 17 00:00:00 2001 From: Benjamin Ritter <7373184+l0wl3vel@users.noreply.github.com> Date: Thu, 11 Jun 2026 11:40:16 +0200 Subject: [PATCH 3/5] Update docs/02-General/04-flavors-of-metalstack.md Co-authored-by: Simon Mayer <49491825+simcod@users.noreply.github.com> --- docs/02-General/04-flavors-of-metalstack.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/02-General/04-flavors-of-metalstack.md b/docs/02-General/04-flavors-of-metalstack.md index ad27b2a..0586f3c 100644 --- a/docs/02-General/04-flavors-of-metalstack.md +++ b/docs/02-General/04-flavors-of-metalstack.md @@ -8,9 +8,7 @@ sidebar_position: 4 metal-stack bare metal provisioning offers machines, networks, firewalls and floating IPs. That`s it. -You can consume it as-is... -> [Plain Flavor](#plain) - -... or use it as foundation for an orchestrator. We offer two K8s Flavors -> [Gardener](#gardener) and [Cluster API](#cluster-api) +You can consume it as-is with our [Plain Flavor](#plain) or use it as foundation for an orchestrator. We offer two K8s Flavors [Gardener](#gardener) and [Cluster API](#cluster-api). ## Plain From 0a8a1356077eb34c1f6ee9c3c4621ad90c222752 Mon Sep 17 00:00:00 2001 From: Benjamin Ritter Date: Thu, 11 Jun 2026 10:16:44 +0000 Subject: [PATCH 4/5] feat: improve Gardener and Cluster API explanations Signed-off-by: Benjamin Ritter --- docs/02-General/04-flavors-of-metalstack.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/02-General/04-flavors-of-metalstack.md b/docs/02-General/04-flavors-of-metalstack.md index 0586f3c..bf248cd 100644 --- a/docs/02-General/04-flavors-of-metalstack.md +++ b/docs/02-General/04-flavors-of-metalstack.md @@ -22,10 +22,12 @@ If you want more features, keep reading. [Gardener](https://gardener.cloud/) is an open-source managed Kubernetes service. It provides a good "batteries-included" developer experience and should be your first choice for a Kubernetes-as-a-service solution. -We recommend using metal-stack with our [Gardener integration](../05-Concepts/04-Kubernetes/01-gardener.md), which allows to manage Kubernetes clusters at scale. This integration is production-hardened, well documented, used by many organizations in production and build on top of the open-source project [Gardener](https://gardener.cloud/). +Gardener is vendor agnostic and can be used with a wide selection of infrastructure providers. One big advantage are its containerized control planes. These allow for control planes to not require three machines for each managed cluster, called `Shoot`. This makes operating many smaller clusters more economical, compared to bare-metal control planes. + +We provide support to run Gardener on metal-stack via [Gardener extensions](../05-Concepts/04-Kubernetes/01-gardener.md). This integration is production-hardened, well documented, used by many organizations in production and build on top of the open-source project [Gardener](https://gardener.cloud/). ## Cluster API -Our [Cluster API integration](https://github.com/metal-stack/cluster-api-provider-metal-stack) is a more experimental approach to provide Kubernetes clusters with metal-stack. It is based on the [Cluster API](https://cluster-api.sigs.k8s.io/) project. +Our [Cluster API integration](../05-Concepts/04-Kubernetes/02-cluster-api.md) is a more verbose approach to provide Kubernetes clusters with metal-stack. Our implementation is still in early development. It is based on the [Cluster API](https://cluster-api.sigs.k8s.io/) project. -Configuring Cluster API is more verbose then Gardener and will be basically unusable for end users. Cluster API will give you building blocks to build a Kubernetes-as-a-service platform on top of it, but no more. If you need KaaS, use Gardener. +Configuring Cluster API is very verbose and will be basically unusable for end users. It requires additional tooling to provide a good developer experience. Cluster API will give you building blocks to build a Kubernetes-as-a-service platform on top of it, but no more. We do not recommend you use Cluster API, unless you already have a large platform engineering team, that is very experienced in bare-metal K8s operations and they agree that your specific requirements cannot be modelled with Gardener. In any other case, you will have more success with Gardener. \ No newline at end of file From 0f57ef5c02b6bfef41b20715a5a998e387273ede Mon Sep 17 00:00:00 2001 From: Benjamin Ritter Date: Mon, 15 Jun 2026 08:54:13 +0000 Subject: [PATCH 5/5] fix: wording Signed-off-by: Benjamin Ritter --- docs/02-General/04-flavors-of-metalstack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/02-General/04-flavors-of-metalstack.md b/docs/02-General/04-flavors-of-metalstack.md index bf248cd..18c0671 100644 --- a/docs/02-General/04-flavors-of-metalstack.md +++ b/docs/02-General/04-flavors-of-metalstack.md @@ -30,4 +30,4 @@ We provide support to run Gardener on metal-stack via [Gardener extensions](../0 Our [Cluster API integration](../05-Concepts/04-Kubernetes/02-cluster-api.md) is a more verbose approach to provide Kubernetes clusters with metal-stack. Our implementation is still in early development. It is based on the [Cluster API](https://cluster-api.sigs.k8s.io/) project. -Configuring Cluster API is very verbose and will be basically unusable for end users. It requires additional tooling to provide a good developer experience. Cluster API will give you building blocks to build a Kubernetes-as-a-service platform on top of it, but no more. We do not recommend you use Cluster API, unless you already have a large platform engineering team, that is very experienced in bare-metal K8s operations and they agree that your specific requirements cannot be modelled with Gardener. In any other case, you will have more success with Gardener. \ No newline at end of file +Configuring Cluster API is very verbose. It requires additional tooling to provide a developer experience. Cluster API will give you building blocks to build a Kubernetes-as-a-service platform on top of it, but no more. We do not recommend you use Cluster API, unless you already have a large platform engineering team, that is very experienced in bare-metal K8s operations and they agree that your specific requirements cannot be modelled with Gardener. In any other case, you will have more success with Gardener. \ No newline at end of file