Creating clusters

Introduction

After you booted and registered your first host(s) for STACKIT Edge Cloud (STEC) the next step is to create a cluster. This guide leads you through those steps by example.

Creating a cluster

Creating a cluster will result in two things:

• Every host that you select to be part of the cluster will get a machine configuration applied. This effectively results in the host exiting it’s maintenance stage and entering the booting stage while the new configuration is being applied.
• Kubernetes will be configured as defined by the machine configuration applied. If this is successful the host should switch into the running stage.

Cluster creation can be done using the STACKIT Edge Cloud UI or API and you will need to have at least one host registered with your STEC instance before you can create a cluster.

The minimal number of hosts to create a cluster is one. This will result in a single-node cluster. While this may be a perfectly valid use case depending on your needs please be aware that this kind of cluster will not provide any level of redundancy and will require downtimes of your workload when performing upgrades. Please consider the Kubernetes cluster architecture and the Talos upgrade process when planning your cluster setup and choose the number of nodes based on your requirements.

UI

Prerequisites:

• Successfully authenticated in the UI of a STEC instance.

Steps:

1. Navigate to the Cluster section. You’ll get to the Clusters overview. Click on the top right button ‘Create Cluster’ to get to the respective dialog.

   

2. Enter a cluster name, compliant with RFC 1034. This means: it has to start and end with a letter and may contain only letters, numbers, and hyphens. Then select the desired Talos and Kubernetes versions.

   The Talos version you choose during cluster creation may differ from the Talos version you used when creating the image you booted your host(s) from. If it differs, Talos will automatically perform a downgrade / upgrade of the Talos version when creating the cluster to make sure all nodes of the cluster are running using the same Talos release. A check will make sure the selected Kubernetes version is supported by the chosen Talos version.

3. Select at least one host to become a Kubernetes node and specify it’s intended role. At least one control plane is required to setup a cluster. From the dropdown select the disk to install Talos on. The resulting cluster configuration should look similar to the one shown next.

   

4. (Optional) you may provide config patches for the machine configuration on the cluster level and/or at the machine level. The resulting machine configuration will be merged with the configuration applied on the machine level having precedence over the configuration defined at the cluster level.

   Talos is completely managed through a so called machine config. STEC generates this machine config on the fly based on the information you provide in this dialog. If you need to further customize the generated machine config please refer to the advanced section.

5. Click on the Create Cluster button to initiate the cluster creation process. You’ll immediately see that the chosen host(s) enter the booting stage and, if the configuration is successful, finally enter the ready stage.

   

   

   

   

6. After a few minutes the cluster should report ‘ready’. The cluster creation process is complete.

   

CLI

Prerequisites:

• Successfully authenticated with a STEC instance.
• Kubeconfig for the STEC instance is exported in your terminal session.
• Tools: a generic Linux bash terminal, kubectl, yq.

Steps:

1. First we have to identify the hosts that will be part of the cluster.

   > export KUBECONFIG=~/.kubeconfig/your-stec.kubeconfig.yaml
   > kubectl get EdgeHost
   
   NAME AGE
   a8cab433-760d-412a-9ce7-9c72e771718c 4m53s
   
   > kubectl get EdgeHost/a8cab433-760d-412a-9ce7-9c72e771718c -o yaml
   
   apiVersion: edge.stackit.cloud/v1alpha1
   kind: EdgeHost
   metadata:
   name: a8cab433-760d-412a-9ce7-9c72e771718c
   namespace: default
   spec:
   proxyConfig: {}
   status:
   hostInfo:
   architecture: arm64
   kernelParams:
   - talos.platform=metal
   - selinux=1
   - edge.joinendpoint=https://join.xxx-xxx-xxx.edge.eu01.stackit.cloud/join
   - edge.jointoken=xxx.xxx.xxx
   version: vx.y.z-stackit.vX.Y.Z
   network:
   - connected: true
   ipAddrs:
   - 192.168.4.154/24
   isDefault: true
   macAddr: 6f:4a:77:a4:54:55
   networkInterfaceName: enp0s1
   ready: true
   storage:
   - deviceName: /dev/vda
   size: 34359738368
   systemDisk: true
   type: HDD
   conditions:
   - message: maintenance
   reason: TalosOsLifecycle
   status: "True"
   type: Stage
       [...]
   - message: System checked in successfully
   reason: ConnectionTest
   status: "True"
   type: Heartbeat
   talosHostStatus:
   schematicId: 106b[...]e04d
   
   > EDGE_HOST_NAME=$(kubectl get EdgeHost/a8cab433-760d-412a-9ce7-9c72e771718c -o yaml | yq.metadata.name)

2. Now it’s time to create the cluster manifest.

   Create a new YAML file in a text editor of your choice. In this example we’ll use the same configuration as in the UI example. Please replace <<EdgeHostName>> with the actual name as saved to the $EDGE_HOST_NAME variable in the previous step, make sure to replace alle the versions with versions currently supported by STEC and apply all other changes to the example file as needed.

   Talos is completely managed through a so called machine config. You may use the optional configPatches and clusterConfigPatches to further customize your deployment, see config patches. STEC generates this machine config on the fly based on the information you provide in this dialog. If you need to further customize the generated machine config please refer to the advanced section.

   The Talos version you choose during cluster creation may differ from the Talos version you used when creating the image you booted your host(s) from. If it differs, Talos will automatically perform a downgrade / upgrade of the Talos version when creating the cluster to make sure all nodes of the cluster are running using the same Talos release. A check will make sure the selected Kubernetes version is supported by the chosen Talos version.

   As of today there is no way to programmatically get a list of supported image versions, overlays or extensions. Please visit our FAQs for more information about this limitation.

   apiVersion: edge.stackit.cloud/v1alpha1
   kind: EdgeCluster
   metadata:
   name: clst
   spec:
   maintenance: {}
   nodes:
   - edgeHost: <<EdgeHostName>>
   role: controlplane
   talos:
   kubernetes:
   version: v1.30.2
   installDisk: /dev/vda
   maintenance: {}
   proxyConfig: {}
   proxy:
   kubernetes: false
   talos: false
   talos:
   kubernetes:
   version: v1.30.2
   version: v1.10.5-stackit.v0.21.0

3. Save the file to a location of your choice. We’ll use ~/stec-cluster.yaml in this example.

4. Apply the manifest to the Kubernetes cluster. This will create the cluster. You’ll immediately see that the chosen host(s) enter the booting stage and, if the configuration is successful, finally enter the ready stage.

   > kubectl apply -f ~/stec-cluster.yaml
   edgecluster.edge.stackit.cloud/clst created
   
   > kubectl get edgecluster/clst -o yaml
   
   apiVersion: edge.stackit.cloud/v1alpha1
   kind: EdgeCluster
   metadata:
   name: clst
   namespace: default
   spec:
   maintenance: {}
   nodes:
   - edgeHost: a8cab433-760d-412a-9ce7-9c72e771718c
   installDisk: /dev/vda
   maintenance: {}
   proxyConfig: {}
   role: controlplane
   talos:
   kubernetes:
   version: v1.30.2
   proxy: {}
   talos:
   kubernetes:
   version: v1.30.2
   version: v1.10.5-stackit.v0.21.0
   status:
   conditions:
   - lastTransitionTime: "2025-08-08T15:47:05Z"
   message: Cluster ready
   reason: Ready
   status: "True"
   type: ClusterReady
   controlPlaneEndpoint:
   host: 192.168.4.154
   port: 6443
   ready: true

5. After a few minutes the cluster should report ‘ready’. The cluster creation process is complete.

References

• Talos machine configuration