Skip to main content

Label Templates Overview

Elemental allows to specify label templates in the spec.machineInventoryLabels section of the MachineRegistration.

Their format is the canonical key:value used in Kubernetes labels.

These label templates are converted to actual labels attached to each MachineInventory resources created during the machine onboarding phase.

The resulting labels have the same key of the label template.

The associated value is generated:

info

The Elemental templating functionality covers also the [MachineRegistration] spec.machineName field, which defines the resulting hostname of the registering machine and the name of the associated MachineInventory resource.

See the Machine Name section for more details.

Label Template Variables​

Elemental Label Templating includes a set of predefined variables that could be used inside the value of the label templates specified in the MachineRegistration.

The syntax used to specify template variables is:

${ VARFAMILY / VARPATH }

where VARFAMILY defines a group (family) of supported variables and VARPATH defines the actual variable name inside the belonging family group.

Elemental currently supports three families of template variables:

  • SMBIOS: ${ System Information / VARPATH }
  • HARDWARE: ${ System Data / VARPATH }
  • RANDOM: ${ Random / VARPATH }

Template variables can be mixed with static text to form the actual labels assigned to (MachineInventories).

Rendering Examples
  • Template label tracking the number of CPU cores of the registering host (assume host has 4 cores):
    • template label: cpu: ${System Data/CPU/Total Cores}-cores
    • rendered label: cpu: 4-cores
  • Template label to track the SMBIOS UUID of the registering host:
    • template label: sbios-UUID: ${System Information/UUID}
    • rendered label: sbios-UUID: fd95324a-c26b-4e28-8727-1dcec293a0ec

Sanitization​

Once the label template value has been rendered accordingly to the included label template variables, the resulting value is sanitized before being assigned to the resulting label.

The sanitization enforce the label value to only contain letters (capitalized or not), numbers and the hyphen (-), point (.) and underscore (_) characters: all the characters not included are substituted with an underscore.

If an underscore is at the beginning or at the end of the label value, it is dropped.

Two consecutive underscores are replaced with one.

Rendering Example
  • Template label with not allowed chars sanitization:
    • template label: sanitized: this:needs--sanitizing!
    • rendered label: sanitized: this-needs-sanitizing

Usage of template labels​

Template labels allow to automatically attach labels to each host's MachineInventory every time an host register to the Elemental Operator.

info

Registration happens not only during the onboarding phase: each host re-registers every 30 minutes (and every time it reboots). During the re-registration, the template labels in the associated MachineRegistration are re-evaluated and added/updated in the MachineInventory.

There are basically three main cases where the template labels are handy:

  • as hardware data added to the Elemental catalog
  • as selectors for Cluster Provisioning
  • as template for custom Machine Names

Hardware data for the Elemental catalog​

The SMBIOS and Hardware template variables can be used to attach to each MachineInventory hardware and system data of each host.

Selectors for Cluster Provisioning​

The template labels can be used to indentify and select machines with special properties to form a new Kubernetes Cluster.

The labels generated for each MachineInventory are an handy selector for the MachineInventorySelectorTemplate resource (see the Kubernetes Cluster provisioning section for more details).

Custom Machine Names​

The hostname of the onboarding machine can be specified using the MachineRegistration spec.machineName field.

spec.machineName value undergoes the same label templates variables and sanitization process reserved to the spec.machineInventoryLabels label values.

warning

There is one notable difference during the sanitization rendering: the underscore (_) is not allowed and is dealt as the other forbidden characters (i.e., it is substituted by an hyphen: -). This is required as the underscore is not allowed in the OS hostnames.

For more information on how to define the hostname for Elemental hosts, see the HowTo/Customize hostname section.

Rendering Example
  • Define an hostname template like SLE-Micro-[random string of 6 hexadecimal values]:
    • MachineRegistration spec: machineName: SLE-Micro-${Random/Hex/6}
    • MachineInventory name: SLE-Micro-32ad41