Cómo CONECTAR Terraform con Google Cloud (GCP) paso a paso | Autenticación Segura con ADC
Conectar Terraform con Google Cloud no debería empezar descargando una clave JSON y copiándola por diferentes máquinas. Para desarrollo local, el patrón moderno es utilizar Application Default Credentials (ADC): Terraform puede utilizar las credenciales proporcionadas por el ecosistema de Google Cloud sin incrustar secretos en el código de infraestructura.
En esta guía construiremos el flujo completo desde cero: instalación de Terraform
y Google Cloud CLI, autenticación, selección del proyecto, configuración del
provider de Google, inicialización del working directory, validación y primer
despliegue. El objetivo no es únicamente conseguir un
terraform apply, sino establecer una base que pueda evolucionar hacia
un entorno empresarial gobernado.
Lo que aprenderás
La arquitectura correcta empieza por la identidad
Terraform no necesita conocer una contraseña de Google Cloud. El provider
google necesita obtener una identidad válida con permisos
suficientes para consultar y modificar recursos GCP.
ADC funciona como una abstracción de autenticación: las librerías de Google buscan credenciales siguiendo un mecanismo estándar y obtienen tokens para realizar llamadas a las APIs. Esto permite separar la configuración de infraestructura de la distribución de secretos.
Para un equipo senior o de arquitectura, esta separación es importante: Terraform describe el estado deseado; IAM determina quién puede materializarlo.
Patrón recomendado para desarrollo local
Utiliza Google Cloud CLI para autenticar la identidad del desarrollador y genera las credenciales ADC con:
gcloud auth application-default login
Una vez configuradas, Terraform puede utilizar ADC sin que el bloque
provider contenga una clave privada.
Matriz de decisión: ¿cómo autenticar Terraform en GCP?
No todos los mecanismos de autenticación tienen el mismo perfil operativo. La elección debe considerar dónde ejecutas Terraform, quién controla la identidad y cómo se gestiona el ciclo de vida de las credenciales.
| Patrón | Entorno | Gestión de secretos | Seguridad | Operación | Uso recomendado |
|---|---|---|---|---|---|
| ADC + usuario | Workstation | Gestionada por Google Cloud CLI | Alta para desarrollo | Baja complejidad | Desarrollo local |
| ADC + impersonation | Workstation / CI | Sin clave descargada | Muy alta | Media | Equipos con IAM maduro |
| Service Account adjunta | Google Cloud | Identidad gestionada por plataforma | Muy alta | Baja | Terraform ejecutándose dentro de GCP |
| Workload Identity Federation | CI/CD externo | Credenciales federadas | Muy alta | Media/Alta | GitHub Actions, GitLab CI y otros IdP |
| Service Account Key JSON | Cualquier entorno | Secreto estático | Mayor riesgo | Alta | Evitar salvo necesidad justificada |
1. Instalar Terraform y Google Cloud CLI
Necesitamos dos herramientas: Terraform CLI para ejecutar la infraestructura
como código y gcloud para interactuar con la plataforma de
Google Cloud y configurar la autenticación local.
Terraform CLI
Terraform se distribuye como un ejecutable y también puede instalarse mediante gestores de paquetes.
brew tap hashicorp/tap
brew install hashicorp/tap/terraform
terraform versionWindows
Si utilizas Chocolatey, puedes instalar Terraform desde una terminal administrativa:
choco install terraform
terraform versionGoogle Cloud CLI
Instala Google Cloud CLI siguiendo el instalador oficial para tu sistema
operativo y comprueba que gcloud está disponible:
gcloud versionDespués de instalar ambas herramientas, el objetivo es que estos dos comandos funcionen desde una terminal nueva:
terraform version
gcloud version2. Crear o seleccionar el proyecto de Google Cloud
Terraform necesita saber sobre qué proyecto va a operar. Puedes trabajar con un proyecto GCP existente o crear uno nuevo desde la consola de Google Cloud.
Una vez tengas el Project ID, configúralo como proyecto activo en Google Cloud CLI:
gcloud auth login
gcloud projects list
gcloud config set project TU_PROJECT_ID
gcloud config get-value projectEs importante distinguir el nombre visible del proyecto de su Project ID. El provider de Terraform utiliza el identificador del proyecto como referencia estable.
3. Configurar Application Default Credentials (ADC)
Este es el punto central de la autenticación Terraform-GCP. En desarrollo local, ejecuta:
gcloud auth application-default loginSe abrirá un flujo de autenticación para autorizar tu identidad. Una vez finalizado, las credenciales locales estarán disponibles para las aplicaciones que utilizan ADC.
Un error habitual consiste en crear una cuenta de servicio, generar una clave privada JSON, descargarla y después colocarla en el portátil del desarrollador o en un repositorio privado.
Aunque técnicamente puede funcionar, introduces un secreto estático cuyo ciclo de vida debes gestionar: distribución, almacenamiento, rotación, revocación y posible exposición.
Para desarrollo local, utiliza ADC. Para automatización externa, considera Workload Identity Federation; para workloads dentro de Google Cloud, utiliza una identidad de servicio administrada y con privilegios mínimos.
4. Configurar el provider de Google para Terraform
Crea un directorio para el proyecto y un archivo
main.tf. La configuración no contiene ningún secreto.
La identidad procede de ADC.
terraform {
required_version = ">= 1.5.0"
required_providers {
google = {
source = "hashicorp/google"
version = "~> 7.43"
}
}
}
provider "google" {
project = var.project_id
region = var.region
}
variable "project_id" {
description = "Google Cloud Project ID"
type = string
}
variable "region" {
description = "Default GCP region"
type = string
default = "europe-west1"
}
Observa una decisión importante: el bloque provider no contiene
credentials. Esto evita convertir el fichero Terraform en un
contenedor de secretos.
5. Separar configuración de infraestructura y parámetros
En un proyecto real no conviene introducir el Project ID directamente en múltiples recursos. Utiliza variables y, cuando corresponda, archivos de variables específicos del entorno.
project_id = "TU_PROJECT_ID"
region = "europe-west1"No subas a Git información sensible. Aunque un Project ID normalmente no es un secreto, las credenciales, tokens y claves privadas sí lo son.
6. Crear una infraestructura mínima y verificable
Para validar todo el circuito podemos crear un bucket de Cloud Storage. Este ejemplo es deliberadamente pequeño: el objetivo es verificar la cadena completa de autenticación, provider, API, permisos, plan y apply.
resource "google_storage_bucket" "terraform_demo" {
name = "${var.project_id}-terraform-demo"
location = "EU"
uniform_bucket_level_access = true
lifecycle {
prevent_destroy = false
}
}En producción, el nombre, la ubicación, las políticas de retención y el ciclo de vida del recurso deberían responder a requisitos de plataforma, seguridad y gobierno. Aquí buscamos únicamente un primer recurso fácil de identificar.
7. El workflow correcto: init → validate → plan → apply
Terraform separa la inicialización, validación y ejecución. Esa separación es especialmente útil cuando pasamos de un entorno de laboratorio a pipelines de CI/CD.
terraform init
terraform fmt -recursive
terraform validate
terraform plan
terraform apply
terraform init prepara el directorio de trabajo y descarga el
provider necesario. Después, validate comprueba la configuración
y plan muestra el cambio propuesto antes de modificar la
infraestructura.
En un entorno empresarial, el patrón habitual es hacer que
plan forme parte de una revisión automatizada y restringir
apply a identidades y pipelines autorizados.
Implementación práctica de referencia
Esta versión concentra el flujo mínimo en una estructura que puede servir como punto de partida para un repositorio real.
terraform-gcp/
├── main.tf
├── variables.tf
├── terraform.tfvars
└── .gitignorevariable "project_id" {
description = "Google Cloud Project ID"
type = string
}
variable "region" {
description = "Default GCP region"
type = string
default = "europe-west1"
}terraform {
required_version = ">= 1.5.0"
required_providers {
google = {
source = "hashicorp/google"
version = "~> 7.43"
}
}
}
provider "google" {
project = var.project_id
region = var.region
}
resource "google_storage_bucket" "terraform_demo" {
name = "${var.project_id}-terraform-demo"
location = "EU"
uniform_bucket_level_access = true
}project_id = "TU_PROJECT_ID"
region = "europe-west1".terraform/
*.tfstate
*.tfstate.*
crash.log
crash.*.log
*.tfvars
*.tfvars.json
.terraform.lock.hcl
El .gitignore debe adaptarse a la política del repositorio.
Especialmente importante: nunca cometas estados que puedan contener valores
sensibles sin haber evaluado previamente el backend y el modelo de exposición.
Patrones de diseño para pasar de laboratorio a producción
La primera ejecución es sencilla. La arquitectura de Terraform que soportará decenas de proyectos, equipos y entornos no lo es. Estos son los patrones que conviene adoptar desde el principio.
01 · Identidad sin secretos
- ADC para desarrollo local.
- Impersonation cuando sea viable.
- Workload Identity Federation para CI/CD externo.
- Evitar claves JSON estáticas.
02 · Least Privilege
- Separar identidades de desarrollo y despliegue.
- Asignar roles mínimos necesarios.
- Evitar cuentas de servicio excesivamente privilegiadas.
- Auditar permisos periódicamente.
03 · State controlado
- Evitar compartir state local manualmente.
- Usar un backend remoto apropiado.
- Controlar concurrencia y acceso.
- No modificar el state manualmente.
04 · Version Pinning
- Fijar la versión de Terraform cuando corresponda.
- Fijar rangos controlados del provider.
- Revisar actualizaciones regularmente.
- Automatizar pruebas antes de actualizar.
05 · CI/CD
- terraform fmt.
- terraform validate.
- terraform plan como artefacto de revisión.
- apply sujeto a controles de aprobación.
06 · Gobernanza
- Módulos reutilizables.
- Políticas de naming y labels.
- Revisión de IAM.
- Separación clara entre entornos.
Antipatrones críticos: seguridad, FinOps y operación
Dar a la identidad de Terraform permisos administrativos globales puede parecer cómodo durante el primer despliegue, pero amplifica el impacto de cualquier error de configuración o compromiso de la identidad.
Un terraform apply puede crear recursos con costes recurrentes.
Bases de datos, IPs, clusters y otros servicios deben considerar explícitamente
sus costes de ejecución, retención y destrucción.
En equipos pequeños puede ser aceptable para prototipos. En producción, conviene mover el despliegue a un pipeline controlado, con revisión del plan, identidad dedicada, logs y trazabilidad.
ADC responde principalmente a la pregunta “¿quién soy?”. IAM responde a “¿qué puedo hacer?”. Configurar correctamente ADC no concede permisos mágicamente: la identidad debe tener los roles adecuados sobre el proyecto o los recursos.
Checklist de implementación empresarial
Antes de considerar terminado el onboarding de Terraform con GCP, comprueba cada uno de estos puntos.
Instalar Terraform
Verifica que la versión instalada sea compatible con el proyecto y establece una política de actualización.
Instalar Google Cloud CLI
Ejecuta gcloud version y confirma que la CLI esté disponible
desde la terminal utilizada por Terraform.
Autenticar la identidad
Utiliza gcloud auth login para la sesión de CLI y
gcloud auth application-default login para crear ADC local.
Seleccionar el proyecto
Configura el Project ID correcto y comprueba el valor con
gcloud config get-value project.
Configurar el provider
Define el provider de Google sin incrustar claves privadas en HCL.
Inicializar Terraform
Ejecuta terraform init para descargar providers y preparar
el working directory.
Validar antes de aplicar
Ejecuta terraform fmt, terraform validate y
revisa cuidadosamente terraform plan.
Aplicar con control
Ejecuta terraform apply únicamente cuando el plan haya sido
revisado y la identidad tenga los permisos mínimos necesarios.
Preguntas frecuentes sobre Terraform + GCP + ADC
¿Cuál es la forma recomendada de autenticar Terraform con Google Cloud?
Para desarrollo local, Google Cloud recomienda Application Default
Credentials mediante
gcloud auth application-default login. Para ejecución en
producción, la identidad debería adaptarse al entorno: una identidad de
servicio administrada cuando Terraform corre en Google Cloud o federación
de identidad cuando procede desde un proveedor externo.
¿Necesito guardar una clave JSON de una cuenta de servicio?
No para el flujo de desarrollo local basado en ADC. Descargar claves estáticas aumenta la superficie de gestión de secretos. Cuando sea posible, utiliza ADC, impersonation o Workload Identity Federation según el contexto de ejecución.
¿Qué comandos necesito para realizar el primer despliegue?
Una secuencia básica es
terraform init,
terraform fmt,
terraform validate,
terraform plan y
terraform apply. Antes de ello, debes haber configurado
correctamente ADC y disponer de permisos IAM suficientes en el proyecto.
Conclusión: la conexión correcta no es “poner credenciales”
Conectar Terraform con GCP de forma profesional consiste en diseñar una cadena de identidad reproducible y segura. Para un desarrollador local, ADC elimina la necesidad de introducir claves privadas directamente en Terraform. A partir de ahí, el siguiente nivel es aplicar impersonation, federación de identidad, mínimo privilegio y CI/CD controlado.
El flujo fundamental queda reducido a una arquitectura sencilla: identidad → ADC → provider → plan → revisión → apply. Lo importante es que cada capa tenga una responsabilidad clara.
Si este patrón se establece desde el primer proyecto, migrar posteriormente hacia una plataforma Terraform empresarial resulta mucho más sencillo: los módulos pueden evolucionar, el backend puede centralizarse y la identidad puede pasar de usuarios locales a workloads federados sin reescribir la infraestructura.