Skip to content

GitLab

New GKE cluster through IaC (DEPRECATED)

Deprecated in GitLab 14.5.

WARNING: The process described on this page uses cluster certificates to connect the new cluster to GitLab, deprecated in GitLab 14.5. You can still create a cluster and then connect it to GitLab through the Agent. An issue exists to migrate this functionality to the Agent.

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.

Prerequisites:

Steps:

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

Import the example project

To create a new group-level cluster from GitLab using Infrastructure as Code, it is necessary to create a project to manage the cluster from. In this tutorial, we import a pre-configured sample project to help you get started.

Start by importing the example project by URL. Use https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke.git as URL.

This project provides you with the following resources:

  • A cluster on Google Cloud Platform (GCP) with defaults for name, location, node count, and Kubernetes version.

  • A gitlab-admin K8s service account with cluster-admin privileges.

  • The new group-level cluster connected to GitLab.

  • Pre-configures Terraform files:

    ├── backend.tf         # State file Location Configuration
├── gke.tf             # Google GKE Configuration
├── gitlab-admin.tf    # Adding kubernetes service account
└── group_cluster.tf   # Registering kubernetes cluster to GitLab `apps` Group

Create your GCP and GitLab credentials

To set up your project to communicate to GCP and the GitLab API:

  1. Create a GitLab personal access token with api scope. The Terraform script uses it to connect the cluster to your GitLab group. Take note of the generated token. You will need it when you configure your project.

  2. To authenticate GCP with GitLab, create a GCP service account with following roles: Compute Network Viewer, Kubernetes Engine Admin, Service Account User, and Service Account Admin. Both User and Admin service accounts are necessary. The User role impersonates the default service account when creating the node pool. The Admin role creates a service account in the kube-system namespace.

  3. Download the JSON file with the service account key you created in the previous step.

  4. 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

  5. Use the output of this command as the BASE64_GOOGLE_CREDENTIALS environment variable in the next step.

Configure your project

Required configuration:

Use CI/CD environment variables to configure your project as detailed below.

Required configuration:

  1. On the left sidebar, select Settings > CI/CD.
  2. Expand Variables.
  3. Set the variable TF_VAR_gitlab_token to the GitLab personal access token you just created.
  4. Set the variable BASE64_GOOGLE_CREDENTIALS to the base64 encoded JSON file you just created.
  5. Set the variable TF_VAR_gcp_project to your GCP's project name.
  6. Set the variable TF_VAR_gitlab_group to the name of the group you want to connect your cluster to. If your group's URL is https://gitlab.example.com/my-example-group, my-example-group is your group's name.

Optional configuration:

The file variables.tf contains other variables that you can override according to your needs:

  • TF_VAR_gcp_region: Set your cluster's region.
  • TF_VAR_cluster_name: Set your cluster's name.
  • TF_VAR_machine_type: Set the machine type for the Kubernetes nodes.
  • TF_VAR_cluster_description: Set a description for the cluster. We recommend setting this to $CI_PROJECT_URL to create a reference to your GitLab project on your GCP cluster detail page. This way you know which project was responsible for provisioning the cluster you see on the GCP dashboard.
  • TF_VAR_base_domain: Set to the base domain to provision resources under.
  • TF_VAR_environment_scope: Set to the environment scope for your cluster.

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

Deploy your cluster

After configuring your project, 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 ({angle-down}) next to the play icon ({play}).
  3. Select deploy to manually trigger the deployment job.

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