Repository: https://github.com/stevius10/Proxmox-GitOps
Demo (1min+): https://youtu.be/2oXDgbvFCWY?si=gSSACmVi0mO6v8xx
Architecture
- A local bootstrap (`./local/run.sh`) seeds a Gitea instance and runner, initializes the pipeline, and creates an initial PR. Merging this PR transitions the system into self-management; subsequent commits converge the desired state across Proxmox LXC containers.
- The system uses a self-contained monorepo with reusable container libraries. Ansible handles provisioning against Proxmox, while Cinc (Chef) performs desired-state convergence and cross-layer orchestration where declarative modeling is insufficient.
Concept
- Recursive self-management: the control plane executes within the managed containers to maximize reproducibility and minimize drift.
- Git as current desired state: operations map to standard Git workflows (commit, merge, rollback) in a stateless management model.
- Convention-based extensibility: add a service by copying a container definition from libs, adding a minimal cookbook and `config.env`; the pipeline handles provisioning, configuration, and validation.
- Loose coupling: containers remain independently replaceable and continue to function without manual follow-up.
Environment
- Proxmox VE 8.4–9.0, Debian 13 LXC per default.
- Local bootstrap via Docker; further actions are repository-driven.
Install
- Configure Proxmox credentials in `./local/config.json`. - Run `./local/run.sh` to seed the environment.
- Accept the initial PR in the seeded Gitea instance at `localhost:8080/main/config`.
- Push changes to trigger provisioning, convergence, and validation on Proxmox VE.
Trade-Offs
- The recursive bootstrap increases complexity to preserve rebuild‑from‑repo semantics and deterministic behavior.
- On Proxmox 9, stricter token privileges limit certain operations; automation uses root‑context API access where tokens are insufficient.