Terraform integration with Google Kubernetes Engine represents a configuration-oriented approach to provisioning and managing container orchestration infrastructure on Google Cloud. The terraform-google-kubernetes-engine repository provides a comprehensive Terraform module system for creating and managing Google Kubernetes Engine clusters with sophisticated code generation, extensive testing, and multi-variant architecture. This module handles opinionated GKE cluster provisioning across different cluster types, security configurations, and feature maturity levels. The page provides a high-level overview of the module system architecture, template-driven code generation, and the various cluster variants available. The system is positioned as a reusable building block that abstracts the complexity of GKE resource definitions while enforcing consistent patterns for network integration, node pool management, and feature toggles.
The module is meant for use with Terraform 1.3+ and tested using Terraform 1.10+. If incompatibilities are found using Terraform >=1.3, an issue should be opened. For users who have not upgraded to 1.3 and need a Terraform 0.13.x-compatible version of this module, the last released version intended for Terraform 0.13.x is 27.0.0. The existence of a supported version boundary shapes upgrade planning for organizations with long-lived Terraform codebases. The 1.3+ requirement aligns with modern Terraform features such as improved provider dependency handling and module composition, while the explicit test target at 1.10+ signals active validation against current CLI capabilities. The 27.0.0 marker for 0.13.x users provides a stable exit point for teams that cannot immediately migrate.
Module System Architecture and Template Driven Code Generation
The terraform-google-kubernetes-engine repository provides a comprehensive Terraform module system for creating and managing Google Kubernetes Engine clusters with sophisticated code generation, extensive testing, and multi-variant architecture. This module handles opinionated GKE cluster provisioning across different cluster types, security configurations, and feature maturity levels.
The architecture is described as template-driven. Code generation implies that the module does not merely wrap static resource definitions but synthesizes configurations based on inputs. The impact for practitioners is reduced manual duplication across environments and a lower risk of configuration drift when new GKE features are introduced. When the underlying GKE resource schema changes, updates can be centralized in the template rather than scattered across dozens of consumer configurations.
Multi-variant architecture indicates support for distinct cluster topologies within a single module system. The reference to different cluster types, security configurations, and feature maturity levels suggests that users can select a variant that matches operational requirements without maintaining separate module forks. Contextually this ties to the examples folder mentioned in the repository, which contains multiple examples illustrating variant usage.
The module handles opinionated provisioning. Opinionation means default choices are made for network policy, load balancing, autoscaling, and driver enablement. For operators, opinionation accelerates initial deployment but requires explicit overrides when non-default behavior is needed. The opinionated nature also reduces decision fatigue for standard workloads.
Terraform Version Compatibility and Module Maturity
The module is meant for use with Terraform 1.3+ and tested using Terraform 1.10+.
This version constraint has direct operational consequences. Teams running Terraform 0.12 or 0.13 must either upgrade or pin to version 27.0.0. The 1.3+ baseline ensures compatibility with modern Terraform language features and provider protocols. The tested 1.10+ statement provides confidence that CI pipelines can target a current CLI without encountering untested behavior.
If you find incompatibilities using Terraform >=1.3, please open an issue.
The open issue instruction establishes a feedback loop between consumers and maintainers. For enterprise users, this means incompatibility reports are tracked publicly and can influence patch releases.
If you haven't upgraded to 1.3 and need a Terraform 0.13.x-compatible version of this module, the last released version intended for Terraform 0.13.x is 27.0.0.
Version 27.0.0 acts as a migration anchor. Organizations can maintain legacy pipelines on 27.0.0 while planning a controlled upgrade to 1.3+ compatible releases. The existence of a final 0.13.x release signals end-of-life for that compatibility line, encouraging migration.
Example Usage and Explicit Provider Configuration
There are multiple examples included in the examples folder but simple usage is as follows.
The examples folder serves as a practical reference for different topologies. The simple usage pattern demonstrates the minimum wiring required to instantiate the module and connect to the cluster.
googleclientconfig and kubernetes provider must be explicitly specified like the following.
data "google_client_config" "default" {}
provider "kubernetes" {
host = "https://${module.gke.endpoint}"
token = data.google_client_config.default.access_token
cluster_ca_certificate = base64decode(module.gke.ca_certificate)
}
Explicit provider configuration is required because the module outputs cluster connection parameters. The googleclientconfig data source retrieves access tokens for the authenticated user, while the kubernetes provider consumes the module outputs to establish API connectivity. Without this explicit wiring, kubectl and other Kubernetes providers would lack credentials and endpoint information.
The module block example shows a concrete instantiation.
module "gke" {
source = "terraform-google-modules/kubernetes-engine/google"
project_id = "<PROJECT ID>"
name = "gke-test-1"
region = "us-central1"
zones = ["us-central1-a", "us-central1-b", "us-central1-f"]
network = "vpc-01"
subnetwork = "us-central1-01"
ip_range_pods = "us-central1-01-gke-01-pods"
ip_range_services = "us-central1-01-gke-01-services"
http_load_balancing = false
network_policy = false
horizontal_pod_autoscaling = true
filestore_csi_driver = false
dns_cache = false
node_pools = [
{
name = "default-node-pool"
machine_type = "e2-medium"
node_locations = "us-central1-b,us-central1-c"
min_count = 1
max_count = 100
local_ssd_count = 0
spot = false
disk_size_gb = 100
disk_type =
}
]
}
The source argument points to terraform-google-modules/kubernetes-engine/google, which identifies the registry location. Project ID, name, region, and zones define the placement of the cluster. Network, subnetwork, iprangepods, and iprangeservices define the VPC integration and secondary IP ranges required for GKE pod and service CIDRs.
Feature toggles such as httploadbalancing, networkpolicy, horizontalpodautoscaling, filestorecsidriver, and dnscache illustrate the opinionated defaults that can be overridden. Horizontal pod autoscaling is set to true, indicating an expectation of workload-driven scaling.
Node pool definition includes name, machinetype, nodelocations, mincount, maxcount, localssdcount, spot, disksizegb, and disktype. The nodelocations value of us-central1-b,us-central1-c shows zone affinity for the pool, while the cluster-level zones list spans us-central1-a, us-central1-b, us-central1-f, demonstrating regional spread.
Module Input Parameters and Network Configuration
The example parameters map to real infrastructure decisions.
- project_id determines the Google Cloud billing and resource container.
- name sets the GKE cluster identifier.
- region and zones control geographic placement and failure domain distribution.
- network and subnetwork bind the cluster to an existing VPC.
- iprangepods and iprangeservices reference secondary ranges allocated in the subnetwork.
The impact of specifying iprangepods and iprangeservices is that pod and service IP allocation is decoupled from the primary subnetwork range, enabling larger address spaces and preventing overlap. The contextual relationship to network_policy false indicates that network segmentation via NetworkPolicy is disabled in this example, which reduces overhead for clusters that do not require pod-level isolation.
httploadbalancing false disables the creation of Google-managed HTTP(S) load balancers by the module. This choice reduces cost for workloads that do not require external ingress or that manage ingress via other means.
Terraform Workflow for GKE Provisioning
HashiCorp Terraform is an infrastructure-as-code tool that lets you provision and manage cloud infrastructure. Terraform provides plugins called providers that let you interact with cloud providers and other APIs. You can use the Terraform provider for Google Cloud to provision and manage Google Cloud resources, including GKE.
This page introduces you to using Terraform with GKE, including an introduction to how Terraform works and some resources to help you get started using Terraform with Google Cloud. You'll also find links to Terraform reference docs for GKE, code examples, and guides for using Terraform to provision GKE resources.
How Terraform works
Terraform has a declarative and configuration-oriented syntax, which you can use to describe the infrastructure that you want to provision in your Google Cloud project. After you author this configuration in one or more Terraform configuration files, you can use the Terraform CLI to apply this configuration to your GKE resources.
The following steps explain how Terraform works.
- You describe the infrastructure you want to provision in a Terraform configuration file. You don't need to write code describing how to provision the infrastructure. Terraform provisions the infrastructure for you.
- You run the
terraform plan
command, which evaluates your configuration and generates an execution plan. You can review the plan and make changes as needed
Each resource block describes one or more infrastructure objects, such as virtual networks or compute instances.
The plan step provides a safety gate. Operators can review proposed create, update, and destroy actions before applying changes. This is critical for production GKE clusters where node pool changes can cause pod evictions.
In the HashiCorp education tutorial workflow, the process continues with initialization and application.
In your terminal, clone the following repository. It contains the example configuration used in this tutorial.
git clone https://github.com/hashicorp-education/learn-terraform-provision-gke-cluster
You can explore this repository by changing directories or navigating in your UI.
cd learn-terraform-provision-gke-cluster
In here, you will find four files used to provision a VPC, subnets and a GKE cluster.
vpc.tf provisions a VPC and subnet. A new VPC is created for this tutorial so it doesn't impact your existing cloud environment and resources. This file outputs region.
gke.tf provisions a GKE cluster and a separately managed node pool. Separately managed node pools allows you to customize your Kubernetes cluster profile — this is useful if some Pods require more resources than others. You can learn more here. The number of nodes in the node pool is defined also defined here.
terraform.tfvars is a template for the project_id and region variables.
versions.tf sets the Terraform version to at least 0.14.
Replace the values in your terraform.tfvars file with your project_id and region. Terraform will use these values to target your project when provisioning your resources.
Finally, add your account to the Application Default Credentials. This will allow Terraform to access these credentials to provision resources on GCloud.
gcloud auth application-default login
Authentication via ADC ensures Terraform can impersonate the user for resource creation without embedding long-lived service account keys in configuration.
In your initialized directory, run terraform apply and review the planned actions.
Your terminal output should indicate the plan is running and what resources will be created.
terraform apply
An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
- create
Terraform will perform the following actions:
Plan: 4 to add, 0 to change, 0 to destroy.
You can see this terraform apply will provision a VPC, subnet, GKE Cluster and a GKE node pool. Confirm the apply with a yes.
This process should take approximately 10 minutes
The 4 to add plan corresponds to VPC, subnet, cluster, and node pool. The approximately 10 minutes duration sets expectations for first-time provisioning, which includes cluster control plane creation and node pool boot time.
If you ever set or change modules or backend configuration for Terraform, rerun this command to reinitialize your working directory. If you forget, other commands will detect it and remind you to do so if necessary.
Reinitialization ensures provider plugins and module sources are refreshed when dependencies change.
Google Cloud Documentation Guides for GKE with Terraform
The following table lists Terraform resources available for GKE.
The documentation page references a table of Terraform resources available for GKE. The presence of this table indicates that the Google Cloud provider supports multiple GKE resource types for cluster, node pool, and add-on management.
Terraform-based guides for GKE
The following table lists Terraform-based how-to guides and tutorials for GKE.
| Guide | Details |
|---|---|
| Create a GKE cluster and deploy a workload by using Terraform | Explains how to create a Google Kubernetes Engine Autopilot cluster and deploy a workload by using Terraform. |
| Create an Autopilot cluster | Explains how to create a GKE cluster in Autopilot. |
| Creating a zonal cluster | Explains shows you how to create a Standard zonal cluster with the default features enabled in GKE. |
| Creating a regional cluster | Explains how to create a Standard regional cluster in GKE. |
| Create a multi-tenant cluster by using Terraform | Explains how to create a multi-tenant cluster and deploy a workload by using Terraform. |
| Add and manage node pools | Explains how to add and perform operations on node pools running your GKE Standard clusters. |
| Create clusters and node pools with Arm nodes | Explains how to create a GKE Standard cluster or node pool with Arm nodes, so that you can run Arm workloads on GKE. |
| Consuming reserved zonal resources | Explains how to consume reserved Compute Engine resources in GKE. |
| Specify a node image | Explains how to specify a node image for nodes in GKE Standard clusters |
The guide list covers Autopilot, Standard zonal, Standard regional, multi-tenant, node pool management, Arm nodes, reserved resources, and node image selection. This breadth demonstrates Terraform coverage across cluster flavors and advanced compute features.
Additional reference entries include:
terraform-google-gke-gitlab | Installs GitLab on GKE.
This entry shows the module ecosystem extends beyond core cluster provisioning to application installation patterns.
What's next
- Terraform code samples for GKE
- Terraform on Google Cloud documentation
- Google Cloud provider documentation in HashiCorp
- Infrastructure as code for Google Cloud
These next steps provide pathways to deeper code samples and provider documentation.
Conclusion
The terraform-google-kubernetes-engine module system combines template-driven code generation with opinionated defaults to accelerate GKE adoption while preserving customization through explicit inputs. Version constraints to Terraform 1.3+ and tested 1.10+ ensure compatibility with modern CLI features, with version 27.0.0 serving as the final bridge for 0.13.x users. The simple usage pattern demonstrates explicit wiring of googleclientconfig and kubernetes providers to consume module outputs, reinforcing the separation between resource provisioning and workload access.
Network integration via network, subnetwork, iprangepods, and iprangeservices parameters couples GKE to existing VPC designs, while feature toggles for httploadbalancing, networkpolicy, horizontalpodautoscaling, filestorecsidriver, and dnscache allow precise control over add-on enablement. Node pool definitions capture machinetype, nodelocations, mincount, maxcount, localssdcount, spot, disksizegb, and disk_type, enabling fine-grained capacity planning.
The Terraform workflow of plan and apply, reinforced by the HashiCorp education tutorial steps for ADC authentication, repository cloning, and variable configuration, provides a repeatable path from code to running clusters. The approximately 10 minutes provisioning time sets operational expectations for initial deployment.
The Google Cloud documentation guide matrix covers Autopilot, zonal, regional, multi-tenant, Arm node, reserved resource, and node image scenarios, indicating comprehensive Terraform coverage for diverse GKE workloads. Together, the module system, provider wiring, and documentation guides form a cohesive toolchain for infrastructure-as-code management of Google Kubernetes Engine at scale.