maarten
/
incus-contrib
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
incus-contrib/CLAUDE.md

7.2 KiB
Raw Blame History

CLAUDE.md - Project context for AI assistants

What this repository is

A collection of peripheral tools, scripts, and snippets for working with Incus, IncusOS, and the broader ecosystem (Operations Center, Migration Manager). Primarily targeting home lab environments but aiming for production-quality scripts.

Repository structure

incus-contrib/
├── CLAUDE.md              # This file -- behavioral rules + project overview
├── .claude/rules/         # Topic-specific context (auto-loaded by paths:)
├── .claude/skills/        # Slash commands: /screenshot, /proxmox-api
├── README.md              # Main overview
├── .gitignore
├── ansible/               # Ansible playbooks for AWX/Aether lifecycle hooks
│   ├── ansible.cfg
│   └── playbooks/
│       ├── post-deploy.yml    # Runs after Aether creates an instance
│       └── decommission.yml   # Runs before Aether deletes an instance
├── incusos/               # IncusOS installation tooling
│   ├── README.md
│   ├── incusos-iso        # ISO/IMG builder (wraps flasher-tool)
│   ├── incusos-seed       # Seed archive generator (Linux + macOS)
│   ├── incusos-proxmox    # Declarative Proxmox VM deployment + lab lifecycle
│   ├── deploy-awx         # AWX deployment + management on Incus cluster
│   ├── awx-manifests/     # K8s manifests for AWX Operator + instance
│   ├── helpers/
│   │   ├── proxmox-screenshot  # VMID -> PNG console screenshot
│   │   └── proxmox-api         # Authenticated API calls (handles ! in token)
│   ├── lab-test           # Guided lab validation (12 test phases)
│   ├── observe-deploy     # Single-VM deploy with console screenshots
│   ├── proxmox.yaml       # Proxmox connection (gitignored)
│   ├── TESTING.md
│   └── examples/          # Example seed + Proxmox YAML files
├── env                    # PROXMOX_TOKEN_SECRET, PROXMOX_ROOT_PASSWORD, AETHER_ADMIN_PASSWORD (gitignored)
└── notes/                 # Reference guides (clustering, networking, OC, AWX, etc.)

Capabilities you have

Proxmox VM screenshots

Take console screenshots during deploys to see boot progress or errors:

incusos/helpers/proxmox-screenshot VMID [/tmp/output.png]

Use the Read tool on the PNG to view it. USE THIS PROACTIVELY during deploy scenarios to monitor boot progress, diagnose hangs, and verify installs.

Proxmox API calls

Make authenticated API calls (handles the ! in automation@pve!deploy):

incusos/helpers/proxmox-api GET /nodes/pve/qemu/900/status/current --json
incusos/helpers/proxmox-api GET /nodes/pve/status --json
incusos/helpers/proxmox-api POST /nodes/pve/qemu/900/status/stop

Aether API

Aether has a documented REST API at https://192.168.102.160:8443/api/.

  • Swagger UI: https://192.168.102.160:8443/api/docs
  • OpenAPI spec: https://192.168.102.160:8443/api/swagger.yaml
  • Auth: JWT via POST /api/auth/token with {"username":"...","password":"..."} Credentials in env file (AETHER_ADMIN_PASSWORD). Token valid 24h.
# Get JWT
TOKEN=$(curl -sk -X POST https://192.168.102.160:8443/api/auth/token \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"admin\",\"password\":\"$AETHER_ADMIN_PASSWORD\"}" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")

# Use it
curl -sk https://192.168.102.160:8443/api/clusters \
  -H "Authorization: Bearer $TOKEN"

Current API coverage (v6.4.317, API v1.0.0):

  • Authentication: POST /api/auth/token
  • Clusters: GET /api/clusters
  • Local ACLs: CRUD on /api/clusters/{id}/rules
  • Global ACLs: CRUD on /api/global/rules

Not yet in the API: AWX endpoints, deploys, blueprints, instance management, health checks. These are available through the web UI only. The API is actively being developed — check /api/swagger.yaml for new endpoints in future Aether versions.

Live AWX job output

Capture output while a job is running (don't just poll status):

curl -sk http://192.168.102.161:30080/api/v2/jobs/{JOB_ID}/stdout/?format=txt \
  -H "Authorization: Bearer $AWX_TOKEN"

Critical safety rules

  • Proxmox SSH is screenshots-only. Full rules in .claude/rules/proxmox-ssh-rules.md.
  • Never hard-stop VMs during first boot -- corrupts TPM permanently.
  • Boot timeout is 180s -- do not reduce (sysext download takes 30-120s).
  • No force_reboot in seeds for Proxmox -- causes crontab race condition.
  • VMID ranges: 400-499 (OC), 800-809 (single), 900-939 (clusters).

Interacting with external systems (Aether, AWX, Incus, etc.)

Strict priority order — follow this hierarchy in all guides, scripts, and automation flows:

  1. API first: if the system has a documented REST API, use it. Authenticate as a regular user (JWT, PAT), never as root / DB superuser.
  2. Web UI fallback: if the API doesn't cover a feature yet, document the UI steps (navigation path, form fields, expected result).
  3. Never use root / direct DB access in guides or automation. Poking around in containers, editing databases directly, or using incus exec into Aether is acceptable only for investigation and learning — never as the documented path for users to follow.

APIs improve over time. When a feature is UI-only today, note it and check /api/swagger.yaml (or equivalent) in future versions before assuming it's still UI-only. The API endpoint may have been added since the guide was written.

Coding conventions

  • Shell: bash with set -euo pipefail
  • Arithmetic: var=$((var + 1)) not ((var++)) (set -e safety)
  • Colors: support NO_COLOR=1 and TERM=dumb; use setup_colors() pattern
  • Flags: both short (-d) and long (--defaults)
  • Defaults: useful behavior with zero flags
  • Dry run: all scripts support --dry-run
  • Cert detection: files on disk first (~/.config/incus/client.crt), CLI second
  • Errors: include actionable remediation steps
  • No hardcoded package managers: say "install the Incus client" with a link

Technical context loading

Detailed technical context loads automatically from .claude/rules/ based on which files are being edited:

Rule file Loads when editing
incusos-scripts.md incusos-iso, incusos-seed, incusos-proxmox, helpers
proxmox-deployment.md incusos-proxmox, observe-deploy, helpers, examples
clustering.md lab-test, incusos-proxmox, clustering/production guides
operations-center.md OC guide, incusos-proxmox, OC example configs
networking-storage.md networking, storage, migration, UTM guides
awx-integration.md ansible/, deploy-awx, awx-manifests, AWX guide
proxmox-ssh-rules.md Always loaded (no paths filter)
lab-infrastructure.md incusos-proxmox, lab-test, examples

For deep reference, see the guides in notes/.

Git workflow

  • Main branch: master
  • Remotes:
    • origin: ssh://git@192.168.1.200:2222/maarten/incus-contrib.git (private Gitea)
    • aether: _gitea@code.sovereignprivatecloud.nl:maarten/incus-contrib.git
  • Push to both remotes when committing
  • Development happens on feature branches