Google Kubernetes Engine (GKE) Terraform Generator
Introduction
gke-tf
was created to streamline the creation of customized Terraform source files that build GKE clusters and supporting resources in GCP. It follows a similar workflow pattern used by other Kubernetes installation tools like Kops to reduce the difficulty of creating complex GKE deployments in GCP down to manipulating a simple YAML configuration file.
Architecture
From a single YAML configuration file that specifies all the desired configuration settings, the gke-tf
binary can validate those settings and combine them with built-in templates to generate Terraform source files in a desired directory. From this point, the user/administrator can use terraform
to plan
, apply
, and then destroy
the infrastructure and GKE cluster.
Prerequisites
Tools
- gke-tf
- Terraform >= 0.12.3
- Google Cloud SDK version >= 253.0.0
- kubectl matching the latest GKE version
bash
orbash
-compatible shell- A Google Cloud Platform project where you have
Project Owner
permissions to create VPC networks, service accounts, IAM Roles, GKE clusters, and more.
Install gke-tf
Download the latest version from the Releases page and move the binary for your platform into your path. We provide OSX, Linux and Windows binaries, but at this point OSX is the tested binary.
Install Cloud SDK
The Google Cloud SDK is used to interact with your GCP resources. Installation instructions for multiple platforms are available online.
Install kubectl CLI
The kubectl CLI is used to interteract with both Kubernetes Engine and kubernetes in general. Installation instructions for multiple platforms are available online.
Install Terraform
Terraform is used to automate the manipulation of cloud infrastructure. Its installation instructions are also available online.
Usage
Authenticate gcloud
Prior to interacting with the Terraform generated by gke-tf
, ensure you have authenticated your gcloud client by running the following command:
gcloud auth application-default login
Also, confirm the gcloud
configuration is properly pointing at your desired project. Run gcloud config list
and make sure that compute/zone
, compute/region
and core/project
are populated with values that work for you. You can set their values with the following commands:
# Where the region is us-east1
gcloud config set compute/region us-east1
Updated property [compute/region].
# Where the zone inside the region is us-east1-c
gcloud config set compute/zone us-east1-c
Updated property [compute/zone].
# Where the project name is my-project-name
gcloud config set project my-project-name
Updated property [core/project].
Setup this project
The Terraform generated by gke-tf
will enable the following Google Cloud Service APIs in the target project:
cloudresourcemanager.googleapis.com
container.googleapis.com
compute.googleapis.com
iam.googleapis.com
logging.googleapis.com
monitoring.googleapis.com
Generating the Desired Terraform
Review the YAML files in the examples
directory for an understanding of how a GKE cluster can be built using gke-tf
. You may use these as a base for customization or one provided by the repository that leverages gke-tf
.
With gke-tf
in your $PATH
, generate the Terraform necessary to build the cluster for this demo. The example command below will send the generated Terraform files to the terraform
directory inside this repository and use the examples/example.yaml
as the cluster configuration file input. The GCP project is passed to this command as well.
export PROJECT="<my-project-name>"
gke-tf gen -d ./terraform -f examples/example.yaml -o -p ${PROJECT}
Review the generated Terraform files in the terraform
directory to understand what will be built inside your GCP project. If anything needs modifying, edit the examples/example.yaml
and re-run the gke-tf gen
command above. The newly generated Terraform files will reflect your changes. You are then ready to proceed to using Terraform to build the cluster and supporting resources.
Provisioning the Generated Terraform
Next, apply the terraform configuration with:
cd terraform # if not already in this directory
terraform init
terraform plan
terraform apply
When prompted, review the generated plan and enter yes
to deploy the environment.
Teardown
To uninstall the resources built using Terraform:
cd terraform # if not already in this directory
terraform destroy
When prompted, review the plan for resource destruction and enter yes
to proceed.
Troubleshooting
- Error parsing terraform/main.tf: At NN:NN: Unknown token: 20:13 IDENT var. - This is typically caused by using Terraform v0.11 against Terraform files in the v0.12.x format. Check your
terraform version
to ensure it's v0.12 or higher.
Relevant Material
This is not an officially supported Google product