Skip to content
Products
Platform
Developer Tools
Portal

Creating clusters

Introduction

Section titled “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

Section titled “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.

Prerequisites:

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.

    Screenshot of the STACKIT Edge Cloud web interface, showing the Clusters view. The main content area is titled "Clusters" and displays a table of clusters, which is currently empty ("Showing 1-0 of 0"). Above the empty table are a Search for items bar and a prominent + Create Cluster button. The left-hand navigation menu highlights Runtime > Clusters (with a badge of 0). Other menu items visible are Dashboard, Images (4), Hosts (2), Imprint, Report content, Terms & Conditions, Cookie note, and Data Protection.

  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 controlplane 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.

    Screenshot of the STACKIT Edge Cloud web interface showing the Create Cluster form. The form is pre-filled with: Cluster Name: clst, Talos Version: v1.0.5-stackit.v0.21.0, and Kubernetes Version: v1.30.2. Below the main fields is a section for host selection. Two hosts are listed, identified by UUIDs. The first host is selected to have the Control Plane role and is configured to Install Disk on /dev/vda - HDD. The second host is unselected and has no role or disk configuration. The configuration summary at the bottom shows Control Planes: 1 and Workers: 0.

  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.

    Console screenshot of a Kubernetes node (Talos OS) named node01 showing the system in a Maintenance state. The header shows: UID (a GUID), TYPE (unknown), KUBERNETES (n/a), and STATUS (SINK) is Maintenance. Log messages indicate the node is being brought into and out of maintenance mode, performing operations like talosctl apply-config and downloading/running components. This suggests the node is undergoing a configuration update or part of the cluster creation/join process.

    Console screenshot of a Kubernetes node (Talos OS) named node01 showing errors during image pulling. The header status is Booting, and RUNELET is reported as unhealthy. The log shows several repetitive ERROR messages indicating: "failed to pull image 'gcr.io/etcd-development/etcd/etcd.5.21': failed to resolve reference 'gcr.io/etcd-development/etcd/etcd.5.21': context canceled". This suggests a network connectivity issue or a misconfigured container registry, preventing the node from pulling the required etcd image for the control plane.

    Console screenshot of a Kubernetes node named node01 (using Talos OS), showing initialization and boot logs. The status header shows: UID (a GUID), TYPE (controlplane), KUBERNETES (v1.30.2), and STATUS (SINK, RUNELET, API-SERVER, CONTROLLER-MANAGER, SCHEDULER) are all reported as Healthy or Running. The IP address is 192.168.4.154. The log messages show a series of system startup events, including health checks, rendering of static Pods (like kds-controller-manager), and several WARNING and ERROR messages. The errors specifically mention an issue with the talos-ext-edgehostlet-bootstrap failing with exit code 12 due to an inability to get system CA trust store, which suggests a security or certificate configuration problem during bootstrapping.

    Console screenshot of a Kubernetes node (Talos OS) named node01 in a Running state, with most components (controlplane, kubelet, API-Server, Scheduler) reported as Healthy. The logs contain messages related to Kubernetes RBAC (Role-Based Access Control) setup, creating ClusterRole and ClusterRoleBinding objects. Critically, there are several repeating ERROR messages from the KdsNodeApplyController component stating: "1 error(s) occurred \nerror getting node: nodes "talos-455-82c" not found." This indicates that while the services are running, a controller is failing to locate its own node object within the cluster, suggesting a potential API-server registration or network connectivity issue for that specific node resource.

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

    Screenshot of the STACKIT Edge Cloud web interface, now showing the Clusters view with a single cluster created. The cluster table displays one entry: Name: clst, Kubernetes Version: v1.30.2, Nodes: 1 Control Plane, 0 Worker, and Status: a green dot indicating Ready. The table summary confirms, "Showing 1-1 of 1". The left-hand navigation menu now shows a badge of 1 next to Runtime > Clusters.

References

Section titled “References”