Usar Terraform con Proxmox

Terraform es una herramienta de infraestructura como código desarrollada por HashiCorp que permite provisionar y gestionar infraestructura de manera automatizada a través de archivos de configuración declarativos. Con Terraform, en lugar de configurar manualmente servidores, redes, y otros recursos, se puede describir tu infraestructura en un archivo de texto que luego se puede aplicar para crear o modificar esos recursos de manera consistente y predecible.

Instalación

Para proceder con la instalación se siguen los pasos indicados en la documentación oficial. Resumiendo los pasos, son los siguientes:

wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list

sudo apt update && sudo apt install terraform

Por otro lado, hará falta tener instalado los siguientes paquetes:

go: https://go.dev/doc/install
goreleaser: https://goreleaser.com/install/#scoop

Configuración en Proxmox

Para poder autenticarnos contra Proxmox es necesario usar un usuario para ello. En este caso, se creará un usuario, con nombre Terraform. Para ello, desde la interfaz web del Proxmox procedemos a añadir un nuevo usuario:

Para el uso de este usuario con Terraform, se neceitará autenticarse contra el proxmox usando Usuario y contraseña o bien un API Key. Con el fin de probar la opción más segura, se creará una API Key.
Esta se puede generar desde la opción de «API Tokens« que se puede ver en la captura anterior, justo debajo de «Users».

Con el usuario y la API Key generada, solo queda un paso previo en el Proxmox para poder empezar a usar terraform. En primer lugar, se crea un rol para esto, tal y como indica la documentación:

pveum role add TerraformProv -privs "Datastore.AllocateSpace Datastore.Audit Pool.Allocate Sys.Audit Sys.Console Sys.Modify VM.Allocate VM.Audit VM.Clone VM.Config.CDROM VM.Config.Cloudinit VM.Config.CPU VM.Config.Disk VM.Config.HWType VM.Config.Memory VM.Config.Network VM.Config.Options VM.Migrate VM.Monitor VM.PowerMgmt SDN.Use"

Por último, se añade el usuario creado al nuevo rol:

pveum aclmod / -user terraform@pam -role TerraformProv

Se puede comprobar los permisos del usuario desde la interfaz web:

Configuración en Terraform

Para explicar los conceptos más básicos de Terraform, partiremos de un ejemplo de main.tf pero… Que es esto de main.tf? Esto es un archivo de configuración donde se define la infraestructura que se quiere gestionar.

Estos archivos están escritos en lenguaje HCL (HashiCorp). Dentro de estos ficheros puedes encontrar lo siguiente:

Proovedores
Recursos
Variables
Módulos
Outputs

Para ejemplificar todo esto, se hará sobre un fichero de prueba:

# Definición del proveedor Proxmox
terraform {
  required_providers {
    proxmox = {
      source  = "telmate/proxmox"                                                                                     
      version = "3.0" 
    }
  }
}

# Configuración del proveedor Proxmox
provider "proxmox" {
  pm_api_url    = "https://192.168.1.106:8006/api2/json"
  pm_api_token_id = "terraform@pam!terraform"
  pm_api_token_secret = "XXXXXXXXXXXXXXXXXXXXXXXXX"
  pm_tls_insecure = true
}

# Definición de un recurso: una máquina virtual
resource "proxmox_lxc" "debian_ct" {
  hostname      = "debian-ct"   #Nombre del contenedor
  target_node   = "pve"         # Nodo de Proxmox donde se desplegar el CT
  ostemplate    = "local:vztmpl/debian-11.0-standard_11.7-1_amd64.tar.gz"  
  rootfs {
    storage     = "local-lvm"   # Almacenamiento para el sistema de archivos raiz
    size        = "8G"          # Tam disco raiz
  }
  cores         = 1             # Numero de CPUs
  memory        = 512           # Memoria en MB
  network {
    name        = "eth0"        # Nombre de la interfaz de red
    bridge      = "vmbr0"       # Bridge de red en Proxmox
    ip          = "dhcp"        # Configuracion de red
  }
}

Este fichero está compuesto en 3 bloques, los 2 últimos hacen referencia a la conexión contra el Proxmox y el recuros que queremos crear. En este caso una VM con 2 CPUs, 2 GB de RAM usando una plantilla de Ubuntu y en que nodo de Proxmox queremos crearla.

Lo importante de entender de este fichero es lo que se define en el primer bloque de código. Sobre este se define el provedor que se va a usar.

Un proveedor en Terraform es un plugin que permite a Terraform interactuar con diferentes APIs para gestionar y provisionar infraestructura. Cada proveedor le dice a Terraform cómo gestionar e interactuar con una plataforma en concreto, como Proxmox, Azure, AWS,…

Por esto, se indica en el fichero de configuración de donde puede sacar la información Terraform para interacturar correctamente con el proveedor que le indicamos.

Para este laboratorio, se ha instalado el proveedor de Promox, el cual se ha hecho mediante el siguiente GitHub:

https://github.com/Telmate/terraform-provider-proxmox

Uso de Terraform

Una vez tenemos el proveedor instalado, el fichero de configuración creado, Proxmox configurado y la paquetería necesaria instalada, podemso proceder a desplegar infraestructura. Para ello, primero ejecutamos lo siguiente:

root@vision:~/terraform# terraform init

Initializing the backend...
Initializing provider plugins...
- Finding telmate/proxmox versions matching ">= 1.0.0"...
- Installing telmate/proxmox v2.9.14...
- Installed telmate/proxmox v2.9.14 (self-signed, key ID A9EBBE091B35AFCE)
Partner and community providers are signed by their developers.
If you'd like to know more about provider signing, you can read about it here:
https://www.terraform.io/docs/cli/plugins/signing.html
Terraform has made some changes to the provider dependency selections recorded
in the .terraform.lock.hcl file. Review those changes and commit them to your
version control system if they represent changes you intended to make.

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

En segundo lugar, ejecutamos lo siguiente:

root@vision:~/terraform# terraform plan

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # proxmox_lxc.debian_ct will be created
  + resource "proxmox_lxc" "debian_ct" {
      + arch         = "amd64"
      + cmode        = "tty"
      + console      = true
      + cores        = 1
      + cpulimit     = 0
      + cpuunits     = 1024
      + hostname     = "debian-ct"
      + id           = (known after apply)
      + memory       = 512
      + onboot       = false
      + ostemplate   = "local:vztmpl/debian-11.0-standard_11.7-1_amd64.tar.gz"
      + ostype       = (known after apply)
      + protection   = false
      + start        = false
      + swap         = 0
      + target_node  = "pve"
      + tty          = 2
      + unprivileged = false
      + unused       = (known after apply)
      + vmid         = (known after apply)

      + network {
          + bridge = "vmbr0"
          + hwaddr = (known after apply)
          + ip     = "dhcp"
          + name   = "eth0"
          + tag    = (known after apply)
          + trunks = (known after apply)
          + type   = (known after apply)
        }

      + rootfs {
          + size    = "8G"
          + storage = "local-lvm"
          + volume  = (known after apply)
        }
    }

Plan: 1 to add, 0 to change, 0 to destroy.

Esto sacará el «plan» que tiene terraform para crear la máquina a crear.

Por último, se ejecutará lo siguiente:

root@vision:~/terraform# terraform apply

Esto mostrará el plan de nuevo y pedirá confirmar la ejecución. Finalmente, esta es la salida esperada:


proxmox_lxc.debian_ct: Creating...
proxmox_lxc.debian_ct: Creation complete after 9s [id=pve/lxc/112]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Desde la interfaz web de Promox se puede ver como está creada: