elemental

Deploying Elemental on the Cloud

To deploy an Elemental cluster on the cloud, you need to:

  1. Prepare the necessary infrastructure resources.
  2. Build a customized image for the specific cloud provider.
  3. Upload the image and spin up the desired machines.

In the sections below you will find general information on what is necessary for Elemental to be deployed on a specific cloud provider.

For plug-and-play examples, refer to the single-node and multi-node AWS examples in the Cookbook document.

Infrastructure Resources Preparation

To facilitate the RKE2 cluster load balancing, before building the customized image, ensure you have the following available on your provider:

  1. Internal loadbalancer that forwards traffic to the RKE2 API (6443) and supervisor (9345) on each of the cluster nodes - The private IP and hostname of this resource is going to be needed during the image customization phase.
  2. [Optional] A second loadbalancer that forwards HTTP (80) and HTTPS (443) traffic to the RKE2 ingress controller - For applications that need to be accessed from outside the cluster (e.g. Rancher UI).

NOTE: This section describes only the expected end state of the infrastructure. It does not cover every resource that may be required to achieve that state, as the specific resources and implementation details will vary between cloud providers.

Preparing the Image

To customize an Elemental image for the cloud, create a configuration directory, add your settings and start the customization process.

The configuration directory has the following requirements:

  1. Under kernelCmdLine in install.yaml you must provide the ignition platform identifier for the cloud provider you will be deploying on - Necessary so that ignition knows from where to retrieve runtime configurations.
  2. Under kubernetes/cluster.yaml make sure to provide the following configurations:
    • network.apiVIP - The private address of the internal loadbalancer created in the previous section.
    • network.apiHost - The host of the internal loadbalancer created in the previous section.
    • network.apiVIPMode: "external" - To avoid the default MetalLB loadbalancing that is done for non-cloud clusters.
  3. Do not define any static node role configuration under the kubernetes/cluster.yaml file - It is hard to match static configurations with the dynamic nature of cloud providers. As such, node role configuration will be provided during the machine creation through ignition.
  4. Do not define any static network configuration under the network/ directory - Any network configuration should happen at the cloud provider level.

You can adjust any further configuration as necessary for your environment. For example, adding an SSH key or another user, writing a file on the filesystem, including additional Kubernetes manifests and charts, or anything else!

An example of a configuration directory for AWS can be found here.

Spinning the Elemental Machines

NOTE: This section assumes you have uploaded your customized image to the desired cloud provider and created the necessary resources so that a machine can be spun from that image.

Up to now, you have customized an image that has no notion of what type of RKE2 node it will be booted as. This is configured at runtime by passing an ignition configuration to the machine’s metadata (e.g. user-data for AWS).

At a minimum, this ignition configuration needs to ship the following:

  1. A runtime.env file created at /var/lib/elemental/ - This file contains runtime configurations that the Elemental tooling parses at boot time.
  2. A defined hostname under the /etc/hostname file - So that nodes can be distinguished from one another.

Below you can find information on how to create this ignition configuration.

Runtime Ignition Creation

runtime.env

To determine the node’s role in the cluster, Elemental usually relies on statically defined network, host and node information.

However, this is not the right approach when it comes to cloud providers. As such, Elemental now supports runtime configurations through a /var/lib/elemental/runtime.env file. This file is provided at boot time on each node through an additional user defined ignition configuration.

This is a standard .env file that supports the following environment variables:

NOTE: Configurations here will be extended in the future based on user feedback and feature development.

Creating the Configuration

NOTE: For specific information on how ignition integrates with Elemental, refer to the Elemental and Ignition Integration document.

The easiest way to create the ignition configuration is to use butane.

For a single-node cluster, create a directory with the following contents:

  1. A runtime.env file with NODETYPE=server and IS_INIT_NODE=true.
  2. A butane.yaml file with the following configuration:
     variant: fcos
     version: 1.6.0
    
     storage:
       files:
         - path: /var/lib/elemental/runtime.env
           mode: 0644
           overwrite: true
           contents:
             local: runtime.env
         - path: /etc/hostname
           mode: 0644
           overwrite: true
           contents:
             inline: |
               single-node-example.com
    

Then run butane against that directory:

butane --strict --pretty --files-dir <dir> butane.yaml > config.ign

This produces the necessary ignition configuration for a single-node cluster. For multi-node clusters, there should be a directory for each node.

For more information, refer to the available examples for single-node and multi-node runtime configurations.