Inventory

Ansible automates tasks on managed nodes (also named hosts) in cluster infrastructure, using a list or group of lists, known as inventory.

Important Settings

There are two key configuration settings, influencing how the cluster will be deployed.

Playbook Batch Size

Because K3s uses tokens to secure the node join process, a serial must be defined, generating the token on first cluster type node. Next, the generated token is copied into additional nodes, while running the Provisioning playbook.

Batch Size Usage

Example of serial structure with 3 server type nodes and 5 agent type nodes, used into Provisioning playbook:

Provisioning Details

serial:
  - 1
  - 2
  - 5

The serial structure has the following pattern:

1, first server type node, where the K3s token is generated
2, two additional server type nodes, where the K3s token is copied into
5, five additional agent type nodes, where the K3s token is copied into

Tip

Update the serial structure into provisioning.yaml playbook file.

Example of serial structure with 3 server type nodes and 5 agent type nodes, used into Reset playbook:

Reset Details

serial:
  - 3
  - 5

The serial structure has the following pattern:

3, server type nodes are reset, first
5, agent type nodes are reset

Tip

Update the serial structure into reset.yaml playbook file.

`k3s_vars.cluster.controlplane.tainted`

The setting allows the end-user to control where the Kubernetes pods will be deployed. In a scenario where there is only a single or no agent type nodes deployed, setting the value to false will allow pods to be deployed into any cluster node type.

Tip

Update the setting into k3s role main.yaml variables file.

Configuration

The hosts.yaml inventory file contains the list of server and agent cluster node types.

Important

Please review the K3s Architecture, for further details.

High Availability

The minimum number of server type nodes for a HA cluster is 3. Ideally, a cluster should have a starting point of 6 nodes, 3 tainted server type nodes (running control-plane and datastore components) and 3 agent type nodes (where Kubernetes pods are deployed).

Example of a HA cluster inventory with 4 nodes:

Inventory Details

Inventory, set into hosts.yaml inventory file:

server:
  hosts:
    apollo:
    boreas:
    cerus:

agent:
  hosts:
    chaos:

cluster:
  children:
    server:
    agent:

Batch size, set into provisioning.yaml playbook file:

serial:
  - 1
  - 2
  - 1

Batch size, set into reset.yaml playbook file:

serial:
  - 3
  - 1

Single Point of Failure

Caution

The above detailed configuration will introduce a SPOF, since Kubernetes pods are deployed to a single or no agent type nodes.

To address this issue, set the k3s_vars.server.controlplane.tainted option to false into k3s role main.yaml variables file.

Non High Availability

The minimum number of server type nodes for a Non HA cluster is 1. By K3s Architecture design, a cluster can have either 1, or 3+ server type nodes.

Important

If the targeted cluster has less than 3 server type nodes, the Provisioning playbook will automatically disable all related HA features.

Example of a Non HA cluster inventory with 2 nodes:

Inventory Details

Inventory, set into hosts.yaml inventory file:

server:
  hosts:
    apollo:

agent:
  hosts:
    chaos:

cluster:
  children:
    server:
    agent:

Batch size, set into provisioning.yaml playbook file:

serial:
  - 1

Batch size, set into reset.yaml playbook file:

serial:
  - 2

Support

If you encounter any configuration problems or want to request a new feature, feel free to open an issue. For general questions or feedback, please use the discussions.

Configuration User