Booting images

Introduction

After you create a bootable medium for STACKIT Edge Cloud, the next step is to boot your host system from it. This guide walks you through the required steps using common examples.

Common boot methods

You can use several methods to deliver the created medium to your target system.

• Boot from an ISO file by:
  • Mounting the ISO using out-of-band management (OOBM).
  • Using a bootable USB device created from the ISO file.
• Boot from a raw image by:
  • Using a pre-formatted medium, such as a MicroSD card.
  • Creating a virtual machine (VM) from the raw image.

The method you choose depends on your preferences and the boot options supported by your target platform.

Machine stages

Talos Linux uses multiple machine stages. The maintenance stage is the initial, temporary state of a Talos node. In this stage, the node has only the minimal configuration required for you to access its API (for example, with talosctl) and waits for you to apply its final configuration. At this stage, the host is not yet part of any Kubernetes cluster.

To learn more about the boot sequence, refer to the official Talos Linux documentation.

If you boot from a Talos ISO on a machine that already has a Talos installation on its disk, the machine will boot from the existing disk installation by default. This behavior prevents unintended system resets when you reboot the system with the ISO still mounted.

Regardless of this feature it’s still considered best practice to set the boot order in your BIOS or UEFI settings to prioritize disk over ISO.

After you complete the steps in the first boot section, your STEC host should be in the maintenance stage. If it is not, review the common issues that often result in boot failures.

First boot

When you first boot your target device from the STEC image, you will see two bootloader entries. The default entry boots automatically after a few seconds and starts Talos Linux in maintenance stage.

Regular machines and VMs

1. Start your target device from the STEC image. The bootloader menu appears, showing the available boot options.

   

2. The (optional) initial boot parameters can be modified by pressing the ‘e’ key on the selected bootloader entry. This may be useful for troubleshooting selected boot options.

   

3. Allow the boot sequence to complete, which should only take a few seconds.

   

4. Verify that the Talos dashboard loads.

   Confirm two things: the stage is maintenance and the connectivity is ok.
   Note the system UUID shown in the top-left corner of the dashboard. You will use this UUID in the next step to identify the host.
   Dashboard
   The dashboard runs on the second virtual TTY. The first virtual TTY shows kernel logs. You can switch between TTYs using the <Alt+F1> and <Alt+F2> keys. You can also use the <F1> through <Fn> keys to switch between different screens of the dashboard.

   

Single board computers

The boot process for single board computers (SBCs) is very similar to that of regular machines and VMs and—given you have chosen the correct overlay image and followed the guidance for single board computers—should look similar to the process outlined in this Raspberry Pi 4b example.

1. Insert your boot medium, e.g. MicroSD card, into your Raspberry PI and boot it.

   

2. You should be presented with the u-boot bootloader. If you see this you know that the overlay has successfully been integrated into your boot image.

   

3. The rest of the boot should be similar to the normal boot experience and you should see the standard GRUB bootloader screen that ships with Talos.

   

4. On single-board computer (SBC) images (Talos Linux 1.9.x and newer), the interactive dashboard is disabled by default. You can enable it, if required, by adding the kernel parameter talos.dashboard.disabled=0.

   The dashboard runs on the second virtual TTY. The first virtual TTY shows kernel logs. You can switch between TTYs using the <Alt+F1> and <Alt+F2> keys. You can also use the <F1> through <Fn> keys to switch between different screens of the dashboard.

   

5. In the STEC GUI you now should see that the new EdgeHost has successfully registered with the STEC instance.

   Prerequisite: You have authenticated access to a STEC instance.

   

Host registration

Once your target system has booted into maintenance stage, it automatically idles and tries to register itself with the STEC management plane.

For registration to succeed, your host’s initial boot parameters must be configured to allow an HTTPS connection (TCP port 443) to *.stackit.cloud.

You can verify the successful registration in the STEC web UI or CLI by matching an identifier, such as the UUID (which you noted from the dashboard) or the MAC address of your target system.

UI

Prerequisites

Before you begin, you need the following:

• Authenticated access to a STEC instance.

Steps

1. Navigate to the hosts section of the GUI. You should see a new host matching the UUID seen in the Talos dashboard. The status should display “ready”.

   

2. By clicking on the host name you can verify additional configuration data of the host.

   

CLI

Prerequisites

Before you begin, you need the following:

• Authenticated access to a STEC instance.
• The kubeconfig for the STEC instance exported in your terminal session.
• Tools: A generic Linux bash terminal with kubectl and yq.

Steps

1. Simply use kubectl to get the EdgeHost CR matching the UUID of the target system. You’ll see the current configuration of the host as well as various status fields.

   > kubectl get EdgeHost/a8cab433-760d-412a-9ce7-9c72e771718c -o yaml | yq
   
   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: v1.10.5-stackit.v0.21.0
   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: 1306525696
   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: 9deb[...]cc99

2. The status of the ready field should be true. If there are problems with the EdgeHost you should see this by checking the relevant status.conditions.

   > kubectl get EdgeHost/a8cab433-760d-412a-9ce7-9c72e771718c -o yaml | yq '.status.ready'
   
   true
   
   > kubectl get EdgeHost/a8cab433-760d-412a-9ce7-9c72e771718c -o yaml | yq '.status.conditions'
   
   - lastTransitionTime: "2025-08-05T09:59:57Z"
   message: maintenance
   reason: TalosOsLifecycle
   status: "True"
   type: Stage
   - lastTransitionTime: "2025-08-05T09:59:57Z"
   message: ""
   reason: ServiceLifecycle
   status: Unknown
   type: Service.Kubelet
   - lastTransitionTime: "2025-08-05T09:59:57Z"
   message: ""
   reason: ServiceLifecycle
   status: Unknown
   type: Service.Etcd
   - lastTransitionTime: "2025-08-05T10:02:22Z"
   message: System checked in successfully
   reason: ConnectionTest
   status: "True"
   type: Heartbeat