incus-contrib/README.md

incus-contrib

Peripheral tools, snippets, and scripts for working with Incus, IncusOS, and the broader ecosystem.

Primarily aimed at home lab environments but useful in production as well.

Contents

bin/

Reusable scripts for building IncusOS installation media, deploying labs, and managing services:

• incusos-iso -- Build customized IncusOS ISO/IMG images using the official flasher-tool. Supports both architectures (x86_64, aarch64), multiple applications (Incus, Operations Center), automatic client certificate injection, and batch generation.

• incusos-seed -- Generate IncusOS seed archives (tar or FAT image) for installation customization. Covers all seed file types: install, applications, Incus preseed, Operations Center, network, and update configuration.

• incusos-proxmox -- Declarative IncusOS deployment on Proxmox VE. Define VMs in YAML, and the script handles seed generation, ISO upload, VM creation with correct settings (UEFI, TPM 2.0, VirtIO-SCSI), and automated installation.

• deploy-awx -- Deploy and manage AWX (Ansible automation) on the Incus cluster. Handles VM creation, K3s install, AWX Operator deployment, project/template configuration, and Aether integration. Requires --config for environment settings.

• deploy-haproxy -- Deploy HA HAProxy load balancing via Aether. Requires --config for environment settings.

• deploy-observability -- Deploy Prometheus + Grafana + Loki monitoring stack. Requires --config for environment settings.

See bin/README.md for full documentation.

envs/

Per-environment configuration, secrets, and deployment settings:

• beelink/ -- Beelink mini PC target (LAN, vmbr0, VLAN 69, local-lvm)
• hetzner/ -- Hetzner dedicated server target (WireGuard, vmbr1, local-zfs)
  • setup/ -- Host provisioning guide and interactive setup script

Each environment has: env (secrets), proxmox.yaml (connection), lab YAML files (VM definitions), and service configs (awx.yaml, haproxy.yaml, observability.yaml). See envs/README.md.

ansible/

Ansible playbooks for AWX/Aether lifecycle hooks. Playbooks use the Incus REST API (not SSH) for all instance operations — works regardless of network topology.

• playbooks/post-deploy.yml -- Runs after Aether creates an instance. Configures hostname, installs base packages, sets timezone, logs deployment.
• playbooks/decommission.yml -- Runs before Aether deletes an instance. Graceful service shutdown and decommission logging (best-effort).

notes/

Guides and reference material (roughly in learning order):

• clustering-guide.md -- Detailed Incus clustering walkthrough (manual cluster formation via remotes).
• operations-center-guide.md -- Operations Center provisioning, cluster management, and tested limitations.
• networking-guide.md -- OVN overlay networking tutorial (bridge + OVN + LAN access).
• shared-storage-guide.md -- iSCSI + lvmcluster shared storage for instant migration.
• production-lab-guide.md -- Manual cluster + OVN + HA workloads (validated end-to-end).
• migration-guide.md -- Migration paths into Incus from Proxmox, UTM, VMware Fusion, and Docker.
• aether-guide.md -- Aether management platform: deployment, instance/blueprint lifecycle, API reference, OVN recovery, and node resizing.
• awx-guide.md -- AWX deployment, Aether integration, Ansible playbook patterns, and the deploy-awx management script.
• incus-version-compatibility.md -- Incus package versions across platforms and install instructions.
• utm-support.md -- Design document for future UTM support on macOS.

Quick Start

# Install the flasher-tool (requires Go 1.22+)
go install github.com/lxc/incus-os/incus-osd/cmd/flasher-tool@latest

# Build a default IncusOS ISO with your client cert injected
bin/incusos-iso

# Build for a specific architecture and application
bin/incusos-iso --arch aarch64 --app operations-center --defaults

# Generate all common ISO variants at once
bin/incusos-iso --batch

# Generate a standalone seed archive
bin/incusos-seed --app incus --defaults --output my-seed.tar

# Deploy a cluster on Hetzner
source envs/hetzner/env
bin/incusos-proxmox --proxmox envs/hetzner/proxmox.yaml envs/hetzner/lab-production.yaml

# Deploy AWX on Hetzner
bin/deploy-awx --config envs/hetzner/awx.yaml --deploy

# Deploy HAProxy on beelink
source envs/beelink/env
bin/deploy-haproxy --config envs/beelink/haproxy.yaml --deploy

Requirements

• Go 1.22+ -- for installing the flasher-tool
• curl -- for downloading images from the CDN
• tar, gzip -- for seed archive creation and image decompression
• Incus client (recommended) -- for automatic client certificate detection. Works with any version; certificates are read directly from disk. See version compatibility notes for install instructions per platform (macOS, Debian/Ubuntu, Arch).
• mtools (optional) -- for creating FAT seed images

License

MIT