Create a Google GKE cluster

Learn how to create a new cluster on Google Kubernetes Engine (GKE) through Infrastructure as Code (IaC). This process uses the Google and Kubernetes Terraform providers create GKE clusters. You connect the clusters to GitLab by using the GitLab agent for Kubernetes.

note
Every new Google Cloud Platform (GCP) account receives $300 in credit, and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with the GitLab integration with Google Kubernetes Engine. Follow this link and apply for credit.

Before you begin:

Steps:

  1. Import the example project.
  2. Register the agent for Kubernetes.
  3. Create your GCP credentials.
  4. Configure your project.
  5. Provision your cluster.

Import the example project

To create a cluster from GitLab using Infrastructure as Code, you must create a project to manage the cluster from. In this tutorial, you start with a sample project and modify it according to your needs.

Start by importing the example project by URL.

To import the project:

  1. In GitLab, on the left sidebar, select Search or go to.
  2. Select View all my projects.
  3. On the right of the page, select New project.
  4. Select Import project.
  5. Select Repository by URL.
  6. For the Git repository URL, enter https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke.git.
  7. Complete the fields and select Create project.

This project provides you with:

Register the agent

  • Changed in GitLab 14.9: A flag named certificate_based_clusters changed the Actions menu to focus on the agent rather than certificates. Disabled by default.

To create a GitLab agent for Kubernetes:

  1. On the left sidebar, select Operate > Kubernetes clusters.
  2. Select Connect a cluster (agent).
  3. From the Select an agent or enter a name to create new dropdown list, choose your agent’s name and select Register.
  4. GitLab generates a registration token for the agent. Securely store this secret token, as you will need it later.
  5. Optional. If you use Helm, GitLab provides an address for the agent server (KAS) in the Helm command example. You need this for later.

Create your GCP credentials

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

  1. 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.
  2. Download the JSON file with the service account key you created in the previous step.

  3. On your computer, encode the JSON file to base64 (replace /path/to/sa-key.json to the path to your key):

    MacOS
    base64 -i /path/to/sa-key.json | tr -d \\n
    Linux
    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.

Configure your project

Use CI/CD environment variables to configure your project.

Required configuration:

  1. On the left sidebar, select Settings > CI/CD.
  2. Expand Variables.
  3. Set the variable BASE64_GOOGLE_CREDENTIALS to the base64 encoded JSON file you just created.
  4. Set the variable TF_VAR_gcp_project to your GCP project ID.
  5. Set the variable TF_VAR_agent_token to the agent token displayed in the previous task.
  6. Set the variable TF_VAR_kas_address to the agent server address displayed in the previous task.

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_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_machine_type: Set the machine type for the Kubernetes nodes.
  • TF_VAR_node_count: Set the number of Kubernetes nodes.
  • TF_VAR_agent_namespace: Set the Kubernetes namespace for the GitLab agent.

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

Enable Kubernetes Engine API

From the Google Cloud console, enable the Kubernetes Engine API.

Provision your cluster

After configuring your project, manually trigger the provisioning of your cluster. In GitLab:

  1. On the left sidebar, select Build > Pipelines.
  2. Select New pipeline.
  3. Next to Play (), select the dropdown list icon ().
  4. Select Deploy to manually trigger the deployment job.

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

Use your cluster

After you provision the cluster, it is connected to GitLab and is ready for deployments. To check the connection:

  1. On the left sidebar, select Operate > Kubernetes clusters.
  2. In the list, view the Connection status column.

For more information about the capabilities of the connection, see the GitLab agent for Kubernetes documentation.

Remove the cluster

A cleanup job is not included in your pipeline by default. To remove all created resources, you must modify your GitLab CI/CD template before running the cleanup job.

To remove all resources:

  1. Add the following to your .gitlab-ci.yml file: 

    stages:
  - init
  - validate
  - build
  - test
  - deploy
  - cleanup

destroy:
  extends: .terraform:destroy
  needs: []
  2. On the left sidebar, select Build > Pipelines and select the most recent pipeline.
  3. For the destroy job, select Play ().