Commit 4dd25129 authored by Marcel Amirault's avatar Marcel Amirault

Merge branch 'sselhorn-master-patch-94645' into 'master'

Docs: A follow-up edit for grammar and style

See merge request gitlab-org/gitlab!81055
parents 3a1bd86c ec8ee409
......@@ -4,57 +4,61 @@ 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
---
# Create a new EKS cluster through IaC
# Create an Amazon EKS cluster
Learn how to create a new cluster on Amazon Elastic Kubernetes Service (EKS) through
[Infrastructure as Code (IaC)](../../index.md).
This process combines the AWS and Kubernetes Terraform providers to help you create EKS clusters
and connect them to GitLab using the [GitLab agent for Kubernetes](../../../clusters/agent/index.md).
This document describes how to set up a Kubernetes cluster on EKS by importing an example project to get you started.
You can then modify the project files according to your needs.
You can create a cluster on Amazon Elastic Kubernetes Service (EKS) through
[Infrastructure as Code (IaC)](../../index.md). This process uses the AWS and
Kubernetes Terraform providers to create EKS clusters. You connect the clusters to GitLab
by using the GitLab agent for Kubernetes.
**Prerequisites:**
- An Amazon Web Services (AWS) account, with a set of configured
[security credentials](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-prereqs.html).
- [Configured GitLab Runners](https://docs.gitlab.com/runner/install/) to run the infrastructure pipeline from GitLab CI/CD.
- [A runner](https://docs.gitlab.com/runner/install/) you can use to run the GitLab CI/CD pipeline.
**Steps:**
1. [Import the example project](#import-the-example-project).
1. [Register the Agent](#register-the-agent).
1. [Register the agent for Kubernetes](#register-the-agent).
1. [Configure your project](#configure-your-project).
1. [Provision your cluster](#provision-your-cluster).
## Import the example project
To create a new 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.
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](../../../project/import/repo_by_url.md).
Start by [importing the example project by URL](../../../project/import/repo_by_url.md). Use `https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks.git` as the URL.
To import the project:
This project provides you with the following resources:
1. On the top bar, select **Menu > Create new project**.
1. Select **Import project**.
1. Select **Repo by URL**.
1. For the **Git repository URL**, enter `https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks.git`.
1. Complete the fields and select **Create project**.
This project provides you with:
- An Amazon [Virtual Private Cloud (VPC)](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks/-/blob/main/vpc.tf).
- An Amazon [Elastic Kubernetes Service (EKS)](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks/-/blob/main/eks.tf) cluster.
- The [GitLab agent for Kubernetes](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks/-/blob/main/agent.tf) installed into the cluster.
- The [GitLab agent for Kubernetes](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks/-/blob/main/agent.tf) installed in the cluster.
## Register the Agent
## Register the agent
To create an Agent in GitLab:
To create a GitLab agent for Kubernetes:
1. From your project's sidebar, select **Infrastructure > Kubernetes clusters**.
1. On the left sidebar, select **Infrastructure > Kubernetes clusters**.
1. Select **Actions**.
1. From the **Select an Agent** dropdown list, select `eks-agent` and select **Register an Agent**.
1. GitLab generates a registration token for this Agent. Securely store this secret token, as you will need it to [configure your project](#configure-your-project) below.
1. GitLab provides you with a KAS address, which will also be needed when configuring your project below.
1. From the **Select an agent** dropdown list, select `eks-agent` and select **Register an agent**.
1. GitLab generates a registration token for the agent. Securely store this secret token, as you will need it later.
1. GitLab provides an address for the agent server (KAS), which you will also need later.
## Configure your project
Use CI/CD environment variables to configure your project as detailed below.
Use CI/CD environment variables to configure your project.
**Required configuration:**
......@@ -62,8 +66,8 @@ Use CI/CD environment variables to configure your project as detailed below.
1. Expand **Variables**.
1. Set the variable `AWS_ACCESS_KEY_ID` to your AWS access key ID.
1. Set the variable `AWS_SECRET_ACCESS_KEY` to your AWS secret access key.
1. Set the variable `TF_VAR_agent_token` to the Agent token displayed in the previous step.
1. Set the variable `TF_VAR_kas_address` to the KAS address displayed in the previous step.
1. Set the variable `TF_VAR_agent_token` to the agent token displayed in the previous task.
1. Set the variable `TF_VAR_kas_address` to the agent server address displayed in the previous task.
**Optional configuration:**
......@@ -78,20 +82,20 @@ contains other variables that you can override according to your needs:
- `TF_VAR_agent_version`: Set the version of the GitLab Agent.
- `TF_VAR_agent_namespace`: Set the Kubernetes namespace for the GitLab Agent.
Refer to the [AWS Terraform provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) and the [Kubernetes Terraform provider](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs) documentation for further resource options.
View the [AWS Terraform provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) and the [Kubernetes Terraform provider](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs) documentation for further resource options.
## Provision your cluster
After configuring your project, manually trigger the provisioning 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.
1. On the left sidebar, go to **CI/CD > Pipelines**.
1. Next to **Play** (**{play}**), select the dropdown icon (**{angle-down}**).
1. Select **Deploy** to manually trigger the deployment job.
When the pipeline finishes successfully, you can see your new cluster:
When the pipeline finishes successfully, you can view the new cluster:
- In AWS: from the [EKS console](https://console.aws.amazon.com/eks/home) select **Amazon EKS > Clusters**.
- In GitLab: from your project's sidebar, select **Infrastructure > Kubernetes clusters**.
- In AWS: From the [EKS console](https://console.aws.amazon.com/eks/home), select **Amazon EKS > Clusters**.
- In GitLab: On the left sidebar, select **Infrastructure > Kubernetes clusters**.
## Use your cluster
......@@ -102,14 +106,14 @@ After you provision the cluster, it is connected to GitLab and is ready for depl
For more information about the capabilities of the connection, see [the GitLab agent for Kubernetes documentation](../index.md).
## Removing the cluster
## Remove the cluster
A cleanup job is not included in your pipeline by default. To remove all created resources, you
need to modify your GitLab CI/CD template before running the cleanup job.
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`:
1. Add the following to your `.gitlab-ci.yml` file:
```yaml
stages:
......@@ -124,5 +128,5 @@ To remove all resources:
needs: []
```
1. From your project's sidebar, go to **CI/CD > Pipelines** and select the most recent pipeline.
1. Click the play icon (**{play}**) for the `destroy` job.
1. On the left sidebar, select **CI/CD > Pipelines** and select the most recent pipeline.
1. For the `destroy` job, select **Play** (**{play}**).
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment