121 lines
5.2 KiB
Markdown
121 lines
5.2 KiB
Markdown
# incu-contrib
|
|
|
|
Peripheral tools, snippets, and scripts for working with [Incus](https://linuxcontainers.org/incus/),
|
|
[IncusOS](https://linuxcontainers.org/incus-os/), and the broader ecosystem.
|
|
|
|
Primarily aimed at home lab environments but useful in production as well.
|
|
|
|
## Contents
|
|
|
|
### [`incusos/`](incusos/)
|
|
|
|
Scripts for building IncusOS installation media and seed configurations:
|
|
|
|
- **`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.
|
|
|
|
- **`targets/`** -- Per-host Proxmox connection configs and lab definitions. Each
|
|
subdirectory (beelink, hetzner) has a `proxmox.yaml.example` and lab YAML files
|
|
sized for that host. See [`targets/README.md`](incusos/targets/README.md).
|
|
|
|
- **`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.
|
|
|
|
See [`incusos/README.md`](incusos/README.md) for full documentation.
|
|
|
|
### [`ansible/`](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).
|
|
|
|
### [`hetzner/`](hetzner/)
|
|
|
|
Setup guide and automation for deploying IncusOS labs on a Hetzner dedicated server:
|
|
|
|
- **`hetzner-setup.md`** -- Step-by-step guide: Proxmox install, private networking,
|
|
WireGuard tunnel, firewall lockdown, and API token creation.
|
|
- **`proxmox-setup`** -- Interactive helper script that automates the guide steps
|
|
over SSH. Configures repos, bridge, storage, WireGuard, firewall, and API tokens.
|
|
|
|
See also [`incusos/targets/`](incusos/targets/) for per-host connection configs
|
|
and lab definitions.
|
|
|
|
### [`notes/`](notes/)
|
|
|
|
Guides and reference material (roughly in learning order):
|
|
|
|
- [`clustering-guide.md`](notes/clustering-guide.md) --
|
|
Detailed Incus clustering walkthrough (manual cluster formation via remotes).
|
|
- [`operations-center-guide.md`](notes/operations-center-guide.md) --
|
|
Operations Center provisioning, cluster management, and tested limitations.
|
|
- [`networking-guide.md`](notes/networking-guide.md) --
|
|
OVN overlay networking tutorial (bridge + OVN + LAN access).
|
|
- [`shared-storage-guide.md`](notes/shared-storage-guide.md) --
|
|
iSCSI + lvmcluster shared storage for instant migration.
|
|
- [`production-lab-guide.md`](notes/production-lab-guide.md) --
|
|
Manual cluster + OVN + HA workloads (validated end-to-end).
|
|
- [`migration-guide.md`](notes/migration-guide.md) --
|
|
Migration paths into Incus from Proxmox, UTM, VMware Fusion, and Docker.
|
|
- [`aether-guide.md`](notes/aether-guide.md) --
|
|
Aether management platform: deployment, instance/blueprint lifecycle, API
|
|
reference, OVN recovery, and node resizing.
|
|
- [`awx-guide.md`](notes/awx-guide.md) --
|
|
AWX deployment, Aether integration, Ansible playbook patterns, and
|
|
the deploy-awx management script.
|
|
- [`incus-version-compatibility.md`](notes/incus-version-compatibility.md) --
|
|
Incus package versions across platforms and install instructions.
|
|
- [`utm-support.md`](notes/utm-support.md) --
|
|
Design document for future UTM support on macOS.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# 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
|
|
./incusos/incusos-iso
|
|
|
|
# Build for a specific architecture and application
|
|
./incusos/incusos-iso --arch aarch64 --app operations-center --defaults
|
|
|
|
# Generate all common ISO variants at once
|
|
./incusos/incusos-iso --batch
|
|
|
|
# Generate a standalone seed archive
|
|
./incusos/incusos-seed --app incus --defaults --output my-seed.tar
|
|
|
|
# Generate a SEED_DATA FAT image for external boot media
|
|
./incusos/incusos-seed --format fat --app incus --defaults --output seed.img
|
|
```
|
|
|
|
## 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](notes/incus-version-compatibility.md)
|
|
for install instructions per platform (macOS, Debian/Ubuntu, Arch).
|
|
- **mtools** (optional) -- for creating FAT seed images
|
|
|
|
## License
|
|
|
|
MIT
|