Skip to main content

Architecture

The Elemental stack can be divided in two main parts: the Elemental OS, an immutable and customizable OS which comprises the tools and the steps needed to prepare the Cloud Native OS image and perform the actual OS installation on the host, and the Elemental Operator, that allows central management of the Elemental OS via Rancher, the Kubernetes way.

Elemental Architecture​

Elemental OS​

In order to deploy the Elemental OS we need:

  • an Elemental base OS image
  • an Elemental installation configuration
  • the Elemental CLI tool, which installs the Elemental OS image on the target host applying the Elemental installation configuration

Elemental OS image​

The Elemental OS image is an OCI container image containing all the files that will make up the OS of the target host. It will contain not only all the desired binaries and libraries, but also the kernel and the boot files required by a linux system. The Elemental Toolkit is at the core of the Elemental OS, enabling to boot and upgrade an OS from container images. It also provides a framework that allows to combine different packages to bake custom OS container images. For more information check the Elemental Toolkit project page.

Elemental installation configuration​

In order to provision a machine with an Elemental OS image, installation configuration parameters are required: things such as the boot device, the root password, system configuration, users and custom files are things that should be provided aside from the Elemental OS image. All the data can be provided in a single .yaml file. More details can be found in the Elemental Toolkit documentation.

Elemental CLI​

Elemental CLI is the tool that allows to turn the Elemental OS image in a bootable and installed OS: it can generate an Elemental ISO image from the provided Elemental OS container image. The generated Elemental ISO image can be used to boot a virtual machine or a bare metal host and start the Elemental OS installation.

The Elemental CLI allows also to install the Elemental OS on the storage device of the live booted host, applying the provided Elemental installation configuration. For the list and syntax of the commands available in the Elemental CLI, check the online documentation.

Elemental ISO

The Elemental ISO is a live ISO based on the Elemental OS (an Elemental live ISO). It includes all the tools needed to perform a full node provisioning, from the OS to Kubernetes, including the Elemental CLI and the Elemental Register client.

Elemental Operator​

The Elemental Operator is responsible for managing OS upgrades and a secure device inventory to assist with zero touch provisioning. It provides an Elemental Operator Helm Chart and an Elemental Register client.

Elemental Operator Helm Chart​

The Elemental Operator Helm Chart must be installed on a Rancher Cluster. It enables new hosts to:

  • register against the Elemental Operator.
  • retrieve the Elemental installation configuration (which is stored in custom Kubernetes resources) to start the Elemental OS installation.
  • download and install the Rancher System Agent, which enables Rancher to provision and manage K3s and RKE2 on the Elemental nodes.

The Elemental Operator allows control of the Elemental Nodes by extending the Kubernetes APIs with a set of elemental.cattle.io Kubernetes CRDs:

  • MachineRegistration
  • MachineInventory
  • MachineInventorySelector
  • MachineInventorySelectorTemplate
  • ManagedOSImage
  • ManagedOSVersion
  • ManagedOSVersionChannel
  • SeedImage

MachineRegistration​

The MachineRegistration includes the Elemental installation configuration (provided by the user) and a registration token (generated by the Elemental Operator), from which a registration URL is derived.

The registration URL is the way through which an host can access the Elemental Operator services, to kick off the Elemental provisioning 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 only 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. See the Elemental Register client section for more info on the registration process and the config:elemental:registration section in the MachineRegistration reference for more details on the available registration options.

MachineInventory​

When a new host registers successfully, the Elemental Operator creates a MachineInventory resource representing that particular host. The MachineInventory stores the TPM hash of the tracked host, retrieved during the registration process, and allows to execute arbitrary commands (plans) on the machine.

A MachineInventory has two conditions:

  • AdoptionReady, which indicates the machine has been adopted by a selector to be part of a cluster.
  • Ready, which indicates that the machine has been registered and provisioned with an Elemental OS.

MachineInventorySelector​

A MachineInventorySelector selects MachineInventories based on applied selectors (usually pattern matching on MachineInventory label values).

MachineInventorySelectors have two conditions:

  • InventoryReady, turns to true if the MachineInventorySelector has found a matching MachineInventory and has successfully set itself as the MachineInventory owner.
  • Ready, tracks if the selector already adopted a machine and started the kubernetes provisioning process (node bootstrap).

MachineInventorySelectorTemplate​

The MachineInventorySelectorTemplate is a user defined resource that will be used as the blueprint to create the required MachineInventorySelectors: it includes the selector to identify the eligible MachineInventories.

SeedImage​

A SeedImage is a resource to handle the installation media creation. Includes the reference to the base installation system and a reference to the machine registration. It is used to create and serve installation ISOs including the MachineRegistration metadata required for the machine registration. The installation media is created and being served in a devoted Pod.

SeedImage have two conditions:

  • SeedImageReady, tracks the status of the associated pod.
  • Ready, tracks if all the SeedImage child resources have been successfully created.

Elemental Register client​

New hosts start the Elemental provisioning process through the Elemental Register client: this tool requires a valid elemental-operator registration URL as input (see the MachineRegistration section), and performs the following steps:

  • setups a websocket connection to the registration URL
  • authenticates itself using the registration token and the onboard TPM (Trusted Platform Module)
  • sends SMBIOS data to the Elemental Operator
  • retrieves the Elemental installation configuration
  • starts the Elemental CLI and performs the Elemental OS installation

Note if no TPM 2.0 is available on the host, TPM can be emulated by software: see the emulate-tpm key in the config.elemental.register reference document.

Elemental Operator includes a Kubernetes operator installed in the management cluster and a client side installed in nodes, so they can self register into the management cluster. Once a node is registered the Elemental Operator will kick-start the OS installation and schedule the Kubernetes provisioning using the Rancher System Agent. Rancher System Agent is responsible for bootstrapping RKE2/k3s and Rancher from an OCI registry. This means an update of containerd, k3s, RKE2, or Rancher does not require an OS upgrade or node reboot.