diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-07-20 09:55:51 +0000 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-07-20 09:55:51 +0000 |
commit | e8d2c2579383897a1dd7f9debd359abe8ae8373d (patch) | |
tree | c42be41678c2586d49a75cabce89322082698334 /doc/user/infrastructure/clusters/connect | |
parent | fc845b37ec3a90aaa719975f607740c22ba6a113 (diff) | |
download | gitlab-ce-e8d2c2579383897a1dd7f9debd359abe8ae8373d.tar.gz |
Add latest changes from gitlab-org/gitlab@14-1-stable-eev14.1.0-rc42
Diffstat (limited to 'doc/user/infrastructure/clusters/connect')
-rw-r--r-- | doc/user/infrastructure/clusters/connect/new_gke_cluster.md | 94 |
1 files changed, 94 insertions, 0 deletions
diff --git a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md new file mode 100644 index 00000000000..35af316d7ac --- /dev/null +++ b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md @@ -0,0 +1,94 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# New GKE cluster through IaC + +Learn how to create a new cluster on Google Kubernetes Engine (GKE) through +[Infrastructure as Code (IaC)](../../index.md). + +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](../../../group/clusters/index.md) on GKE by importing an example project to get you started. +You can then modify the project files according to your needs. + +**Prerequisites:** + +- A GitLab group. +- A GitLab user with the Maintainer role in the group. +- A [GitLab personal access token](../../../profile/personal_access_tokens.md) with `api` access, created by a user with at least the Maintainer role in the group. +- A [Google Cloud Platform (GCP) service account](https://cloud.google.com/docs/authentication/getting-started). + +**Steps:** + +1. [Import the example project](#import-the-example-project). +1. [Add your GCP credentials to GitLab](#add-your-gcp-credentials-to-gitlab). +1. [Configure your project](#configure-your-project). +1. [Deploy your cluster](#deploy-your-cluster). + +## Import the example project + +Start by [importing the example project by URL](../../../project/import/repo_by_url.md). Use `https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke.git` as URL. + +## Add your GCP credentials to GitLab + +After importing the project, you need to set up [CI environment variables](../../../../ci/variables/index.md) to associate your cluster on GCP to your group in GitLab. + +We advise that you [set environment variables through the GitLab UI](../../../../ci/variables/index.md#add-a-cicd-variable-to-a-project) +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](https://cloud.google.com/docs/authentication/getting-started) to authenticate GCP with GitLab. It needs the following roles: `Computer Network Viewer`, `Kubernetes Engine Admin`, and `Service Account User`. +1. Download the JSON file with the service account key. +1. On your computer, encode the JSON file to `base64` (replace `/path/to/sa-key.json` to the path to your key): + + ```shell + base64 /path/to/sa-key.json | tr -d \\n` + ``` + +1. 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**. +1. Add your `GITLAB_TOKEN` ([personal access token](../../../profile/personal_access_tokens.md)). +1. 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. + +Edit `gke.tf`: + +1. **(Required)** Replace the GCP `project` with a unique project name. +1. **(Optional)** Choose the `name` of your cluster. +1. **(Optional)** Choose the `region` and `zone` that you would like to deploy your cluster to. +1. Push the changes to your project's default branch. + +Edit `group_cluster.tf`: + +1. **(Required)**: Replace the `full_path` with the path to your group. +1. **(Optional)**: Choose your cluster base domain through `domain`. +1. **(Optional)**: Choose your environment through `environment_scope`. +1. Push the changes to your project's default branch. + +Refer to the [GitLab Terraform provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs) and the [Google Terraform provider](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/provider_reference) 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**. +1. Select the dropdown icon (**{angle-down}**) next to the play icon (**{play}**). +1. Select **deploy** to manually trigger the deployment job. + +When the pipeline finishes successfully, you can see your new cluster: + +- In GCP: on your [GCP console's Kubernetes list](https://console.cloud.google.com/kubernetes/list). +- In GitLab: from your project's sidebar, select **Infrastructure > Kubernetes clusters**. |