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 Templates' 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 the following template variable families:

  • BIOS: ${ BIOS / VARPATH }
  • BaseBoard: ${ BaseBoard / VARPATH }
  • CPU: ${ CPU / VARPATH }
  • Chassis: ${ Chassis / VARPATH }
  • GPU: ${ GPU / VARPATH }
  • Memory: ${ Memory / VARPATH }
  • Network: ${ Network / VARPATH }
  • Product: ${ Product / VARPATH }
  • Runtime: ${ Runtime / VARPATH }
  • Storage: ${ Storage / VARPATH }
warning

All the template variable families (but Random) are enabled only if MachineRegistration elemental:registration:no-smbios field is set to false (default).

When elemental:registration:no-smbios field is set to true, the registering machines do not send any data required for rendering the template variables, so no variables will be available, but the Random variables, which are the only notable exception.

Random variables are always available since they are built-in on the operator side.

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

Rendering Examples
  • Label Template tracking the number of CPU cores of the registering host (assume host has 4 cores):
    • original label: cpu: ${CPU/TotalCores}-cores
    • rendered label: cpu: 4-cores
  • Label Template tracking the SMBIOS UUID of the registering host:
    • original label: sbios-UUID: ${Product/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 hyphen.

Any character at the beginning and at the end of the label value must be a letter or a number. If it is not, it is dropped.

Two consecutive hyphens are replaced with one.

Rendering Example
  • Label Template with sanitization of prohibited chars:
    • original label: sanitized: this:needs--sanitizing!
    • rendered label: sanitized: this-needs-sanitizing

Usage of Label Templates​

Label Templates 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 Label Templatess in the associated MachineRegistration are re-evaluated and added/updated in the MachineInventory.

There are basically three main cases where the label templates can be used:

  • 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 Label Templates' variables can be used to attach hardware data to each MachineInventory resource.

Selectors for Cluster Provisioning​

The Label Templates 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 rendering.

warning

There is one notable difference during the sanitization process: 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 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

Label Templates in action​

registration example with Label Templates' variables
apiVersion: elemental.cattle.io/v1beta1
kind: MachineRegistration
metadata:
  name: my-nodes
  namespace: fleet-default
spec:
  machineName: "${Runtime/Hostname}"
  config:
    cloud-config:
      users:
        - name: root
          passwd: root
    elemental:
      install:
        reboot: true
        device: /dev/sda
        debug: true
  machineInventoryLabels:
    elemental.cattle.io/CpuTotalCores: "${CPU/TotalCores}"
    elemental.cattle.io/CpuTotalThreads: "${CPU/TotalThreads}"
    elemental.cattle.io/TotalMemoryBytes: "${Memory/TotalPhysicalBytes}"
    elemental.cattle.io/NumDisks: "${Storage/TotalDisks}"