Ansible Cluster Management¶

Directory Structure¶

devops/ansible/
  ansible.cfg                          # Ansible configuration
  inventory/
    hosts.local.yml                    # Single-node local inventory
    hosts.example.yml                  # Multi-node example
    group_vars/
      all.yml                          # Global variables (k3s version, etc.)
  roles/
    k3s_server/                        # Install and configure k3s server
    k3s_agent/                         # Join agent nodes to cluster
    helm/                              # Install Helm binary
    addons/                            # Install observability stack
  playbooks/
    bootstrap-k3s.yml                  # Full cluster bootstrap
    upgrade-k3s.yml                    # Rolling k3s upgrade
    install-addons.yml                 # Install cluster add-ons

Inventories¶

Local single-node (default)¶

The default inventory (hosts.local.yml) uses connection: local for a single-node k3s cluster on the current machine. No SSH required.

Multi-node SSH cluster¶

Copy hosts.example.yml to hosts.yml and fill in your actual host IPs:

cp inventory/hosts.example.yml inventory/hosts.yml
# Edit inventory/hosts.yml with your server and agent IPs

Playbooks¶

Bootstrap k3s¶

cd devops/ansible

# Single-node local:
ansible-playbook playbooks/bootstrap-k3s.yml

# Multi-node:
ansible-playbook playbooks/bootstrap-k3s.yml -i inventory/hosts.yml

# Override k3s version:
ansible-playbook playbooks/bootstrap-k3s.yml -e k3s_version=v1.31.0+k3s1

This playbook: 1. Installs k3s server with pinned version 2. Enables and starts the k3s service 3. Waits for the node to be Ready 4. Joins agent nodes (if any in inventory) 5. Installs Helm on the server

Upgrade k3s¶

ansible-playbook playbooks/upgrade-k3s.yml -e k3s_version=v1.31.0+k3s1

This playbook performs a rolling upgrade: 1. Cordon the node (multi-node only) 2. Drain workloads (multi-node only) 3. Upgrade k3s binary 4. Restart the service 5. Wait for node Ready 6. Uncordon the node

Single-node clusters skip the cordon/drain steps.

Install add-ons¶

ansible-playbook playbooks/install-addons.yml

Installs the observability stack: kube-prometheus-stack, Loki, Promtail, Tempo.

Roles¶

k3s_server¶

Installs k3s server with configurable version and kubeconfig mode.

Variables: - k3s_version — pinned k3s version (default in group_vars) - k3s_kubeconfig_mode — file permissions for kubeconfig (default: 644) - k3s_extra_args — additional k3s server arguments

k3s_agent¶

Joins a node to an existing k3s cluster.

Variables: - k3s_server_url — URL of the k3s server API - k3s_node_token — node join token

helm¶

Installs the Helm binary if not present.

Variables: - helm_version — pinned Helm version

addons¶

Installs the observability stack via Helm charts using the same values files and release names as devops/scripts/install-observability.sh. This ensures both paths produce identical cluster state.

Variables: - addons_prometheus_enabled — install kube-prometheus-stack (default: true) - addons_loki_enabled — install Loki (default: true) - addons_promtail_enabled — install Promtail (default: true) - addons_tempo_enabled — install Tempo (default: true) - addons_values_dir — path to values files directory (default: relative to playbook) - addons_prometheus_release — Helm release name (default: kube-prometheus-stack) - addons_loki_release — Helm release name (default: loki) - addons_promtail_release — Helm release name (default: promtail) - addons_tempo_release — Helm release name (default: tempo)