Terraform GCP GKE: Despliega Kubernetes En Google Cloud 2025

Terraform GCP GKE es la combinación perfecta para desplegar clusters de Kubernetes en Google Cloud Platform usando infraestructura como código. En este artículo descubrirás cómo automatizar la creación de clusters GKE con el módulo oficial de Terraform, ahorrando tiempo y reduciendo errores en tus despliegues de contenedores.

¿Qué es Terraform GCP GKE?

Google Kubernetes Engine (GKE) es la implementación gestionada de Kubernetes en Google Cloud Platform. Cuando combinas el módulo oficial terraform-google-modules/kubernetes-engine con las capacidades de infraestructura como código de Terraform, obtienes una solución poderosa para aprovisionar y gestionar clusters de Kubernetes de forma declarativa.

El módulo oficial gestiona la creación de clusters GKE con configuración optimizada, incluyendo node pools, políticas de red, agente de IP masquerading y más de 100 parámetros configurables. Esta herramienta elimina la necesidad de configurar manualmente clusters desde la consola de GCP o mediante comandos gcloud.

Ventajas de usar Terraform GCP GKE

Aprovisionar clusters de Kubernetes con infraestructura como código ofrece múltiples beneficios sobre las configuraciones manuales:

Flujo de trabajo unificado: Integra la creación del cluster con el resto de tu infraestructura en GCP
Gestión completa del ciclo de vida: Crea, actualiza y destruye recursos de forma seamless con un solo comando
Conciencia de dependencias: Terraform comprende las relaciones entre recursos y gestiona automáticamente el orden de creación
Reproducibilidad: La misma configuración genera clusters idénticos en diferentes entornos
Versionado: Almacena tus configuraciones en Git para trazabilidad completa de cambios

Según la documentación oficial de HashiCorp, el aprovisionamiento de un cluster GKE con node pools distribuidos en múltiples zonas toma aproximadamente 10 minutos usando Terraform.

Prerequisitos para Terraform GCP GKE

Antes de comenzar a trabajar con el módulo, necesitas tener configurado tu entorno:

Cuenta de Google Cloud Platform con las APIs habilitadas:
- Compute Engine API
- Kubernetes Engine API
Google Cloud SDK (gcloud) instalado y autenticado
Terraform versión 1.3 o superior (recomendado 1.10+)
kubectl para interactuar con el cluster una vez creado

Para autenticar Terraform con GCP, ejecuta estos comandos:

gcloud init
gcloud auth application-default login

Si aún no tienes Docker configurado en tu entorno DevOps, te recomendamos revisar nuestros tutoriales sobre contenedores antes de continuar.

Configuración básica de Terraform GCP GKE

La estructura básica de un proyecto para aprovisionar un cluster incluye cuatro archivos principales:

Archivo versions.tf

Define los providers y versiones de Terraform requeridas:

terraform {
  required_version = ">= 1.3"
  
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 5.0"
    }
  }
}

provider "google" {
  project = var.project_id
  region  = var.region
}

Archivo vpc.tf

Crea una VPC dedicada para aislar los recursos del cluster:

resource "google_compute_network" "vpc" {
  name                    = "${var.cluster_name}-vpc"
  auto_create_subnetworks = "false"
}

resource "google_compute_subnetwork" "subnet" {
  name          = "${var.cluster_name}-subnet"
  region        = var.region
  network       = google_compute_network.vpc.name
  ip_cidr_range = "10.10.0.0/24"
  
  secondary_ip_range {
    range_name    = "pods-range"
    ip_cidr_range = "10.20.0.0/16"
  }
  
  secondary_ip_range {
    range_name    = "services-range"
    ip_cidr_range = "10.30.0.0/16"
  }
}

Archivo gke.tf

Utiliza el módulo oficial para crear el cluster con node pool gestionado por separado:

module "gke" {
  source  = "terraform-google-modules/kubernetes-engine/google"
  version = "~> 31.0"

  project_id              = var.project_id
  name                    = var.cluster_name
  region                  = var.region
  network                 = google_compute_network.vpc.name
  subnetwork              = google_compute_subnetwork.subnet.name
  ip_range_pods           = "pods-range"
  ip_range_services       = "services-range"
  
  http_load_balancing     = true
  network_policy          = true
  horizontal_pod_autoscaling = true
  
  node_pools = [
    {
      name               = "default-pool"
      machine_type       = "e2-medium"
      min_count          = 1
      max_count          = 3
      disk_size_gb       = 100
      disk_type          = "pd-standard"
      auto_repair        = true
      auto_upgrade       = true
    }
  ]
}

Este ejemplo crea un cluster con autoscaling entre 1 y 3 nodos, similar a configuraciones que usarías para monitorear servicios con Uptime Kuma.

Variables y personalización del módulo

El módulo terraform-google-modules/kubernetes-engine ofrece más de 100 parámetros configurables. Aquí están los más importantes:

Variables de red

network: VPC donde se despliega el cluster
subnetwork: Subred específica para los nodos
ip_range_pods: Rango IP secundario para pods
ip_range_services: Rango IP secundario para servicios

Variables de seguridad

enable_binary_authorization: Activa autorización binaria de imágenes
enable_shielded_nodes: Habilita nodos con Shielded VM
enable_confidential_nodes: Activa nodos confidenciales para cargas de trabajo sensibles

Para proyectos que manejan credenciales sensibles, como cuando configuras Vaultwarden con Docker Compose, los nodos confidenciales son especialmente recomendados.

Variables de addons

http_load_balancing: Habilita balanceador de carga HTTP(S)
horizontal_pod_autoscaling: Activa HPA para escalar pods
network_policy: Habilita políticas de red entre pods
dns_cache: Activa caché de DNS para mejor rendimiento

Crea un archivo terraform.tfvars para tus valores específicos:

project_id   = "mi-proyecto-gcp"
region       = "us-central1"
cluster_name = "produccion-cluster"

Despliegue del cluster con Terraform GCP GKE

Una vez definida la configuración, el despliegue sigue el flujo estándar de Terraform:

1. Inicializar el workspace

terraform init

Este comando descarga el módulo terraform-google-modules/kubernetes-engine desde el Terraform Registry y configura el backend.

2. Revisar el plan de ejecución

terraform plan

Verifica qué recursos se crearán antes de aplicar cambios. Terraform mostrará la VPC, subnet, cluster GKE y node pools que se aprovisionarán.

3. Aplicar la configuración

terraform apply

Confirma con «yes» para iniciar el aprovisionamiento. El proceso toma aproximadamente 10 minutos según la complejidad del cluster.

4. Configurar kubectl

Después del despliegue exitoso, conecta kubectl al nuevo cluster:

gcloud container clusters get-credentials produccion-cluster --region us-central1

Verifica la conexión:

kubectl get nodes

Modos de operación: Autopilot vs Standard

GKE ofrece dos modos de operación que puedes configurar en tu código Terraform:

Modo Autopilot (recomendado)

Google gestiona completamente los nodos, incluyendo hardening automático, actualizaciones de seguridad y escalado. Solo pagas por los recursos que tus pods solicitan:

module "gke_autopilot" {
  source  = "terraform-google-modules/kubernetes-engine/google//modules/beta-autopilot-private-cluster"
  version = "~> 31.0"

  project_id = var.project_id
  name       = "autopilot-cluster"
  region     = var.region
  network    = google_compute_network.vpc.name
  subnetwork = google_compute_subnetwork.subnet.name
  
  release_channel = "REGULAR"
}

Este modo es ideal para equipos que prefieren enfocarse en las aplicaciones en lugar de gestionar infraestructura Kubernetes.

Modo Standard

Ofrece control manual completo sobre la configuración de nodos, machine types, y gestión del cluster. Útil cuando necesitas personalizaciones específicas o ejecutar workloads especializadas.

Configuración avanzada con node pools

Los node pools separados permiten ejecutar diferentes tipos de workloads en el mismo cluster. Aquí un ejemplo con GPU para cargas de trabajo de ML/AI:

module "gke" {
  source  = "terraform-google-modules/kubernetes-engine/google"
  version = "~> 31.0"

  # ... configuración base ...

  node_pools = [
    {
      name         = "general-pool"
      machine_type = "e2-medium"
      min_count    = 1
      max_count    = 5
      disk_size_gb = 100
    },
    {
      name               = "gpu-pool"
      machine_type       = "n1-standard-4"
      min_count          = 0
      max_count          = 2
      disk_size_gb       = 200
      accelerator_count  = 1
      accelerator_type   = "nvidia-tesla-l4"
      gpu_sharing_strategy = "TIME_SHARING"
      max_shared_clients_per_gpu = 4
    }
  ]
}

Según el repositorio oficial de Terraform, la gestión separada de node pools es una best practice que facilita actualizaciones sin downtime.

Mejores prácticas para Terraform GCP GKE

1. Usa Remote State

Almacena el estado de Terraform en Google Cloud Storage para colaboración en equipo:

terraform {
  backend "gcs" {
    bucket = "mi-proyecto-terraform-state"
    prefix = "gke/produccion"
  }
}

2. Habilita auto-repair y auto-upgrade

Configura los node pools para mantenimiento automático:

node_pools = [
  {
    name         = "default-pool"
    auto_repair  = true
    auto_upgrade = true
    # ... resto de configuración ...
  }
]

3. Implementa network policies

Activa políticas de red para segmentar tráfico entre namespaces:

network_policy = true

4. Usa release channels

Los release channels de GKE gestionan automáticamente las versiones de Kubernetes:

Rapid: Últimas features, mayor frecuencia de actualizaciones
Regular: Balance entre estabilidad y nuevas funcionalidades (recomendado)
Stable: Máxima estabilidad, actualizaciones conservadoras

release_channel = "REGULAR"

5. Configura ventanas de mantenimiento

Define cuándo GKE puede realizar mantenimiento automático:

maintenance_start_time = "03:00"
maintenance_end_time   = "06:00"
maintenance_recurrence = "FREQ=WEEKLY;BYDAY=SU"

Monitoreo y observabilidad

Habilita las capacidades de monitoreo integradas de GKE en tu configuración:

module "gke" {
  # ... configuración base ...
  
  monitoring_enable_managed_prometheus = true
  logging_enabled_components           = ["SYSTEM_COMPONENTS", "WORKLOADS"]
  monitoring_enabled_components        = ["SYSTEM_COMPONENTS", "WORKLOADS"]
}

Esto envía métricas y logs a Google Cloud Monitoring y Logging. Para alertas adicionales, puedes integrar herramientas de monitoreo externo que complementen la observabilidad nativa.

Costos de Terraform GCP GKE

Según HashiCorp, Google Cloud cobra aproximadamente $0.10 por hora como tarifa de gestión por cada cluster GKE, aunque un cluster zonal por cuenta de facturación es gratuito. Los costos principales provienen de:

Nodos del cluster: Facturación por instancias de Compute Engine según el machine type
Almacenamiento persistente: Volúmenes PD-Standard, PD-SSD o PD-Balanced
Tráfico de red: Egress entre zonas o regiones
Load balancers: Si usas servicios tipo LoadBalancer

En modo Autopilot, pagas solo por los recursos que tus pods solicitan, lo que puede resultar más económico para cargas variables.

Troubleshooting común

Error: API not enabled

Si recibes errores sobre APIs deshabilitadas, actívalas manualmente:

gcloud services enable compute.googleapis.com
gcloud services enable container.googleapis.com

Error: Insufficient permissions

Verifica que tu cuenta tenga los roles necesarios:

roles/container.admin: Para crear clusters GKE
roles/compute.networkAdmin: Para gestionar VPCs
roles/iam.serviceAccountUser: Para asignar service accounts a nodos

Cluster tarda mucho en crearse

El aprovisionamiento de un cluster con node pools distribuidos toma 8-15 minutos normalmente. Si excede 20 minutos, revisa los logs en GCP Console.

Actualización y destrucción del cluster

Para actualizar la configuración del cluster, modifica tus archivos .tf y ejecuta:

terraform plan
terraform apply

Terraform calculará los cambios necesarios y los aplicará con downtime mínimo cuando uses node pools separados.

Para destruir completamente el cluster y todos los recursos asociados:

terraform destroy

Este comando elimina el cluster, node pools, VPC y todos los recursos creados, liberando los costos asociados.

Preguntas frecuentes (FAQ)

¿Cuál es la diferencia entre el módulo oficial y crear el cluster manualmente?

El módulo terraform-google-modules/kubernetes-engine incorpora best practices probadas en producción, gestiona automáticamente dependencias complejas entre recursos, y ofrece configuraciones pre-validadas que reducen errores. Crear recursos manualmente con google_container_cluster te da control total pero requiere más experiencia.

¿Puedo migrar un cluster GKE existente a Terraform?

Sí, usando el comando terraform import puedes importar clusters existentes al state de Terraform. Sin embargo, necesitarás escribir manualmente la configuración que coincida con el estado actual del cluster.

¿Qué versión del módulo debo usar?

Usa siempre la última versión estable (actualmente v31.x). Si estás en Terraform 0.13 o anterior, la última versión compatible es v27.0.0. Verifica compatibilidad en la documentación del módulo antes de actualizar.

¿Cómo escalo el cluster después del despliegue?

Modifica los parámetros min_count y max_count en la definición del node pool y ejecuta terraform apply. El cluster escalará automáticamente dentro de los nuevos límites según la demanda de recursos.

¿Es recomendable usar Autopilot o Standard para producción?

Autopilot es recomendado para la mayoría de casos de uso en producción porque Google gestiona la seguridad, actualizaciones y escalado automáticamente. Usa Standard solo si necesitas configuraciones muy específicas como machine types especiales, kernels personalizados o acceso a funcionalidades experimentales de Kubernetes.

Ahora tienes todo lo necesario para aprovisionar clusters de Google Kubernetes Engine usando infraestructura como código con el módulo oficial. Esta combinación de tecnologías te permitirá gestionar tus despliegues de contenedores de forma reproducible, versionada y completamente automatizada.

Terraform GCP GKE: Despliega Kubernetes en Google Cloud 2025