### Example Inventory Setup

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-prereq.md

This example demonstrates how to define K3s cluster hosts and variables in an Ansible inventory file. It includes host definitions and common variables like api_port and server/agent group assignments.

```yaml
k3s_cluster:
  hosts:
    server1:
      ansible_host: 192.168.1.10
    agent1:
      ansible_host: 192.168.1.20

  vars:
    api_port: 6443
    server_group: server
    agent_group: agent
```

--------------------------------

### Airgap Install Directory Structure

Source: https://github.com/k3s-io/k3s-ansible/blob/main/README.md

Example of the expected directory structure for an airgap installation, including the K3s binary and image tarball. Paths are relative to the playbooks directory.

```bash
$ ls ./playbooks/my-airgap/
total 248M
-rwxr-xr-x 1 $USER $USER  58M Nov 14 11:28 k3s
-rw-r--r-- 1 $USER $USER 190M Nov 14 11:30 k3s-airgap-images-amd64.tar.gz
```

--------------------------------

### Install/Upgrade K3s Server

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-k3s-upgrade.md

Use this command to install or upgrade K3s on server nodes. Environment variables control the installation process, such as skipping the start or specifying the version.

```bash
/usr/local/bin/k3s-install.sh

Environment:
  INSTALL_K3S_SKIP_START: "true"
  INSTALL_K3S_VERSION: {{ k3s_version }}
  INSTALL_K3S_EXEC: {{ extra_server_args }}
  INSTALL_K3S_SKIP_DOWNLOAD: {{ airgap_dir defined ? true : false }}
```

--------------------------------

### Install Script Execution for Servers

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-airgap.md

Execute the K3s installation script on server nodes, skipping enable and download steps.

```bash
/usr/local/bin/k3s-install.sh

Environment:
  INSTALL_K3S_SKIP_ENABLE: "true"
  INSTALL_K3S_SKIP_DOWNLOAD: "true"
```

--------------------------------

### Example K3s Ansible Inventory for Agent Setup

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-k3s-agent.md

Defines a sample Ansible inventory structure for a K3s cluster, specifying server and agent hosts, common variables, and agent-specific configurations like extra arguments, service environment variables, and agent config YAML.

```yaml
k3s_cluster:
  children:
    server:
      hosts:
        k3s-server1:
          ansible_host: 192.168.1.10

    agent:
      hosts:
        k3s-agent1:
          ansible_host: 192.168.1.20
        k3s-agent2:
          ansible_host: 192.168.1.21

  vars:
    ansible_user: debian
    k3s_version: v1.31.12+k3s1
    token: "my-secure-token"
    api_endpoint: 192.168.1.10
    api_port: 6443
    extra_agent_args: "--kubelet-arg max-pods=250 --labels role=compute"
    extra_service_envs:
      - 'HTTP_PROXY=http://proxy.local:3128'
      - 'HTTPS_PROXY=http://proxy.local:3128'
    agent_config_yaml: |
      node-labels:
        workload-type: compute
      kubelet-arg:
        - "max-pods=250"
        - "memory-manager-type=static"
```

--------------------------------

### Troubleshooting Missing Install Script

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-airgap.md

Guidance for resolving issues when the K3s install script is not found in the airgap directory.

```bash
# Install script not found in airgap_dir
# Solution: Ensure k3s-install.sh is in airgap_dir, or allow control node internet access

# Control node must either have:
1. airgap_dir/k3s-install.sh (pre-downloaded), OR
2. Internet access to fetch from https://get.k3s.io/
```

--------------------------------

### Conditional Package Installation for Ubuntu/Debian

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-prereq.md

Installs the 'policycoreutils' package on Ubuntu/Debian systems. This is part of the prerequisite setup for SELinux context restoration.

```yaml
when: ansible_facts['distribution'] in ['Ubuntu']
  # Install policycoreutils
```

--------------------------------

### Custom Install Script Usage

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-airgap.md

Replace the default K3s install script with a custom one by placing it in the airgap directory.

```bash
cp ./my-k3s-install.sh airgap_dir/k3s-install.sh
```

--------------------------------

### Example Node Labels Output

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/types.md

Demonstrates how to view applied node labels using kubectl.

```bash
kubectl get nodes --show-labels
# NAME       ROLES    ... LABELS
# worker-1   <none>   ... disktype=ssd,workload-type=compute,region=us-west-1
```

--------------------------------

### Install K3s Airgap Artifacts with DNF

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-airgap.md

On RHEL/SUSE systems, this command installs the necessary SELinux RPMs for K3s to function in an air-gapped environment. It installs container-selinux, selinux-policy, and k3s-selinux RPMs in the correct dependency order, ignoring GPG checks and disabling other repositories.

```bash
dnf install /tmp/container-selinux*.rpm /tmp/selinux-policy*.rpm /tmp/k3s-selinux*.rpm
```

--------------------------------

### Airgap Install Inventory Configuration

Source: https://github.com/k3s-io/k3s-ansible/blob/main/README.md

Configuration for `airgap_dir` in `inventory.yml` for an airgap installation. Paths are relative to the playbooks directory.

```yaml
airgap_dir: ./my-airgap # Paths are relative to the playbooks directory
```

--------------------------------

### Install Script Execution for Agents

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-airgap.md

Execute the K3s installation script on agent nodes, skipping enable and download, and specifying the agent role.

```bash
/usr/local/bin/k3s-install.sh

Environment:
  INSTALL_K3S_SKIP_ENABLE: "true"
  INSTALL_K3S_SKIP_DOWNLOAD: "true"
  INSTALL_K3S_EXEC: "agent"
```

--------------------------------

### Initial Airgap Deployment Inventory Setup

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-airgap.md

Configure inventory variables for an initial airgap deployment of K3s.

```yaml
k3s_cluster:
  vars:
    airgap_dir: ./playbooks/my-airgap
    k3s_version: v1.31.12+k3s1
    token: "my-token"
    api_endpoint: 192.168.1.10
```

--------------------------------

### Get Kubeconfig (ansible-galaxy)

Source: https://github.com/k3s-io/k3s-ansible/blob/main/README.md

Run this command to get a fresh copy of the kubeconfig when k3s-ansible was installed via ansible-galaxy. Uses the 'kubeconfig' tag.

```bash
ansible-playbook k3s.orchestration.site -i inventory.yml --tags kubeconfig
```

--------------------------------

### Basic Inventory Configuration

Source: https://github.com/k3s-io/k3s-ansible/blob/main/README.md

Configure your inventory.yml file to define the server and agent nodes for your K3s cluster. This example shows a simple setup with one server and two agents.

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

--------------------------------

### Minimal Inventory Example

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/variables-quick-reference.md

Sets up a basic K3s cluster with server and agent groups, defining essential variables like Ansible user and K3s version.

```yaml
k3s_cluster:
  children:
    server:
      hosts:
        server1:
          ansible_host: 192.168.1.10
    agent:
      hosts:
        agent1:
          ansible_host: 192.168.1.20

  vars:
    ansible_user: debian
    k3s_version: v1.31.12+k3s1
    api_endpoint: 192.168.1.10
```

--------------------------------

### Troubleshooting SELinux RPM Installation Fails

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-airgap.md

Verify the presence of necessary SELinux RPMs in the airgap directory for RHEL/SUSE systems.

```bash
# On RHEL/SUSE systems
# Check if RPMs are in airgap_dir:

ls airgap_dir/ | grep selinux
# Should show: container-selinux-*.rpm, selinux-policy-*.rpm, k3s-selinux-*.rpm
```

--------------------------------

### Agent Environment Variable Merging Example

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-k3s-agent.md

Illustrates how user-defined extra installation environment variables can override role defaults. The K3S_TOKEN is always applied last.

```yaml
extra_install_envs:
  INSTALL_K3S_VERSION: "v1.30.0+k3s1"  # Overrides role default
  INSTALL_K3S_SKIP_DOWNLOAD: "false"   # Overrides role default

# Result: INSTALL_K3S_VERSION uses user value, K3S_TOKEN overrides all
```

--------------------------------

### Troubleshooting Missing Container Images

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-airgap.md

Instructions for resolving issues where K3s starts but no container images are available.

```bash
# K3s starts but no images available
# Solution: Copy appropriate images to airgap_dir

# For amd64: k3s-airgap-images-amd64.tar.gz (or .tar.zst, .tar)
# For arm64: k3s-airgap-images-arm64.tar.gz (or .tar.zst, .tar)
```

--------------------------------

### Example K3s Ansible Inventory

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-k3s-server.md

A comprehensive example of an Ansible inventory file for setting up a K3s cluster. It defines server and agent nodes, along with cluster-wide variables.

```yaml
k3s_cluster:
  children:
    server:
      hosts:
        k3s-server1:
          ansible_host: 192.168.1.10
        k3s-server2:
          ansible_host: 192.168.1.11
        k3s-server3:
          ansible_host: 192.168.1.12
    agent:
      hosts:
        k3s-agent1:
          ansible_host: 192.168.1.20

  vars:
    ansible_user: debian
    k3s_version: v1.31.12+k3s1
    token: "my-secure-token"
    api_endpoint: 192.168.1.10
    api_port: 6443
    cluster_context: production
    extra_server_args: "--kubelet-arg feature-gates=GracefulNodeShutdown=true"
    server_config_yaml: |
      etcd-snapshot-retention: 10
      disable:
        - local-storage
```

--------------------------------

### Complete Ansible Inventory Example for K3s Cluster

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/configuration.md

A comprehensive example of an Ansible inventory file for a K3s cluster, demonstrating group and host definitions, global variables for SSH and K3s settings, and detailed server/agent configuration using YAML strings.

```yaml
---
k3s_cluster:
  children:
    server:
      hosts:
        k3s-master-1:
          ansible_host: 192.168.1.10
        k3s-master-2:
          ansible_host: 192.168.1.11
        k3s-master-3:
          ansible_host: 192.168.1.12
      vars:
        extra_server_args: "--disable=traefik --kubelet-arg max-pods=250"
    
    agent:
      hosts:
        k3s-worker-1:
          ansible_host: 192.168.1.20
        k3s-worker-2:
          ansible_host: 192.168.1.21
        k3s-worker-3:
          ansible_host: 192.168.1.22
      vars:
        extra_agent_args: "--kubelet-arg max-pods=250"
  
  vars:
    # SSH Configuration
    ansible_user: debian
    ansible_port: 22
    ansible_become_method: sudo
    
    # K3s Version and Token
    k3s_version: v1.31.12+k3s1
    token: "K1234567890abcdefghijklmnopqrstuvw=="
    
    # Cluster Configuration
    api_endpoint: 192.168.1.10
    api_port: 6443
    cluster_context: production
    
    # Server Configuration
    server_config_yaml: |
      disable:
        - traefik
      kubelet-arg:
        - "max-pods=250"
      etcd-snapshot-retention: 10
      etcd-snapshot-schedule-cron: "0 */6 * * *"
    
    # Agent Configuration
    agent_config_yaml: |
      node-labels:
        workload-type: general
      kubelet-arg:
        - "max-pods=250"
    
    # Service Environment
    extra_service_envs:
      - 'HTTP_PROXY=http://proxy.local:3128'
    
    # kubeconfig Setup
    kubeconfig: ~/.kube/config.new
    user_kubectl: true
```

--------------------------------

### Full Inventory Example

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/variables-quick-reference.md

Provides a comprehensive inventory configuration for a K3s cluster, including multiple servers and agents, detailed variables, and multi-line configuration settings.

```yaml
k3s_cluster:
  children:
    server:
      hosts:
        server1:
          ansible_host: 192.168.1.10
        server2:
          ansible_host: 192.168.1.11
      vars:
        extra_server_args: "--disable=traefik"
    
    agent:
      hosts:
        agent1:
          ansible_host: 192.168.1.20
        agent2:
          ansible_host: 192.168.1.21
      vars:
        extra_agent_args: "--kubelet-arg max-pods=250"

  vars:
    ansible_user: debian
    ansible_port: 22
    k3s_version: v1.31.12+k3s1
    token: "my-token"
    api_endpoint: 192.168.1.10
    api_port: 6443
    cluster_context: prod
    kubeconfig: "~/.kube/config.new"
    user_kubectl: true
    
    server_config_yaml: |
      disable:
        - traefik
        - local-storage
      etcd-snapshot-retention: 10
    
    extra_service_envs:
      - 'HTTP_PROXY=http://proxy:3128'
```

--------------------------------

### Re-run Kubeconfig Setup

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/playbooks.md

Use the `kubeconfig` tag to re-run only the kubeconfig setup process without performing a full deployment. This is useful for re-establishing access to your cluster.

```bash
ansible-playbook playbooks/site.yml -i inventory.yml --tags kubeconfig
```

--------------------------------

### Start Local Testing Cluster with Vagrant

Source: https://github.com/k3s-io/k3s-ansible/blob/main/README.md

Command to provision a 5-node K3s cluster using Vagrant. The Vagrantfile can be edited to customize node resources and provider.

```bash
vagrant up
```

--------------------------------

### Troubleshooting Missing K3s Binary

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-airgap.md

Steps to resolve issues when the K3s binary is not found during the installation process.

```bash
# Binary lookup failed (with_first_found)
# Solution: Ensure k3s or k3s-<arch> file is in airgap_dir

ls airgap_dir/
# Should show: k3s (or k3s-amd64, k3s-arm64, etc.)
```

--------------------------------

### Example Inventory for Raspberry Pi Cluster

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-raspberrypi.md

An example Ansible inventory file defining hosts for a K3s cluster, including specific variables for Raspberry Pi nodes such as the user, K3s version, and API endpoint.

```yaml
k3s_cluster:
  hosts:
    pi-server:
      ansible_host: 192.168.1.10
    pi-agent1:
      ansible_host: 192.168.1.20
    pi-agent2:
      ansible_host: 192.168.1.21

  vars:
    ansible_user: pi
    k3s_version: v1.31.12+k3s1
    token: "my-token"
    api_endpoint: 192.168.1.10
```

--------------------------------

### Variable Precedence Example

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/variables-quick-reference.md

Demonstrates how variables are overridden from global to host level, with command-line arguments having the highest priority.

```yaml
vars:
  extra_server_args: "--disable=traefik"

# Group override
server:
  vars:
    extra_server_args: "--disable=traefik,local-storage"

# Host override
server1:
  extra_server_args: "--disable=traefik,local-storage,servicelb"

# Command-line (highest priority)
# ansible-playbook site.yml -e "extra_server_args='--disable=all'"
```

--------------------------------

### K3s Installation Environment Variables

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/types.md

Define environment variables to customize the K3s installation process. These are used by the K3s installation script.

```yaml
extra_install_envs:
  INSTALL_K3S_EXEC: "--docker"              # Use Docker instead of containerd
  INSTALL_K3S_SKIP_SELINUX_RPM: "true"      # Skip SELinux RPM (RHEL/SUSE)
  INSTALL_K3S_SKIP_VALIDATION: "true"       # Skip validation checks
  INSTALL_K3S_SYMLINK: "skip"               # Don't create /usr/local/bin/k3s symlink
  INSTALL_K3S_CHANNEL: "latest"             # Use latest channel instead of version
  INSTALL_K3S_CHANNEL_URL: "https://update.k3s.io"  # Custom channel URL
  HTTP_PROXY: "http://proxy:3128"           # HTTP proxy
  HTTPS_PROXY: "http://proxy:3128"          # HTTPS proxy
  NO_PROXY: "localhost,127.0.0.1"           # No proxy for these hosts
  SSL_CERT_FILE: "/etc/ssl/certs/ca-bundle.crt"  # Custom CA certificate
```

--------------------------------

### Install k3s-ansible Collection

Source: https://github.com/k3s-io/k3s-ansible/blob/main/README.md

Install the k3s-ansible collection directly from GitHub using ansible-galaxy. This is the recommended method for integrating k3s-ansible into your Ansible projects.

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

--------------------------------

### NFTables Rules Example

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-prereq.md

This snippet shows example nftables rules generated by the role for inter-node communication, API access, etcd ports, CNI, cluster/service CIDRs, NodePort range, and established connections.

```nftables
insert rule inet filter input ip saddr 192.168.1.10 accept
insert rule inet filter input tcp dport 6443 accept
insert rule inet filter input tcp dport 2379-2381 accept
insert rule inet filter input tcp dport { 5001, 10250 } accept
insert rule inet filter input udp dport { 8472, 51820, 51821 } accept
insert rule inet filter input ip saddr 10.42.0.0/16 accept
insert rule inet filter input ip saddr 10.43.0.0/16 accept
insert rule inet filter input tcp dport 30000-32767 accept
insert rule inet filter input udp dport 30000-32767 accept
insert rule inet filter forward ct state established,related accept
insert rule inet filter forward accept
```

--------------------------------

### Set Additional Environment Variables for K3s Install

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/configuration.md

Use `extra_install_envs` to specify environment variables for the K3s install script. User values override defaults.

```yaml
vars:
  extra_install_envs:
    INSTALL_K3S_EXEC: "--docker"                # Alternative container runtime
    INSTALL_K3S_SKIP_SELINUX_RPM: "true"       # Skip SELinux RPM installation
    INSTALL_K3S_SKIP_VALIDATION: "true"        # Skip validation
    HTTP_PROXY: "http://proxy:3128"             # Proxy settings
```

--------------------------------

### Integer Values for Ports

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/types.md

Examples of using integer values for configuration parameters like API port and HTTPS listen port.

```yaml
api_port: 6443
https_listen_port: 6443
```

--------------------------------

### Conditional Package Installation for RHEL 10

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-prereq.md

Installs 'kernel-modules-extra' on RHEL 10 systems (excluding Oracle Linux) to load the 'br_netfilter' module. This is a system requirement for K3s.

```yaml
when:
  - ansible_facts['os_family'] == 'RedHat'
  - ansible_facts['distribution_major_version'] == "10"
  - ansible_facts['distribution'] != 'OracleLinux'
  # Install kernel-modules-extra (Red Hat 10 only)
```

--------------------------------

### YAML List Values Example (Flow)

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/variables-quick-reference.md

Defines a list of strings using the flow style, enclosed in square brackets.

```yaml
extra_service_envs: ['VAR1=value1', 'VAR2=value2']
```

--------------------------------

### K3s Server Configuration YAML Example

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-k3s-server.md

Use the `server_config_yaml` variable to provide inline YAML configuration for K3s server. This configuration is merged with automatically generated settings.

```yaml
server_config_yaml: |
  etcd-snapshot-retention: 10
  etcd-snapshot-schedule-cron: "0 */6 * * *"
  disable:
    - traefik
    - local-storage
  node-taint:
    - "node-role.kubernetes.io/control-plane=true:NoSchedule"
```

--------------------------------

### Conditional Package Installation for Oracle Linux 10

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-prereq.md

Installs 'kernel-uek-modules-extra' on Oracle Linux 10 systems. This ensures the necessary kernel modules for the UEK kernel are loaded.

```yaml
when:
  - ansible_facts['distribution'] == 'OracleLinux'
  - ansible_facts['distribution_major_version'] == "10"
  # Install kernel-uek-modules-extra
```

--------------------------------

### Detect HA Setup Based on Host Count

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/playbook-tags-and-conditionals.md

Use Jinja2 templating with `groups[group_name] | length` to determine the number of hosts in a group. This allows for conditional logic, such as differentiating between single-server and multi-server (HA) setups.

```yaml
# Multiple servers in inventory
when: (groups[server_group] | length) > 1
      and not use_external_database
```

--------------------------------

### K3s Agent Installation Script Execution Environment

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-k3s-agent.md

Specifies environment variables for the K3s installation script when deploying an agent. This includes controlling download behavior, setting the systemd directory, specifying the K3s version, and defining agent connection parameters.

```bash
INSTALL_K3S_SKIP_DOWNLOAD: "{{ skip_download | default('true') }}"
INSTALL_K3S_SKIP_START: "true"
INSTALL_K3S_SYSTEMD_DIR: "{{ systemd_dir }}"
INSTALL_K3S_VERSION: "{{ k3s_version }}"
INSTALL_K3S_EXEC: "agent --server https://{{ api_endpoint }}:{{ api_port }} {{ extra_agent_args }}"
K3S_TOKEN: "{{ token }}"
```

--------------------------------

### YAML Dictionary Values Example (Flow)

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/variables-quick-reference.md

Defines a dictionary with key-value pairs using the flow style, enclosed in curly braces.

```yaml
extra_install_envs: {INSTALL_K3S_EXEC: "--docker", HTTP_PROXY: "http://proxy:3128"}
```

--------------------------------

### YAML Literal Block Scalar Example

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/variables-quick-reference.md

Shows how to define multi-line configurations using the literal block scalar style, which preserves newlines.

```yaml
server_config_yaml: |
  disable:
    - traefik
  kubelet-arg:
    - "max-pods=250"
```

--------------------------------

### YAML List Values Example (Literal)

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/variables-quick-reference.md

Defines a list of strings using the literal block style, with each item on a new line.

```yaml
extra_service_envs:
  - 'VAR1=value1'
  - 'VAR2=value2'
```

--------------------------------

### Inventory Structure Example

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/playbooks.md

This YAML snippet illustrates the expected inventory structure for k3s-ansible, defining `k3s_cluster`, `server`, and `agent` groups.

```yaml
k3s_cluster:
  children:
    server:        # Control plane nodes
      hosts:
        node1:
    agent:         # Worker nodes
      hosts:
        node2:
        node3:
```

--------------------------------

### Example Variable Scope Hierarchy

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/variables-quick-reference.md

Illustrates the precedence of variable definitions in Ansible, from highest to lowest.

```yaml
all:
  vars:
    group_var: "group"
  children:
    group1:
      vars:
        group_var: "group1"
      hosts:
        host1:
          vars:
            host_var: "host1"
            group_var: "host1"

# Precedence:
# 1. Command-line (-e "var=value")
# 2. Host-specific (inventory)
# 3. Group-specific (inventory)
# 4. Global (inventory vars)
# 5. Role defaults
```

--------------------------------

### Install/Upgrade K3s Agent

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-k3s-upgrade.md

This command is used to install or upgrade K3s agents. It ensures arguments and environment variables are reconfigured, even if the version has not changed.

```bash
/usr/local/bin/k3s-install.sh

Environment:
  INSTALL_K3S_SKIP_DOWNLOAD: {{ (airgap or no version change) ? true : false }}
  INSTALL_K3S_SKIP_START: "true"
  INSTALL_K3S_VERSION: {{ k3s_version }}
  INSTALL_K3S_EXEC: "agent --server https://{{ api_endpoint }}:{{ api_port }} {{ extra_agent_args }}"
  K3S_TOKEN: {{ token }}
```

--------------------------------

### Valid K3s Version Formats

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/types.md

Examples of valid semantic versioning formats for K3s, including release, latest, and patch versions.

```yaml
# Valid Examples:
- "v1.31.12+k3s1" - Release build
- "v1.31.0+k3s1" - Latest v1.31
- "v1.30.5+k3s1" - Patch release
- "v1.29.10+k3s1" - Older version
```

--------------------------------

### YAML Dictionary Values Example (Literal)

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/variables-quick-reference.md

Defines a dictionary with key-value pairs using the literal block style.

```yaml
extra_install_envs:
  INSTALL_K3S_EXEC: "--docker"
  HTTP_PROXY: "http://proxy:3128"
```

--------------------------------

### K3s Version Detection Command

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-k3s-upgrade.md

Shows the bash command used to detect the currently installed K3s version on a node. The output is parsed to extract the version string.

```bash
$ k3s --version
k3s version v1.31.0+k3s1 (hash)

# Extracted: v1.31.0+k3s1
```

--------------------------------

### Confirm Cluster Access with Kubectl

Source: https://github.com/k3s-io/k3s-ansible/blob/main/README.md

Commands to confirm access to the Kubernetes cluster using kubectl after installation. Sets the context to 'k3s-ansible' and lists nodes.

```bash
kubectl config use-context k3s-ansible
kubectl get nodes
```

--------------------------------

### Override K3s Version with Command-Line Variable

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/configuration.md

Demonstrates how to override variables during playbook execution using the `-e` flag. This example shows setting a specific K3s version, which takes precedence over inventory or role defaults.

```bash
# Command-line overrides all
ansible-playbook site.yml -i inventory.yml -e "k3s_version=v1.32.0+k3s1"
```

--------------------------------

### Copy Sample Inventory

Source: https://github.com/k3s-io/k3s-ansible/blob/main/README.md

Copy the sample inventory file to your working directory to begin configuring your cluster. This file serves as a template for defining your cluster's hosts and groups.

```bash
cp inventory-sample.yml inventory.yml
```

--------------------------------

### Initial Airgap Deployment Playbook Execution

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-airgap.md

Execute the Ansible playbook for an initial airgap deployment after setting up the inventory.

```bash
cd playbooks
ls ./my-airgap/
# k3s  k3s-install.sh  k3s-airgap-images-amd64.tar.gz

ansible-playbook site.yml -i inventory.yml
# prereq → airgap → k3s_server → k3s_agent
```

--------------------------------

### Import Playbook (ansible-galaxy install)

Source: https://github.com/k3s-io/k3s-ansible/blob/main/README.md

Import the K3s cluster playbook into your existing Ansible project when k3s-ansible is installed via ansible-galaxy. This allows for programmatic inclusion.

```yaml
- name: Import kube cluster playbook
  ansible.builtin.import_playbook: k3s.orchestration.site
```

--------------------------------

### K3s Version Comparison Logic

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/types.md

Demonstrates how version comparison is performed using semantic versioning logic in YAML.

```yaml
# Version comparison uses semantic versioning
k3s_upgrade_current_version is version(k3s_version, '<')
# Compares: "v1.30.0+k3s1" < "v1.31.0+k3s1" = true
```

--------------------------------

### Set Airgap Directory for K3s Installation

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/configuration.md

Specify the path to the directory containing K3s artifacts for air-gapped installations. This variable triggers the airgap role to distribute the necessary files.

```yaml
vars:
  airgap_dir: ./playbooks/my-airgap
```

--------------------------------

### Conditional Task Execution for HA Setup

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/playbook-tags-and-conditionals.md

Assign specific roles to hosts within an HA setup using `inventory_hostname` and `groups`. This ensures that the first server initializes the cluster, while subsequent servers join it.

```yaml
# For HA embedded etcd setup
block:
  - name: First server initialization
    when: inventory_hostname == groups[server_group][0] 
          or ansible_host == groups[server_group][0]
    # First server specific tasks

  - name: Other servers join cluster
    when: inventory_hostname != groups[server_group][0]
          and ansible_host != groups[server_group][0]
    # Join tasks
```

--------------------------------

### Mixed Architecture Cluster Configuration

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-airgap.md

Structure the airgap directory to include K3s binaries and image tarballs for multiple architectures.

```bash
airgap_dir/
├── k3s-amd64      # x86_64 servers
├── k3s-arm64      # ARM64 agents (Raspberry Pi 4)
├── k3s-airgap-images-amd64.tar.gz
└── k3s-airgap-images-arm64.tar.gz
```

--------------------------------

### Separate Environments with Inventory Files

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/configuration.md

Organize your K3s deployments by maintaining separate inventory files for different environments like production, staging, and development.

```directory
inventories/
├── production.yml
├── staging.yml
└── dev.yml
```

--------------------------------

### Kubelet Arguments Configuration

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/types.md

Configure various kubelet arguments as an array of strings. Each item in the array is a single argument.

```yaml
kubelet-arg:
  - "max-pods=250"
  - "system-reserved=cpu=100m,memory=100Mi"
  - "eviction-hard=nodefs.available<10%,nodefs.inodesFree<5%"
  - "feature-gates=GracefulNodeShutdown=true,SidecarContainers=true"
  - "pod-manifest-path=/etc/kubernetes/manifests"
  - "read-only-port=10255"
  - "kubeconfig=/etc/rancher/k3s/k3s.yaml"
```

--------------------------------

### Include OS-Specific Tasks

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-raspberrypi.md

This task dynamically includes OS-specific prerequisite YAML files based on the detected distribution. It uses `with_first_found` to try a list of potential file paths, falling back to `default.yml` if none match.

```yaml
- name: Execute OS related tasks on the Raspberry Pi
  ansible.builtin.include_tasks: "{{ item }}"
  with_first_found:
    - "prereq/{{ detected_distribution }}.yml"
    - "prereq/{{ ansible_facts['distribution'] }}-{{ ansible_facts['distribution_major_version'] }}.yml"
    - "prereq/{{ ansible_facts['distribution'] }}.yml"
    - "prereq/default.yml"
```

--------------------------------

### No Value Node Taints

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/types.md

Example of configuring node taints without a specific value, only key and effect.

```yaml
node-taints:
  - "dedicated:NoSchedule"        # No value, just key:Effect
```

--------------------------------

### Troubleshooting: Detect Raspberry Pi Hardware

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-raspberrypi.md

Commands to verify if the current system is recognized as a Raspberry Pi by checking `/proc/cpuinfo` and `/proc/device-tree/model`.

```bash
# On Raspberry Pi:
grep "Raspberry Pi\|BCM2708\|BCM2709\|BCM2835\|BCM2836" /proc/cpuinfo

cat /proc/device-tree/model  # Check this too
```

--------------------------------

### K3s Agent Role Base Variables

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/types.md

Base environment variables automatically set by the k3s_agent role during installation.

```yaml
INSTALL_K3S_SKIP_DOWNLOAD: "true" or "false"
INSTALL_K3S_SKIP_START: "true"
INSTALL_K3S_SYSTEMD_DIR: "{{ systemd_dir }}"
INSTALL_K3S_VERSION: "{{ k3s_version }}"
INSTALL_K3S_EXEC: "agent --server https://{{ api_endpoint }}:{{ api_port }} {{ extra_agent_args }}"
```

--------------------------------

### K3s Server Role Base Variables

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/types.md

Base environment variables automatically set by the k3s_server role during installation.

```yaml
INSTALL_K3S_SKIP_DOWNLOAD: "true" or "false"
INSTALL_K3S_SKIP_START: "true"
INSTALL_K3S_VERSION: "{{ k3s_version }}"
INSTALL_K3S_EXEC: "{{ extra_server_args }}"
```

--------------------------------

### Copy SELinux Policy RPMs for Airgap

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-airgap.md

Copies the SELinux policy RPMs to the airgap directory. Ensure these packages are downloaded from the specified GitHub releases and your distribution's repositories before running this command.

```bash
cp selinux-policy-*.rpm airgap_dir/
cp container-selinux-*.rpm airgap_dir/
cp k3s-selinux-*.rpm airgap_dir/
```

--------------------------------

### Invalid K3s Version Formats

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/types.md

Examples of invalid K3s version formats that do not adhere to semantic versioning rules.

```yaml
# Invalid Examples:
- "1.31.12+k3s1" - Missing `v` prefix
- "v1.31.12" - Missing `+k3s` suffix
- "latest" - Not a specific version (use INSTALL_K3S_CHANNEL instead)
```

--------------------------------

### Integer Values for Retention and Limits

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/types.md

Illustrates using integer values for settings such as etcd snapshot retention and kubelet maximum pods.

```yaml
server_config_yaml: |
  etcd-snapshot-retention: 10           # integer
  max-pods: 250                         # in kubelet-arg
```

--------------------------------

### Use External Database with Extra Server Arguments

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/configuration.md

Configure `use_external_database` and provide the datastore endpoint via `extra_server_args` for external database connections.

```yaml
vars:
  use_external_database: true
  extra_server_args: "--datastore-endpoint=postgres://user:pass@host:5432/db"
```

--------------------------------

### Role Integration in site.yml

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-raspberrypi.md

Demonstrates how the `raspberrypi` role is integrated into the overall Ansible playbook structure, showing its position relative to other roles like `prereq` and `airgap`.

```yaml
- name: Cluster prep
  hosts: k3s_cluster
  gather_facts: true
  become: true
  roles:
    - role: prereq
    - role: airgap
    - role: raspberrypi
```

--------------------------------

### Create Ansible Inventory File

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/README.md

Create and configure the inventory file for your K3s cluster deployment. This includes defining server and agent nodes, along with essential variables like Ansible user, K3s version, token, and API endpoint.

```bash
cp inventory-sample.yml inventory.yml
```

```yaml
k3s_cluster:
  children:
    server:
      hosts:
        server1:
          ansible_host: 192.168.1.10
    agent:
      hosts:
        agent1:
          ansible_host: 192.168.1.20

  vars:
    ansible_user: debian
    k3s_version: v1.31.12+k3s1
    token: "my-token"
    api_endpoint: "192.168.1.10"
```

--------------------------------

### Troubleshooting: Check Bootloader Script

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-raspberrypi.md

Command to verify the existence of the `/boot/mkscr` script, which is used for regenerating the bootloader image on some Raspberry Pi models.

```bash
ls -la /boot/mkscr
```

--------------------------------

### Deploy K3s Cluster (Galaxy)

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/playbooks.md

Use this command to deploy a K3s cluster using the k3s-ansible playbooks installed via Ansible Galaxy.

```bash
ansible-playbook k3s.orchestration.site -i inventory.yml
```

--------------------------------

### Boolean Values in YAML

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/types.md

Demonstrates how to set boolean values in YAML configuration files. Common true/false variants are accepted.

```yaml
use_external_database: true
user_kubectl: false
disable-network-policy: true
```

--------------------------------

### Conditional Execution on First Server Node

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/playbook-tags-and-conditionals.md

This task is designed to run only on the first server node in a high-availability setup, typically for initialization tasks.

```yaml
- name: Init first server node
  when: inventory_hostname == groups[server_group][0] or ansible_host == groups[server_group][0]
  # Only runs on first server
```

--------------------------------

### YAML Folded Block Scalar Example

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/variables-quick-reference.md

Illustrates the folded block scalar style for defining long strings, where newlines are folded into spaces.

```yaml
long_string: >
  This is a very long string that can
  be spread across multiple lines
```

--------------------------------

### Verify k3s-ansible Configuration

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/README.md

Use these commands to inspect your Ansible inventory and gather facts about all hosts in your deployment. Ensure your inventory file is correctly structured and accessible.

```bash
ansible-inventory -i inventory.yml --list
ansible all -i inventory.yml -m setup
```

--------------------------------

### Run Task Once Across All Hosts

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/playbook-tags-and-conditionals.md

Employ `run_once: true` to ensure a task executes only one time, regardless of the number of hosts in the play. This is ideal for tasks that should be performed globally, like setting up a central service.

```yaml
# Run once across all hosts
- name: Wait for control plane
  ansible.builtin.wait_for:
    host: "{{ api_endpoint }}"
    port: "{{ api_port }}"
  run_once: true
```

--------------------------------

### Document Custom Arguments in Inventory

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/configuration.md

Document custom arguments for K3s servers directly within inventory comments to explain specific configurations, such as disabling the local storage provisioner.

```yaml
# Disables local storage provisioner - using external NFS
extra_server_args: "--disable=local-storage"
```

--------------------------------

### Verify Airgap Image Contents

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-airgap.md

List the contents of the K3s airgap image tarball to verify included images.

```bash
tar -tzf k3s-airgap-images-amd64.tar.gz | head -20
```

--------------------------------

### Incorrect Kubelet Argument Format

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/types.md

Illustrates the incorrect way to format kubelet arguments, showing that arguments should not be split into separate array items.

```yaml
# WRONG:
kubelet-arg:
  - "max-pods"
  - "250"

# RIGHT:
kubelet-arg:
  - "max-pods=250"
```

--------------------------------

### Detect Raspberry Pi via /proc/cpuinfo

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-raspberrypi.md

This command checks the /proc/cpuinfo file for patterns indicating Raspberry Pi hardware. It's used as one of the methods for hardware detection within the role. The command is designed to not fail the playbook if no match is found.

```bash
grep -E "Raspberry Pi|BCM2708|BCM2709|BCM2835|BCM2836" /proc/cpuinfo
```

--------------------------------

### Version Comparison Logic in Ansible

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/role-k3s-upgrade.md

Demonstrates how the role uses Ansible's version filter to compare the current K3s version with the target version. This logic determines whether a full upgrade, configuration update, or skip is performed.

```yaml
k3s_upgrade_current_version is version(k3s_version, '<=')
```

--------------------------------

### Reboot K3s Cluster Nodes (Galaxy)

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/playbooks.md

Use this command to perform staggered reboots of cluster nodes with health verification, using playbooks installed via Ansible Galaxy.

```bash
ansible-playbook k3s.orchestration.reboot -i inventory.yml
```

--------------------------------

### Reset K3s Cluster (Galaxy)

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/playbooks.md

Use this command to uninstall K3s and revert cluster configuration using the k3s-ansible playbooks installed via Ansible Galaxy. This action is destructive.

```bash
ansible-playbook k3s.orchestration.reset -i inventory.yml
```

--------------------------------

### K3s-Ansible File Organization

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/INDEX.md

This snippet displays the directory structure of the k3s-ansible project, outlining the location of key documentation and configuration files.

```text
output/
├── README.md                                      # Main overview
├── INDEX.md                                       # This file
├── configuration.md                               # Configuration variables
├── variables-quick-reference.md                   # Compact variable tables
├── types.md                                       # YAML structure definitions
├── playbook-tags-and-conditionals.md             # Tags and execution logic
└── api-reference/
    ├── playbooks.md                              # Playbook documentation
    ├── role-k3s-server.md                        # Server role
    ├── role-k3s-agent.md                         # Agent role
    ├── role-k3s-upgrade.md                       # Upgrade role
    ├── role-prereq.md                            # Prerequisites role
    ├── role-airgap.md                            # Airgap role
    └── role-raspberrypi.md                       # Raspberry Pi role
```

--------------------------------

### Proxy Environment Variables Configuration

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/variables-quick-reference.md

Configure HTTP, HTTPS, and NO_PROXY environment variables for K3s installation and service execution. These settings are crucial for deployments within restricted network environments.

```yaml
vars:
  k3s_version: v1.31.12+k3s1
  api_endpoint: 192.168.1.10
  extra_install_envs:
    HTTP_PROXY: "http://proxy.local:3128"
    HTTPS_PROXY: "http://proxy.local:3128"
    NO_PROXY: "localhost,127.0.0.1,.local"
  extra_service_envs:
    - 'HTTP_PROXY=http://proxy.local:3128'
    - 'HTTPS_PROXY=http://proxy.local:3128'
    - 'NO_PROXY=localhost,127.0.0.1,.local'
```

--------------------------------

### Upgrade K3s Cluster (Galaxy)

Source: https://github.com/k3s-io/k3s-ansible/blob/main/_autodocs/api-reference/playbooks.md

Use this command to upgrade an existing K3s cluster using the k3s-ansible playbooks installed via Ansible Galaxy. Ensure `k3s_version` is set in your inventory.

```bash
ansible-playbook k3s.orchestration.upgrade -i inventory.yml
```