xanmanning.k3s

Ansible Role: k3s (v3.x)

This Ansible role is for installing K3S ("Lightweight Kubernetes") as a standalone server or a cluster.

Help Wanted!

Hello! :wave: @xanmanning is looking for a new maintainer for this Ansible role since I no longer have enough time to maintain it regularly. If you’re interested, please reach out.

Release Notes

Check out the Releases and CHANGELOG.md for update information.

Requirements

To run Ansible from your host, you need the following Python packages:

python >= 3.6.0 - See Notes below.
ansible >= 2.9.16 or ansible-base >= 2.10.4

You can install these using the requirements.txt file in this repository by running: pip3 install -r requirements.txt.

This role has been tested on various Linux distributions including Alpine Linux, Ubuntu 20.04 LTS, and others.

:warning: The v3 releases of this role only support k3s >= v1.19. If you need k3s < v1.19, please consider updating or use the v1.x versions of this role.

Make sure to check the CHANGELOG before upgrading for any breaking changes.

Role Variables

From K3s v1.19.1+k3s1, you can configure K3s using a configuration file instead of using environment variables or command-line options. The v2 of this role focuses on this configuration file approach primarily.

Global/Cluster Variables

These variables affect all hosts in your playbook:

Variable	Description	Default Value
`k3s_state`	Current state of k3s: installed, started, stopped, etc.	installed
`k3s_release_version`	Specify a version of k3s to use (e.g., `v0.2.0`). For the latest version, use `false`.	`false`
`k3s_airgap`	Boolean for enabling air-gapped installations	`false`
`k3s_config_file`	Path to the k3s configuration file.	`/etc/rancher/k3s/config.yaml`
`k3s_build_cluster`	Allow clustering when multiple hosts are configured.	`true`
More variables are listed in the complete documentation.

K3S Service Configuration

These variables define how and when the k3s service starts with systemd:

Variable	Description	Default Value
`k3s_start_on_boot`	Start k3s automatically on boot.	`true`
More variables are listed in the complete documentation.

Group/Host Variables

These are the variables set for individual hosts or groups:

Variable	Description	Default Value
`k3s_control_node`	Indicates if a host or group is part of the control plane.	`false` (the role will choose a control node)
More variables are listed in the complete documentation.

Important Notes

Python Requirement

Python 3 is required on both the target systems and the Ansible controller. If both Python 2 and 3 exist, set ansible_python_interpreter in your inventory to ensure Python 3 is used.

Release Version

If k3s_release_version is not set, it defaults to the latest stable version. You can specify different release channels as needed.

Hard Links vs. Symbolic Links

If working with the system-upgrade-controller, set k3s_install_hard_links to true to use hard links, as symbolic links may cause issues.

Example Playbooks

Playbook for Single Control Node

- hosts: k3s_nodes
  vars:
    k3s_release_version: testing
  roles:
    - role: xanmanning.k3s

Playbook for Highly Available Setup

- hosts: k3s_nodes
  vars:
    k3s_registration_address: loadbalancer
    k3s_server:
      datastore-endpoint: "postgres://postgres:verybadpass@database:5432/postgres?sslmode=disable"
  pre_tasks:
    - name: Set each node to be a control node
      ansible.builtin.set_fact:
        k3s_control_node: true
      when: inventory_hostname in ['node2', 'node3']
  roles:
    - role: xanmanning.k3s