El Proyecto | Sobre nosotros | Contribuir | Donaciones | Licencia

HOME

Introducción

El estado de Terraform (terraform.tfstate) es el corazón de cómo Terraform entiende y gestiona tu infraestructura. Es el mapa que conecta tu código HCL con los recursos reales en la nube. Cuando el estado tiene problemas, Terraform puede tomar decisiones incorrectas: destruir recursos que debería conservar, intentar crear recursos que ya existen, o simplemente negarse a ejecutar cualquier operación.

Esta lección cubre los problemas de estado más comunes, cómo diagnosticarlos, cómo resolverlos con seguridad, y qué medidas preventivas implementar para evitarlos.

Advertencia importante: Las operaciones de estado son potencialmente destructivas. Siempre realiza un backup del estado antes de cualquier manipulación manual.

Tipos de Problemas de Estado Más Comunes

Los problemas de estado se pueden categorizar en cinco tipos principales:

Estado corrupto: El archivo de estado contiene datos inválidos o inconsistentes.
Estado desincronizado (drift): La infraestructura real difiere del estado que Terraform tiene registrado.
Recursos huérfanos: El estado contiene recursos que ya no existen en la nube.
Estado bloqueado indefinidamente: El lock de estado no se liberó tras una operación fallida.
Conflictos de estado en equipo: Múltiples personas o procesos modifican la infraestructura sin coordinación.

Estado Corrupto: Causas y Síntomas

Causas comunes de corrupción

Interrumpir violentamente un terraform apply en curso (Ctrl+C durante la escritura del estado)
Editar manualmente el archivo terraform.tfstate con errores
Fallo del backend remoto durante la escritura (por ejemplo, S3 con un timeout)
Bug en una versión específica del provider que escribe datos incorrectos

Síntomas de estado corrupto

terraform plan
# Error:
# │ Error: Failed to read the Terraform managed state
# │
# │ Terraform failed to read the managed state for the workspace "default".
# │ The file is not valid JSON: invalid character 'T' looking for beginning
# │ of value

O bien:

│ Error: state snapshot was created by Terraform v1.5.0, which is newer
│ than current v1.4.6; upgrade to Terraform v1.5.0 or greater to work
│ with this state

Verificar si el estado está corrupto

# Intentar leer el estado actual
terraform state list

# Si el estado es JSON válido pero con problemas de contenido
cat terraform.tfstate | python3 -m json.tool > /dev/null && echo "JSON válido" || echo "JSON inválido"

# Ver los metadatos del estado
terraform show

Recuperar un Estado Corrupto desde el Backup

Terraform crea automáticamente un backup del estado antes de cada operación que lo modifica. Este archivo se llama terraform.tfstate.backup.

# Ver si existe el backup
ls -la terraform.tfstate*

# terraform.tfstate          <- Estado actual (posiblemente corrupto)
# terraform.tfstate.backup   <- Backup del estado anterior

# Verificar que el backup es válido
cat terraform.tfstate.backup | python3 -m json.tool > /dev/null && echo "Backup válido"

# Restaurar el backup (HACER ESTO CON CUIDADO)
# Primero, guardar el estado corrupto por si acaso
cp terraform.tfstate terraform.tfstate.corrupted

# Restaurar desde el backup
cp terraform.tfstate.backup terraform.tfstate

# Verificar que Terraform puede leer el estado restaurado
terraform state list

Recuperación desde backend remoto (S3)

Si usas S3 como backend con versioning habilitado:

# Listar versiones del archivo de estado
aws s3api list-object-versions \
  --bucket mi-terraform-state-bucket \
  --prefix terraform.tfstate \
  --query 'Versions[*].[LastModified,VersionId,IsLatest]' \
  --output table

# Restaurar una versión anterior específica
aws s3api copy-object \
  --bucket mi-terraform-state-bucket \
  --copy-source mi-terraform-state-bucket/terraform.tfstate?versionId=VERSION_ID_ANTERIOR \
  --key terraform.tfstate

Estado Desincronizado (Drift): Detección y Resolución

El "drift" ocurre cuando alguien modifica la infraestructura directamente en la consola de AWS/Azure/GCP sin pasar por Terraform, creando una diferencia entre el estado registrado y la realidad.

Detectar drift

# terraform plan siempre detecta drift comparando el estado con la realidad
terraform plan

# Si hay drift, verás algo como:
# aws_instance.web will be updated in-place
#   ~ resource "aws_instance" "web" {
#       id            = "i-0123456789abcdef0"
#     ~ instance_type = "t2.micro" -> "t2.large"  # Alguien lo cambió manualmente
#     }

# Para un refresh explícito del estado sin aplicar cambios
terraform refresh  # Deprecado, usar plan con refresh
terraform plan -refresh=true  # Actualiza el estado local con la realidad actual

Resolver el drift

Opción A: Revertir los cambios manuales (Terraform es la fuente de verdad)

# Aplicar el plan para volver al estado deseado por el código
terraform apply
# Esto revertirá instance_type de t2.large a t2.micro

Opción B: Aceptar los cambios manuales (actualizar el código para que coincida)

# Si el cambio manual es intencional, actualizar el código:
resource "aws_instance" "web" {
  ami           = data.aws_ami.ubuntu.id
  instance_type = "t2.large"  # Actualizado para coincidir con la realidad
  # ...
}

# Después de actualizar el código, verificar que el plan no muestra cambios
terraform plan
# Debe mostrar: No changes. Your infrastructure matches the configuration.

Opción C: Importar el estado actual para recursos nuevos encontrados

Si el drift incluye recursos nuevos que no están en el estado:

# Importar un recurso existente al estado de Terraform
terraform import aws_instance.nuevo_servidor i-0987654321fedcba0

Recursos Huérfanos en el Estado

Un recurso huérfano es un recurso registrado en el estado de Terraform pero que ya no existe en la nube (fue eliminado manualmente o por otro proceso).

Síntoma típico

terraform plan
# Output:
# aws_instance.old_server: Refreshing state... [id=i-0000000000000000]
#
# ╷
# │ Error: reading EC2 Instance (i-0000000000000000): operation error EC2:
# │ DescribeInstances, https response error StatusCode: 400,
# │ RequestID: abc123, api error InvalidInstanceID.NotFound:
# │ The instance ID 'i-0000000000000000' does not exist
# ╵

Resolver recursos huérfanos

# Opción 1: Dejar que Terraform lo detecte y lo elimine del estado automáticamente
# Cuando terraform plan detecta que el recurso no existe,
# lo planea como "crear de nuevo"

# Opción 2: Eliminar manualmente del estado sin destruir nada en la nube
# (el recurso ya no existe en la nube, solo en el estado)
terraform state rm aws_instance.old_server

# Verificar que ya no aparece en el estado
terraform state list

# Volver a ejecutar plan para confirmar que está limpio
terraform plan

Eliminar múltiples recursos huérfanos

# Ver todos los recursos en el estado
terraform state list

# Eliminar varios recursos del estado (uno por uno)
terraform state rm aws_instance.old_server_1
terraform state rm aws_instance.old_server_2
terraform state rm aws_eip.old_elastic_ip

# Alternativa: script para eliminar múltiples recursos
for resource in $(terraform state list | grep "old_"); do
  echo "Eliminando del estado: $resource"
  terraform state rm "$resource"
done

Limpiar Recursos del Estado sin Destruirlos

A veces necesitas que Terraform "olvide" un recurso sin destruirlo (por ejemplo, para transferir su gestión a otro workspace o estado).

# Ver el recurso antes de eliminarlo del estado
terraform state show aws_s3_bucket.legacy_bucket

# Eliminar del estado (el bucket SIGUE EXISTIENDO en AWS)
terraform state rm aws_s3_bucket.legacy_bucket

# Verificar
terraform state list | grep legacy_bucket
# (no debe aparecer)

# El bucket sigue en AWS, pero Terraform ya no lo gestiona

Mover recursos entre estados

Si quieres transferir un recurso de un estado a otro:

# En el workspace/directorio origen
terraform state pull > origin-state.json

# Mover el recurso al nuevo estado
terraform state mv \
  -state=origin-state.json \
  -state-out=destination-state.json \
  aws_s3_bucket.legacy_bucket \
  aws_s3_bucket.migrated_bucket

# En el workspace/directorio destino
terraform state push destination-state.json

Estado Bloqueado Indefinidamente

Cuando Terraform ejecuta una operación, adquiere un lock del estado para evitar modificaciones concurrentes. Si la operación falla abruptamente, el lock puede quedar indefinidamente activo.

Identificar el bloqueo

terraform plan
# Output:
# │ Error: Error acquiring the state lock
# │
# │ Error message: ConditionalCheckFailedException: The conditional request failed
# │ Lock Info:
# │   ID:        abc12345-def6-7890-ghij-klmnopqrstuv
# │   Path:      mi-bucket/terraform.tfstate
# │   Operation: OperationTypePlan
# │   Who:       usuario@maquina
# │   Version:   1.5.7
# │   Created:   2024-01-15 09:30:00 UTC
# │   Info:
# │
# │ Terraform acquires a state lock to protect the state from being written
# │ by multiple users at the same time.

Verificar que no hay otra operación en curso

IMPORTANTE: Antes de forzar el desbloqueo, confirma que realmente no hay ninguna operación de Terraform ejecutándose en otro terminal o en un pipeline de CI/CD.

# Verificar procesos de Terraform en curso en la máquina local
ps aux | grep terraform

# Si usas S3 con DynamoDB para el lock, verificar en AWS
aws dynamodb scan \
  --table-name terraform-state-locks \
  --filter-expression "attribute_exists(LockID)" \
  --output json

# Para Terraform Cloud, verificar en la interfaz web o via API
curl -H "Authorization: Bearer $TF_TOKEN" \
  "https://app.terraform.io/api/v2/workspaces/ws-xxxx/runs?filter[status]=running"

Usar `terraform force-unlock` con precaución

# SOLO ejecutar si has CONFIRMADO que no hay operaciones en curso
# Copiar el ID del lock del mensaje de error
terraform force-unlock abc12345-def6-7890-ghij-klmnopqrstuv

# Confirmación requerida:
# Do you really want to force-unlock?
#   Terraform will remove the lock on the remote state.
#   This will allow local Terraform commands to modify this state, even though
#   it may be still be in use. Only 'yes' will be accepted to confirm.
#
# Enter a value: yes

Advertencia crítica: Si fuerzas el desbloqueo mientras otra operación está activa, puedes corromper el estado. Verifica siempre dos veces antes de ejecutar este comando.

Conflictos al Trabajar en Equipo con Estado Local

El estado local (terraform.tfstate en el disco) es peligroso en entornos de equipo porque:

Cada persona tiene su propia copia del estado
No hay mecanismo de bloqueo entre personas
Los cambios de un miembro no son visibles para otros

Señales de conflicto de estado en equipo

terraform plan
# Output confuso:
# # aws_instance.web must be replaced
# - id = "i-0aabbccddeeff1122"  <- ID que solo existe en el estado de otra persona
# + ami = "ami-0c55b159cbfafe1f0" (forces replacement)

Solución: Migrar a un backend remoto compartido

# backend.tf - Configurar backend remoto en S3 (compartido por todo el equipo)
terraform {
  backend "s3" {
    bucket         = "mi-empresa-terraform-state"
    key            = "proyecto/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true

    # DynamoDB para state locking
    dynamodb_table = "terraform-state-locks"
  }
}

# Migrar el estado local al backend remoto
terraform init -migrate-state

# Terraform preguntará si deseas copiar el estado existente:
# Do you want to copy existing state to the new backend?
# Enter a value: yes

Recuperar Estado desde Terraform Cloud

Si usas Terraform Cloud y el workspace tiene problemas:

# Listar workspaces
terraform workspace list

# Descargar el estado actual del workspace remoto
terraform state pull > current-state.json

# Ver el contenido del estado descargado
cat current-state.json | python3 -m json.tool | less

# Si necesitas restaurar un estado anterior, subir el estado corregido
terraform state push corrected-state.json

Migración de Estado entre Backends

Cuando necesitas cambiar el backend (por ejemplo, de local a S3, o de S3 a Terraform Cloud):

De local a S3

# Paso 1: Añadir la configuración del nuevo backend a main.tf
terraform {
  backend "s3" {
    bucket = "nuevo-bucket-de-estado"
    key    = "terraform.tfstate"
    region = "us-east-1"
  }
}

# Paso 2: Ejecutar init con migración
terraform init -migrate-state

# Terraform detectará el cambio de backend y preguntará:
# Initializing the backend...
# Do you want to copy existing state to the new backend?
# ...
# Enter a value: yes

De S3 a Terraform Cloud

# Paso 1: Cambiar la configuración del backend
terraform {
  cloud {
    organization = "mi-organizacion"

    workspaces {
      name = "mi-proyecto-prod"
    }
  }
}

# Paso 2: Autenticarse en Terraform Cloud
terraform login

# Paso 3: Migrar
terraform init -migrate-state

Tabla de Problemas de Estado

Problema	Síntomas	Diagnóstico	Solución
Estado corrupto	`Failed to read the Terraform managed state`	`cat terraform.tfstate \| python3 -m json.tool`	Restaurar desde `terraform.tfstate.backup`
Drift	Plan muestra cambios inesperados	`terraform plan -refresh=true`	Aplicar el plan (revertir) o actualizar el código
Recurso huérfano	Error `NotFound` al hacer `terraform plan`	`terraform state list` y verificar en la nube	`terraform state rm <recurso>`
Estado bloqueado	`Error acquiring the state lock`	Verificar procesos activos de Terraform	`terraform force-unlock <ID>` (con precaución)
Conflicto en equipo	IDs desconocidos en el plan, cambios inesperados	Comparar estados locales de cada persona	Migrar a backend remoto compartido
Estado desactualizado	Plan muestra recursos a crear que ya existen	`terraform refresh` o `terraform plan`	`terraform import` para recursos no gestionados

Flujo de Decisión para Resolver Problemas de Estado

Usa este árbol de decisiones cuando encuentres un problema de estado:

¿Terraform puede leer el estado?
│
├── NO → ¿Existe terraform.tfstate.backup?
│         │
│         ├── SÍ → Restaurar desde backup
│         │         cp terraform.tfstate.backup terraform.tfstate
│         │
│         └── NO → ¿Backend remoto con versioning?
│                   │
│                   ├── SÍ → Restaurar versión anterior desde S3/GCS
│                   └── NO → Reconstruir estado con terraform import
│
└── SÍ → ¿El plan muestra cambios inesperados?
          │
          ├── SÍ → ¿Los recursos existen en la nube?
          │         │
          │         ├── NO → Recurso huérfano
          │         │         → terraform state rm <recurso>
          │         │
          │         └── SÍ → Drift detectado
          │                   → ¿Los cambios son intencionales?
          │                   │
          │                   ├── SÍ → Actualizar código HCL
          │                   └── NO → terraform apply para revertir
          │
          └── NO → ¿Hay un error de lock?
                    │
                    ├── SÍ → ¿Hay otra operación activa?
                    │         │
                    │         ├── SÍ → Esperar a que termine
                    │         └── NO → terraform force-unlock <ID>
                    │
                    └── NO → El estado está bien, revisar el código

Ejercicio: Resolver un Escenario de Estado con Recursos Huérfanos y Drift

Escenario

Eres el nuevo responsable de infraestructura de una empresa. El equipo anterior usaba Terraform pero no tenía buenas prácticas. Al revisar el estado, encuentras la siguiente situación:

terraform state list
# aws_instance.web_server_v1          <- Ya no existe en AWS
# aws_instance.web_server_v2          <- Existe pero con instance_type cambiado manualmente
# aws_s3_bucket.logs                  <- Existe y está correcto
# aws_s3_bucket.old_backups           <- Ya no existe en AWS
# aws_rds_instance.main               <- Existe pero en una versión diferente de DB engine

terraform plan
# Output (resumido):
# aws_instance.web_server_v1: Refreshing state... [id=i-0000000000000001]
# Error: reading EC2 Instance: InvalidInstanceID.NotFound
#
# (Si corrigieras ese error, verías también:)
# ~ aws_instance.web_server_v2 will be updated in-place
#   ~ instance_type = "t2.large" -> "t2.micro"
#
# ~ aws_rds_instance.main will be updated in-place
#   ~ engine_version = "14.10" -> "14.8"

Tu tarea:

Limpia los recursos huérfanos del estado.
Decide cómo manejar el drift en web_server_v2 y rds_instance.main.
Documenta cada decisión tomada.

Solución Detallada

Paso 1: Backup del estado antes de cualquier cambio

# SIEMPRE hacer backup antes de manipular el estado
cp terraform.tfstate terraform.tfstate.pre-cleanup-$(date +%Y%m%d)
echo "Backup creado: terraform.tfstate.pre-cleanup-$(date +%Y%m%d)"

Paso 2: Eliminar recursos huérfanos

# Verificar en AWS que el recurso realmente no existe
aws ec2 describe-instances --instance-ids i-0000000000000001 2>&1
# Output esperado: InvalidInstanceID.NotFound

# Confirmar que el bucket tampoco existe
aws s3api head-bucket --bucket old-backups-bucket-name 2>&1
# Output esperado: 404 Not Found

# Eliminar los recursos huérfanos del estado
terraform state rm aws_instance.web_server_v1
# Removed aws_instance.web_server_v1 from the state

terraform state rm aws_s3_bucket.old_backups
# Removed aws_s3_bucket.old_backups from the state

# Verificar el estado limpio
terraform state list

Paso 3: Resolver el drift en web_server_v2

# Verificar el estado actual del recurso en AWS
aws ec2 describe-instances \
  --instance-ids i-0000000000000002 \
  --query 'Reservations[0].Instances[0].InstanceType'
# Output: "t2.large"

# Decisión: El cambio fue intencional (el equipo anterior lo escaló para producción)
# Actualizar el código HCL para reflejar la realidad

# En main.tf, actualizar el tipo de instancia:
resource "aws_instance" "web_server_v2" {
  ami           = data.aws_ami.ubuntu.id
  instance_type = "t2.large"  # Actualizado para coincidir con la realidad
  # ...
}

# Verificar que el plan ya no muestra cambios para este recurso
terraform plan
# aws_instance.web_server_v2: No changes

Paso 4: Resolver el drift en rds_instance.main

# Verificar la versión del motor en RDS
aws rds describe-db-instances \
  --db-instance-identifier main-db \
  --query 'DBInstances[0].EngineVersion'
# Output: "14.10"

# Decisión: La versión fue actualizada automáticamente por AWS (minor version auto-update)
# NO queremos degradar la versión de la base de datos
# Actualizar el código para aceptar la versión actual

resource "aws_db_instance" "main" {
  identifier     = "main-db"
  engine         = "postgres"
  engine_version = "14.10"  # Actualizado para coincidir con la realidad

  # Prevenir actualizaciones automáticas futuras que causen drift
  allow_major_version_upgrade = false
  auto_minor_version_upgrade  = false

  # ... resto de la configuración
}

Paso 5: Verificación final

# Ejecutar plan para confirmar que no hay más cambios inesperados
terraform plan

# Debe mostrar:
# No changes. Your infrastructure matches the configuration.

Medidas Preventivas para Evitar Problemas de Estado

Medida 1: Siempre usar backend remoto con locking

# Configuración recomendada para equipos
terraform {
  backend "s3" {
    bucket         = "empresa-terraform-state"
    key            = "${var.project}/${var.environment}/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-state-locks"

    # Versionado habilitado en el bucket para recuperación
    # (configurar en AWS, no en Terraform)
  }
}

Medida 2: Habilitar versioning en el bucket de estado

# Crear el bucket con versioning habilitado
resource "aws_s3_bucket" "terraform_state" {
  bucket = "empresa-terraform-state"
}

resource "aws_s3_bucket_versioning" "terraform_state" {
  bucket = aws_s3_bucket.terraform_state.id

  versioning_configuration {
    status = "Enabled"
  }
}

resource "aws_s3_bucket_server_side_encryption_configuration" "terraform_state" {
  bucket = aws_s3_bucket.terraform_state.id

  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm = "AES256"
    }
  }
}

Medida 3: Políticas de acceso estrictas

# Solo el rol de CI/CD y los administradores pueden modificar el estado
resource "aws_s3_bucket_policy" "terraform_state" {
  bucket = aws_s3_bucket.terraform_state.id

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Sid    = "AllowTerraformAccess"
        Effect = "Allow"
        Principal = {
          AWS = [
            "arn:aws:iam::123456789:role/terraform-cicd-role",
            "arn:aws:iam::123456789:user/terraform-admin"
          ]
        }
        Action = [
          "s3:GetObject",
          "s3:PutObject",
          "s3:DeleteObject",
          "s3:ListBucket"
        ]
        Resource = [
          "arn:aws:s3:::empresa-terraform-state",
          "arn:aws:s3:::empresa-terraform-state/*"
        ]
      }
    ]
  })
}

Medida 4: No interrumpir operaciones de Terraform en curso

# Si necesitas cancelar un apply, hazlo de forma controlada:
# 1. Presiona Ctrl+C UNA SOLA VEZ
# 2. Espera a que Terraform termine el recurso actual y libere el lock
# 3. NO presiones Ctrl+C de nuevo ni cierres la terminal

# Si el proceso fue interrumpido abruptamente, verifica el estado:
terraform state list
terraform plan  # Para ver si hay inconsistencias

Medida 5: Nunca editar el estado manualmente

Si necesitas modificar el estado, usa los comandos de Terraform:

# En lugar de editar terraform.tfstate con un editor de texto, usa:
terraform state mv  # Para mover/renombrar recursos en el estado
terraform state rm  # Para eliminar recursos del estado
terraform import    # Para añadir recursos al estado
terraform state push  # Para subir un estado modificado externamente

Resumen

En esta lección has aprendido a manejar los problemas de estado más críticos de Terraform:

Estado corrupto: Cómo restaurarlo desde el backup automático o desde versiones previas en S3.
Drift: Cómo detectarlo con terraform plan y resolverlo ya sea revertiendo cambios o actualizando el código.
Recursos huérfanos: Cómo limpiarlos del estado con terraform state rm sin afectar otros recursos.
Estado bloqueado: Cómo identificar si el lock es genuino y cómo forzar el desbloqueo con terraform force-unlock de forma segura.
Conflictos en equipo: Por qué el estado local es peligroso y cómo migrar a un backend remoto compartido.
Medidas preventivas: Backend remoto con locking, versioning en S3, permisos estrictos y nunca editar el estado manualmente.

El estado es el activo más valioso de tu configuración Terraform. Trátalo con el mismo cuidado que tratarías una base de datos de producción: backups regulares, acceso controlado y operaciones cuidadosamente planificadas.

En la siguiente lección exploraremos los recursos de comunidad y soporte disponibles en el ecosistema de Terraform, incluyendo documentación, foros, herramientas complementarias y las certificaciones de HashiCorp.

Problemas de Gestión del Estado