Managing Proxmox VE with GitLab Runner and Terraform: Bringing GitOps to Open Source Virtualization

In modern virtualization environments, Infrastructure as Code (IaC) has evolved from a best practice into an operational necessity. Proxmox Virtual Environment (PVE), one of the most widely adopted open source hypervisors in enterprise and advanced homelab setups, can now be managed in a fully declarative way by integrating GitLab Runner and Terraform.

This approach enables administrators to provision, update, and remove Proxmox resources in a reproducible, version-controlled manner, leveraging CI/CD pipelines and the GitOps methodology.

---

Why This Integration Matters

Terraform, developed by HashiCorp, has become a de facto standard for IaC. The bpg/proxmox Terraform provider bridges the gap between Terraform’s declarative language and the Proxmox API.

However, to apply these configurations securely and consistently, they must be executed in a controlled environment. GitLab Runner fulfills this role by automating Terraform tasks whenever changes are pushed to the repository, ensuring every deployment follows the same pipeline.

---

Step-by-Step Deployment Workflow

1. Clone the Repository
   Start by cloning the GitLab or GitHub repository containing your Terraform configuration for Proxmox VE.
2. Create a Dedicated Runner
   In GitLab, navigate to Settings > CI/CD > Runner, create a project runner, enable Run untagged jobs, and obtain the authentication token for the runner.
3. Prepare the Proxmox Node
   From the PVE Web UI, open the Shell on the target node and execute: bash <(curl -s https://gitlab.com/joevizcara/terraform-proxmox/-/raw/master/prep.sh) This script will:
   • Create a privileged PAM user to authenticate via API token.
   • Deploy a lightweight LXC container running GitLab Runner to manage Proxmox resources.
   • Add the LXC’s public SSH key to the node’s authorized keys, enabling the writing of cloud-init YAML files to the local Snippets datastore.
   • Register additional data types in the datastore (e.g., Snippets, Import).
   Security Note: Always review the script before running it, and consider enabling GitLab two-factor authentication in production environments.
4. Set Environment Variables in GitLab
   In Settings > CI/CD > Variables, add:
   • Key: PM_API_TOKEN_SECRET
   • Value: the token secret from credentials.txt.
5. Adjust Terraform Configurations
   If cloned locally, edit .tf and variables.tf files to reflect your PVE setup (storage pools, networks, IP addressing, etc.).
6. Run the Pipeline Jobs
   • The first CI stage validates the Terraform plan.
   • The second stage applies the infrastructure changes.
     Once completed, new VMs will appear in PVE, ready to start.
7. Post-Deployment Operations
   Access the gitlab-runner LXC console in PVE to connect via SSH (ssh k3s@<VM-IP>), configure the VMs, convert them into templates, or add them to an HA cluster.

---

Key Benefits of This Approach

• Full Automation: Infrastructure changes are triggered automatically via git push.
• Reproducibility: Consistent state across environments, thanks to version-controlled IaC.
• Security: Isolated runner environment and API token authentication.
• Scalability: Quickly spin up complete development, test, or production clusters.

---

Risks and Best Practices

While this setup offers agility and precision, it also demands strict security controls:

• Runner Security: If compromised, a runner could control the entire virtualization stack.
• Credential Management: Keep sensitive tokens in GitLab’s protected variables.
• Infrastructure Drift: Avoid manual changes in PVE outside Terraform to prevent configuration mismatches.

---

Conclusion: Proxmox Moves Closer to Cloud-Grade Operations

By combining Proxmox VE, GitLab Runner, and Terraform, open source virtualization moves a step closer to the operational sophistication of cloud providers like AWS, Azure, or GCP.
For DevOps teams and systems administrators, this is a robust, scalable, and secure path to managing Proxmox clusters without repetitive manual intervention.

---

FAQs

1. Can this method manage multiple Proxmox nodes?
Yes — simply configure the Terraform provider for each node and declare them in your IaC code.

2. Is it safe to execute the prep.sh script?
You can review its content before execution. For production, audit it and test in a sandbox environment first.

3. Can I use a CI/CD platform other than GitLab?
Yes — the workflow can be adapted to Jenkins, GitHub Actions, or other CI systems with access to the PVE API.

4. Can this integrate with Proxmox Backup Server?
Yes — backup job creation and retention policies can be incorporated into the Terraform workflow for end-to-end automation.

---

If you’d like, I can now create a clear architecture diagram showing the GitLab → Runner LXC → Proxmox API → VM Deployment flow, which would make this piece much more visually compelling for a tech publication.
Do you want me to prepare that next?