DEV Community: Steven Koch

Proxmox-GitOps: Selfhosted GitOps IaC Container Automation

Steven Koch — Sat, 27 Sep 2025 10:04:04 +0000

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 libs directory, adding a minimal cookbook and a config.env file. 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.

Proxmox-GitOps: Self-configuring GitOps Environment for Container Automation in Proxmox VE.

Steven Koch — Mon, 28 Jul 2025 16:02:11 +0000

Overview

Proxmox-GitOps implements a self-sufficient, extensible CI/CD environment for provisioning, configuring, and orchestrating Linux Containers (LXC) within Proxmox VE. Leveraging an Infrastructure-as-Code approach, it manages the complete container lifecycle—bootstrapping, deployment, configuration, and validation—via version-controlled automation.

Architecture

The system architecture is based on a multi-stage pipeline capable of recursively deploying and configuring itself. Initial bootstrapping is performed via a local Docker environment, with subsequent deployments targeting Proxmox VE.

Core Concepts

Ephemeral State: Git repository represents current desired state; state purity across deployments. Deployment consistency and stateless infrastructure over version history.
Recursive Self-Containment: Embedded control plane recursively provisions itself within target containers. Prevents configuration drift; enables consistent and reproducible behavior.
Mono-Repository: Central code artifact; submodules modularize development at runtime. Consistency and modularity; dynamically resolved in recursive context.

Trade-offs

Complexity vs. Autonomy: Recursive self-replication increases system complexity to achieve deterministic bootstrap and reproducible behavior.
Git Convention vs. Infrastructure State: Uses Git as a state engine in stateless contexts; the mono-repo encapsulates infrastructure as a self-contained, version-controlled asset.

Feedback

Architectural feedback, edge cases, and use-case experiences are welcome.
The project is under active development; suggestions and critical review are appreciated.

⸻

GitHub: stevius10/Proxmox-GitOps

Self-Configuring GitOps for Proxmox: Recursive LXC Automation as Code

Steven Koch — Sun, 20 Jul 2025 05:15:40 +0000

GitHub: stevius10/Proxmox-GitOps

⸻

What it is

Proxmox-GitOps is a self-configuring CI/CD environment for Proxmox LXC.
It manages container provisioning, configuration, and orchestration using an infrastructure-as-code workflow.
All automation is version-controlled and idempotent.

⸻

How it works
• Bootstrap locally in Docker (one command)
• CI/CD pipeline pushes codebase into a Gitea instance
• Recursive self-configuration: The pipeline triggers itself in every new container environment (“pipeline within a pipeline”)
• Provisioning with Ansible (Proxmox API)
• Configuration with Chef/Cinc (application logic)
• Consistent, modular: base config and workflows apply to all services, changes propagate automatically

⸻

• Self-managed, self-verifying infrastructure
• Full lifecycle: bootstrapping, deployment, configuration, validation
• Recursive, idempotent execution
• Modular and extensible (add container modules, adapt pipelines)
• Pure GitOps: all state and change managed via commits and PRs

⸻

Who is this for?

Primarily built for my own homelab, but extensible for anyone who wants to automate and codify their Proxmox environment—without manual steps.

⸻

Feedback

This project is still young and likely has rough edges.
I would be very interested in technical feedback, ideas, or just what you are thinking.
So, if you’re into Proxmox, GitOps, CI/CD, and infrastructure-as-code - or just to moan together recursion in an actually not idempotent Git based automation — feel free to check it out 🙂

⸻

GitHub: stevius10/Proxmox-GitOps