Gestionar Proxmox VE con GitLab Runner y Terraform: el salto a la automatización declarativa

En entornos de virtualización modernos, la infraestructura como código (IaC) ya no es una opción, sino una necesidad. Proxmox Virtual Environment (PVE), uno de los hipervisores open source más populares en entornos corporativos y homelabs avanzados, ahora puede gestionarse de forma totalmente declarativa gracias a una integración directa con GitLab Runner y Terraform.

Este enfoque permite desplegar, modificar y eliminar recursos de Proxmox de forma reproducible, con control de versiones y pipelines CI/CD, siguiendo la filosofía GitOps.

La lógica detrás de la integración

Terraform, desarrollado por HashiCorp, es uno de los estándares de facto en IaC, y el proveedor bpg/proxmox ofrece una API para interactuar con PVE.
Sin embargo, ejecutar Terraform desde un entorno seguro y con las credenciales adecuadas es clave para evitar riesgos de seguridad y garantizar consistencia.

Aquí es donde entra GitLab Runner: una instancia dedicada que ejecuta las tareas definidas en el pipeline del repositorio y aplica los cambios a Proxmox automáticamente cuando se hace un git push.

Cómo funciona el despliegue paso a paso

1. Clonación del repositorio
   El administrador clona el repositorio GitLab/Hub con la configuración Terraform para su entorno PVE.
2. Creación de un runner dedicado
   Desde Settings > CI/CD > Runner en GitLab, se crea un project runner con la opción Run untagged jobs. Se genera un token de autenticación para registrar el runner.
3. Preparación del nodo Proxmox
   En la interfaz web de PVE, se accede al Shell del nodo de destino y se ejecuta el script de preparación: bash <(curl -s https://gitlab.com/joevizcara/terraform-proxmox/-/raw/master/prep.sh) Este script:
   • Crea un usuario PAM privilegiado para autenticación vía API token.
   • Lanza un contenedor LXC con GitLab Runner para gestionar PVE.
   • Añade la clave pública SSH del LXC al nodo para permitir la escritura de ficheros cloud-init en el datastore Snippets.
   • Habilita nuevos tipos de datos aceptados en el datastore (e.g., Snippets, Import).
   Seguridad: Se recomienda revisar el contenido del script antes de ejecutarlo y habilitar autenticación en dos pasos en GitLab para entornos de producción.
4. Configuración de variables de entorno en GitLab
   En Settings > CI/CD > Variables, se añade:
   • Key: PM_API_TOKEN_SECRET
   • Value: token de autenticación del archivo credentials.txt generado en el paso anterior.
5. Adaptación de ficheros .tf
   Si se clona el repositorio localmente, se ajustan las variables (.tf y variables.tf) para reflejar la configuración real de PVE (almacenamiento, redes, direcciones IP, etc.).
6. Ejecución de los jobs en GitLab
   • El primer job valida la configuración.
   • El segundo job aplica los cambios de infraestructura.
     Al completarse, las nuevas VMs aparecen en PVE listas para arrancar.
7. Post-despliegue
   Desde la consola del LXC gitlab-runner es posible conectarse por SSH a las VMs (ssh k3s@<IP>) para configurarlas, convertirlas en plantillas o añadirlas a un clúster HA.

Ventajas de este enfoque

• Automatización total: despliegue y modificación de VMs con un simple git push.
• Reproducibilidad: la configuración vive en el repositorio, garantizando consistencia en cada entorno.
• Seguridad: uso de API tokens y contenedores aislados para el runner.
• Escalabilidad: facilita la creación de entornos completos para desarrollo, pruebas o producción.

Riesgos y buenas prácticas

Aunque esta metodología ofrece control y eficiencia, también introduce desafíos:

• Seguridad del runner: un runner comprometido puede alterar toda la infraestructura.
• Gestión de credenciales: deben almacenarse en GitLab con permisos estrictos.
• Versionado de infraestructura: cambios directos en PVE sin pasar por Terraform pueden causar drift (desalineación) que deberá corregirse.

Conclusión: Proxmox se acerca a la experiencia de nube pública

Integrar Proxmox VE con GitLab Runner y Terraform acerca la experiencia del open source a lo que ofrecen proveedores como AWS, Azure o GCP en términos de IaC y GitOps.
Para equipos DevOps y administradores de sistemas, supone una forma más segura, ágil y escalable de gestionar clústeres de Proxmox sin depender de intervenciones manuales.

FAQs

1. ¿Puedo usar este método con múltiples nodos de Proxmox?
Sí, basta con configurar el Terraform provider para cada nodo y definirlos en el código IaC.

2. ¿Es seguro ejecutar el script prep.sh?
Su contenido puede revisarse antes de ejecutarlo. Para producción, se recomienda auditarlo y aplicarlo en un entorno controlado primero.

3. ¿Puedo usar otra plataforma CI/CD que no sea GitLab?
Sí, la arquitectura es adaptable a Jenkins, GitHub Actions u otros, siempre que el runner tenga acceso al API y al nodo PVE.

4. ¿Se puede integrar con Proxmox Backup Server?
Sí, puede añadirse la creación de jobs y configuraciones de backup en el flujo Terraform para una solución integral.