Terraform desde cero hasta trabajar con él en equipo

Bloque 01 · Fundamentos · ~2 h

Qué es la infraestructura como código y qué hace Terraform

Antes de escribir una línea, entiende el problema que resuelve Terraform y las tres piezas con las que trabaja: el código, los providers y el state.

El problema: infraestructura hecha a mano

Imagina que montas un entorno en la consola de AWS: una red, dos subredes, un balanceador, tres servidores y una base de datos. Funciona. Seis meses después te piden un entorno idéntico para pruebas. Nadie recuerda qué casillas se marcaron, qué puerto se abrió “un momento” para depurar ni por qué la base de datos tiene ese tamaño.

• No es reproducible: cada entorno se parece al anterior, pero no es igual.
• No hay historial: no sabes quién cambió qué, cuándo ni por qué.
• No hay revisión: un cambio en producción no pasa por ningún pull request.
• Deriva: la realidad se aleja de la documentación desde el primer día.

La solución: describir la infraestructura en ficheros

Infraestructura como código (IaC) significa que la infraestructura se define en ficheros de texto que viven en git, se revisan en pull requests y se aplican con una herramienta. Terraform es la herramienta de IaC más usada para esto, y funciona con casi cualquier plataforma que tenga API: AWS, Azure, Google Cloud, Kubernetes, GitHub, Cloudflare, Datadog y miles más.

Esta es la idea central de todo el curso. En un enfoque imperativo escribes los pasos. En uno declarativo escribes el estado final que quieres, y la herramienta calcula los pasos necesarios para llegar desde donde estás. Por eso Terraform es idempotente: si la realidad ya coincide con el código, no hace nada.

Cómo funciona Terraform por dentro

• Terraform Core es el binario terraform. Lee tus ficheros, construye un grafo de dependencias, compara lo que quieres con lo que existe y decide qué crear, cambiar o borrar. No sabe nada de AWS ni de Azure.
• Providers son plugins que traducen recursos a llamadas de API. hashicorp/aws sabe crear una instancia EC2; integrations/github sabe crear un repositorio. Se descargan del Terraform Registry.
• State es un fichero JSON donde Terraform apunta qué objeto real corresponde a cada recurso de tu código (por ejemplo, que aws_instance.web es i-0b7d4e19a2). Sin él, Terraform no sabría qué gestiona. Tiene un bloque entero dedicado (07).

Terraform frente a otras herramientas

Bloque 02 · Entorno · ~3 h

Instalación, editor y tu primer proyecto sin gastar dinero

Instala Terraform, configura el editor y crea y destruye un contenedor nginx con Docker. No necesitas cuenta en ninguna nube para este bloque.

Instalar Terraform

Instrucciones oficiales para todos los sistemas en developer.hashicorp.com/terraform/install.

Fijar la versión por proyecto con tfenv

En equipo, todos deben usar la misma versión. tfenv instala varias versiones y elige la correcta leyendo un fichero .terraform-version del repositorio. Si prefieres una herramienta para todos tus lenguajes, mise o asdf hacen lo mismo. Usa un único método: no mezcles el paquete de apt con tfenv.

Editor

• VS Code: extensión oficial HashiCorp Terraform (autocompletado, documentación al pasar el ratón, formateo al guardar).
• Neovim / LazyVim: :LazyExtras y activa lang.terraform. Instala terraform-ls y el formateo.
• Autocompletado en la terminal: terraform -install-autocomplete y reinicia la shell.

Tu primer proyecto: nginx en Docker

Necesitas Docker en marcha. Crea una carpeta y dentro un fichero main.tf:

Fíjate en image = docker_image.nginx.image_id: el contenedor usa un atributo de la imagen. Esa referencia hace que Terraform cree primero la imagen y después el contenedor. Lo verás a fondo en el bloque 05.

Credenciales de nube (cuando pases a AWS)

Terraform usa las mismas credenciales que la CLI de cada nube. Nunca las escribas en ficheros .tf.

Estructura de un proyecto y qué va a git

Terraform carga todos los ficheros .tf del directorio como si fueran uno solo. Los nombres de fichero son convención, no reglas. Esta es la convención más extendida:

mi-proyecto/
├── versions.tf          # bloque terraform {}: versión y required_providers
├── providers.tf         # configuración de cada provider
├── main.tf              # recursos
├── variables.tf         # variables de entrada
├── outputs.tf           # valores de salida
├── terraform.tfvars     # valores de las variables (cuidado con secretos)
├── .terraform.lock.hcl  # versiones exactas de providers: SÍ va a git
└── .terraform/          # plugins descargados: NO va a git

Bloque 03 · Lenguaje · ~3 h

El lenguaje HCL: bloques, argumentos, tipos y referencias

HCL (HashiCorp Configuration Language) es pequeño. En una tarde conoces toda su sintaxis; el resto del curso es aprender qué bloques existen y cómo combinarlos.

Anatomía de un bloque

resource "aws_instance" "web" {
  ami           = "ami-0abc123"
  instance_type = var.instance_type

  tags = {
    Name = "web-${var.env}"
  }

  root_block_device {
    volume_size = 20
  }
}  # comentario

La forma general de todo HCL es siempre la misma: TIPO "etiqueta" "etiqueta" { argumento = valor }. El número de etiquetas depende del tipo de bloque: resource lleva dos, variable una y locals ninguna.

Tipos de datos

Strings, interpolación y textos multilínea

Fuera de un string no hace falta ${}: escribe instance_type = var.instance_type, no "${var.instance_type}". La segunda forma es de versiones antiguas (0.11) y terraform fmt no la corrige por ti.

Referencias: cómo se nombra cada cosa

Operadores disponibles: aritméticos + - * / %, comparación == != < > <= >=, lógicos && || ! y el condicional condición ? si_true : si_false.

Tu laboratorio: terraform console

Ejecuta terraform console en cualquier carpeta para probar expresiones y funciones sin crear nada. Úsalo cada vez que dudes de lo que devuelve algo.

Dos comandos más que usarás a diario: terraform fmt formatea el código según el estilo oficial (alinea los =, la sangría a 2 espacios) y terraform validate comprueba que la sintaxis y los tipos son correctos sin conectarse a ninguna nube.

Bloque 04 · Flujo de trabajo · ~3 h

El ciclo de vida: init, plan, apply y destroy

Cuatro comandos cubren el 90 % del trabajo diario. Lo más importante del bloque: aprender a leer un plan antes de aprobarlo.

Qué hace cada comando

Cómo leer un plan

(known after apply) significa que el valor lo decide la plataforma al crear el objeto (un ID, una IP, un ARN). Lee siempre la última línea primero: si esperabas “1 to change” y ves “3 to destroy”, para y averigua por qué.

Bloque 05 · Piezas básicas · ~4 h

Providers, recursos, data sources y el grafo de dependencias

Aquí empiezas a escribir configuraciones reales. La habilidad clave: leer la documentación de un recurso en el Registry y entender en qué orden crea Terraform las cosas.

Providers y versiones

La restricción dice qué versiones aceptas; el fichero .terraform.lock.hcl registra cuál se eligió exactamente (con sus hashes). Por eso se commitea: todo el equipo y el CI usan los mismos binarios. Para subir de versión, terraform init -upgrade y revisa el changelog del provider.

Recursos: argumentos y atributos

Un recurso tiene una dirección única: TIPO.NOMBRE, por ejemplo aws_s3_bucket.logs. El tipo empieza siempre por el nombre del provider (aws_, docker_, github_).

• Argumentos son lo que tú escribes: bucket = "acme-logs".
• Atributos son lo que puedes leer después: aws_s3_bucket.logs.arn. Incluyen los argumentos y los valores que calcula la plataforma.

Cada página de recurso en el Registry tiene la misma estructura: Example Usage (copia de aquí), Argument Reference (qué puedes configurar, cuáles son obligatorios), Attribute Reference (qué puedes leer) e Import (cómo adoptar uno existente). Leerla bien es la mitad del trabajo con Terraform.

Data sources: leer lo que ya existe

Un data consulta algo que no gestiona esta configuración: la AMI más reciente, una VPC creada por otro equipo, la cuenta actual. Nunca crea ni borra nada.

Dependencias y el grafo

Terraform no ejecuta los recursos en el orden en que aparecen en el fichero. Construye un grafo dirigido a partir de las referencias: si la subred usa aws_vpc.main.id, la VPC va antes. Todo lo que no depende entre sí se crea en paralelo (10 operaciones a la vez por defecto, ajustable con -parallelism=N). Al destruir, el orden se invierte.

Pulsa “Simular apply”.

Si una dependencia existe pero no se ve en el código (por ejemplo, la aplicación de la instancia necesita que una política IAM exista al arrancar, pero no la referencia), declárala con depends_on. Úsalo solo en ese caso: las referencias son siempre preferibles porque además transmiten valores.

Puedes ver el grafo real de tu configuración con terraform graph | dot -Tsvg > grafo.svg (necesita Graphviz).

Bloque 06 · Parametrizar · ~3 h

Variables, outputs y locals

Las variables son las entradas de tu configuración, los outputs sus salidas y los locals sus cálculos internos. Juntos convierten un ejemplo fijo en código reutilizable.

Variables de entrada

Una variable sin default es obligatoria: si nadie le da valor, Terraform la pide por teclado (o falla con -input=false, como en CI). Escribe siempre description y type: son la documentación de tu módulo.

Cómo se asignan los valores y cuál gana

Locals: cálculos internos

Regla práctica: si un valor lo decide quien usa el código, es una variable. Si se deriva de otros valores o se repite, es un local. No conviertas en variable algo que nunca va a cambiar.

Outputs

Los outputs tienen dos usos: mostrar información tras el apply y, sobre todo, pasar valores de un módulo a otro (bloque 10).

Bloque 07 · El concepto más importante · ~4 h

El state: cómo sabe Terraform qué existe

Casi todos los sustos con Terraform vienen de no entender el state. Dedica a este bloque el tiempo que necesites y juega con el simulador hasta que puedas predecir cada plan.

Tres fuentes de verdad

En cada plan, Terraform mira tres cosas: el código (lo que quieres), el state (lo que Terraform cree que gestiona, con sus IDs) y la realidad (lo que devuelve la API). Primero refresca el state con la realidad y después compara el resultado con el código.

Experimentos que merecen la pena: aplica, cambia instance_type en la consola y haz plan (Terraform quiere devolverlo a lo que dice el código); borra el state y haz apply (la instancia vieja queda huérfana y el bucket choca con el existente); después importa en lugar de aplicar.

Qué hay dentro del state

serial aumenta con cada escritura y lineage identifica la “historia” del state; Terraform los usa para no mezclar states distintos. Los atributos incluyen todo lo que devuelve la API, contraseñas incluidas.

Drift: cambios fuera de Terraform

Cuando alguien cambia algo en la consola, el siguiente plan muestra Objects have changed outside of Terraform y propone volver a lo que dice el código. Tienes dos opciones: dejar que Terraform lo revierta, o aceptar el cambio actualizando el código. Si solo quieres ver el drift sin proponer cambios:

Comandos de state

Refactorizar sin destruir: moved, import y removed

Si renombras aws_instance.web a aws_instance.app en el código sin más, Terraform ve un recurso que ya no existe (destroy) y uno nuevo (create). Estos bloques declaran la intención en el código, se revisan en el pull request y funcionan igual para todo el equipo:

Con import no necesitas escribir la configuración a mano: terraform plan -generate-config-out=generated.tf la genera a partir del objeto real. Revísala y límpiala antes de commitear.

Bloque 08 · Expresiones · ~4 h

Bucles, condicionales y funciones

Para crear diez buckets no escribes diez bloques. count, for_each, las expresiones for y los bloques dynamic generan configuración a partir de datos.

count: N copias

for_each: una instancia por clave

Regla: usa count para “cero o uno” y para copias idénticas e intercambiables. Usa for_each para colecciones de cosas distintas con identidad propia (usuarios, buckets, subredes). for_each acepta un map o un set(string); convierte listas con toset(). Las claves deben conocerse en el plan: no pueden depender de atributos (known after apply).

Expresiones for y splat

Bloques dynamic

Algunos argumentos son bloques anidados repetibles (ingress, setting, rule). dynamic los genera desde una colección. Úsalo con moderación: un bloque escrito a mano se lee mejor que uno dinámico.

Funciones imprescindibles

No hay funciones definidas por el usuario: solo las integradas (más las que exponen algunos providers desde la 1.8). La referencia completa está agrupada por categorías.

Bloque 09 · Control fino · ~2 h

Meta-argumentos, lifecycle y comprobaciones

Los meta-argumentos funcionan en cualquier recurso, sea del provider que sea, y cambian cómo Terraform lo trata: cuántas copias, con qué provider, en qué orden y cómo se reemplaza.

lifecycle

terraform_data (desde 1.4) es un recurso integrado que no crea nada en ninguna nube; sirve para guardar un valor y disparar reemplazos. Sustituye al antiguo null_resource.

Bloques check: verificar que todo funciona

Un check (desde 1.5) se evalúa en cada plan y apply. Si falla, muestra un aviso pero no detiene la operación. Es útil para comprobar que la web responde o que un certificado no está a punto de caducar.

Provisioners: el último recurso

local-exec y remote-exec ejecutan comandos al crear un recurso. Terraform no puede planificar lo que hacen, no detecta drift en ellos y, si fallan, el recurso queda marcado como tainted. La documentación oficial los desaconseja. Alternativas, en orden de preferencia:

1. Imágenes preconstruidas con Packer: la máquina arranca ya configurada.
2. user_data / cloud-init para configuración al arrancar.
3. Gestión de configuración (Ansible) para lo que cambia a menudo dentro de la máquina.
4. El argumento o recurso nativo del provider, si existe: casi siempre existe.

Bloque 10 · Reutilizar · ~4 h

Módulos: componer infraestructura con piezas reutilizables

Un módulo es una carpeta con ficheros .tf. Ya llevas nueve bloques escribiendo uno sin saberlo: el módulo raíz. Ahora aprenderás a llamar a otros.

La idea

Un módulo funciona como una función: recibe variables, crea recursos por dentro y devuelve outputs. Desde fuera solo se ve esa interfaz.

Escribir un módulo

infra/
├── modules/
│   └── network/
│       ├── main.tf        # recursos
│       ├── variables.tf   # interfaz de entrada
│       ├── outputs.tf     # interfaz de salida
│       ├── versions.tf    # required_providers, sin bloque provider
│       └── README.md
└── envs/
    └── dev/
        └── main.tf        # llama a ../../modules/network

Llamar a módulos

Después de añadir o cambiar el source de un módulo, ejecuta terraform init para descargarlo. Las direcciones dentro de un módulo llevan prefijo: module.network.aws_vpc.this. Para mover recursos existentes a un módulo sin destruirlos, usa un bloque moved (bloque 07).

Qué hace bueno a un módulo

• Representa un concepto (una red, un servicio web, una base de datos con sus backups), no un único recurso. Un módulo que envuelve un solo aws_s3_bucket y reexpone todos sus argumentos solo añade una capa.
• Interfaz pequeña con defaults sensatos y description en cada variable y output.
• Sin bloques provider dentro. El que llama configura los providers; el módulo solo declara required_providers. Si necesita un alias, se pasa con providers = { aws = aws.use1 }.
• Versionado con tags semánticos si lo usan otros equipos. Documentación generada con terraform-docs.
• Poca profundidad: módulos que llaman a módulos que llaman a módulos son muy difíciles de depurar. Dos niveles suelen bastar.

Antes de escribir uno, busca en el Registry de módulos. Los de terraform-aws-modules son muy usados y una buena referencia de estilo, aunque leerlos enteros cuesta: son genéricos a propósito.

Bloque 11 · Trabajo en equipo · ~4 h

Backends remotos, locking y varios entornos

Un state en tu portátil vale para aprender. En un equipo, el state vive en un sitio compartido, cifrado, versionado y con bloqueo para que dos personas no apliquen a la vez.

El backend S3

El backend decide dónde se guarda el state. Los más comunes son s3, azurerm, gcs y HCP Terraform. Primero hay que crear el bucket del state, normalmente con una configuración pequeña aparte que usa state local (el problema del huevo y la gallina):

Qué evita el locking

Varios entornos: workspaces o directorios

infra/
├── modules/
│   ├── network/
│   └── web/
└── envs/
    ├── dev/
    │   ├── main.tf           # module "network" { source = "../../modules/network" ... }
    │   ├── backend.tf        # key = "envs/dev/..."
    │   └── terraform.tfvars  # instance_type = "t3.micro"
    └── prod/
        ├── main.tf
        ├── backend.tf        # key = "envs/prod/...", a menudo otra cuenta
        └── terraform.tfvars  # instance_type = "m6i.large"

Además de por entorno, divide los states por capas con distinto ritmo de cambio: red, datos y aplicaciones. Un state con 2.000 recursos tarda minutos en cada plan y cualquier error afecta a todo. Herramientas como Terragrunt ayudan a orquestar muchos states, pero empieza sin ellas.

Compartir datos entre states

Bloque 12 · Calidad · ~4 h

Calidad, tests y seguridad

El código de infraestructura merece las mismas garantías que el de aplicación: formato, análisis estático, tests y escaneo de seguridad, en local y en CI.

La cadena de comprobaciones

1. fmtEstilo uniforme
2. validateSintaxis, tipos, referencias
3. tflintErrores del provider y malas prácticas
4. Trivy / CheckovConfiguración insegura
5. terraform testComportamiento esperado
6. Revisar el planSiempre una persona

• tflint: linter con plugins por provider (AWS, Azure, GCP).
• Trivy y Checkov: escáneres de seguridad de IaC. Trivy absorbió a tfsec.
• Infracost: estima cuánto cuesta un plan antes de aplicarlo.

Tests nativos: terraform test

Desde la versión 1.6, los ficheros *.tftest.hcl contienen bloques run con aserciones. Con command = plan no se crea nada; con command = apply (el valor por defecto) se crea infraestructura real y se destruye al final. Desde la 1.7, mock_provider simula un provider para testear sin credenciales.

Para tests de integración más complejos (desplegar, hacer peticiones HTTP, destruir) existe Terratest, en Go.

Secretos

Bloque 13 · Automatizar · ~4 h

CI/CD y trabajo en equipo

En un equipo nadie aplica desde su portátil. Los cambios entran por pull request, el pipeline muestra el plan, alguien lo revisa y el apply se ejecuta de forma automática y auditada.

El flujo

1. Rama + PRCambio en el código
2. Checksfmt, validate, tflint, trivy, test
3. PlanSe publica en el PR
4. RevisiónUna persona lee el plan
5. MergeA main
6. ApplyDel plan revisado
7. DriftPlan programado diario

GitHub Actions

Bitbucket Pipelines

Plataformas especializadas

Si no quieres montar el flujo a mano: Atlantis (open source, comenta el plan en el PR y aplica con un comentario atlantis apply), HCP Terraform (state, ejecuciones, políticas y registro privado de HashiCorp), y alternativas como Spacelift, env0 o Scalr.

Prácticas de equipo

• Nada de cambios en la consola en entornos gestionados. Si hay emergencia, después se refleja en el código.
• States pequeños por entorno y capa: limitan el radio de impacto de cada error.
• Versiones fijadas: Terraform (required_version y .terraform-version), providers (lock file commiteado) y módulos (version o ref).
• Planes legibles en el PR y revisión obligatoria cuando hay - o -/+.
• Detección de drift con un plan programado que avise si el resultado no es “No changes”. terraform plan -detailed-exitcode devuelve 2 cuando hay cambios.
• Convención de etiquetas (default_tags) para saber de quién es cada recurso y cuánto cuesta.

Bloque 14 · Proyecto final · ~10 h

Proyecto final: una web en AWS de principio a fin

Junta todo lo aprendido en un repositorio que podrías enseñar en una entrevista: red, servidores, dos entornos, state remoto, tests y pipeline. Marca cada tarea al terminarla; se guarda en este navegador.

tf-web/
├── bootstrap/                 # bucket del state (state local)
├── modules/
│   ├── network/               # VPC, 2 subredes públicas, IGW, rutas
│   └── web/                   # SG dinámico, instancias, user_data con templatefile
├── envs/
│   ├── dev/                   # backend propio, t3.micro, 1 instancia
│   └── prod/                  # backend propio, 2 instancias, prevent_destroy
├── tests/                     # terraform test con mock_provider
├── .pre-commit-config.yaml
├── .tflint.hcl
├── .terraform-version
└── bitbucket-pipelines.yml    # o .github/workflows/terraform.yml

Anexo · Para volver siempre

Recursos, chuleta de comandos y glosario

Recursos para seguir aprendiendo

Chuleta de comandos

Glosario

Provider

Plugin que traduce recursos de Terraform a llamadas a la API de una plataforma.

Resource

Objeto que Terraform crea y gestiona: una instancia, un bucket, un registro DNS.

Data source

Consulta de solo lectura sobre algo que existe fuera de esta configuración.

State

Registro que relaciona cada dirección del código con su objeto real y sus atributos.

Backend

Dónde se guarda el state y cómo se bloquea.

Plan

Lista de acciones que Terraform propone para que la realidad coincida con el código.

Drift

Diferencia entre la realidad y el state provocada por cambios fuera de Terraform.

Module

Carpeta de ficheros .tf con variables de entrada y outputs. El directorio donde ejecutas es el módulo raíz.

Address

Nombre único de un recurso: module.network.aws_subnet.public["eu-west-1a"].

Lock file

.terraform.lock.hcl: versiones y hashes exactos de los providers elegidos.

Workspace

Varios states para la misma configuración y el mismo backend.

Idempotencia

Aplicar lo mismo varias veces da el mismo resultado: sin cambios si ya coincide.

Tainted

Recurso marcado para reemplazo, por ejemplo porque falló su creación.

HCL

HashiCorp Configuration Language, el lenguaje de los ficheros .tf.