# Runbook: Drift Detection

How to interpret and respond to drift detected by the CI pipeline or local script.

## What is drift?

**Terraform drift** — a Proxmox VM, DNS record, or Pi-hole entry exists in a different
state than what's declared in the Terraform workspace. Common causes:
- A VM was resized or reconfigured manually in the PVE web UI
- A DNS record was added directly via Dynu or Pi-hole admin
- A VM was deleted outside of Terraform

**Ansible drift** — a host's configuration differs from what the Ansible role declares.
Common causes:
- A config file was edited by hand on the host
- A package was installed/removed manually
- A service was stopped/disabled without updating the role

## CI workflow

The `drift-detect` workflow runs daily at 06:00 AEST. If drift is detected, a Gotify
notification is sent to the push notification dashboard. The step summary in Gitea CI
contains the full `terraform plan` diff.

## Responding to Terraform drift

```bash
# See exactly what changed
cd terraform/proxmox
terraform plan

# Option A: The manual change was intentional — update the .tf file to match reality,
# then run terraform apply to reconcile state
vim proxmox/docker.tf  # update the resource to match current state
terraform apply

# Option B: The manual change was accidental — apply to restore declared state
terraform apply  # will revert the manual change
```

## Responding to Ansible drift

```bash
# See exactly what would change
cd ansible
ansible-playbook playbooks/site.yml --check --diff --limit <drifted_host>

# Apply to restore declared state
ansible-playbook playbooks/site.yml --limit <drifted_host>
```

## Required Gitea secrets

The following secrets must be configured in the Gitea repo for CI drift detection to work:

| Secret | Used by |
|--------|---------|
| `PROXMOX_ENDPOINT` | Terraform proxmox workspace |
| `PROXMOX_API_TOKEN_ID` | Terraform proxmox workspace |
| `PROXMOX_API_TOKEN_SECRET` | Terraform proxmox workspace |
| `DYNU_API_KEY` | Terraform dns workspace |
| `ANSIBLE_SSH_KEY` | Ansible drift check |
| `GOTIFY_URL` | Drift notifications |
| `GOTIFY_TOKEN` | Drift notifications |