New GKE cluster through IaC

Learn how to create a new cluster on Google Kubernetes Engine (GKE) through Infrastructure as Code (IaC).

This process combines the GitLab Terraform and Google Terraform providers with Kubernetes to help you create GKE clusters and deploy them through GitLab.

This document describes how to set up a group-level cluster on GKE by importing an example project to get you started. You can then modify the project files according to your needs.



  1. Import the example project.
  2. Add your GCP credentials to GitLab.
  3. Configure your project.
  4. Deploy your cluster.

Import the example project

Start by importing the example project by URL. Use as URL.

Add your GCP credentials to GitLab

After importing the project, you need to set up CI environment variables to associate your cluster on GCP to your group in GitLab.

We advise that you set environment variables through the GitLab UI so that your credentials are not exposed through the code. To do so, follow the steps below.

Prepare your credentials on GCP

  1. Create a GCP service account to authenticate GCP with GitLab. It needs the following roles: Computer Network Viewer, Kubernetes Engine Admin, and Service Account User.
  2. Download the JSON file with the service account key.
  3. On your computer, encode the JSON file to base64 (replace /path/to/sa-key.json to the path to your key):

    base64 /path/to/sa-key.json | tr -d \\n`
  4. Use the output of this command as the BASE64_GOOGLE_CREDENTIALS environment variable in the next step.

Add your credentials to GitLab as environment variables

  1. On GitLab, from your project’s sidebar, go to Settings > CI/CD and expand Variables.
  2. Add your GITLAB_TOKEN (personal access token).
  3. Add the variable BASE64_GOOGLE_CREDENTIALS from the previous step.

Configure your project

After authenticating with GCP, replace the project’s defaults from the example project with your own. To do so, edit the files as described below.


  1. (Required) Replace the GCP project with a unique project name.
  2. (Optional) Choose the name of your cluster.
  3. (Optional) Choose the region and zone that you would like to deploy your cluster to.
  4. Push the changes to your project’s default branch.


  1. (Required): Replace the full_path with the path to your group.
  2. (Optional): Choose your cluster base domain through domain.
  3. (Optional): Choose your environment through environment_scope.
  4. Push the changes to your project’s default branch.

Refer to the GitLab Terraform provider and the Google Terraform provider documentation for further resource options.

Deploy your cluster

After adjusting the files in the previous step, manually trigger the deployment of your cluster. In GitLab:

  1. From your project’s sidebar, go to CI/CD > Pipelines.
  2. Select the dropdown icon () next to the play icon ().
  3. Select deploy to manually trigger the deployment job.

When the pipeline finishes successfully, you can see your new cluster: