lablabs-ansible-role-rke2

This Ansible role deploys RKE2 Kubernetes clusters using the tarball installation method. It supports three primary deployment modes:

1. RKE2 single node: A standalone node containing all components.
2. RKE2 Cluster (Standard): One Server (Master) node and one or more Agent (Worker) nodes.
3. RKE2 Cluster (High Availability): Multiple Server (Master) nodes in HA mode with zero or more Agent (Worker) nodes. For HA mode, it is recommended to use an odd number of server nodes (e.g., three) to run etcd, the Kubernetes API (via Keepalived VIP or Kube-VIP), and other control plane services.

Additionally, all three modes can be deployed in an Air-Gapped environment using local artifacts.

To use this role, your Ansible controller must meet the following requirements:

• Ansible: version 2.10 or higher
• Python Package: netaddr must be installed on the controller.

To increase security, you can define a separate rke2_agent_token for worker nodes. This requires removing the global rke2_token and assigning tokens specifically via group variables:

1. In group_vars/masters.yml, define both rke2_token (for servers) and rke2_agent_token (for agents).
2. In group_vars/workers.yml, set rke2_token to match the rke2_agent_token defined in the masters group.

# group_vars/masters.yml
rke2_token: defaultSecret12345
rke2_agent_token: agentSecret54321

# group_vars/workers.yml
rke2_token: agentSecret54321

The lablabs.rke2 role requires a specific inventory hierarchy. You must define two main groups: masters (for RKE2 server/control-plane nodes) and workers (for RKE2 agent/worker nodes). Both groups must be children of a parent group named k8s_cluster.

[masters]
master-01 ansible_host=192.168.123.1
master-02 ansible_host=192.168.123.2
master-03 ansible_host=192.168.123.3

[workers]
worker-01 ansible_host=192.168.123.11
worker-02 ansible_host=192.168.123.12
worker-03 ansible_host=192.168.123.13

[k8s_cluster:children]
masters
workers

For environments without internet access, use rke2_airgap_mode to install RKE2 from local artifacts.

Implementation types (rke2_airgap_implementation):

• download: Fetches the artifacts on each node.
• copy: Transfers local files defined in rke2_artifact to the nodes.
• exists: Assumes rke2_artifact files are already present in rke2_artifact_path.

Required variables for Airgap:

• rke2_airgap_mode: true
• rke2_artifact: A list of files required (e.g., rke2.linux-amd64.tar.gz).
• rke2_artifact_path: The local path where artifacts are stored (default: /rke2/artifact).

rke2_airgap_mode: true
rke2_airgap_implementation: copy
rke2_artifact:
  - sha256sum-amd64.txt
  - rke2.linux-amd64.tar.gz
  - rke2-images.linux-amd64.tar.zst
rke2_airgap_copy_sourcepath: local_artifacts

To upgrade your RKE2 installation, update the rke2_version variable in your configuration and re-run the playbook.

The role performs a rolling upgrade: it restarts the RKE2 service on nodes one by one. The role will verify that the node has returned to a Ready state before proceeding to the next node in the cluster.

Playbook hangs on agent service start

If the playbook hangs during Start RKE2 service on the rest of the nodes or fails at Wait for remaining nodes to be ready, verify that your network allows the required inbound rules for RKE2 Server nodes as specified in the official RKE2 documentation.

Failed upgrade due to interrupted process

If an upgrade is interrupted and the new RKE2 version is installed but not running, the role's downgrade prevention will block subsequent runs. To bypass this, rerun the playbook with rke2_allow_downgrade: true.

For HA deployments, set rke2_ha_mode: true. You can manage the Virtual IP (VIP) using either keepalived (default) or kube-vip.

If using keepalived, specify rke2_api_ip. If using kube-vip, set rke2_ha_mode_kubevip: true and define the rke2_loadbalancer_ip_range. You can also customize the ingress controller (e.g., traefik) and download the kubeconfig to your local machine using rke2_download_kubeconf: true.

- name: Deploy RKE2
  hosts: all
  become: yes
  vars:
    rke2_ha_mode: true
    rke2_ha_mode_keepalived: false
    rke2_ha_mode_kubevip: true
    rke2_api_ip: 192.168.123.100
    rke2_loadbalancer_ip_range:
      range-global: 192.168.123.200-192.168.123.250
    rke2_ingress_controller: traefik
    rke2_traefik_values:
      logs:
        general:
          level: "DEBUG"
    rke2_download_kubeconf: true
  roles:
     - role: lablabs.rke2

To deploy RKE2 in an air-gapped environment, set rke2_airgap_mode: true and choose an implementation (e.g., copy to transfer files from the Ansible controller). You must specify the rke2_cni and provide the necessary rke2_artifact files and any additional tarballs required for the chosen CNIs.

- name: Deploy RKE2
  hosts: all
  become: yes
  vars:
    rke2_airgap_mode: true
    rke2_airgap_implementation: copy
    rke2_cni:
      - multus
      - calico
    rke2_artifact:
      - sha256sum-{{ rke2_architecture }}.txt
      - rke2.linux-{{ rke2_architecture }}.tar.gz
      - rke2-images.linux-{{ rke2_architecture }}.tar.zst
    rke2_airgap_copy_additional_tarballs:
      - rke2-images-multus.linux-{{ rke2_architecture }}
      - rke2-images-calico.linux-{{ rke2_architecture }}
  roles:
     - role: lablabs.rke2

Use these variables to manage etcd snapshots for disaster recovery.

# Local Snapshot Configuration
rke2_etcd_snapshot_source_dir: etcd_snapshots
rke2_etcd_snapshot_destination_dir: "{{ rke2_data_path }}/server/db/snapshots"
rke2_etcd_snapshot_file: ""
# rke2_etcd_snapshot_schedule: "0 */12 * * *" (Cron format)

# S3-Compatible Object Store Configuration
# Requires setting either rke2_etcd_snapshot_file or the following:
rke2_etcd_snapshot_s3_options:
  s3_endpoint: ""
  access_key: ""
  secret_key: ""
  bucket: ""
  s3_retention: 5