k3s-ansible

To provision a cluster, first create an inventory.yml by copying the sample: cp inventory-sample.yml inventory.yml. Edit the inventory to define your server and agent hosts.

Note: If multiple hosts are in the server group, the playbook automatically configures High Availability (HA) mode with embedded etcd. An odd number of server nodes (3, 5, 7) is required for HA.

You can install k3s-ansible as an Ansible collection using the ansible-galaxy command. Alternatively, you can include it in your project's requirements.yaml file using a git source.

$ ansible-galaxy collection install git+https://github.com/k3s-io/k3s-ansible.git

Or in requirements.yaml:

collections:
  - name: https://github.com/k3s-io/k3s-ansible.git
    type: git
    version: <comit-ish>

To run the playbooks directly from the repository without installing it as a collection, clone the repository and navigate to the directory.

$ git clone https://github.com/k3s-io/k3s-ansible.git
$ cd k3s-ansible

To upgrade K3s, update the k3s_version variable in your inventory.yml. You can then use the dedicated upgrade playbook or re-run the site playbook.

Important: When upgrading an HA cluster, use --forks=1 with the site playbook to ensure servers are restarted one at a time, preserving etcd quorum.

To use an external database instead of embedded etcd, set use_external_database: true and provide the connection string via extra_server_args using the --datastore-endpoint flag. This is required if you have more than one server node defined.

k3s_cluster:
  children:
    server:
      hosts:
        192.16.35.11:
        192.16.35.12:
    agent:
      hosts:
        192.16.35.13:

  vars:
    use_external_database: true
    extra_server_args: "--datastore-endpoint=postgres://username:password@hostname:port/database-name"

Upon successful deployment, the cluster's kubeconfig is merged into ~/.kube/config under the k3s-ansible context. You can customize the context name using cluster_context or the destination path using kubeconfig in inventory.yml.

To re-fetch the kubeconfig without re-running the full deployment, use the kubeconfig tag.

# Verify access
kubectl config use-context k3s-ansible
kubectl get nodes

# Re-run only kubeconfig generation (if installed via galaxy)
ansible-playbook k3s.orchestration.site -i inventory.yml --tags kubeconfig