# kazauwa/ansible-role-headscale architecture

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

- Interactive diagram: https://gitdiagram.com/kazauwa/ansible-role-headscale
- Repository: https://github.com/kazauwa/ansible-role-headscale

## Overview

This Ansible role installs and manages Headscale on Linux: an operator applies the role, which installs the selected binary, configures Headscale, and can enable advertised routes and exit nodes. The README also documents user creation, ACL configuration, and service-account and path settings. Source excerpts were unavailable, so links among task files and service actions reflect documented role behavior, not inspected task implementations.

Main entry points: [`tasks/configure.yml`](https://github.com/kazauwa/ansible-role-headscale/blob/main/tasks/configure.yml) (Configure Headscale), [`tasks/main.yml`](https://github.com/kazauwa/ansible-role-headscale/blob/main/tasks/main.yml) (Role entry tasks), [`tasks/install.yml`](https://github.com/kazauwa/ansible-role-headscale/blob/main/tasks/install.yml) (Install Headscale), [`defaults/main.yml`](https://github.com/kazauwa/ansible-role-headscale/blob/main/defaults/main.yml) (Role defaults)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Role orchestration"]
  node_role_main["Role entry tasks<br/>[main.yml]"]
  node_defaults["Role defaults<br/>[main.yml]"]
end

subgraph group_host_setup["Host setup"]
  node_install["Install Headscale<br/>[install.yml]"]
end

subgraph group_headscale_config["Headscale configuration"]
  node_configure["Configure Headscale<br/>[configure.yml]"]
  node_routes["Enable routes<br/>[enable_routes.yml]"]
end

subgraph group_service["Service management"]
  node_systemd_template["Systemd unit template"]
  node_handlers["Service handlers<br/>[main.yml]"]
end

node_operator(("Ansible operator"))
node_release["Headscale releases"]
node_linux_host["Linux host"]
node_headscale_service["Headscale service"]
node_headscale_config_file["Headscale configuration"]
node_acl_file["ACL file"]

node_operator -->|"applies role"| node_role_main
node_role_main -->|"runs tasks"| node_install
node_role_main -->|"runs tasks"| node_configure
node_role_main -->|"runs tasks"| node_routes
node_defaults -->|"provides settings"| node_install
node_defaults -->|"provides settings"| node_configure
node_defaults -->|"provides settings"| node_routes
node_install -->|"downloads version"| node_release
node_install -->|"installs binary"| node_linux_host
node_configure -->|"configures host"| node_linux_host
node_configure -->|"writes config"| node_headscale_config_file
node_configure -->|"sets ACL path"| node_acl_file
node_configure -->|"uses template"| node_systemd_template
node_systemd_template -->|"defines service"| node_linux_host
node_handlers -->|"manages service"| node_headscale_service
node_routes -->|"enables routes"| node_headscale_service
node_headscale_service -->|"reads config"| node_headscale_config_file
node_headscale_service -->|"reads ACL"| node_acl_file

click node_role_main "https://github.com/kazauwa/ansible-role-headscale/blob/main/tasks/main.yml"
click node_defaults "https://github.com/kazauwa/ansible-role-headscale/blob/main/defaults/main.yml"
click node_install "https://github.com/kazauwa/ansible-role-headscale/blob/main/tasks/install.yml"
click node_configure "https://github.com/kazauwa/ansible-role-headscale/blob/main/tasks/configure.yml"
click node_routes "https://github.com/kazauwa/ansible-role-headscale/blob/main/tasks/enable_routes.yml"
click node_systemd_template "https://github.com/kazauwa/ansible-role-headscale/blob/main/templates/etc/systemd/system/headscale.service.j2"
click node_handlers "https://github.com/kazauwa/ansible-role-headscale/blob/main/handlers/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_role_main,node_defaults toneBlue
class node_install toneAmber
class node_configure,node_routes toneMint
class node_systemd_template,node_handlers toneRose
class node_operator,node_release,node_linux_host,node_headscale_service,node_headscale_config_file,node_acl_file toneIndigo
```

## Components

### Role orchestration

- [Role entry tasks](https://github.com/kazauwa/ansible-role-headscale/blob/main/tasks/main.yml): `tasks/main.yml`
- [Role defaults](https://github.com/kazauwa/ansible-role-headscale/blob/main/defaults/main.yml): `defaults/main.yml`

### Host setup

- [Install Headscale](https://github.com/kazauwa/ansible-role-headscale/blob/main/tasks/install.yml): `tasks/install.yml`

### Headscale configuration

- [Configure Headscale](https://github.com/kazauwa/ansible-role-headscale/blob/main/tasks/configure.yml): `tasks/configure.yml`
- [Enable routes](https://github.com/kazauwa/ansible-role-headscale/blob/main/tasks/enable_routes.yml): `tasks/enable_routes.yml`

### Service management

- [Systemd unit template](https://github.com/kazauwa/ansible-role-headscale/blob/main/templates/etc/systemd/system/headscale.service.j2): `templates/etc/systemd/system/headscale.service.j2`
- [Service handlers](https://github.com/kazauwa/ansible-role-headscale/blob/main/handlers/main.yml): `handlers/main.yml`

### Other components

- **Ansible operator**
- **Headscale releases**
- **Linux host**
- **Headscale service**
- **Headscale configuration**
- **ACL file**

## Connections

- Ansible operator → Role entry tasks: applies role
- Role entry tasks → Install Headscale: runs tasks
- Role entry tasks → Configure Headscale: runs tasks
- Role entry tasks → Enable routes: runs tasks
- Role defaults → Install Headscale: provides settings
- Role defaults → Configure Headscale: provides settings
- Role defaults → Enable routes: provides settings
- Install Headscale → Headscale releases: downloads version
- Install Headscale → Linux host: installs binary
- Configure Headscale → Linux host: configures host
- Configure Headscale → Headscale configuration: writes config
- Configure Headscale → ACL file: sets ACL path
- Configure Headscale → Systemd unit template: uses template
- Systemd unit template → Linux host: defines service
- Service handlers → Headscale service: manages service
- Enable routes → Headscale service: enables routes
- Headscale service → Headscale configuration: reads config
- Headscale service → ACL file: reads ACL