Set up node identifier modes

This feature is available in versions v1.12.10-stackit.v1.8.0 and v1.13.7-stackit.v1.8.0 or higher. You can read about our Talos versioning approach under “Getting started”.

Introduction

When deploying your own hardware in remote locations with the STACKIT Edge Cloud management plane, each host machine must be uniquely identified. The edgehostlet agent running on your hardware uses a unique node identifier to register the node as an EdgeHost in your STEC instance. This identifier is then used to match the machine with an EdgeMachine or EdgeCluster resource in the STACKIT management plane.

In certain use cases, you need to override this default behavior. The edgehostlet agent supports three customization strategies via the edge.identifier-mode configuration flag. This guide explains the available modes, their best use cases, and how they behave during the machine life cycle.

Configuration modes

The STEC agent supports three distinct strategies to determine the host’s unique identifier.

machined mode (default)

If you do not specify an edge.identifier-mode, machined is the default mode. In this case, the agent queries the host machine’s hardware/OS UUID directly from the underlying Talos Linux subsystem.

• How it works: The agent retrieves the stable UUID directly from the system’s hardware.
• Behavior: The returned UUID is deterministic, stable, matches the host’s actual bare-metal or VM UUID, and is consistently formatted in lowercase.
• Best use case: Standard bare-metal deployments where the physical machine’s identity must remain consistent across operating system reinstall.

This mode is not recommended if your virtualized environment clones VMs, as the hardware UUIDs may not be unique across instances.

random mode

In random mode, the agent generates a cryptographically random UUID locally and manages its life cycle through persistent state storage.

• How it works: During the initial boot phase, the agent generates a random UUID. This UUID is saved once the node successfully joins an EdgeCluster. On subsequent boots, the agent reads and reuses this stored UUID.
• Behavior: Provides a randomized identifier that survives agent reboots as long as the host remains part of an EdgeCluster. When the node is deleted from an EdgeCluster and transitions to maintenance mode, the old EdgeHost is deleted. The edgehostlet agent then generates a new random UUID, registering the machine as a new EdgeHost in your STEC instance.
• Best use case: Environments where hardware UUIDs are non-unique, duplicated (e.g., cloned virtual machine templates), or restricted.

Data persistence warning: If the machine restarts during the maintenance phase, the random UUID will be recreated. This occurs because persistent storage is not available before a cluster is joined, resulting in a duplicate registration of the host within the STEC management plane. The old, orphaned EdgeHost record will remain in the plane and must be cleaned up manually.

fixed mode

In fixed mode, the identifier is explicitly hardcoded via configuration.

• How it works: You must supply the static UUID using the parameter edge.uuid. If this parameter is missing or does not contain a valid UUID value, the edgehostlet agent will fail to start. This mode requires a unique boot image or unique kernel arguments for each machine.
• Behavior: The node strictly uses the static value supplied by the parameter across its entire life cycle.
• Best use case: Managed provisioning environments where node identities are pre-allocated or managed by an external orchestrator.

Behavior comparison

The following table summarizes the behavior and recommended environments for each identifier mode:

Mode	Identifier Source	Persistence Strategy	Recommended Use Case
machined (default)	Hardware/OS BIOS UUID	Inherently persistent (hardware-based)	Standard bare-metal and persistent VMs
random	Cryptographically generated UUID	Node storage	Cloned VMs, duplicate UUID environments
fixed	Manually provided static UUID	Configuration-driven	Pre-allocated, orchestrated environments

How to set up

Choose your required mode when creating a new EdgeImage. Use the extraKernelArgs field to configure the edge.identifier-mode flag:

apiVersion: edge.stackit.cloud/v1alpha1
kind: EdgeImage
metadata:
  name: image-node-identifier-random
  namespace: default
spec:
  schematic: |
    customization:
      extraKernelArgs:
      - edge.identifier-mode=random
      systemExtensions:
        officialExtensions: []
    overlay: {}
  talosVersion: v1.13.7-stackit.v1.8.0

If you choose to use the fixed option, you must create a separate, unique EdgeImage for each individual Talos node to define its distinct static UUID:

apiVersion: edge.stackit.cloud/v1alpha1
kind: EdgeImage
metadata:
  name: es-001-cp-1
  namespace: default
spec:
  schematic: |
    customization:
      extraKernelArgs:
      - edge.identifier-mode=fixed
      - edge.uuid=4a867796-a1a3-4ee1-bfd7-e52cbca8daa7
      systemExtensions:
        officialExtensions: []
    overlay: {}
  talosVersion: v1.13.7-stackit.v1.8.0
---
apiVersion: edge.stackit.cloud/v1alpha1
kind: EdgeImage
metadata:
  name: es-001-cp-2
  namespace: default
spec:
  schematic: |
    customization:
      extraKernelArgs:
      - edge.identifier-mode=fixed
      - edge.uuid=11901060-a14f-42a1-9f88-511f010deef1
      systemExtensions:
        officialExtensions: []
    overlay: {}
  talosVersion: v1.13.7-stackit.v1.8.0
---
apiVersion: edge.stackit.cloud/v1alpha1
kind: EdgeImage
metadata:
  name: es-001-cp-3
  namespace: default
spec:
  schematic: |
    customization:
      extraKernelArgs:
      - edge.identifier-mode=fixed
      - edge.uuid=9ec89f38-c489-452d-b312-94bc2ffc308c
      systemExtensions:
        officialExtensions: []
    overlay: {}
  talosVersion: v1.13.7-stackit.v1.8.0