terraform/
├── .gitignore
├── clone/
│ ├── main.tf (1)
│ ├── variables.tf (2)
│ └── terraform.tfvars (3)
├── create/
│ ├── main.tf (4)
│ ├── variables.tf (5)
│ └── terraform.tfvars (6)
├── docs/
│ ├── GUIA_DESPLIEGUE_TERRAFORM_PROXMOX.adoc
│ └── DOCUMENTACION_PROVIDER_BPG_PROXMOX.adoc
└── evidencias/
├── 1.token.png
├── 2.token.png
└── 3.token.png¶ Guía de Despliegue de Máquinas Virtuales con Terraform en Proxmox VE
Índice
- 1. Introducción
- 2. Tecnologías utilizadas
- 3. Arquitectura del proyecto
- 4. Configuración del entorno
- 5. Creación del API Token en Proxmox VE
- 6. Modelo de permisos en Proxmox VE
- 7. Problemas encontrados y soluciones
- 7.1. Error #1 — Resolución DNS fallida
- 7.2. Error #2 — Sin permisos en el almacenamiento
- 7.3. Error #3 — Sin permisos para leer la configuración del disco
- 7.4. Error #4 — ID de VM duplicado (causa raíz real)
- 7.5. Error #5 — Sin permiso SDN al clonar (Fallo de SDN.Use en la plantilla)
- 7.6. Error #6 — Storage
local-lvmno existe
- 8. Gestión de permisos mediante la API REST
- 9. Configuración final
- 10. Resultado
- 11. Módulo clone — Clonado de máquinas virtuales
- 12. Conclusión
¶ 1. Introducción
|
Por motivos de seguridad y confidencialidad, todos los nombres de usuario, identificadores de tokens de API, pools de Proxmox, direcciones IP y dominios de red utilizados en los ejemplos y comandos de esta guía son ficticios y han sido anonimizados. |
Esta guía documenta el proceso de despliegue automatizado de una máquina virtual con Fedora Linux en un clúster Proxmox VE mediante Terraform, utilizando el proveedor comunitario bpg/proxmox.
El objetivo es demostrar el uso de Infraestructura como Código (IaC) para aprovisionar recursos de virtualización de forma declarativa, reproducible y controlada, aplicando el principio de mínimo privilegio en la gestión de permisos del API token de Proxmox.
Proxmox VE expone una API REST completa que Terraform consume para crear, modificar y destruir recursos (VMs, contenedores, redes, almacenamiento). La autenticación se realiza mediante tokens de API vinculados a usuarios, cuyo alcance de permisos puede configurarse de dos formas distintas que se detallan en esta guía.
Código fuente: Repositorio en GitHub
¶ 2. Tecnologías utilizadas
| Tecnología | Versión / Detalle |
|---|---|
Terraform |
1.14.7 |
Proveedor |
~> 0.66 |
Proxmox VE |
Clúster escolar (nodo: |
Sistema operativo VM |
Fedora Linux (tipo de SO: |
Almacenamiento |
|
Red |
Bridge |
¶ 3. Arquitectura del proyecto
¶ 3.1. Estructura de ficheros
| 1 | Configuración del módulo de clonado: definición de VM a partir de una plantilla y cloud-init. |
| 2 | Variables del proveedor y plantilla para el clonado. |
| 3 | Valores de variables para el clonado (excluido de git). |
| 4 | Configuración del módulo de creación: aprovisionamiento desde cero de Fedora y Ubuntu. |
| 5 | Variables para el módulo de creación (endpoints, tokens, imágenes ISO). |
| 6 | Valores de variables para la creación (excluido de git). |
¶ 3.2. Flujo de ejecución
API REST (HTTPS:8006)
┌──────────────┐ terraform apply ┌──────────────────────────────────────┐
│ Terraform │ ────────────────► │ Proxmox VE — nodo proxmox4 │
│ (local) │ │ │
│ │ API Token auth │ Pool : pool-asir-tfg │
│ main.tf │ ◄──────────────── │ Storage : local-zfs │
└──────────────┘ bpg/proxmox │ VM ID : 4444 — fedora-workstation │
└──────────────────────────────────────┘¶ 4. Configuración del entorno
¶ 4.1. Proveedor Terraform
Se utiliza el proveedor comunitario bpg/proxmox, que ofrece soporte completo para Proxmox VE incluyendo VMs, contenedores LXC, almacenamiento y redes.
terraform {
required_providers {
proxmox = {
source = "bpg/proxmox"
version = "~> 0.66"
}
}
}
provider "proxmox" {
endpoint = var.proxmox_endpoint # https://host:8006/
api_token = var.proxmox_api_token # usuario@realm!tokenid=secret
insecure = true # Omite verificación TLS (cert. autofirmado)
}¶ 4.2. Variables
Las variables sensibles (token) se almacenan en terraform.tfvars, excluido del repositorio git mediante .gitignore.
variable "proxmox_endpoint" { type = string }
variable "proxmox_api_token" { type = string; sensitive = true }
variable "proxmox_node" { type = string; default = "proxmox4" }¶ 4.3. Autenticación — API Token
Los tokens de API de Proxmox siguen el formato:
<usuario>@<realm>!<nombre_token>=<uuid>Se generan en: Proxmox UI → Datacenter → API Tokens → Add
| El token debe tratarse como una contraseña. No debe incluirse en el repositorio git ni en logs de CI/CD. |
¶ 5. Creación del API Token en Proxmox VE
A continuación se documentan los pasos para crear un API Token desde la interfaz web de Proxmox VE, con capturas de pantalla de cada paso.
¶ 5.1. Paso 1 — Acceder a la sección de API Tokens
Desde la interfaz web de Proxmox, navegar a:
Datacenter → API Tokens → Add
En esta pantalla se muestra el listado de tokens existentes para todos los usuarios. Las columnas indican el usuario propietario, el nombre del token, la fecha de expiración, un comentario opcional y si tiene la separación de privilegios activada o no. Para crear uno nuevo, pulsar el botón Add.
¶ 5.2. Paso 2 — Rellenar el formulario de creación
Se abre un diálogo con los campos de configuración del token:
| Campo | Descripción |
|---|---|
User |
Usuario de Proxmox al que quedará vinculado el token. El token hereda el realm del usuario ( |
Token ID |
Nombre identificativo del token (sin espacios). Forma parte del identificador completo: |
Expire |
Fecha de expiración opcional. El valor |
Comment |
Campo libre para describir el propósito del token. |
Privilege Separation |
Casilla que controla si el token tiene permisos independientes del usuario. Ver explicación detallada a continuación. |
¶ 5.2.1. La casilla Privilege Separation
Esta casilla, destacada en la captura anterior, es el punto clave del modelo de seguridad del token:
Casilla MARCADA (activada): El token tiene su propio conjunto de permisos configurados mediante ACL, independientes del usuario. Los permisos efectivos son la intersección de los permisos del usuario y los del token. El token nunca puede superar los permisos de su usuario propietario. Esta es la opción más segura y la recomendada para entornos de producción o IaC, ya que limita el alcance del token al mínimo necesario.
Casilla DESMARCADA (desactivada): El token hereda directamente todos los permisos del usuario propietario, sin restricciones adicionales. No hace falta configurar ACL para el token. Es la opción más rápida para pruebas o entornos de desarrollo, pero implica que el token tiene el mismo nivel de acceso que el usuario completo.
| En este proyecto se desactivó la separación de privilegios para desbloquear el despliegue durante las pruebas. En un entorno de producción, se debería activar y configurar ACLs específicas con el mínimo de privilegios necesarios. |
¶ 5.3. Paso 3 — Guardar el secreto del token
Tras pulsar Add, Proxmox muestra el secreto del token una única vez:
El identificador completo del token sigue el formato usuario@realm!token-id y el secreto es el UUID que actúa como contraseña. Usar el botón Copy Secret Value para copiarlo y guardarlo de inmediato en un lugar seguro (por ejemplo, en terraform.tfvars que está excluido de git).
| Una vez cerrado este diálogo, el secreto no puede recuperarse. Si se pierde, es necesario eliminar el token y crear uno nuevo. |
¶ 6. Modelo de permisos en Proxmox VE
Proxmox VE permite gestionar los permisos de los API Tokens de dos formas distintas. Comprender la diferencia es clave para aplicar el principio de mínimo privilegio.
| Un API Token siempre está vinculado a un usuario. Los permisos efectivos del token dependen de cómo esté configurada la separación de privilegios. |
¶ 6.1. Separación de privilegios (Privilege Separation)
¶ 6.1.1. Activada (por defecto — comportamiento más seguro)
El token tiene sus propios permisos definidos mediante ACL de forma independiente al usuario. Los permisos efectivos son la intersección entre los permisos del usuario propietario y los permisos asignados directamente al token.
┌──────────────────────┐ ┌──────────────────────┐
│ Permisos usuario │ ∩ │ Permisos del token │ = Acceso efectivo
└──────────────────────┘ └──────────────────────┘
{A, B, C, D} {B, C, E} {B, C}| Aspecto | Detalle |
|---|---|
Ventaja |
El token nunca puede tener más permisos que su usuario. Ideal para producción y entornos IaC. |
Desventaja |
Requiere configurar ACL tanto para el usuario como para el token por separado. |
¶ 6.1.2. Desactivada
El token hereda directamente todos los permisos del usuario. No es necesario asignar ACL al token de forma independiente.
┌──────────────────────┐
│ Permisos usuario │ ──────────────────────────► Acceso efectivo
└──────────────────────┘
{A, B, C, D} {A, B, C, D}| Aspecto | Detalle |
|---|---|
Ventaja |
Configuración rápida y sencilla. |
Desventaja |
El token adquiere todos los permisos del usuario. Si el token se compromete, el impacto es mayor. |
¶ 6.2. ACL y Roles
Las ACL (Access Control Lists) de Proxmox asignan un Rol a una entidad (usuario o token) sobre un Path específico del árbol de objetos del clúster.
ACL = PATH + ENTIDAD (usuario / token) + ROL¶ 6.2.1. Paths principales
| Path | Objeto que controla |
|---|---|
|
Todo el clúster (raíz, se propaga hacia abajo) |
|
Nodo físico específico |
|
VM o contenedor específico |
|
Todas las VMs y contenedores |
|
Almacenamiento específico |
|
Pool de recursos |
|
Zona SDN específica (necesaria para conectar VMs a redes SDN) |
¶ 6.2.2. Roles predefinidos relevantes
| Rol | Privilegios incluidos (selección) |
|---|---|
|
|
|
|
|
|
|
|
|
Todos los privilegios (equivalente a administrador completo) |
¶ 6.2.3. Privilegios mínimos necesarios para este despliegue
| Path | Privilegios necesarios |
|---|---|
|
|
|
|
|
|
¶ 6.3. Comparativa
| Característica | Separación ACTIVADA | Separación DESACTIVADA |
|---|---|---|
Permisos del token |
ACL propias del token |
Hereda del usuario |
Permisos efectivos |
Intersección usuario ∩ token |
Los del usuario |
Riesgo si el token se compromete |
Bajo |
Alto |
Complejidad de configuración |
Alta |
Baja |
Recomendado para |
Producción / IaC |
Pruebas / desarrollo |
| En entornos de producción, usar separación de privilegios activada con un rol personalizado que contenga únicamente los privilegios necesarios para la tarea concreta. |
¶ 7. Problemas encontrados y soluciones
Durante el despliegue se encontraron los siguientes errores. Se documentan con su causa raíz y la solución aplicada.
¶ 7.1. Error #1 — Resolución DNS fallida
dial tcp: lookup informatica.ies-centro.org: no such hostCausa: El equipo no estaba conectado a la red del centro en el momento de ejecutar terraform apply. El hostname del servidor Proxmox solo es resolvible desde la red escolar.
Solución: Conectarse a la red del instituto (presencial o VPN) antes de ejecutar cualquier comando Terraform.
¶ 7.2. Error #2 — Sin permisos en el almacenamiento
received an HTTP 403 response
Reason: Permission check failed (/storage/local-zfs, Datastore.AllocateSpace)Causa: El API token tenía la separación de privilegios activada pero no tenía ninguna ACL asignada sobre /storage/local-zfs.
Solución: Desactivar la separación de privilegios del token (hereda los permisos del usuario) o asignar al token el rol PVEDatastoreUser sobre /storage/local-zfs.
¶ 7.3. Error #3 — Sin permisos para leer la configuración del disco
error get file local-zfs:vm-2000-disk-0 from datastore local-zfs:
received an HTTP 403 response
Reason: Permission check failed (/vms/2000, VM.Config.Disk)Causa: Tras crear la VM, el proveedor bpg/proxmox intenta leer de vuelta la configuración del disco para poblar el estado de Terraform. El token carecía del privilegio VM.Config.Disk sobre /vms/2000.
Solución: Asegurarse de que el token o su usuario dispone del privilegio VM.Config.Disk sobre /vms o /vms/<vmid>.
¶ 7.4. Error #4 — ID de VM duplicado (causa raíz real)
error creating VM: VM ID already in useCausa: Los IDs de VM probados (2000, 4000) ya estaban en uso por otras máquinas del clúster. Proxmox exige que el VM ID sea único en todo el clúster, no solo en el nodo destino.
Solución: Cambiar vm_id a un valor disponible, comprobándolo previamente en la interfaz web de Proxmox.
resource "proxmox_virtual_environment_vm" "fedora_workstation" {
vm_id = 4444 # Verificar disponibilidad en Proxmox UI antes de aplicar
...
}| Los errores #2 y #3 se persiguieron creyendo que eran la causa raíz. El problema real siempre fue el ID de VM duplicado. Al cambiar a un ID libre (4444), la VM se creó correctamente con los permisos ya disponibles. |
¶ 7.5. Error #5 — Sin permiso SDN al clonar (Fallo de SDN.Use en la plantilla)
Error: VM clone
All attempts fail:
#1: error cloning VM: received an HTTP 403 response
Reason: Permission check failed (/sdn/zones/localnetwork/vmbr0, SDN.Use)Causa: Al clonar una VM cuya plantilla tiene su interfaz de red (NIC) conectada a la zona SDN localnetwork (bridge vmbr0), Proxmox verifica el privilegio SDN.Use sobre esa zona de la plantilla origen antes de completar el clonado, aunque en main.tf el clon destino defina una red diferente (como bridge = "vmbr23").
Detalle del conflicto de permisos:
Inicialmente se intentó asignar el permiso directamente al token del API (alumno-asir@pve!token-terraform). Sin embargo, el despliegue seguía fallando. La causa raíz fue que el grupo de usuarios grupo-asir al que pertenece el usuario tiene asignada la regla NoAccess en la ruta /sdn/zones/localnetwork/vmbr0.
Al estar la separación de privilegios (Privilege Separation) activada en el API token, Proxmox calcula los permisos efectivos como la intersección entre los permisos del token y los de su usuario propietario:
Permisos Efectivos = Permisos del Usuario ∩ Permisos del TokenComo el bloqueo NoAccess heredado del grupo denegaba el privilegio al usuario, el token quedaba inhabilitado para usarlo, a pesar de tenerlo asignado individualmente.
Solución: Asignar el permiso directamente al usuario propietario del token (no al grupo y no solo al token), lo que anula la regla restrictiva de grupo para ese usuario en específico y permite que la intersección de permisos del token vuelva a ser válida.
Para aplicar esto en el servidor Proxmox, el administrador o un usuario con permisos suficientes (Permissions.Modify en /sdn/zones o en /) debe ejecutar:
pvesh set /access/acl \
--path /sdn/zones/localnetwork \
--users alumno-asir@pve \
--roles PVESDNUser \
--propagate 1Verificación de la solución: Se puede comprobar que el permiso se ha aplicado correctamente en el usuario listando las ACLs:
pvesh get /access/acl | grep localnetworkDeberá figurar una línea de tipo usuario (type = user) asignando el rol PVESDNUser al usuario alumno-asir@pve sobre el path /sdn/zones/localnetwork.
¶ 7.5.1. Notas para la investigación y auditoría del administrador (profesor)
Si desea auditar o investigar más a fondo la lógica de este fallo de permisos, se sugieren los siguientes puntos de inspección en el servidor Proxmox VE:
-
Configuración de usuarios y ACLs en disco:
Toda la política de accesos se almacena en el archivo
/etc/pve/user.cfg. Puede verificar cómo colisionan las reglas del grupo y del usuario buscando líneas del tipo:# Ejemplo de inspección directa del archivo de configuración grep -E "grupo-asir|localnetwork" /etc/pve/user.cfgPreste atención a las directivas
aclque contengangroup:grupo-asiry tengan asignado un rol restrictivo o carezcan de los permisos heredados necesarios. -
Cálculo de permisos con Privilege Separation en Proxmox:
Cuando el token se genera con separación de privilegios activa (
privsep: 1en la API/configuración), la fórmula de autorización sigue una regla estricta de intersección:Permisos del Token Efectivos = Permisos del Usuario ∩ Permisos Asignados al TokenSi una regla de grupo aplica
NoAccessen/sdn/zones/localnetwork/vmbr0, el usuario pierde ese privilegio en ese sub-path. Por lo tanto, aunque al token se le asigne explícitamente el rolPVESDNUsersobre/sdn/zones/localnetwork, la intersección de conjuntos de permisos dará como resultadoNoAccesspara el token.Asignar el rol directamente al usuario (
type: user) sobrescribe la herencia de grupo en Proxmox, ya que en la jerarquía de ACLs de PVE, los permisos explícitos de usuario tienen prioridad sobre las políticas generales de grupo. -
Alternativas de diseño de red para evitar el conflicto:
-
Ajuste en la plantilla origen: Si la plantilla clonada (
9000) no requiere estar vinculada al bridge administrativovmbr0delocalnetwork, el administrador puede editar el hardware de la plantilla y desconectar la tarjeta de red (o cambiarla de bridge a uno libre) antes de convertirla en template. Esto evita la necesidad de que los alumnos tengan permisosSDN.Usesobre zonas restringidas. -
Separación de privilegios desactivada: Para entornos aislados de pruebas, desactivar la separación de privilegios (
privsep: 0) hace que el token herede directamente el contexto completo del usuario. Si el usuario ya tiene el permiso adecuado por otros medios, el token funcionará sin ACLs dedicadas.
-
-
Monitoreo de logs de la API:
Para ver en tiempo real qué llamadas realiza Terraform contra la API de Proxmox y qué códigos HTTP retorna, el administrador puede monitorizar los logs del servicio web:
# Ver peticiones REST en tiempo real tail -f /var/log/pveproxy/access.log | grep -E "clone|qemu"Un código HTTP
403seguido del endpoint de la API REST indica un fallo de validación de ACLs durante el proceso de clonado en el endpoint:POST /api2/json/nodes/<nodo>/qemu/<vmid_plantilla>/clone
¶ 7.6. Error #6 — Storage local-lvm no existe
Error: All attempts fail:
#1: the requested resource does not exist
received an HTTP 500 response - Reason: storage 'local-lvm' does not existCausa: El bloque initialization del proveedor bpg/proxmox usa local-lvm como datastore por defecto para el disco de cloud-init. En el clúster escolar ese storage no existe — el disponible es local-zfs.
Solución: Añadir datastore_id = "local-zfs" explícitamente en el bloque initialization:
initialization {
datastore_id = "local-zfs" # Obligatorio si local-lvm no existe en el clúster
user_account {
username = "debian"
keys = [var.sshkeys]
}
...
}¶ 8. Gestión de permisos mediante la API REST
Cuando la interfaz web de Proxmox no muestra la pestaña Permissions (por permisos insuficientes en la UI), los permisos pueden gestionarse directamente a través de la API REST de Proxmox usando curl o Python.
¶ 8.1. Obtener un ticket de sesión
curl -sk -X POST "https://<host>:8006/api2/json/access/ticket" \
-d "username=<usuario>@pve&password=<contraseña>"La respuesta incluye ticket (cookie de sesión) y CSRFPreventionToken (necesario para operaciones de escritura), además del objeto cap con los privilegios efectivos del usuario.
¶ 8.2. Consultar los privilegios actuales
El objeto cap de la respuesta del ticket muestra todos los privilegios del usuario agrupados por categoría:
{
"vms": { "VM.Clone": 1, "VM.Allocate": 1, ... },
"dc": { "SDN.Use": 1, "SDN.Audit": 1 },
"sdn": { "SDN.Use": 1, "SDN.Audit": 1 },
"storage":{ "Datastore.AllocateSpace": 1, ... },
"access": { "Permissions.Modify": 1 }
}
El objeto cap refleja los privilegios del usuario, no del token. Si el token tiene separación de privilegios activada, sus permisos efectivos pueden ser un subconjunto.
|
¶ 8.3. Añadir una ACL mediante la API
import requests, urllib3
urllib3.disable_warnings()
base = "https://<host>:8006/api2/json"
# Paso 1 — obtener ticket
r = requests.post(f"{base}/access/ticket",
data={"username": "<usuario>@pve", "password": "<contraseña>"},
verify=False)
d = r.json()["data"]
ticket, csrf = d["ticket"], d["CSRFPreventionToken"]
# Paso 2 — añadir ACL
r2 = requests.put(f"{base}/access/acl",
headers={"CSRFPreventionToken": csrf},
cookies={"PVEAuthCookie": ticket},
data={
"path": "/sdn/zones/localnetwork",
"roles": "PVESDNUser",
"tokens": "<usuario>@pve!<token-id>",
"propagate": "1"
},
verify=False)
print(r2.status_code, r2.text) # 200 {"data":null} = éxito
Se usa Python en lugar de curl para evitar problemas de escape con caracteres especiales (!, +) en la shell zsh.
|
¶ 8.4. Limitación del privilegio Permissions.Modify
El privilegio Permissions.Modify solo permite modificar ACL en los paths sobre los que se ha concedido. Si está asignado únicamente en /access, no alcanza a /sdn/zones/…, /storage/… ni /pool/….
Path donde se concede Permissions.Modify |
Puede modificar ACL en… |
|---|---|
|
Cualquier path del clúster |
|
Solo paths bajo |
|
Solo paths bajo |
Si se recibe un 403 Permission check failed (/sdn/zones/localnetwork, Permissions.Modify), significa que el usuario puede gestionar permisos en /access pero no en rutas SDN. En ese caso, debe solicitarlo al administrador del clúster.
¶ 9. Configuración final
Fichero create/main.tf definitivo que despliega correctamente las VMs Fedora y Ubuntu:
terraform {
required_providers {
proxmox = {
source = "bpg/proxmox"
version = "~> 0.66"
}
}
}
provider "proxmox" {
endpoint = var.proxmox_endpoint
api_token = var.proxmox_api_token
insecure = true
}
resource "proxmox_virtual_environment_vm" "fedora_workstation" {
name = "fedora-workstation"
node_name = var.proxmox_node
vm_id = 4444
pool_id = "pool-asir-tfg"
started = false
on_boot = false
cpu {
cores = 2
sockets = 1
type = "x86-64-v2-AES"
}
memory {
dedicated = 4096
}
disk {
datastore_id = "local-zfs"
size = 40
interface = "virtio0"
file_format = "raw"
}
network_device {
bridge = "vmbr23"
model = "virtio"
}
cdrom {
file_id = var.fedora_iso
interface = "ide2"
}
boot_order = ["ide2", "virtio0"]
operating_system {
type = "l26"
}
vga {
type = "std"
memory = 16
}
}
resource "proxmox_virtual_environment_vm" "ubuntu-server" {
name = "ubuntu-server"
node_name = var.proxmox_node
vm_id = 4445
pool_id = "pool-asir-tfg"
started = false
on_boot = false
cpu {
cores = 2
sockets = 1
type = "x86-64-v2-AES"
}
memory {
dedicated = 4096
}
disk {
datastore_id = "local-zfs"
size = 40
interface = "virtio0"
file_format = "raw"
}
network_device {
bridge = "vmbr23"
model = "virtio"
}
cdrom {
file_id = var.ubuntu_iso
interface = "ide2"
}
boot_order = ["ide2", "virtio0"]
operating_system {
type = "l26"
}
vga {
type = "std"
memory = 16
}
}¶ 10. Resultado
VMs desplegadas correctamente con los siguientes parámetros:
| Parámetro | VM Fedora | VM Ubuntu |
|---|---|---|
Nombre |
|
|
VM ID |
|
|
Nodo |
|
|
Pool |
|
|
CPU |
2 vCPUs — |
2 vCPUs — |
RAM |
4096 MB (4 GB) |
4096 MB (4 GB) |
Disco |
40 GB — |
40 GB — |
Red |
|
|
Unidad CD-ROM |
|
|
Arranque |
|
|
Estado inicial |
Apagada ( |
Apagada ( |
Arranque automático |
Desactivado ( |
Desactivado ( |
¶ 11. Módulo clone — Clonado de máquinas virtuales
Además del despliegue desde cero, el proyecto incluye un segundo módulo (clone/) que clona una VM a partir de una plantilla existente en Proxmox y la configura mediante cloud-init.
¶ 11.1. Estructura del módulo
clone/
├── main.tf (1)
├── variables.tf (2)
└── terraform.tfvars (3)| 1 | Recurso VM con bloque clone y configuración cloud-init. |
| 2 | Variables del proveedor y del template origen. |
| 3 | Valores de las variables (excluido de git). |
¶ 11.2. Diferencias respecto al módulo create/
| Aspecto | Módulo create/ |
Módulo clone/ |
|---|---|---|
Origen de la VM |
Desde cero (sin imagen base Terraform) |
Clonado de una plantilla existente en Proxmox |
Disco |
Bloque |
Heredado de la plantilla; no se define |
Cloud-init |
No aplica |
Bloque |
Permisos adicionales necesarios |
— |
|
¶ 11.3. Permisos necesarios para el clonado
| Path | Rol / Privilegio |
|---|---|
|
|
|
|
|
|
|
|
¶ 11.4. Configuración del módulo clone
terraform {
required_providers {
proxmox = {
source = "bpg/proxmox"
version = "~> 0.66"
}
}
}
provider "proxmox" {
endpoint = var.proxmox_endpoint
api_token = var.proxmox_api_token
insecure = true
}
resource "proxmox_virtual_environment_vm" "bastion" {
name = "debian-copiada"
node_name = var.proxmox_node # proxmox4
vm_id = 1312
pool_id = "pool-asir-tfg"
clone {
vm_id = var.proxmox_template_vmid # ID de la plantilla origen
full = true # Clonado completo (no linked clone)
}
cpu {
cores = 2
sockets = 2
}
memory {
dedicated = 4096
}
agent {
enabled = true # Requiere qemu-guest-agent instalado en la plantilla
}
network_device {
bridge = "vmbr23"
model = "virtio"
}
initialization {
datastore_id = "local-zfs" # Obligatorio si local-lvm no existe
user_account {
username = "debian"
keys = [var.sshkeys]
}
ip_config {
ipv4 {
address = "dhcp"
}
}
vendor_data_file_id = "local:snippets/qemu-guest-agent.yml" (1)
}
}| 1 | Fichero de cloud-init para activar el guest agent. Debe existir previamente en el storage local del nodo Proxmox bajo Snippets. |
¶ 11.5. Variables del módulo clone
variable "proxmox_endpoint" { type = string }
variable "proxmox_api_token" { type = string; sensitive = true }
variable "proxmox_node" { type = string; default = "proxmox4" }
variable "sshkeys" { type = string; sensitive = true }
variable "proxmox_template_vmid" { type = number } # ID de la plantilla a clonar¶ 12. Conclusión
Se ha conseguido desplegar de forma exitosa una máquina virtual Fedora en Proxmox VE utilizando Terraform como herramienta de IaC.
Los principales aprendizajes de este proceso son:
-
Modelo de permisos de Proxmox: La diferencia entre separación de privilegios activada y desactivada es fundamental. Para entornos reales se recomienda activarla y asignar ACLs específicas con el mínimo de privilegios necesarios para cada tarea.
-
Unicidad del VM ID: El ID de VM debe ser único en todo el clúster Proxmox, no solo en el nodo destino. Conviene verificarlo en la interfaz web antes de definirlo en el código Terraform.
-
Conectividad de red: El endpoint de Proxmox puede no ser resolvible desde redes externas. Es necesario estar en la red del centro o usar una VPN antes de ejecutar Terraform.
-
Infraestructura como Código: Terraform permite describir la infraestructura de forma declarativa, versionable y reproducible. Con un simple
terraform applyse puede recrear el entorno completo de forma idéntica, lo que facilita la automatización y la auditabilidad. -
Permisos SDN en clonado: Al clonar una VM, Proxmox verifica los permisos SDN de la plantilla origen, no solo los de la configuración destino. Es necesario conceder
SDN.Useal token sobre la zona SDN correspondiente aunque el bridge final sea diferente. -
API REST de Proxmox: Cuando la interfaz web no muestra ciertas opciones por falta de permisos en la UI, la API REST permite realizar las mismas operaciones. El privilegio
Permissions.Modifysolo alcanza los paths sobre los que está concedido, por lo que gestionar ACL en rutas como/sdn/zonespuede requerir intervención del administrador. -
Defaults del proveedor bpg/proxmox: Algunos parámetros como
datastore_iden el bloqueinitializationtienen valores por defecto (local-lvm) que pueden no existir en el clúster destino. Siempre es recomendable declararlos explícitamente.