gke-terraform-generator

README

Google Kubernetes Engine (GKE) Terraform Generator

• Introduction
• Architecture
• Prerequisites
• Usage
• Troubleshooting
• Relevant Material

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

1. gke-tf
2. Terraform >= 0.12.3
3. Google Cloud SDK version >= 253.0.0
4. kubectl matching the latest GKE version
5. bash or bash-compatible shell
6. 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

• Terraform

This is not an officially supported Google product