Terraform AWS ECR: repositorios y políticas en AWS 2026

Con Terraform AWS ECR puedes declarar repositorios de imágenes Docker en Amazon Elastic Container Registry, políticas de ciclo de vida y permisos IAM como infraestructura reproducible. Es el eslabón habitual entre tu pipeline de build y despliegues en ECS o EKS: un solo terraform apply crea el registro, las etiquetas permitidas y las reglas que evitan que el almacenamiento crezca sin control.

• Qué verás: recurso aws_ecr_repository, políticas de lifecycle y ejemplo de lectura desde Kubernetes o ECS.
• Qué necesitas: AWS CLI configurado, provider AWS en Terraform y permisos para ECR en la cuenta destino.
• Salida práctica: URL del registry lista para docker push y documentación en código.

Terraform AWS ECR: cuándo usarlo en tu flujo DevOps

Terraform AWS ECR encaja cuando quieres versionar infraestructura de registro igual que versionas redes con Terraform AWS VPC o clusters con Terraform GCP GKE: un repositorio por equipo o por servicio, etiquetas inmutables y políticas que limpian imágenes antiguas. Sin IaC, es fácil acabar con nombres arbitrarios, reglas manuales en la consola y sorpresas en la factura de almacenamiento.

ECR se integra nativamente con IAM: los mismos roles que usas en CI pueden obtener tokens de login efímeros para docker push. Modelar eso con Terraform AWS ECR permite que el onboarding de un nuevo microservio sea “añadir módulo + PR”, no tickets interminables a cloud.

Terraform AWS ECR: requisitos, provider y estado remoto

Instala Terraform y configura el provider hashicorp/aws con región y credenciales (perfil SSO, role asumido o variables de entorno estándar). La guía conceptual de orquestación sigue siendo la documentación oficial de Terraform y el mapa de permisos mínimos en IAM para Amazon ECR.

En equipos maduros, separa estados por entorno (dev/stage/prod) y evita mezclar repositorios globales en un solo estado sin remotos bloqueados. Terraform AWS ECR no sustituye el escaneo de imágenes: combina con AWS Inspector o herramientas CI si tu política lo exige.

El backend remoto (S3 + DynamoDB para lock, o Terraform Cloud) es obligatorio cuando varias personas tocan los mismos repos lógicos. Documenta el nombre del workspace y los tags estándar Environment, Owner y CostCenter en el proveedor AWS para que Cost Explorer pueda atribuir gasto de almacenamiento ECR a un equipo. Sin etiquetas, optimizar costes de Terraform AWS ECR se convierte en adivinanza.

Versiona el proveedor AWS en required_providers y fija restricciones de versión; los cambios en el esquema de recursos ECR son poco frecuentes pero una actualización mayor del provider puede exigir ajustes en atributos obsoletos. Ejecuta terraform fmt y validate en CI antes de permitir merge a la rama que alimenta producción.

Terraform AWS ECR: repositorio base y etiquetado

El recurso principal es aws_ecr_repository. El siguiente ejemplo crea un repo con escaneo inmutable opcional y cifrado AES por defecto; ajusta nombres a tu convención:

resource "aws_ecr_repository" "app" {
  name                 = "mi-servicio/api"
  image_tag_mutability = "MUTABLE"

  image_scanning_configuration {
    scan_on_push = true
  }

  encryption_configuration {
    encryption_type = "AES256"
  }
}

output "repository_url" {
  value = aws_ecr_repository.app.repository_url
}

Si tu política de seguridad exige una clave KMS propia en lugar de AES256 gestionado por AWS, sustituye el bloque de cifrado por encryption_type = "KMS" y kms_key apuntando al ARN de una clave con política que permita a ECR usarla. Documenta la dependencia: rotar la clave sin actualizar Terraform puede dejar pulls fallando hasta el siguiente apply coordinado.

  encryption_configuration {
    encryption_type = "KMS"
    kms_key         = aws_kms_key.ecr.arn
  }

La URL de salida alimenta pipelines GitHub Actions o GitLab CI. Mantén nombres en minúsculas y jerárquicos para reflejar dominio de negocio. Un módulo reutilizable de Terraform AWS ECR puede exponer variables para scan_on_push y para el tiempo de retención vinculado al lifecycle.

Si necesitas replicación entre regiones por continuidad de negocio, valora aws_ecr_replication_configuration en un módulo aparte; aumenta complejidad operativa y coste, pero evita depender de un único punto de fallo regional. Para la mayoría de equipos medianos, un único repo con backups de pipeline fuera de ECR basta.

Los tags de imagen deben seguir convención: sha-git inmutable para releases y latest solo en entornos efímeros. Documenta en el README del módulo cómo consumir el output repository_url desde workflows y desde manifiestos que ya gestionas con Terraform Helm Provider.

Terraform AWS ECR: lifecycle, retención y costes

El almacenamiento de capas huérfanas crece rápido. Usa aws_ecr_lifecycle_policy para conservar solo las últimas N imágenes o filtrar por prefijo de tag. Ejemplo conservador:

resource "aws_ecr_lifecycle_policy" "app" {
  repository = aws_ecr_repository.app.name

  policy = jsonencode({
    rules = [{
      rulePriority = 1
      description  = "Mantener últimas 15 imágenes"
      selection = {
        tagStatus   = "any"
        countType   = "imageCountMoreThan"
        countNumber = 15
      }
      action = { type = "expire" }
    }]
  })
}

Ajusta umbrales según frecuencia de despliegue. Las políticas mal calibradas borran builds que aún referencia un manifiesto de Kubernetes: coordina con el equipo de plataforma antes de bajar countNumber. La referencia de AWS sobre lifecycle está en la documentación de políticas de ciclo de vida de ECR.

Puedes combinar reglas por prefijo de tag: por ejemplo conservar siempre release-* y limitar ramas de desarrollo. Terraform permite gestionar el JSON como plantilla o con jsonencode como en el ejemplo; evita concatenar strings manualmente para no romper el JSON. Tras cada cambio, revisa en la consola de ECR la pestaña de lifecycle y valida con una imagen de prueba que la regla hace lo esperado.

Supervisa el métrica de almacenamiento en CloudWatch y alerta si crece de forma sostenida: a veces el problema no es lifecycle sino builds que generan capas enormes por falta de multi-stage Dockerfile. Terraform AWS ECR limpia metadatos, pero no arregla imágenes mal construidas.

Terraform AWS ECR: IAM, políticas de repositorio y multi-cuenta

Para que CI empuje imágenes, asocia políticas IAM mínimas (ecr:GetAuthorizationToken más permisos de push en el ARN del repo). Para pulls desde otra cuenta (por ejemplo un EKS en cuenta workload), usa aws_ecr_repository_policy o IAM conditions en el role de los nodos. Documenta cada excepción cross-account en el mismo repositorio Terraform para evitar configuraciones “solo en consola”.

Si combinas Terraform AWS ECR con organizaciones AWS Organizations, valida SCPs que limiten creación de repos en cuentas sandbox. Un error frecuente es permitir ecr:* en desarrollo y olvidar cerrar el mismo patrón en producción.

Para lectura pública restringida (por ejemplo artefactos compartidos con un partner), usa políticas de repositorio con condiciones IP o con principal externo explícito. Cada excepción debe justificarse en el control de cambios: las políticas JSON mal editadas son una fuente habitual de incidentes de “demasiado permisivo”.

Terraform AWS ECR: Kubernetes, CI/CD y promoción de imágenes

En EKS, el control plane necesita permisos para leer del registry; los nodos usan el role de instancia o IRSA. Tras crear el repo, actualiza los manifiestos Helm o el image de tus Deployments con la URL devuelta por Terraform. Si también gestionas clusters con Terraform Kubernetes Provider, mantén versiones de chart alineadas con los tags que publicas en ECR.

En entornos híbridos, muchos equipos combinan ECR con builds locales documentados en Docker Compose del blog: la imagen se construye en CI, se sube a ECR y el mismo digest se promociona entre entornos. Terraform AWS ECR fija el contrato de nombres y evita que cada desarrollador publique en registros personales fuera de auditoría.

Automatiza terraform plan en merge requests y requiere revisión para cambios en lifecycle: un error puede purgar imágenes aún referenciadas por releases largos.

En pipelines CI, usa OIDC hacia AWS en lugar de claves de larga duración; el rol debe listar solo el ARN del repositorio creado por Terraform AWS ECR. Añade paso de escaneo con herramientas como Trivy antes del push a prod y falla el job si hay CVE críticas no aceptadas por política.

La promoción entre entornos puede ser “mismo digest, distintas cuentas o tags”: evita reconstruir la imagen al pasar a producción; copia el manifiesto entre registros si tu arquitectura lo requiere. Documenta ese flujo junto al código Terraform para que nuevos ingenieros no publiquen desde laptops locales.

El ecosistema HashiCorp publica referencias en el Terraform Registry, la documentación de producto en HashiCorp y el código del proveedor en terraform-provider-aws en GitHub: úsalos para contrastar versiones de recursos antes de actualizar el pin del provider. Si modelas roles IAM junto al registro, revisa patrones complementarios en Terraform AWS IAM del blog para alinear políticas de push y pull sin duplicar definiciones contradictorias.

Terraform AWS ECR: importación, drift y gobernanza

Cuando el repositorio ya existe en la cuenta, no lo recrees a mano: declara el bloque equivalente y usa terraform import aws_ecr_repository.nombre id-o-arn para adoptar el recurso. Después de importar, ejecuta plan y corrige diferencias en cifrado, etiquetas o image_tag_mutability hasta lograr un plan vacío. Si el equipo dejó políticas de lifecycle en la consola, impórtalas como aws_ecr_lifecycle_policy o gestiona el JSON desde Terraform para evitar dos fuentes de verdad.

El drift aparece cuando alguien modifica el repositorio fuera de IaC: activa notificaciones o revisiones periódicas y documenta que los cambios deben pasar por merge request. En organizaciones con varias cuentas AWS, alinea los nombres de repo con el catálogo de servicios y con el inventario de imágenes base; nada impide que dos equipos elijan el mismo string si no hay convención central. Una tabla interna simple (servicio, cuenta, URL de ECR, owner) reduce incidentes de “empujamos al registry equivocado”.

Antes del primer apply en producción, revisa: permisos mínimos en CI, lifecycle probado en entorno espejo, outputs consumidos por pipelines y runbook de rollback si una política borra de más. Guarda el estado en backend con cifrado y control de acceso equivalente al de la cuenta donde vive ECR. Anota en el mismo repositorio quién aprueba cambios en políticas de retención y cómo escalar si un despliegue urgente necesita una imagen que acaba de caducar. Esta disciplina es la misma que aplicarías a redes o identidades: Terraform AWS ECR solo automatiza; la gobernanza sigue siendo humana.

Terraform AWS ECR: errores frecuentes

Si terraform apply falla por nombre de repositorio duplicado, alguien creó el recurso fuera de Terraform: importa o elimina manualmente según gobernanza. Si el push Docker falla con 403, casi siempre es IAM o token caducado; regenera login con aws ecr get-login-password y verifica el role.

Si el lifecycle borró una imagen necesaria, restaura desde pipeline o vuelve a construir desde el commit etiquetado; por eso los tags inmutables por SHA son mejores prácticas. Mantén comunicación con equipos de aplicación antes de endurecer reglas: un cambio aparentemente inocuo en Terraform AWS ECR puede bloquear un rollback de emergencia.

FAQ sobre Terraform AWS ECR

¿ECR público o solo privado?
Este artículo asume registros privados estándar; el flujo y las políticas cambian si publicas artefactos en registros públicos.

¿Puedo importar repositorios ya creados?
Sí, con terraform import sobre aws_ecr_repository y, si aplica, sobre la política de lifecycle; alinea primero el código con el estado real para evitar sustituciones accidentales.

¿Qué ocurre si cambio la política de lifecycle?
Terraform mostrará el diff y AWS aplicará las nuevas reglas en la siguiente evaluación; prueba en desarrollo y comunica a equipos de aplicación antes de endurecer límites en producción.

¿Necesito KMS CMK en todos los casos?
No; el cifrado AES256 gestionado por AWS suele bastar salvo requisitos regulatorios o políticas internas que exijan claves dedicadas y rotación explícita.

¿Cómo evito que latest rompa despliegues?
En entornos serios referencia digest o tags inmutables por commit; reserva latest para pruebas locales o pipelines efímeros con conciencia del riesgo.

En conjunto, modelar el registro con Terraform AWS ECR desde el principio aporta trazabilidad, limpieza automática de imágenes y coherencia con el resto de tu IaC en AWS. Itera políticas con datos reales de uso, revisa costes en Cost Explorer y mantén el estado remoto protegido como cualquier otro proyecto crítico de infraestructura. Si amplías patrones de identidad, mantén la misma rigurosidad que en el resto de cuentas y servicios que ya automatizas con Terraform.