# Ansible Configuration

This directory contains Ansible configuration for fleet management tasks.

## Structure

```
ansible/
├── ansible.cfg              # Ansible configuration
├── inventory/
│   ├── dynamic_flake.py     # Dynamic inventory from NixOS flake
│   ├── static.yml           # Non-flake hosts (Proxmox, etc.)
│   └── group_vars/
│       └── all.yml          # Common variables
└── playbooks/
    ├── build-and-deploy-template.yml
    ├── provision-approle.yml
    ├── restart-service.yml
    └── run-upgrade.yml
```

## Usage

The devshell automatically configures `ANSIBLE_CONFIG`, so commands work without extra flags:

```bash
# List inventory groups
nix develop -c ansible-inventory --graph

# List hosts in a specific group
nix develop -c ansible-inventory --list | jq '.role_dns'

# Run a playbook
nix develop -c ansible-playbook ansible/playbooks/run-upgrade.yml -l tier_test
```

## Inventory

The inventory combines dynamic and static sources automatically.

### Dynamic Inventory (from flake)

The `dynamic_flake.py` script extracts hosts from the NixOS flake using `homelab.host.*` options:

**Groups generated:**
- `flake_hosts` - All NixOS hosts from the flake
- `tier_test`, `tier_prod` - By `homelab.host.tier`
- `role_dns`, `role_vault`, `role_monitoring`, etc. - By `homelab.host.role`

**Host variables set:**
- `tier` - Deployment tier (test/prod)
- `role` - Host role
- `short_hostname` - Hostname without domain

### Static Inventory

Non-flake hosts are defined in `inventory/static.yml`:

- `proxmox` - Proxmox hypervisors

## Playbooks

| Playbook | Description | Example |
|----------|-------------|---------|
| `run-upgrade.yml` | Trigger nixos-upgrade on hosts | `-l tier_prod` |
| `restart-service.yml` | Restart a systemd service | `-l role_dns -e service=unbound` |
| `reboot.yml` | Rolling reboot (one host at a time) | `-l tier_test` |
| `provision-approle.yml` | Deploy Vault credentials (single host only) | `-l testvm01` |
| `build-and-deploy-template.yml` | Build and deploy Proxmox template | (no limit needed) |

### Examples

```bash
# Restart unbound on all DNS servers
nix develop -c ansible-playbook ansible/playbooks/restart-service.yml \
  -l role_dns -e service=unbound

# Trigger upgrade on all test hosts
nix develop -c ansible-playbook ansible/playbooks/run-upgrade.yml -l tier_test

# Provision Vault credentials for a specific host
nix develop -c ansible-playbook ansible/playbooks/provision-approle.yml -l testvm01

# Build and deploy Proxmox template
nix develop -c ansible-playbook ansible/playbooks/build-and-deploy-template.yml

# Rolling reboot of test hosts (one at a time, waits for each to come back)
nix develop -c ansible-playbook ansible/playbooks/reboot.yml -l tier_test
```

## Excluding Flake Hosts

To exclude a flake host from the dynamic inventory, add the `ansible = "false"` label in the host's configuration:

```nix
homelab.host.labels.ansible = "false";
```

Hosts with `homelab.dns.enable = false` are also excluded automatically.

## Adding Non-Flake Hosts

Edit `inventory/static.yml` to add hosts not managed by the NixOS flake:

```yaml
all:
  children:
    my_group:
      hosts:
        host1.example.com:
          ansible_user: admin
```

## Common Variables

Variables in `inventory/group_vars/all.yml` apply to all hosts:

- `ansible_user` - Default SSH user (root)
- `domain` - Domain name (home.2rjus.net)
- `vault_addr` - Vault server URL