Proxmox GitOps

Proxmox GitOps is a robust solution for automating the lifecycle of Linux Containers (LXC) in Proxmox VE, utilizing a self-sufficient, extensible CI/CD environment. By adopting an Infrastructure-as-Code (IaC) approach, this project streamlines the processes of provisioning, configuring, and orchestrating containers through version-controlled automation.

Overview

This project facilitates automated management of container infrastructure, ensuring consistent and reproducible deployments. With Proxmox GitOps, the entire lifecycle—from bootstrapping and deployment to configuration and validation—is effectively managed.

Architecture

The architecture comprises a multi-stage pipeline that can recursively deploy and configure itself, ensuring a seamless transition from local development to production environments. The initial setup occurs via a local Docker environment, with further deployments targeting Proxmox VE.

Key Features

• Self-Managed Infrastructure: Automatically provisions, configures, and verifies itself recursively, enhancing reliability.
• Container Provisioning: Handled by Ansible through the Proxmox API, simplifying resource management.
• Container Configuration: Utilizes cookbooks for application-level setup, allowing for detailed customization.
• CI/CD Orchestration: Automatically installs and executes within the container via a Runner, ensuring smooth operations.
• Environment Management: Initial variables are loaded from a configuration file and propagated recursively into the GitOps system.
• Modularity: Supports distinct components and modular reusable workflows managed within Gitea, promoting easy extensions and enhancements.

Getting Started

1. Configure your credentials and Proxmox API token in the local/.config.json.
2. Initialize the local Docker environment with local/run.sh.
3. Deploy on Proxmox VE to accept the Pull Request.

Container Creation

Create reusable container definitions in the libs folder, and follow these steps:

1. Define container parameters in the config.env file, such as:

   IP=192.168.178.42
   ID=42
   HOSTNAME=apache
   CORES=2
   MEMORY=2048
   SWAP=512
   DISK=local-lvm:8
   BOOT=yes
   

2. Use a generic pipeline in gitea/workflows:

   on:
     workflow_dispatch:
     push:
       branches: [ release, main, develop ]
   
   jobs:
     include:
       runs-on: shell
       steps:
         - id: init
           uses: srv/config/.gitea/workflows@main
           with:
             repo: ${{ gitea.repository }}
             ref: ${{ gitea.ref_name }}
             cache_bust: ${{ gitea.run_number }}
   

3. Add your cookbook to the container definition root, e.g., for Apache setup:

   # ./libs/apache/recipes/default.rb
   package 'apache2'
   
   service 'apache2' do
     action [:enable, :start]
   end
   
   file '/var/www/html/index.html' do
     content "<h1>Hello from #{Env.get(node, 'login')}</h1>"
     mode '0644'
     owner 'app'
     group 'app'
   end
   

4. Optionally, utilize Env.get() and Env.set() for environment variables access.
5. Deploy by pushing to the release branch of a new repository and adding it to the Meta-/Mono-Repository for deployment.

Requirements

• Docker
• Proxmox VE
• Proxmox API token

For detailed recommendations, refer to the Wiki.

Proxmox GitOps exemplifies efficient, automated management of containerized environments while supporting a modular and extensible architecture.