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:
- rendering the
label template variables
(if present) sanitizing
the resulting value
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 }
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).
- 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.
- 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.
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.
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.
- 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​
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}"