# k3s-io/k3s-ansible architecture

> Architecture diagram of the GitHub repository k3s-io/k3s-ansible, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/k3s-io/k3s-ansible
- Repository: https://github.com/k3s-io/k3s-ansible

## Overview

This Ansible collection provisions and upgrades K3s clusters from an operator-supplied inventory. Its documented workflow invokes the site playbook, which installs K3s on managed hosts and can retrieve kubeconfig; separate capabilities include airgap deployment, server/agent roles, and upgrades. No source excerpts were provided, so role-to-playbook wiring is omitted; edges show only relationships stated in the README.

Main entry points: [`playbooks/site.yml`](https://github.com/k3s-io/k3s-ansible/blob/main/playbooks/site.yml) (Site playbook), [`inventory-sample.yml`](https://github.com/k3s-io/k3s-ansible/blob/main/inventory-sample.yml) (Cluster inventory), [`roles/airgap/tasks/main.yml`](https://github.com/k3s-io/k3s-ansible/blob/main/roles/airgap/tasks/main.yml) (Airgap preparation), [`playbooks/upgrade.yml`](https://github.com/k3s-io/k3s-ansible/blob/main/playbooks/upgrade.yml) (Upgrade playbook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Provisioning entrypoints"]
  node_inventory["Cluster inventory"]
  node_site["Site playbook<br/>[site.yml]"]
end

subgraph group_install["Cluster installation"]
  node_server["K3s server role<br/>[main.yml]"]
  node_agent["K3s agent role<br/>[main.yml]"]
  node_prereq["Host prerequisites<br/>[main.yml]"]
  node_raspberrypi["Raspberry Pi setup<br/>[main.yml]"]
  node_airgap["Airgap preparation<br/>[main.yml]"]
end

subgraph group_operations["Cluster operations"]
  node_upgrade["Upgrade playbook<br/>[upgrade.yml]"]
  node_upgrade_role["K3s upgrade role<br/>[main.yml]"]
  node_kubeconfig["Kubeconfig output"]
end

node_operator(("Operator"))
node_managed["Managed hosts"]
node_cluster["K3s cluster"]
node_external_db[("External database")]

node_operator -->|"runs"| node_site
node_operator -->|"configures"| node_inventory
node_inventory -->|"configures"| node_site
node_site -->|"provisions"| node_managed
node_site -->|"brings up"| node_cluster
node_site -->|"copies"| node_kubeconfig
node_operator -->|"runs"| node_upgrade
node_upgrade -->|"upgrades"| node_cluster
node_operator -->|"runs"| node_airgap
node_airgap -->|"prepares"| node_managed
node_cluster -.->|"uses optionally"| node_external_db

click node_inventory "https://github.com/k3s-io/k3s-ansible/blob/main/inventory-sample.yml"
click node_site "https://github.com/k3s-io/k3s-ansible/blob/main/playbooks/site.yml"
click node_server "https://github.com/k3s-io/k3s-ansible/blob/main/roles/k3s_server/tasks/main.yml"
click node_agent "https://github.com/k3s-io/k3s-ansible/blob/main/roles/k3s_agent/tasks/main.yml"
click node_prereq "https://github.com/k3s-io/k3s-ansible/blob/main/roles/prereq/tasks/main.yml"
click node_raspberrypi "https://github.com/k3s-io/k3s-ansible/blob/main/roles/raspberrypi/tasks/main.yml"
click node_airgap "https://github.com/k3s-io/k3s-ansible/blob/main/roles/airgap/tasks/main.yml"
click node_upgrade "https://github.com/k3s-io/k3s-ansible/blob/main/playbooks/upgrade.yml"
click node_upgrade_role "https://github.com/k3s-io/k3s-ansible/blob/main/roles/k3s_upgrade/tasks/main.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_inventory,node_site toneBlue
class node_server,node_agent,node_prereq,node_raspberrypi,node_airgap,node_external_db toneAmber
class node_upgrade,node_upgrade_role,node_kubeconfig toneMint
class node_operator,node_managed,node_cluster toneIndigo
```

## Components

### Provisioning entrypoints

- [Cluster inventory](https://github.com/k3s-io/k3s-ansible/blob/main/inventory-sample.yml): `inventory-sample.yml`
- [Site playbook](https://github.com/k3s-io/k3s-ansible/blob/main/playbooks/site.yml): `playbooks/site.yml`

### Cluster installation

- [K3s server role](https://github.com/k3s-io/k3s-ansible/blob/main/roles/k3s_server/tasks/main.yml): `roles/k3s_server/tasks/main.yml`
- [K3s agent role](https://github.com/k3s-io/k3s-ansible/blob/main/roles/k3s_agent/tasks/main.yml): `roles/k3s_agent/tasks/main.yml`
- [Host prerequisites](https://github.com/k3s-io/k3s-ansible/blob/main/roles/prereq/tasks/main.yml): `roles/prereq/tasks/main.yml`
- [Raspberry Pi setup](https://github.com/k3s-io/k3s-ansible/blob/main/roles/raspberrypi/tasks/main.yml): `roles/raspberrypi/tasks/main.yml`
- [Airgap preparation](https://github.com/k3s-io/k3s-ansible/blob/main/roles/airgap/tasks/main.yml): `roles/airgap/tasks/main.yml`

### Cluster operations

- [Upgrade playbook](https://github.com/k3s-io/k3s-ansible/blob/main/playbooks/upgrade.yml): `playbooks/upgrade.yml`
- [K3s upgrade role](https://github.com/k3s-io/k3s-ansible/blob/main/roles/k3s_upgrade/tasks/main.yml): `roles/k3s_upgrade/tasks/main.yml`
- **Kubeconfig output**

### Other components

- **Operator**
- **Managed hosts**
- **K3s cluster**
- **External database**

## Connections

- Operator → Site playbook: runs (evidence: `README.md`)
- Operator → Cluster inventory: configures (evidence: `README.md`)
- Cluster inventory → Site playbook: configures (evidence: `README.md`)
- Site playbook → Managed hosts: provisions (evidence: `README.md`)
- Site playbook → K3s cluster: brings up (evidence: `README.md`)
- Site playbook → Kubeconfig output: copies (evidence: `README.md`)
- Operator → Upgrade playbook: runs (evidence: `README.md`)
- Upgrade playbook → K3s cluster: upgrades (evidence: `README.md`)
- Operator → Airgap preparation: runs (evidence: `README.md`)
- Airgap preparation → Managed hosts: prepares (evidence: `README.md`)
- K3s cluster → External database: uses optionally (evidence: `README.md`)
