OpenTofu: gestione su flota de VPS con Infrastructure as Code

Por qué OpenTofu en lugar de seguir con SSH manual

Lo que gana con un estado declarativo

• Inventario fiable — el archivo terraform.tfstate dice exactamente qué servidores existen, con qué IP y qué atributos, sin tener que conectarse a cada uno.
• Reproducibilidad — un nuevo cliente o un nuevo proyecto recibe el mismo VPS configurado de la misma forma, desde el mismo archivo .tf versionado en Git.
• Destrucción limpia — tofu destroy retira los recursos en el orden correcto, sin dejar servidores huérfanos que se siguen facturando.
• Diff legible — tofu plan muestra exactamente lo que se creará, modificará o destruirá antes de actuar, como un git diff de su infraestructura.
• Complementariedad con Ansible — OpenTofu crea el VPS y coloca los metadatos (clave SSH, nombre, red); Ansible toma el relevo para desplegar Docker, Nginx y sus aplicaciones.
• Versionable y auditable — su infraestructura se convierte en un repositorio Git con commits, revisiones de código y un historial de cambios.
• Licencia open source duradera — OpenTofu está bajo MPL-2.0, sin restricción comercial, con una gobernanza comunitaria bajo la CNCF.

Requisitos previos antes de empezar

Implementar OpenTofu en una flota de VPS

1. 01

   Instalar OpenTofu en local

   Diríjase a opentofu.org/docs/intro/install para las instrucciones según su OS. En macOS con Homebrew: brew install opentofu. En Debian/Ubuntu: el repositorio oficial de OpenTofu proporciona el paquete opentofu. Verifique la instalación con tofu version — el comando debe devolver la versión instalada.

2. 02

   Estructurar su proyecto Infrastructure as Code

   Cree un directorio dedicado y cuatro archivos estándar.

   # main.tf — recursos principales
   # variables.tf — declaraciones de variables
   # outputs.tf — valores expuestos tras el apply
   # terraform.tfvars — valores concretos (añadir a gitignore si son secretos)

   Esta estructura no es obligatoria para OpenTofu, pero es la convención ampliamente adoptada: main.tf contiene los recursos, variables.tf declara los tipos y valores por defecto, outputs.tf expone lo que Ansible u otra herramienta debe leer tras el aprovisionamiento (IP del servidor, nombre de host…), y terraform.tfvars contiene los valores concretos que no desea codificar de forma fija en main.tf.

3. 03

   Declarar el provider y generar una clave SSH

   OpenTofu instala los providers necesarios en el tofu init. El provider hashicorp/tls genera un par de claves SSH en local, lo que evita gestionar claves manualmente.

   terraform {
     required_providers {
       tls = {
         source  = "hashicorp/tls"
         version = "~> 4.0"
       }
     }
   }
   
   resource "tls_private_key" "vps_key" {
     algorithm = "ED25519"
   }
   
   output "private_key_pem" {
     value     = tls_private_key.vps_key.private_key_pem
     sensitive = true
   }

   Lance tofu init para descargar el provider y luego tofu apply para generar la clave. Recupérela con tofu output -raw private_key_pem > ~/.ssh/vps_key && chmod 600 ~/.ssh/vps_key.

4. 04

   Aprovisionar el VPS con null y local-exec

   Si su proveedor de VPS no tiene un provider OpenTofu oficial, el provider hashicorp/null con un local-exec permite ejecutar un comando local (una llamada API con curl, un script shell) y modelar el recurso en el state.

   resource "null_resource" "vps_provision" {
     triggers = {
       server_name = var.server_name
     }
   
     provisioner "local-exec" {
       command = <<EOT
         curl -s -X POST https://api.votre-fournisseur.com/v1/servers \
           -H "Authorization: Bearer ${var.api_token}" \
           -d '{"name": "${var.server_name}", "image": "ubuntu-22.04"}'
       EOT
     }
   }

   Este patrón es adecuado para una fase transitoria. Si su proveedor expone una API REST, basta con un script shell llamado en local-exec para crear el servidor y escribir su IP en un archivo que outputs.tf expondrá después.

5. 05

   Pilotar Docker en el VPS con el provider kreuzwerker

   Una vez aprovisionado el VPS e instalado Docker (por Ansible, normalmente), el provider kreuzwerker/docker le permite declarar contenedores, redes y volúmenes en OpenTofu.

   terraform {
     required_providers {
       docker = {
         source  = "kreuzwerker/docker"
         version = "~> 3.0"
       }
     }
   }
   
   provider "docker" {
     host = "ssh://root@${var.server_ip}:22"
   }
   
   resource "docker_container" "app" {
     name  = "mon-app"
     image = docker_image.app.image_id
   }
   
   resource "docker_image" "app" {
     name = "nginx:alpine"
   }

   El provider se conecta al daemon Docker del VPS por SSH — ningún puerto TCP adicional que abrir. La versión estable del provider está disponible en el Terraform Registry.

6. 06

   Versionar el state para un equipo

   En desarrollo en solitario, el state local (terraform.tfstate) basta. En equipo o en CI/CD, dos desarrolladores que lanzan tofu apply a la vez corrompen el state. La solución es un backend remoto con bloqueo.

   OpenTofu soporta de forma nativa S3 (AWS, MinIO autoalojado) y el GitLab Managed Terraform State. Con un bucket MinIO en un VPS:

   terraform {
     backend "s3" {
       bucket                      = "tofu-state"
       key                         = "production/terraform.tfstate"
       region                      = "eu-west-1"
       endpoint                    = "https://minio.votre-domaine.com"
       skip_credentials_validation = true
       skip_metadata_api_check     = true
       skip_region_validation      = true
       force_path_style            = true
     }
   }

   El bloqueo es automático: si hay un tofu apply en curso, un segundo se rechaza hasta que termine el primero.

7. 07

   Integrar OpenTofu en su pipeline CI/CD

   Un pipeline típico de Woodpecker CI o Forgejo Actions ejecuta tofu plan en cada pull request (para revisión humana del diff de infraestructura) y tofu apply al hacer merge en la rama principal.

   steps:
     - name: tofu-plan
       image: ghcr.io/opentofu/opentofu:latest
       commands:
         - tofu init
         - tofu plan -out=tfplan
   
     - name: tofu-apply
       image: ghcr.io/opentofu/opentofu:latest
       commands:
         - tofu apply tfplan
       when:
         branch: main
         event: push

   El state remoto (paso anterior) es indispensable aquí: el runner de CI no tiene acceso al state local de su equipo.

Ansible y OpenTofu: la frontera entre ambos

Solución de problemas: los errores frecuentes

Errores comunes y su corrección

• Error acquiring the state lock — un fallo durante un apply deja un archivo .terraform.tfstate.lock.info en el backend. OpenTofu se niega a continuar mientras exista el bloqueo. Tras comprobar que ningún otro apply está en curso, elimine el bloqueo con tofu force-unlock <LOCK_ID> (el ID aparece en el mensaje de error). En un backend S3/MinIO, el archivo es visible en el bucket.
• tofu plan muestra un destroy + create inesperado — algunos atributos de un recurso fuerzan una recreación (force new resource) cuando cambian: el nombre del servidor, el tipo de imagen del OS, la región. Si modifica uno de esos atributos, OpenTofu no puede hacer una actualización en el sitio — destruye y vuelve a crear. Lea el plan con atención antes de aplicar y utilice tofu plan -target=resource.name para limitar el alcance.
• State perdido o desincronizado — si el archivo de state se pierde y los servidores siguen existiendo, tofu state list enumera lo que OpenTofu cree aprovisionado, y tofu import <resource.type.name> <id-externe> importa un recurso existente en el state sin volver a crearlo. Es la herramienta de recuperación cuando la realidad y el state han divergido.
• Provider no encontrado tras tofu init — compruebe que el source del provider es exacto (p. ej. kreuzwerker/docker y no docker/docker) y que tiene acceso a internet desde la máquina que lanza tofu init. En un entorno air-gapped, descargue los providers por adelantado y utilice plugin_cache_dir.
• Error: No valid credential sources found — OpenTofu no encuentra las credenciales del provider. Compruebe las variables de entorno que espera el provider (a menudo TF_VAR_api_token o un archivo de credenciales específico) y que terraform.tfvars se lee correctamente (debe estar en el mismo directorio que main.tf).

Su infraestructura se convierte en código versionado