---
paths:
  - "ansible/**"
  - "incusos/deploy-awx"
  - "incusos/awx-manifests/*"
  - "notes/awx-guide.md"
---

# AWX Integration (Ansible for Aether)

## Overview

- AWX: open-source Ansible platform. Debian 12 VM with K3s + AWX Operator.
- Lab VM: `awx` on oc-node-02, IP 192.168.102.161/22 (VLAN 69).
- **AWX URL**: `http://192.168.102.161:30080` (K3s NodePort, not Traefik ingress).
- `deploy-awx` script: `--deploy`, `--status`, `--heal`, `--configure`,
  `--join-aether`, `--cleanup`, `--doctor`.

## Live job output

Capture AWX job output while running (don't just poll status):
```bash
curl -sk http://192.168.102.161:30080/api/v2/jobs/{JOB_ID}/stdout/?format=txt \
  -H "Authorization: Bearer $AWX_TOKEN"
```

## Aether extra vars

Aether passes `ffsdn_` prefixed vars: `ffsdn_instance_name`, `ffsdn_instance_ip`,
`ffsdn_cluster_id`, `ffsdn_cluster_name`, `ffsdn_deployed_by`, `ffsdn_image_os`,
`ffsdn_image_release`, `ffsdn_image_alias`.

It does NOT pass: `vm_name`, `vm_ip`, `environment`, `owner`, `cost_center`.

## Playbook pattern: Incus REST API, not SSH

- AWX cannot SSH to containers on incusbr0 (not routable, nftables blocks).
- Use `uri` module with client cert for file push + exec.
- Cert at `/runner/project/incus-client.crt` (EE mounts at `/runner/project/`,
  NOT `/var/lib/awx/projects/`).

## Manual project (local_path)

- EE containers can't reach private git repo.
- Use `scm_type: ""`, `local_path: "incus-contrib"`.
- Push playbooks to AWX task pod at `/var/lib/awx/projects/incus-contrib/playbooks/`.

## Gotchas

- **Self-referencing vars**: `vm_ip: "{{ vm_ip | default('') }}"` causes
  infinite recursion. Use `ffsdn_*` vars directly.
- **`environment` is reserved**: resolves to `[]` as extra var.
- **AWX config API bug**: `PUT /api/clusters/{id}/awx-config` returns
  "Invalid cluster ID" (v6.4.317). Use the Aether UI instead (cluster
  Settings tab or per-blueprint AWX template IDs).
- **Lifecycle hooks**: post-deploy failure -> auto-rollback (instance deleted).
  Decommission failure does NOT block deletion.