Terraform: ¿.terraform.lock.hcl en .gitignore? Mi opinión clara

Cada vez que alguien pregunta si el archivo .terraform.lock.hcl debe ir en .gitignore, me dan ganas de gritar un poco. La respuesta corta, y la que yo siempre recomiendo, es un rotundo NO, no va en .gitignore. Este archivo es fundamental para la reproducibilidad de tu infraestructura, y si lo ignoras, estás abriendo la puerta a problemas que pueden ser un dolor de cabeza.

En mi experiencia, y te lo digo con más de una década en esto, he visto suficientes bugs y despliegues fallidos por cosas como esta. El archivo .terraform.lock.hcl guarda las selecciones de versiones exactas de los providers que Terraform usó la última vez que ejecutaste terraform init. Así de simple.

El Core: Reproducibilidad y Consistencia

Cuando trabajas con Terraform, dependes de providers (AWS, Azure, Google Cloud, etc.) y cada uno tiene sus versiones. Si tu configuración dice que usas el provider de AWS ~> 4.0, eso significa “cualquier versión 4.x.y que sea compatible con 4.0”. El problema es que una nueva versión 4.5.0 podría introducir un cambio que rompa tu código, aunque siga siendo 4.x. El archivo .terraform.lock.hcl entra aquí para fijar la versión exacta que funcionó en tu ambiente.

Cuando ejecutas terraform init:

• Si no existe el .terraform.lock.hcl, Terraform busca la última versión compatible con tus restricciones, la instala y crea el archivo con esa selección.
• Si ya existe, Terraform reutiliza las versiones exactas guardadas en él, garantizando que todos los que trabajen con ese código usen las mismas versiones de providers. Esto es oro puro para la consistencia entre desarrolladores y el CI/CD.

Si quieres que Terraform ignore el archivo de bloqueo y busque versiones más nuevas, puedes forzarlo con la opción -upgrade:

terraform init
# O para actualizar las versiones de los providers
terraform init -upgrade

Yo uso esto solo cuando intencionalmente quiero actualizar los providers, no como rutina. De hecho, me ha salvado de bugs a las 3 AM que habrían sido imposibles de depurar si cada ambiente tuviera versiones distintas de providers.

El Famoso Problema Multiplataforma

Ahora, entiendo por qué la gente se confunde y, a veces, cede a la tentación de ignorar este archivo. El problema más común surge en equipos heterogéneos, con desarrolladores en macOS, otros en Windows, y el CI en Linux. Aquí es donde te puede aparecer un error como este:

│ Error: Failed to install provider
│
│ Error while installing hashicorp/null v3.1.1: the local package for registry.terraform.io/hashicorp/null 3.1.1 doesn't match any of the checksums previously recorded in the dependency lock file
│ (this might be because the available checksums are for packages targeting different platforms)

Esto me costó un PR rechazado una vez en un proyecto con un cliente que usaba varios sistemas operativos. Yo había actualizado un provider en mi Mac, y el CI en Linux no lograba hacer match con los checksums registrados. Es frustrante, sí.

El error se debe a que el archivo .terraform.lock.hcl también contiene checksums específicos para la plataforma en la que se generó. Si un compañero con Windows ejecuta terraform init, generará un checksum para Windows. Si tú, con macOS, intentas usar ese mismo archivo sin el checksum de tu plataforma, Terraform se queja.

La solución limpia, y la que te evita perder la reproducibilidad, no es tirar el archivo al .gitignore. Es decirle a Terraform que genere los checksums para todas las plataformas que tu equipo usa. Esto lo haces con terraform providers lock:

terraform providers lock \
    -platform=windows_amd64 \
    -platform=darwin_amd64 \
    -platform=linux_amd64 \
    -platform=darwin_arm64 \
    -platform=linux_arm64

Con esto, el archivo .terraform.lock.hcl incluirá los checksums para todas esas plataformas, y ya no tendrás el error cuando cambies de OS. A mí me carga cuando la gente se rinde y lo manda al .gitignore. Es una solución parche que crea más problemas de los que resuelve a largo plazo. Sí, es un paso extra al principio, pero te ahorra dolores de cabeza grandes más adelante.

Mi Opinión Final

Para mí, la filosofía de Terraform es tener la infraestructura como código. Y como cualquier código, necesita ser versionado y reproducible. El archivo .terraform.lock.hcl es una parte integral de eso. Ignorarlo es como ignorar el package-lock.json en Node.js o el Gemfile.lock en Ruby: pierdes el control sobre las dependencias exactas que tu código usa.

Entiendo que la sobreingeniería puede ser un problema, pero aquí no estamos hablando de eso. Estamos hablando de una práctica fundamental para la estabilidad y el trabajo en equipo. Es el costo de la consistencia.

¿En qué se equivoca la gente con esto?

El error más común es pensar que este archivo es 'ruido' o algo que genera conflictos y debe ignorarse. No es ruido; es información crítica. Otro error es generar el archivo en una sola plataforma y no pensar en los demás miembros del equipo o en el CI/CD. Ojo, un terraform init -upgrade ocasional puede ser útil, pero no debe ser la norma sin un control adecuado, porque puede introducir cambios no deseados.

Mi consejo es simple: comprométete con la reproducibilidad. Incluye siempre .terraform.lock.hcl en tu control de versiones y, si trabajas en un equipo multiplataforma, usa terraform providers lock para pre-poblar los checksums necesarios. Te lo agradecerás.