Skip to content

Commit 92c3782

Browse files
committed
improve initial cluster deployment guide
1 parent bdb6362 commit 92c3782

1 file changed

Lines changed: 41 additions & 5 deletions

File tree

docs/04-For Operators/03-Deployment/02_initial-cluster.md

Lines changed: 41 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,24 +6,60 @@ sidebar_position: 2
66

77
# Initial Cluster
88

9-
Before creating the `Garden cluster`, a base Kubernetes cluster needs to be in place. This initial cluster serves as the bootstrap infrastructure, where both the metal-stack control plane and Gardener are deployed.
9+
Before creating the `Garden cluster`, a base Kubernetes cluster needs to be in place. This initial cluster serves as the bootstrap infrastructure for the **metal-stack control plane**.
10+
11+
## Deployment Options
12+
13+
There are three supported approaches for hosting the initial cluster:
14+
15+
### Option 1: Shared Initial Cluster
16+
17+
It is possible to use a **single initial cluster** for both metal-stack and Gardener. This approach is technically feasible but **not recommended** for production environments. Sharing a single cluster mixes platform infrastructure with lifecycle management, which can complicate operational boundaries and failure isolation.
18+
19+
### Option 2: Dedicated Clusters
20+
21+
We recommend using **dedicated (initial) clusters** for metal-stack and Gardener — one cluster for the metal-stack control plane and a separate cluster for Gardener. This approach provides:
22+
23+
- **Clearer operational boundaries** — Separation of platform administrators and Gardener operators aligns with the role model described in the [Kubernetes Cluster Lifecycle Management](/Kubernetes%20Cluster%20Lifecycle%20Management) documentation
24+
- **Better isolation** — Physical separation of control planes follows best practices for critical infrastructure, where operator-managed control plane components are inaccessible to end-users
25+
- **Simplified failure boundaries** — Outages of the Gardener cluster only affect cluster provisioning, not the metal-stack infrastructure or existing workloads
26+
27+
### Option 3: Autonomous Control Plane (Best for Digital Sovereignty and Critical Infrastructure)
28+
29+
For self-hosted deployments, metal-stack can be set up with an [Autonomous Control Plane](/community/MEP-18-autonomous-control-plane) cluster. This approach is the best choice for organizations that require full digital sovereignty and autonomy over their entire infrastructure stack. The only requirement from metal-stack is that your partitions can establish network connections to the metal control plane.
1030

1131
## Suggestions for the Initial Cluster
1232

13-
The initial cluster can be hosted anywhere — a hyperscaler, metalstack.cloud, or a self-hosted solution. Some common options:
33+
### For Options 1 & 2: Cloud-Hosted Clusters
34+
35+
For the shared and dedicated cluster approaches, the initial cluster can be hosted anywhere — a hyperscaler, metalstack.cloud, or any other managed Kubernetes provider. Some common options:
1436

1537
- **metalstack.cloud** — A Kubernetes cluster can be created via [UI](https://metalstack.cloud/de/documentation/UserManual#creating-a-cluster), CLI, or Terraform.
1638
- **GCP/GKE** — A GCP account is required. The Ansible [gcp-auth role](https://github.com/metal-stack/ansible-common/tree/master/roles/gcp-auth) can be used for authentication, and the [gcp-create role](https://github.com/metal-stack/ansible-common/tree/master/roles/gcp-create) for creating a GKE cluster.
1739
- Suggested defaults: `gcp_machine_type`: e2-standard-8, `gcp_autoscaling_min_nodes`: 1, `gcp_autoscaling_max_nodes`: 3
1840

1941
:::tip
20-
For metal-stack it does not matter where your control plane Kubernetes cluster is located. You can of course use a cluster managed by a hyperscaler. This has the advantage of not having to setup Kubernetes by yourself and could even become beneficial in terms of fail-safe operation. However, we also describe a solution of how to setup metal-stack with a self-hosted, [Autonomous Control Plane](/community/MEP-18-autonomous-control-plane) cluster. The only requirement from metal-stack is that your partitions can establish network connections to the metal control plane. If you are interested, you can find a reasoning behind this deployment decision [here](../../05-Concepts/01-architecture.mdx#target-deployment-platforms).
42+
For metal-stack it does not matter where your control plane Kubernetes cluster is located. You can of course use a cluster managed by a hyperscaler. This has the advantage of not having to setup Kubernetes by yourself and could even become beneficial in terms of fail-safe operation. If you are interested, you can find a reasoning behind this deployment decision [here](../../05-Concepts/01-architecture.mdx#target-deployment-platforms).
2143
:::
2244

45+
### For Option 3: Autonomous Control Plane with k3s
46+
47+
For the autonomous control plane approach, [MEP-18](/community/MEP-18-autonomous-control-plane) proposes using [k3s](https://k3s.io/) as the initial cluster. This is because Gardener is not yet able to create an initial cluster itself (though this may change with the implementation of [GEP-28](https://github.com/gardener/gardener/blob/master/docs/proposals/28-autonomous-shoot-clusters.md)).
48+
49+
The k3s cluster serves as a minimal control plane whose sole purpose is to host the production control plane cluster (the "Matryoshka principle"). This brings several advantages:
50+
51+
- **Failure isolation** — In the event of an interruption or loss of the initial k3s cluster, the production control plane remains unaffected, and end users can continue to manage their clusters as normal.
52+
- **Separate operational responsibility** — A dedicated operations team can take care of the Day-2 maintenance of the k3s installation, which uses different tools than the rest of the setup.
53+
- **Minimal resource requirements** — Since the number of shoot clusters to host is static, resource requirements are minimal and stable over time.
54+
55+
The k3s nodes can be either bare metal machines or virtual machines. For a minimal setup, a single node with 8–16 cores, 64GB RAM, and two NVMe drives of 1TB is a good starting point. For high availability, a clustered k3s configuration across multiple nodes is recommended, with ETCD replication and backup-restore mechanisms configured for metal-stack and Gardener components.
56+
57+
See the [Autonomous Control Plane](/community/MEP-18-autonomous-control-plane) proposal for detailed architecture, failure scenarios, and implementation guidance.
58+
2359
## Next Steps
2460

2561
Once the initial cluster is in place, the deployment continues with:
2662

27-
1. **[Metal Control Plane Deploymen](./03_control-plane.mdx)** — Deploy the metal-stack control plane into the initial cluster.
63+
1. **[Metal Control Plane Deployment](./03_control-plane.mdx)** — Deploy the metal-stack control plane into the initial cluster.
2864
2. **[Partition Deployment](./04_partition.md)** — Set up a partition
29-
3. **[Gardener Setup](./05_gardener.md)** — Configure Gardener to use metal-stack as a provider.
65+
3. **[Gardener Setup](./05_gardener.md)** — Configure Gardener on its own dedicated cluster to use metal-stack as a provider.

0 commit comments

Comments
 (0)