TL;DR: This post introduces Proxmox-GitOps, a system that creates a self-managing CI/CD control plane for Proxmox VE. It bootstraps from a single repository and manages itself recursively within the LXC containers it oversees.
Proxmox-GitOps implements a self-contained CI/CD control plane for Proxmox VE that bootstraps from a single repository and manages itself recursively within the LXC containers under management.
Repository: stevius10/Proxmox-GitOps
Demo (1min+):
Architecture
A local bootstrap script (./local/run.sh) seeds a Gitea instance and a runner, initializes the pipeline, and creates an initial pull request. Merging this PR transitions the system into full self-management. From that point on, subsequent commits automatically converge the desired state across all Proxmox LXC containers.
The system uses a self-contained monorepo with reusable container libraries. Ansible handles provisioning against Proxmox, while Cinc (a Chef distribution) performs desired-state convergence and cross-layer orchestration where declarative modeling is insufficient.
Core Concepts
- Recursive Self-Management: The control plane executes from within the managed containers to maximize reproducibility and minimize configuration drift.
- Git as Current Desired State: All operations map to standard Git workflows (commit, merge, rollback) in a completely stateless management model.
-
Convention-Based Extensibility: Add a new service by copying a container definition from the
libsdirectory, adding a minimal cookbook and aconfig.envfile. The pipeline automatically handles provisioning, configuration, and validation. - Loose Coupling: Containers remain independently replaceable and continue to function without requiring manual follow-up actions after changes.
Environment
- Proxmox VE: Versions 8.4–9.0
- Container OS: Debian 13 LXC by default
- Bootstrap: Local bootstrap via Docker; all further actions are repository-driven.
Installation
- Configure your Proxmox credentials in
./local/config.json. -
Run the bootstrap script to seed the environment:
./local/run.sh Accept the initial Pull Request in the newly seeded Gitea instance at
http://localhost:8080/main/config.Push any changes to your repository to trigger provisioning, convergence, and validation on Proxmox VE.
Trade-Offs
- The recursive bootstrap model increases initial complexity to preserve "rebuild-from-repo" semantics and ensure deterministic behavior.
- On Proxmox 9, stricter token privileges limit certain operations. The automation therefore uses root-context API access where token permissions are insufficient.
Top comments (0)