---

name: ansible description: Create, update, or run Ansible playbooks and inventory in this repo for multi-node changes (ansible/). Use for node bootstrap, package installs, or cluster-wide config updates.

Ansible

Overview

Use Ansible for repeatable, idempotent changes across nodes. Keep playbooks minimal, explicit about hosts, and safe to re-run.

When to use

• You need to apply the same change on multiple hosts.
• The change touches OS packages, services, or system config.
• You are bootstrapping or maintaining k3s, Rancher, or Tailscale on nodes.

Inventory and groups

Inventory lives in ansible/inventory/hosts.ini. Common groups:

• kube_masters (k3s masters)
• kube_workers (k3s workers)
• k3s_cluster (masters + workers)
• proxy (nuc)
• docker_hosts (docker-host)

Quick start

Ping all nodes in the cluster:

ansible -i ansible/inventory/hosts.ini k3s_cluster -m ping -u kalmyk

Run a playbook on all nodes in the cluster:

ansible-playbook -i ansible/inventory/hosts.ini ansible/playbooks/install_nfs_client.yml -u kalmyk -b

Limit to a single host:

ansible-playbook -i ansible/inventory/hosts.ini ansible/playbooks/install_tailscale.yml -u kalmyk -b --limit kube-worker-00

Common playbooks in this repo

• install_nfs_client.yml - install NFS client tools on nodes
• install_tailscale.yml - install Tailscale packages
• start_enable_tailscale.yml - enable and start tailscaled
• start_enable_tailscale_client.yml - start Tailscale client services
• k3s-ha.yml - configure k3s HA cluster
• k3s-oidc.yml - configure OIDC for k3s
• rancher2.yml - install Rancher
• wait_for_rancher.yml - wait until Rancher is ready
• rancher_bootstrap_logs.yml - capture Rancher bootstrap logs
• start_rancher2_container.yml - start Rancher container

Safety and idempotency

• Prefer Ansible modules over shell commands.
• Use --check and --diff when validating a risky change.
• Use --limit to scope changes during testing.
• Keep playbooks idempotent so re-runs are safe.

Validation

• Service check: systemctl status tailscaled
• Logs: journalctl -u tailscaled --no-pager -n 50
• Cluster check: kubectl get nodes -o wide

Resources

• Reference: references/ansible-runbook.md
• Runner: scripts/run-playbook.sh
• Template: assets/playbook-template.yml