MachineRegistration reference
The MachineRegistration resource allows:
- to configure the registration process
- to provide OS installation parameters
- to define the Elemental services enabled for the registering machine Once created it generates the registration URL used by nodes to register and start the machine onboarding process.
The MachineRegistration has a Ready condition which turns to true when the Elemental Operator has successfully generated the registration URL and an associated ServiceAccount. From this point on the target host can connect to the registration URL to kick off the provisioning process.
An HTTP GET request against the registration URL returns the registration file: a .yaml file containing the registration data (i.e., the spec:config:elemental:registration section from the just created MachineRegistration). The registration file contains all the required data to allow the target host to perform self registration and start the Elemental provisioning.
There are several keys that can be configured under a MachineRegistration resource spec.
apiVersion: elemental.cattle.io/v1beta1
kind: MachineRegistration
metadata:
name: my-nodes
namespace: fleet-default
spec:
machineName: name
machineInventoryLabels:
label: value
machineInventoryAnnotations:
annotation: value
config:
cloud-config:
...
elemental:
registration:
...
install:
...
config.cloud-config
Contains the cloud-configuration to be injected in the node.
Both yip and cloud-init syntax are supported. See the Cloud Config Reference for full information.
config.network
Contains the Declarative Networking configuration, supporting integration with CAPI IPAM Providers.
See the Declarative Networking Reference for full information.
| Key | Type | Default value | Description |
|---|---|---|---|
| configurator | string | nmc | The network configurator type to use (nmc, nmstate, or nmconnections) |
| ipAddresses | objRefMap | empty | A map of IPPool references. Map keys can be used for IPAddress substitution in the network config template. |
| config | obj | empty | The network config template. Syntax varies depending on the configurator in use. |
config.elemental.registration
Contains the configuration used for the connection and the initial registration to the Elemental Operator.
Supports the following values:
| Key | Type | Default value | Description |
|---|---|---|---|
| url | string | empty | URL to connect to the Elemental Operator |
| ca-cert | string | empty | CA to validate the certificate provided by the server at 'url' (required if the certificate is not signed by a public CA) |
| no-smbios | bool | false | Whether SMBIOS data should be sent to the Elemental Operator (see the SMBIOS reference for more information) |
| no-toolkit | bool | false | Disables the Elemental Toolkit support and allows registration of an unmanaged OS |
The following values are for development purposes only.
| Key | Type | Default value | Description |
|---|---|---|---|
| auth | string | tpm | Authentication method to use during registration, one of tpm, mac or sys-uuid. See Authentication for more information |
| emulate-tpm | bool | false | This will use software emulation of the TPM (required for hosts without TPM hardware) |
| emulated-tpm-seed | int64 | 1 | Fixed seed to use with 'emulate-tpm'. Set to -1 to get a random seed. See TPM for more information |
config.elemental.install
Contains the installation configuration that would be applied via elemental-register --install when booted from an ISO and passed to elemental install
Supports the following values:
| Key | Type | Default value | Description |
|---|---|---|---|
| firmware | string | efi | Firmware to install ('efi' or 'bios') |
| device | string | empty | Device to install the system to |
| device-selector | string | empty | Rules for picking device to install the system to |
| no-format | bool | false | Don’t format disks. It is implied that COS_STATE, COS_RECOVERY, COS_PERSISTENT, COS_OEM partitions are already existing on the target disk |
| config-urls | list | empty | Cloud-init config files locations |
| iso | string | empty | Performs an installation from the ISO url instead of the running ISO |
| system-uri | string | empty | Sets the system image source and its type (e.g. 'docker:registry.org/image:tag') instead of using the running ISO |
| debug | bool | false | Enable debug output |
| tty | string | empty | Add named tty to grub |
| poweroff | bool | false | Shutdown the system after install |
| reboot | bool | false | Reboot the system after install |
| snapshotter | obj | empty | Snapshotter configuration. See reference |
| eject-cd | bool | false | Try to eject the cd on reboot |
In case of using both iso and system-uri the iso value takes precedence
It is only required to specify either the device or device-selector fields for a successful install, the rest of the parameters are all optional.
If both device and device-selector is specified the value of device is used and device-selector is ignored.
Example
apiVersion: elemental.cattle.io/v1beta1
kind: MachineRegistration
metadata:
name: my-nodes
namespace: fleet-default
spec:
config:
elemental:
install:
device: /dev/sda
debug: true
reboot: true
eject-cd: true
system-uri: registry.suse.com/rancher/sle-micro/5.5:latest
config.elemental.install.device-selector
The device-selector field can be used to dynamically pick device during installation. The field contains a list of rules that looks like the following:
Example device-selector based on device name
device-selector:
- key: Name
operator: In
values:
- /dev/sda
- /dev/vda
- /dev/nvme0
Example device-selector based on device size
device-selector:
- key: Size
operator: Lt
values:
- 100Gi
- key: Size
operator: Gt
values:
- 30Gi
The currently supported operators are:
| Operator | Description |
|---|---|
| In | The key matches one of the provided values |
| NotIn | The key does not match any of the provided values |
| Gt | The key is greater than a single provided value |
| Lt | The key is lesser than a single provided value |
The currently supported keys are:
| Key | Description |
|---|---|
| Name | The device name (eg. /dev/sda) |
| Size | The device size (values can be specified using kubernetes resources, eg 100Gi) |
The rules are AND:ed together, which means all rules must match the targeted device.
config.elemental.install.snapshotter
You can configure how Elemental manages snapshots on the installed machine.
New snapshots are created for example when upgrading the machine with a new OS image.
The loopdevice snapshotter will unpack new images on a ext4 filesystem, while the btrfs snapshotter will make use of the underlying btrfs snapshots functionality, greatly reducing the amount of disk space needed to store multiple snapshots.
| Key | Type | Default value | Description |
|---|---|---|---|
| type | string | loopdevice | Type of device used to manage snapshots in OS images ('loopdevice' or 'btrfs'). |
| maxSnaps | int | 2 | Maximum amount of snapshots to keep. |
config.elemental.reset
Contains the reset configuration that would be applied via elemental-register --reset, when booted from the recovery partition and passed to elemental reset
Supports the following values:
| Key | Type | Default value | Description |
|---|---|---|---|
| enabled | bool | false | MachineInventories created from this MachineRegistration will have reset functionality enabled |
| reset-persistent | bool | true | Format the COS_PERSISTENT partition |
| reset-oem | bool | true | Format the COS_OEM partition |
| config-urls | list | empty | Cloud-init config files |
| system-uri | string | empty | Sets the system image source and its type (e.g. 'docker:registry.org/image:tag') instead of using the running ISO |
| debug | bool | false | Enable debug output |
| poweroff | bool | false | Shutdown the system after reset |
| reboot | bool | true | Reboot the system after reset |
Example
apiVersion: elemental.cattle.io/v1beta1
kind: MachineRegistration
metadata:
name: my-nodes
namespace: fleet-default
spec:
config:
elemental:
reset:
enabled: true
debug: true
reset-persistent: true
reset-oem: true
reboot: true
system-uri: registry.suse.com/rancher/sle-micro/5.5:latest
machineName
Template used to derive the hostname to be set to the node and as the name of the associated MachineInventory kubernetes resource.
The value is interpolated using Label Templates.
If no machineName is specified, a default one in the form m-$UUID will be set.
See the Customize Hostname section for further details.
Example
apiVersion: elemental.cattle.io/v1beta1
kind: MachineRegistration
metadata:
name: my-nodes
namespace: fleet-default
spec:
machineName: hostname-test-4
machineInventoryLabels
Labels to be set to the MachineInventory created from this MachineRegistration.
The label values are interpolated using Label Templates.
These labels could be used to establish a selection criteria in MachineInventorySelectorTemplate.
Elemental nodes will run elemental-register every 30 minutes.
It is possible to update the machineInventoryLabels so that all registered nodes apply the new labels on the next successfull registration update.
Example
apiVersion: elemental.cattle.io/v1beta1
kind: MachineRegistration
metadata:
name: my-nodes
namespace: fleet-default
spec:
machineInventoryLabels:
my.prefix.io/element: fire
my.prefix.io/cpus: 32
my.prefix.io/manufacturer: "${System Information/Manufacturer}"
my.prefix.io/productName: "${System Information/Product Name}"
my.prefix.io/serialNumber: "${System Information/Serial Number}"
my.prefix.io/machineUUID: "${System Information/UUID}"
machineInventoryAnnotations
Annotations that will be set to the MachineInventory that is created from this MachineRegistration
Key: value type
Example
apiVersion: elemental.cattle.io/v1beta1
kind: MachineRegistration
metadata:
name: my-nodes
namespace: fleet-default
spec:
machineInventoryAnnotations:
owner: bob
version: 1.0.0