Skip to content

Guest discovery and inventory reconciliation

Operational workflow for reconciling Proxmox and Whrrr VMM guests against inventory, optionally powering on stopped guests for in-guest probes, and proposing YAML patches for owner review.

Architecture context: compute-live index, lab audit.

Principles

  • Inventory YAML is source of truth — automation proposes patches; you commit.
  • Proxmox power ops run only via discover-proxmox-power.yml on prox with /etc/homelab/DISCOVER set (separate from patching MAINTENANCE).
  • Never touch production VMIDs: 100 (saltierpoop), 123 (infra-services), 200 (haos) — hard-coded in playbook defaults.

Prerequisites

Item Notes
.env with PVE + DSM creds See Proxmox API token
Repo checkout Operator workstation or infra-services
Optional: discovery API token VM.PowerMgmt on prox for Ansible power playbook
SSH proxbox for prox; patch-controller key from infra-services for guests

Windows operators: run Ansible playbooks from WSL (native Windows Python often fails UTF-8 locale checks). Set ANSIBLE_CONFIG to the repo infra/ansible/ansible.cfg so roles resolve correctly on /mnt/c/... paths.

Unmanaged LXCs/VMs: discovery inventory uses ansible_user: root. The patch-controller key must be in root@<guest> authorized_keys. Run bootstrap-discovery-ssh.yml or scripts/ops/bootstrap-discovery-lxc-keys.sh (run on prox via infra-services jump) before discover-guests.yml.

Phase 1 — Hypervisor reconciliation (read-only)

1. Proxmox scan

python scripts/proxmox-scan.py --dry-run    # preview
python scripts/proxmox-scan.py              # write compute-live/prox-*.json

Compare against baseline (self-hosted runner or homelab):

python scripts/proxmox-scan.py --check

After intentional inventory changes:

python scripts/proxmox-scan.py --write-baseline

2. Propose inventory patches

python scripts/inventory-propose-patches.py
# Review artifacts/inventory-patches/<date>/

Apply patches manually, then:

python inventory/generators/render-ansible.py --check
python scripts/validate-inventory-refs.py

3. Whrrr VMM scan

python scripts/whrrr-vmm-scan.py --dry-run
python scripts/whrrr-vmm-scan.py

Phase 2 — Discovery window (power + facts)

1. Enable discovery maintenance on prox

ssh proxbox 'touch /etc/homelab/DISCOVER'

Remove when finished:

ssh proxbox 'rm -f /etc/homelab/DISCOVER'

2. Generate discovery inventory

python inventory/generators/render-discovery-inventory.py
# Optional VMID filter:
python inventory/generators/render-discovery-inventory.py --vmids 106,107,116

Outputs:

  • inventory/generators/discovery/generated.yml
  • inventory/generators/discovery/discover-vars.json

3. Start stopped guests (batch small sets — prox is memory-constrained)

From infra-services (or operator host with Ansible + SSH to prox):

cd /var/lib/ansible-pull/homelab/infra/ansible   # or local checkout

ansible-playbook playbooks/discover-proxmox-power.yml \
  --tags discover-start \
  -l prox \
  -e @../../inventory/generators/discovery/discover-vars.json \
  -e 'discover_target_vmids=[106,107]' \
  -e discover_pve_token_id='labctl@pve!discover' \
  -e discover_pve_token_secret='...'

Use root @pam + password only if no token — prefer a dedicated discovery token.

4. Collect in-guest facts

ANSIBLE_PRIVATE_KEY_FILE=/etc/homelab/patch-controller/id_ed25519 \
ansible-playbook playbooks/discover-guests.yml \
  -i ../../inventory/generators/discovery/generated.yml \
  --tags discover-facts

Artifacts: docs/architecture/compute-live/guests/<id>.json

Optional Docker probe:

ansible-playbook playbooks/discover-guests.yml ... --tags discover-docker

5. Stop guests (optional)

ansible-playbook playbooks/discover-proxmox-power.yml \
  --tags discover-stop \
  -l prox \
  -e @../../inventory/generators/discovery/discover-vars.json \
  -e discover_auto_stop=true \
  -e 'discover_target_vmids=[106,107]'

6. Re-scan and commit

python scripts/proxmox-scan.py
python inventory/generators/render-diagram.py

Commit inventory updates + docs/architecture/compute-live/ artifacts.

7. Owner disposition review

Fill in compute disposition review (keep / consolidate / retire per instance). Re-run scans after inventory changes.

Safety checklist

  • [ ] discover_target_vmids excludes 100, 123, 200
  • [ ] /etc/homelab/DISCOVER present on prox before start/stop
  • [ ] Start guests in small batches (2–3 at a time on prox)
  • [ ] Remove DISCOVER flag when done
  • [ ] Review patch proposals before applying inventory YAML