Terraform Docker: Una guía completa

He dedicado innumerables horas a gestionar manualmente contenedores Docker en entornos de desarrollo y producción. Las configuraciones incompatibles, los estados cambiantes y la incertidumbre sobre si mi configuración local coincidía con la de producción afectaban a cada implementación. Cuando descubrí el proveedor Docker de Terraform, todo cambió.

En este tutorial, te guiaré a través de la integración de Terraform con Docker para crear una infraestructura reproducible y con control de versiones. Aprenderás a aprovisionar contenedores, gestionar redes y volúmenes, implementar restricciones de recursos y mantener el estado en todo tu equipo.

Tanto si gestionas servidores de compilación como si coordinas microservicios, coge tu terminal y transformemos tu forma de gestionar la infraestructura de Docker.

Si eres nuevo en Docker, te recomiendo que comiences con nuestro curso Introducción a Docker.

¿Qué es la integración de Terraform Docker?

Terraform es una herramienta de infraestructura como código que gestiona los ciclos de vida de los recursos a través de un flujo de trabajo declarativo. En lugar de ejecutar comandos Docker individuales, defines el estado deseado de la infraestructura en archivos de configuración. A continuación, Terraform ejecuta un ciclo de vida de planificación, aplicación y destrucción: calcula los cambios necesarios, muestra una vista previa y los aplica solo después de su aprobación.

El servidor Terraform Docker provider actúa como capa de traducción entre el código HashiCorp Configuration Language (HCL) y la API de Docker. Al escribir resource “docker_container" en una configuración, el proveedor convierte esa declaración en las llamadas API de Docker adecuadas. Esta abstracción significa que los recursos de Docker se pueden gestionar utilizando el mismo flujo de trabajo que se utiliza para la infraestructura en la nube.

Aquí es donde Terraform se diferencia de Docker Compose.

Aunque Compose gestiona los contenedores mediante un enfoque basado en proyectos que utiliza archivos YAML, no mantiene un archivo de estado que haga un seguimiento de lo que realmente existe. 

Terraform, por el contrario, registra todos los recursos que crea en terraform.tfstate, lo que te permite detectar desviaciones entre tu configuración y la realidad. Si alguien modifica manualmente un contenedor, Terraform lo detectará y podrá restaurarlo al estado definido.

Este enfoque destaca en varios escenarios:

• En el caso de los servidores de compilación reproducibles, puedes destruir y recrear todo el entorno con un solo comando, lo que garantiza la coherencia. 
• En entornos de prueba, puedes crear una infraestructura aislada para cada ejecución de prueba. 
• En el caso de las implementaciones inmutables, se sustituyen los contenedores por completo en lugar de modificarlos in situ, lo que reduce los riesgos de implementación.

Requisitos previos e instalación

Antes de profundizar en las configuraciones de Terraform, comprueba que las herramientas necesarias estén instaladas y configuradas correctamente.

Cumplimiento de los requisitos del sistema

En primer lugar, comprueba que Docker Engine se está ejecutando en tu máquina. 

• Linux: Consulta con docker ps

• macOS o Windows: Asegúrate de que Docker Desktop esté instalado y en ejecución.

El proveedor Terraform necesita acceder al demonio Docker, por lo que debes confirmar que tu usuario tiene permiso para acceder al socket Unix en /var/run/docker.sock en Linux o al canal con nombre en Windows.

A continuación, instala la CLI de Terraform desde el sitio web oficial de HashiCorp. La instalación de Terraform varía segúnel sistema operativo:

• Linux: Descarga el paquete adecuado o utiliza el gestor de paquetes de tu distribución. 

• macOS: Utiliza Homebrew. En primer lugar, instala el tap de HashiCorp utilizando brew tap hashicorp/tap y, a continuación, instala Terraform con el comando brew install hashicorp/tap/terraform. 

• Ventanas: Descarga el binario desde hashicorp.com y añádelo a tu PATH, o utiliza Chocolatey: choco install terraform. 

Una vez instalado, verifica la instalación ejecutando terraform version. 

Una vez verificados Docker y Terraform, el siguiente paso es organizar los archivos del proyecto para facilitar su mantenimiento.

Configuración de la estructura del proyecto

Los proyectos de Terraform se benefician de un enfoque claro y estructurado. Por lo general, creas un directorio específico para tu proyecto Terraform e inicializas el control de versiones:

mkdir terraform-docker-project
cd terraform-docker-project
git init

El control de versiones es fundamental para la infraestructura como código. Cada cambio en la infraestructura de Docker debe ser rastreado, revisado y reversible. Normalmente añado el directorio de trabajo y los archivos de estado de Terraform alarchivoo alarchivo .gitignore para excluirlos del control de versiones:

.terraform/
*.tfstate
*.tfstate.backup
.terraform.lock.hcl

Por último, creas un archivo main.tf en blanco donde definirás tu infraestructura. Este archivo contendrá la configuración del proveedor y las definiciones de recursos.

Proveedor Terraform Docker y recursos básicos

Una vez establecida la estructura del proyecto, es hora de configurar el proveedor Docker y empezar a definir los recursos.

Inicializando el proveedor Docker

Primero, añadiendo la configuración del proveedor a main.tf:

terraform {
  required_providers {
    docker = {
      source  = "kreuzwerker/docker"
      version = "~> 3.0"
    }
  }
}

provider "docker" {
  host = "unix:///var/run/docker.sock"
}

El bloque « required_providers » especifica dónde debe descargar Terraform el complemento del proveedor. El uso de restricciones de versión (~> 3.0) permite actualizaciones menores de la versión, al tiempo que evita cambios importantes. Para hosts Docker remotos, puedes cambiar el parámetro host por algo como tcp://192.168.1.100:2376.

Ahora ejecuta terraform init en el directorio raíz del proyecto. Esto descarga el complemento del proveedor Docker y lo almacena en .terraform/providers/. El comando muestra la versión exacta instalada y Terraform crea un archivo de bloqueo para garantizar la coherencia de las versiones del proveedor en todo tu equipo.

Gestión de imágenes de contenedores

Una vez inicializado el proveedor, el siguiente paso es definir las imágenes del contenedor. Antes de crear contenedores, debes gestionar las imágenes que utilizarán, por lo que debes definir un recurso de imagen:

resource "docker_image" "nginx" {
  name         = "nginx:1.29"
  keep_locally = true
}

Añade este recurso directamente después del bloque del proveedor. El parámetro « keep_locally » es importante, ya que evita que Terraform elimine la imagen cuando ejecutas « terraform destroy ». Esto resulta útil cuando varios contenedores comparten la misma imagen o cuando se desea conservar las imágenes almacenadas en caché entre implementaciones.

Para implementaciones de producción, fija las imágenes mediante su resumen SHA256 para garantizar la inmutabilidad:

resource "docker_image" "nginx" {
 name = "nginx@sha256:b60f25eb5acdd79172de1a289891d9cfe4fc3669daddeeb68619240cbe839d9f"
}

El resumen se puede obtener en el registro de contenedores. Las imágenes de Docker Hub como nginx se pueden encontrar en el sitio web oficial de Docker, en la sección Etiquetas. El uso de resúmenes garantiza que siempre se implemente exactamente el mismo binario de imagen, incluso si alguien envía unanueva imagen con la misma etiqueta.

Aprovisionamiento de contenedores Docker

Una vez definidas las imágenes, el siguiente paso es crear contenedores que hagan referencia a ellas:

resource "docker_container" "web" {
  name  = "nginx-web"
  image = docker_image.nginx.image_id

  ports {
    internal = 80
    external = 8080
  }

  env = [
    "NGINX_HOST=example.com",
    "NGINX_PORT=80"
  ]
}

La imagen se referencia utilizando docker_image.nginx.image_id. Esto crea una dependencia implícita, ya que Terraform no intentará crear el contenedor hasta que exista la imagen. El bloque « ports » asigna el puerto interno 80 del contenedor al puerto 8080 de tu host, equivalente a docker run -p 8080:80.

Las variables de entorno se incluyen en la lista env como cadenas. Terraform volverá a crear el contenedor si cambia alguno de los parámetros, lo que garantiza que la infraestructura en ejecución siempre coincida con la configuración.

En este punto, ejecuta terraform plan para ver lo que Terraform creará y, a continuación, terraform apply para aprovisionar la infraestructura. Terraform creará la imagen y el contenedor. Puedes verificarlo comprobando el recurso en Docker Desktop o ejecutando « docker ps » en la terminal.

Redes, almacenamiento y límites de recursos en Terraform

Ahora que ya tienes un contenedor básico en funcionamiento y comprendes el flujo de trabajo principal, vamos a ampliar la infraestructura con funciones listas para la producción. Las siguientes secciones se basan en estos fundamentos y añaden redes, almacenamiento persistente y restricciones de recursos, todos ellos elementos esenciales para las implementaciones en el mundo real.

Gestión de redes

Para permitir la comunicación entre contenedores y mantener al mismo tiempo el aislamiento, es esencial crear redes dedicadas. A continuación se explica cómo crear redes aisladas para controlar la conectividad de los contenedores. Añade el siguiente recurso al archivo main.tf:

resource "docker_network" "app_network" {
  name   = "application_net"
  driver = "bridge"
}

Ahora añade un segundo contenedor que utilice esta red. Añade esto después del contenedor web:

resource "docker_container" "api" {
  name  = "api-server"
  image = docker_image.nginx.image_id

  networks_advanced {
    name = docker_network.app_network.name
  }
}

Esto crea una red puente dedicada y conecta el contenedor api a ella. Los contenedores de la misma red pueden comunicarse utilizando sus nombres de contenedor como nombres de host, lo que resulta perfecto para arquitecturas de microservicios. 

Verifica el aislamiento de la red ejecutando docker network inspect application_net y confirmando que solo estén conectados los contenedores previstos. Asegúrate de ejecutar este comando después de crear los recursos utilizando terraform plan y terraform apply.

Una vez configurada la red para la comunicación entre contenedores, el siguiente aspecto crítico es la persistencia de los datos.

Configuración de volúmenes persistentes

Para los datos que deben sobrevivir al reinicio del contenedor, agrega recursos de volumen. Inserta esto antes de las definiciones del contenedor:

resource "docker_volume" "db_data" {
  name = "postgres_data"
}

Ahora añade un contenedor de base de datos que utilice este volumen:

resource "docker_container" "database" {
  name  = "postgres"
  image = "postgres:15"

 env = [
    "POSTGRES_PASSWORD=mysecretpassword"
  ]

  volumes {
    volume_name    = docker_volume.db_data.name
    container_path = "/var/lib/postgresql/data"
  }
}

Los volúmenes gestionados de este tipo son creados y controlados por Docker, y se almacenan en el directorio de datos de Docker. Para compartir archivos de configuración desde el host, utiliza montajes vinculantes especificando host_path en lugar de volume_name.

volumes {
  host_path      = "/opt/app/config"
  container_path = "/etc/app/config"
  read_only      = true
}

Después de asegurarte de que los datos sobrevivan al reinicio de los contenedores, es igualmente importante evitar que un solo contenedor monopolice los recursos del sistema.

Establecimiento de restricciones de recursos

Más allá del almacenamiento, controlar cuánta CPU y memoria puede consumir cada contenedor es fundamental para la estabilidad del sistema. Para evitar que los contenedores consuman recursos excesivos, aplica límites de recursos.

Aunque Docker permite actualizar algunos límites de recursos in situ, el modelo declarativo de Terraform a menudo requiere sustituir el contenedor para garantizar que el estado coincida con tu configuración. Para evitar el tiempo de inactividad durante esta sustitución, utilizamos la regla del ciclo de vida « create_before_destroy » (Elimina el antiguo, instala el nuevo). 

Importante: Debemos eliminar el argumento fijo name para evitar conflictos de nombres durante el proceso de sustitución. Una opción es utilizar el argumento « name_prefix » (Añadir a la lista de control de cambios).

resource "docker_container" "api" {
  name_prefix       = "api-server-"
  image      = docker_image.nginx.image_id
  memory     = 512
  cpu_shares = 1024

  networks_advanced {
    name = docker_network.app_network.name
  }

 lifecycle {
    create_before_destroy = true
  }
}

El parámetro memory limita la RAM en megabytes. El parámetro cpu_shares funciona de manera diferente. Es un peso relativo que se utiliza cuando se produce una contienda por la CPU. Un contenedor con 1024 acciones obtendrá el doble de tiempo de CPU que uno con 512 acciones, pero solo cuando el host esté bajo carga. 

Para los límites rígidos de CPU, también puedes utilizar cpu_set para fijar contenedores a núcleos de CPU específicos:

cpu_set = "0,1"
}

Valida estas restricciones ejecutando docker inspect background-worker --format='{{.HostConfig.Memory}} {{.HostConfig.CpuShares}} y comprobando que los valores de Memoria y NanoCpus coinciden con la configuración. 

Una vez más, tal y como se ha indicado anteriormente, primero debes ejecutar terraform plan y terraform apply para crear los recursos.

En este momento, el archivo main.tf contiene la configuración del proveedor, una imagen, una red, un volumen y tres contenedores con diversas configuraciones. 

Variables, módulos y secretos en Terraform

A medida que crece la infraestructura, los valores codificados se vuelven inflexibles. Esta sección muestra cómo hacer que la configuración sea reutilizable utilizando variables, módulos y un manejo adecuado de los secretos.

Uso de variables de entrada

El primer paso para flexibilizar las configuraciones es extraer los valores codificados en variables que se puedan modificar fácilmente sin cambiar el código principal. Esto se puede hacer creando un nuevo archivo llamado variables.tf en el mismo directorio:

variable "web_port" {
  description = "External port for web container"
  type        = number
  default     = 8080

  validation {
    condition     = var.web_port > 1024 && var.web_port < 65535
    error_message = "Port must be between 1024 and 65535."
  }
}

Ahora actualiza el contenedor web en main.tf para utilizar esta variable:

resource "docker_container" "web" {
  name  = "nginx-web"
  image = docker_image.nginx.image_id

  ports {
    internal = 80
    external = var.web_port
  }

  env = [
    "NGINX_HOST=example.com",
    "NGINX_PORT=80"
  ]
}

El bloque de validación impide el uso de puertos privilegiados. Para anular el valor predeterminado, crea un archivo terraform.tfvars:

web_port = 9000

Al ejecutar terraform apply, Terraform leerá automáticamente los valores de este archivo. Como alternativa, pasa los valores a través de la línea de comandos: terraform apply -var="web_port=9000".

Creación de módulos reutilizables

Las variables resuelven el problema de los valores codificados, pero ¿qué ocurre si necesitas implementar el mismo patrón completo varias veces, con todos sus recursos? 

Aquí es donde los módulos destacan. Piensa en un módulo como un plano que agrupa todas esas piezas separadas en un solo paquete, lo que te permite «eliminar» toda esa compleja configuración como una sola unidad.

Comienza creando una estructura de directorios para los módulos:

mkdir -p modules/web-app

Ahora, crea el archivo modules/web-app/variables.tf y añade lo siguiente:

variable "environment" {
  description = "Environment name"
  type        = string
}

variable "port" {
  description = "External port"
  type        = number
}

A continuación, crea un archivo principal modules/web-app/main.tf con este recurso:

resource "docker_container" "app" {
  name  = "app-${var.environment}"
  image = var.image_id

  ports {
    internal = 80
    external = var.port
  }
}

Por último, crea un archivo de salida modules/web-app/outputs.tf, que se utiliza principalmente para mostrar en la terminal el valor deseado después de ejecutar terraform apply:

output "container_ip" {
  value       = docker_container.app.network_data[0].ip_address
  description = "IP address of the application container"
}

Después de añadir las definiciones de los módulos, ejecuta « terraform init » para instalar los módulos y, a continuación, « terraform apply » para crear ambos contenedores a partir de la misma plantilla. Deberías poder ver todos los recursos en Docker Desktop.

Con los patrones de infraestructura reutilizables establecidos a través de módulos, hay otro aspecto crítico de la gestión de la configuración: el manejo seguro de información confidencial, como contraseñas y claves API.

Manejo de datos confidenciales

Los valores confidenciales, como las contraseñas de bases de datos, no deben estar codificados de forma fija. En su lugar, puedes utilizar el archivo variables.tf y establecer sensitive = true:

variable "db_password" {
  description = "Database root password"
  type        = string
  sensitive   = true
}

Ahora actualiza el contenedor de la base de datos en main.tf para que haga referencia a la contraseña de la base de datos:

resource "docker_container" "database" {
  name  = "postgres"
  image = "postgres:15"

  env = [
    "POSTGRES_PASSWORD=${var.db_password}"
  ]

  volumes {
    volume_name    = docker_volume.db_data.name
    container_path = "/var/lib/postgresql/data"
  }
}

En lugar de introducir la contraseña en terraform.tfvars y codificarla, configúrala como una variable de entorno:

export TF_VAR_db_password="your-secure-password"
terraform apply

La bandera ` sensitive = true ` impide que Terraform muestre el valor en la salida de la consola. 

Sin embargo, estos valores se almacenan en texto plano en terraform.tfstate, por lo que, para garantizar la seguridad de este archivo, podemos protegerlo utilizando backends remotos con cifrado. Veamos cómo hacerlo.

Gestión del estado de Terraform e integración de CI/CD

Esta sección trata sobre la mecánica de estados y los flujos de trabajo de automatización esenciales para las implementaciones de producción. Pero antes de implementar la automatización, es esencial comprender cómo Terraform realiza un seguimiento de tu infraestructura a través de su archivo de estado. 

Comprender la mecánica de los estados

El estado es la base de la capacidad de Terraform para gestionar la infraestructura. El archivo terraform.tfstate asigna la configuración a los ID reales de los contenedores Docker y a los atributos de los recursos. Al ejecutar « terraform apply », Terraform compara este estado con la configuración y calcula los cambios mínimos necesarios.

Inspecciona el estado actual con terraform show, que muestra todos los recursos gestionados. Para los equipos, los archivos de estado locales crean problemas, conflictos y posibles pérdidas de datos. La solución son los backends remotos.

Para flujos de trabajo centrados en Docker sin infraestructura en la nube, el nivel gratuito « » de Terraform Cloud es ideal. Añade un bloque backend a la sección « terraform » (Configuración de la red) en « main.tf » (Configuración de la red):

terraform {
  required_providers {
    docker = {
      source  = "kreuzwerker/docker"
      version = "~> 3.0"
    }
  }
  
  backend "remote" {
    organization = "your-org-name"
    
    workspaces {
      name = "docker-infrastructure"
    }
  }
}

Crea unacuenta gratuitaen el sitio web de Terraform. en, ejecuta terraform login para autenticarte con el token proporcionado y, a continuación, terraform init para migrar el estado. Esto proporciona bloqueo de estado en un espacio de trabajo remoto y colaboración en equipo sin infraestructura en la nube. 

Sin embargo, también es posible crear unbackend remotoen proveedores de nube como AWS o GCP.

Automatización de flujos de trabajo

Con la gestión estatal configurada y almacenada de forma remota, la infraestructura está lista para la colaboración en equipo. La pieza final es automatizar el proceso de implementación a través de canalizaciones CI/CD, lo que garantiza cambios coherentes y revisables.

Primero, crea un .github/workflows/terraform.yml:

name: Terraform Docker Deploy

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      
      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        
      - name: Terraform Init
        run: terraform init
        
      - name: Terraform Plan
        if: github.event_name == 'pull_request'
        run: terraform plan
        
      - name: Terraform Apply
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        run: terraform apply -auto-approve

Este flujo de trabajo ejecuta terraform plan en cada solicitud de extracción, mostrando a los revisores qué cambios se producirán en la infraestructura. Cuando los cambios se fusionan con el código principal, se ejecuta automáticamente terraform apply, lo que garantiza que todos los cambios en la infraestructura se sometan al mismo proceso de revisión que los cambios en el código.

Solución de problemas de Terraform Docker

Incluso con una configuración cuidadosa, pueden surgir problemas. Comprender los problemas comunes y saber cuándo considerar alternativas ayuda a tomar mejores decisiones arquitectónicas. 

«Permiso denegado»

El error más común en Linux es «permiso denegado» al conectarse al socket de Docker. Esto ocurre cuando no tienes permiso para acceder a /var/run/docker.sock. Soluciona el problema añadiendo al usuario al grupo docker:

sudo usermod -aG docker $USER

A continuación, cierra la sesión y vuelve a iniciarla.

Problemas de conectividad con WSL2

En Windows con WSL2, surgen problemas de conectividad porque la ruta del socket es diferente. Asegúrate de que la configuración «Exponer el daemon en tcp://localhost:2375 sin TLS» de Docker Desktop esté habilitada y, a continuación, actualiza el proveedor en main.tf:

provider "docker" {
  host = "tcp://localhost:2375"
}

Fallos en la autenticación del registro privado

Para los registros privados de Docker, añade la autenticación al bloque del proveedor, define las credenciales como variables y configúralas a través de variables de entorno para evitar problemas debidos al código fijo.

hclprovider "docker" {
  host = "unix:///var/run/docker.sock"
  
  registry_auth {
    address  = "registry.mycompany.com"
    username = var.registry_username
    password = var.registry_password
  }
}

Alternativas a Terraform

Más allá de la resolución de problemas, es igualmente valioso comprender cuándo otras herramientas pueden ser más adecuadas que Terraform para tu caso de uso específico.

Terraform frente a Kubernetes

Kubernetes ofrece funciones de orquestación mucho más sofisticadas : 

• Autocuración
• Programación avanzada
• Descubrimiento de servicios
• Equilibrio de carga integrado

Para implementaciones complejas de múltiples nodos con requisitos de alta disponibilidad, Kubernetes es la mejor opción. Terraform puede aprovisionar la infraestructura de Kubernetes, mientras que Helm olos manifiestos de Kubernetes se encargan de la implementación de aplicaciones.

Terraform frente a Ansible

Ansible destaca en la gestión de la configuración dentro de contenedores. Mientras Terraform se encarga de la provisión de infraestructura, Ansible gestiona la configuración del software y la instalación de paquetes. Las dos herramientas suelen funcionar juntas: Terraform crea contenedores Docker y, a continuación, Ansible configura las aplicaciones que se ejecutan en ellos.

Terraform frente a Docker Compose

Paraentornos de desarrollo locales sencillos, Docker Compose sigue siendo la opción más pragmática. Terraform destaca por sus implementaciones reproducibles en distintos entornosy cuando es necesaria la integración con otros componentes de infraestructura.

Para ayudarte a decidir cuál elegir, he resumido lasdiferencias más importantesen esta tabla:

Si estás buscando una herramienta para sustituir a Docker, consultanuestra guía sobre las mejores alternativas a Docker.

Conclusión

La incorporación de Docker a la gestión del ciclo de vida de Terraform transforma las implementaciones de contenedores de procedimientos manuales en una infraestructura reproducible y controlada por versiones. En este tutorial, he mostrado cómo crear una infraestructura completa paso a paso, empezando por un proveedor y un único contenedor, y añadiendo progresivamente redes, almacenamiento, variables, módulos y automatización.

La diferencia clave es que Terraform se encarga del aprovisionamiento, la creación, la actualización y la destrucción de recursos basándose en una configuración declarativa. La orquestación completa con escalado automático y autorreparación requiere herramientas como Kubernetes o Docker Swarm. Terraform puede aprovisionar estos orquestadores, pero no los sustituye.

Para los siguientes pasos, consulta la documentación oficial del Registro de Terraform para el proveedor Docker, donde encontrarás opciones avanzadas de recursos, como servicios Docker para Swarm, gestión de secretos y configuraciones de complementos.

Si deseas adquirir experiencia práctica con contenedores, te recomiendo que te inscribas en nuestro programa interactivo «Contenedorización y virtualización con Docker y Kubernetes ».