Providers Terraform: restricciones, lockfile y cadena de suministro

Un provider es código ejecutable que Terraform u OpenTofu descarga y ejecuta para hablar con una API. Tratarlo como “el conector de AWS” se queda corto: es una dependencia de software con versión, origen, firma, checksums, permisos y capacidad para modificar infraestructura.

Cada módulo debe declarar el source address y una restricción compatible. El root module reúne esas restricciones y el runtime selecciona una sola versión por provider. OpenTofu recomienda declarar al menos la versión mínima conocida y dejar que el root administre el máximo cuando corresponda. [1]

Restricción no es selección

Esta configuración expresa un conjunto aceptable:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.40"
    }
  }
}

No dice qué build se instaló hoy. La selección concreta queda registrada en .terraform.lock.hcl. Por eso hay dos decisiones distintas:

• restricción: qué versiones creemos compatibles con el código;
• lock: qué versión y checksums aceptamos para ejecuciones reproducibles.

HashiCorp indica que el lockfile pertenece a la configuración completa y debe versionarse para que sus cambios se revisen como código. Actualmente fija providers; no fija automáticamente versiones de módulos remotos. [2]

State, lockfile y plan no son intercambiables. El state vincula direcciones con objetos remotos; el lockfile fija la dependencia ejecutable aceptada; el plan calcula acciones usando configuración, state, provider seleccionado y observación remota. Revisar solo uno deja sin explicar los otros dos cambios posibles.

El checksum responde una pregunta limitada

Un hash coincidente demuestra que el paquete descargado es el mismo que registraste; no demuestra que el provider sea seguro, correcto o apropiado. La confianza inicial sigue siendo una decisión humana u organizacional: origen esperado, publisher, firma y política de admisión.

Ese matiz importa en mirrors internos. Si el lock se generó solo desde un mirror y una plataforma, puede carecer de los checksums oficiales para otras plataformas. terraform providers lock o tofu providers lock permite precargar plataformas y consultar el origen para registrar paquetes verificables. OpenTofu advierte que el comando no decide si el firmante es confiable: muestra la evidencia para que tú lo decidas. [3]

tofu providers lock \
  -platform=linux_amd64 \
  -platform=darwin_arm64 \
  -platform=windows_amd64

¿Constraint exacto o rango compatible?

Un upgrade es una migración observada

No borres el lockfile para “arreglar init”. Ese gesto descarta la decisión que debías revisar. Un upgrade disciplinado tiene esta secuencia:

1. actualiza la restricción de forma intencional;
2. ejecuta init -upgrade en una rama aislada;
3. revisa el diff del lockfile, versiones, hashes y firmantes;
4. consulta changelog y breaking changes del provider;
5. ejecuta tests y genera un plan guardado;
6. inspecciona reemplazos, campos desconocidos y cambios de default;
7. aplica primero en un entorno descartable;
8. documenta rollback o forward fix.

El plan puede cambiar aunque el HCL no cambie: un provider nuevo puede leer la API de otra forma, modificar defaults o corregir un diff. Por eso “solo cambió .terraform.lock.hcl” no significa “no cambió infraestructura”.

Fallo típico: lockfile generado en una sola laptop

El equipo Linux recibe un error de checksum después de que el lockfile fue creado desde un mirror en macOS. Añadir el hash que aparece en el error a mano resuelve el síntoma y destruye la cadena de confianza. La respuesta correcta es regenerar entradas para las plataformas soportadas desde el origen autorizado, revisar el firmante y volver a ejecutar init en un entorno limpio.

Resolver dependencias como una operación de suministro

El constraint declara qué versiones aceptaría el código; el lockfile registra cuál fue seleccionada y qué paquetes se consideran válidos. La diferencia importa durante una instalación limpia: sin lockfile, dos runners pueden resolver versiones distintas aun con el mismo HCL. Con un lock incompleto, una plataforma adicional puede consultar el registry y ampliar la confianza sin revisión consciente.

Define las plataformas que el equipo soporta y genera sus hashes desde una fuente autorizada. Si usas un mirror, documenta quién lo alimenta, cómo verifica firmas y cuándo se invalida la caché. Un mirror acelera y permite operar aislado; también se convierte en un punto de suministro que merece controles propios.

Durante un upgrade, revisa tres capas. El changelog del provider anuncia cambios conocidos; el diff del lockfile muestra selección y hashes; el plan revela el efecto contra tu configuración y estado. Ninguna sustituye a las otras. Si el plan no cambia, todavía conviene ejecutar smoke tests de lecturas y operaciones críticas, porque un bug puede aparecer fuera del diff calculado.

Automatiza una instalación sin caché en CI. Es la prueba que demuestra que registry, mirror, lockfile y plataformas declaradas pueden reconstruir el entorno. Un runner que siempre reutiliza plugins locales puede permanecer verde mientras un colaborador nuevo ya no puede inicializar el proyecto.

Cuando retires una plataforma, elimina sus hashes mediante un cambio revisado y explica la decisión. La limpieza silenciosa hace imposible distinguir mantenimiento intencional de una reducción accidental en la cadena de confianza.

Contrato de lab

El lab usa un provider inofensivo y debe producir:

• constraint documentado;
• lockfile commiteable con al menos dos plataformas;
• evidencia de checksum válido;
• prueba negativa con un paquete alterado o hash inválido;
• diff controlado de init -upgrade;
• plan posterior sin cambios no explicados.

Conexiones dentro de la serie

• Antes: Módulos como contratos de composición.
• Después: Testing, planes y políticas.
• Lab relacionado: Terraform lab network.