bpg/proxmox, y se autentica con un token de API acotado, nunca con root@pam.plan antes de aplicar.Hay un momento en la vida de todo cloud privado en el que la interfaz web deja de ser una comodidad y empieza a ser un problema. Al principio creas VMs a mano y va perfecto: clonas una plantilla, ajustas CPU y RAM, asignas una IP, arrancas. Con cinco máquinas, bien. Con cincuenta, empiezan las preguntas incómodas: ¿por qué la VM 12 tiene una configuración distinta a la 11? ¿Quién cambió el tamaño de disco de esa y cuándo? ¿Cómo reconstruyo todo esto si mañana hay que levantarlo en otro clúster?
La respuesta a esas preguntas se llama infraestructura como código (IaC): en lugar de hacer clic, describes lo que quieres en ficheros de texto versionados, y una herramienta se encarga de que la realidad coincida con esa descripción. Tu cloud privado deja de vivir en la cabeza de quien lo montó y pasa a vivir en un repositorio Git que cualquiera puede leer, revisar y reproducir.
Este artículo explica cómo se hace IaC sobre Proxmox en producción con Terraform u OpenTofu: qué provider usar, cómo se estructura un proyecto y qué patrones separan un despliegue mantenible de un lío que nadie se atreve a tocar. Es, además, una pieza natural para quien migra desde VMware: si vienes de gestionar vSphere con Terraform, el modelo mental se traslada casi entero.
IaC no es una moda de DevOps. Resuelve tres problemas concretos que cualquiera que gestione más de un puñado de máquinas reconoce.
Reproducibilidad. Si tu infraestructura está descrita en código, reconstruirla es ejecutar el código. En otro clúster, en un entorno de pruebas idéntico al de producción, tras un desastre: el mismo fichero produce la misma infraestructura. Deja de existir la máquina «especial» que nadie sabe recrear.
Trazabilidad. Cada cambio pasa por Git: quién lo hizo, cuándo, por qué, y —si trabajas con pull requests— revisado por otra persona antes de aplicarse. La pregunta «¿quién tocó esto?» tiene respuesta en el historial en vez de en una discusión.
Consistencia. El código no se distrae ni se cansa. Cincuenta VMs creadas desde la misma plantilla de código son idénticas en lo que deben serlo. Se acabó el drift silencioso de configuraciones que divergen a fuerza de ajustes manuales.
La contrapartida es honesta: IaC tiene curva de entrada. Montar el primer despliegue lleva más que crear una VM a mano. La inversión se paga a partir de la segunda, la décima y, sobre todo, el día del incidente. Para infraestructuras que crecen, no es un lujo: es lo que las hace gobernables.
Terraform, de HashiCorp, fue durante años el estándar de facto de IaC. En 2023 cambió su licencia de código abierto (MPL) a una licencia de fuente disponible (BSL), más restrictiva. La comunidad respondió creando OpenTofu: un fork de Terraform, bajo el paraguas de la Linux Foundation, que mantiene la licencia abierta original y es compatible a nivel de sintaxis y providers.
Para lo que nos ocupa, la elección es sencilla y tranquilizadora: el código HCL es prácticamente idéntico en ambos, los providers funcionan en los dos y migrar de uno a otro es, hoy por hoy, cambiar el binario. OpenTofu es la opción coherente para quien construye un cloud privado con la lógica de la soberanía y el software abierto: sin ataduras de licencia, gobernado por una fundación. Terraform sigue siendo válido si ya lo usas. En este artículo, cuando decimos «Terraform» aplica igual a OpenTofu.
Terraform no sabe nada de Proxmox por sí mismo. Aprende a través de un provider, un plugin que traduce el código HCL a llamadas a la API de Proxmox. Para Proxmox, el provider de referencia hoy es bpg/proxmox, mantenido activamente y bastante más completo y estable que el veterano telmate/proxmox que dominaba hace años.
El provider se autentica contra la API de Proxmox. La buena práctica es no usar la contraseña de root@pam, sino un token de API con permisos acotados, creado para esto:
# provider.tf
terraform {
required_providers {
proxmox = {
source = "bpg/proxmox"
version = ">= 0.60.0"
}
}
}
provider "proxmox" {
endpoint = "https://pve.midominio.local:8006/"
api_token = var.proxmox_api_token # usuario!token=uuid, en una variable secreta
insecure = false # true solo si usas certificado autofirmado
}El token se crea en Datacenter → Permissions → API Tokens, con un rol que solo permita lo necesario (crear y gestionar VMs en un pool o nodo concreto). Regla de oro: el código de IaC nunca lleva secretos dentro. El token va en una variable, y esa variable en un fichero fuera de Git, en variables de entorno o en un gestor de secretos.
Lo que sigue crea una VM clonando una plantilla existente. Es el patrón que se repite miles de veces en un cloud privado real:
# vm.tf
resource "proxmox_virtual_environment_vm" "web" {
name = "web-01"
node_name = "pve-nodo1"
vm_id = 201
clone {
vm_id = 9000 # ID de la plantilla base (una cloud-init de Debian, p.ej.)
}
cpu {
cores = 2
type = "host"
}
memory {
dedicated = 4096 # MB
}
disk {
datastore_id = "local-zfs"
size = 40 # GB
interface = "scsi0"
}
network_device {
bridge = "vmbr0"
}
# cloud-init: IP, usuario y clave SSH sin entrar a la consola
initialization {
ip_config {
ipv4 {
address = "10.20.0.201/24"
gateway = "10.20.0.1"
}
}
user_account {
username = "admin"
keys = [var.ssh_public_key]
}
}
}El flujo de trabajo es siempre el mismo, y esa previsibilidad es media gracia:
terraform init # descarga el provider
terraform plan # muestra qué va a cambiar, sin tocar nada
terraform apply # aplica los cambios tras confirmarEl plan es la pieza que da tranquilidad: te enseña exactamente qué va a crear, modificar o destruir antes de hacerlo. Nada de sorpresas. Y si el plan dice que va a destruir algo que no esperabas, paras y lo revisas. Ese hábito evita la mayoría de los desastres.
La sintaxis se aprende en una tarde. Lo que marca la diferencia a los seis meses son los patrones de organización.
Terraform guarda en un fichero de estado su mapa entre el código y la realidad. Ese fichero es crítico: si se pierde o se corrompe, Terraform deja de saber qué gestiona. Dos reglas no negociables:
Si todas tus VMs web se parecen, no copies el bloque cincuenta veces. Un módulo encapsula «cómo es una VM web en nuestra casa» y se instancia con parámetros. Cambias el módulo una vez y se propaga a todas. Es la diferencia entre mantener una plantilla y mantener cincuenta copias divergentes.
El patrón que mejor escala en Proxmox: una plantilla cloud-init por sistema operativo (una Debian, una Ubuntu, una Rocky), y Terraform clonando de ella e inyectando la configuración específica —IP, claves, hostname— vía cloud-init. Así el sistema base se mantiene en un solo sitio y las VMs nacen configuradas, sin entrar nunca a la consola.
Producción y pruebas no comparten estado. Se separan en directorios o workspaces distintos, con sus propias variables. Así puedes probar un cambio en pre y aplicarlo a producción solo cuando el plan sale limpio. Y si algo se rompe en pruebas, producción ni se entera.
.gitignore para los ficheros sensibles y de estado local.apply intentará «corregir» tu cambio manual, a veces destruyendo. Regla: lo que gestiona Terraform, se toca solo por Terraform.plan. El plan avisa de lo que va a pasar. Aplicar en automático sin mirarlo es cómo se destruyen VMs por error. En equipo, el plan se revisa en un pull request antes de aprobar.apply. Divide por entornos y por dominios de responsabilidad.No hace falta convertir todo el cloud a IaC de golpe. Un camino que funciona:
bpg/proxmox.root@pam.init/plan/apply con algo sin riesgo.plan antes de aplicar a producción.A partir de ahí, tu infraestructura deja de ser una acumulación de decisiones olvidadas y pasa a ser un documento vivo, versionado y reproducible. Que es, al final, de lo que va tener un cloud privado que puedas gobernar en vez de solo mantener.
¿Terraform u OpenTofu para Proxmox? Para este caso son intercambiables: el código HCL es prácticamente idéntico y los providers funcionan en ambos. OpenTofu es la opción de licencia abierta bajo la Linux Foundation, coherente con un cloud privado sin ataduras. Terraform sirve igual si ya lo usas. Migrar de uno a otro es casi cambiar el binario.
¿Qué provider de Proxmox debo usar?
bpg/proxmox es hoy el más completo y mantenido. El antiguo telmate/proxmox fue popular pero va por detrás en funcionalidad y estabilidad. Ambos hablan con la API de Proxmox; bpg es la recomendación actual para proyectos nuevos.
¿Puedo gestionar VMs que ya creé a mano?
Sí, mediante terraform import, que trae un recurso existente al estado. Pero es laborioso y propenso a errores. Para empezar, es más sencillo aplicar IaC a VMs nuevas y dejar las antiguas como están hasta que toque recrearlas.
¿Dónde guardo el token de la API sin comprometerlo?
Nunca en el código ni en Git. Va en una variable de Terraform alimentada desde una variable de entorno, un fichero .tfvars excluido de Git o un gestor de secretos. El fichero de estado también contiene datos sensibles y debe ir cifrado y con acceso restringido.
¿Esto sustituye a Ansible? No, se complementan. Terraform/OpenTofu crea y gestiona la infraestructura (las VMs, redes, discos). Ansible u otra herramienta de gestión de configuración se ocupa de lo que va dentro (paquetes, servicios, ficheros). El patrón común: Terraform aprovisiona, la configuración la aplica cloud-init o Ansible después.
bpg/proxmox.¿Tu cloud privado ha crecido hasta el punto de que nadie recuerda cómo se montó cada VM? Te ayudamos a llevar tu infraestructura Proxmox a código con OpenTofu o Terraform: reproducible, versionada y revisable. Empieza por nuestra comparativa de cloud o hablemos de tu proyecto.
Proxmox VE 9.2 estrena versión oficial para ARM64 (AArch64), la primera fuera de x86-64 en la historia del producto. Misma base de código, mismos repositorios y mismo soporte, con NVIDIA Grace y NVIDIA Vera como plataformas certificadas de salida. Repasamos qué hardware cumple los requisitos, qué funciones se quedan en x86 y qué cambia (poco, de momento) para quien ya tiene un clúster en producción.
Haces backup de la VM cada noche y duermes tranquilo. Hasta que restauras y la base de datos arranca corrupta o pierde las últimas transacciones. Un snapshot de disco no es lo mismo que un backup consistente de una base de datos. Explicamos la diferencia entre backup consistente por caída, por sistema de ficheros y por aplicación, y cómo conseguir el bueno en Proxmox con el agente invitado, hooks y volcados nativos.
Una red IP enrutada abajo, los servicios de cada cliente encapsulados arriba y BGP distribuyendo dónde está cada MAC. Qué resuelve EVPN-VXLAN, cómo encajan underlay y overlay, qué detalles rompen un fabric (la MTU, siempre la MTU) y cuándo no compensa montarlo.