gitlab-org--gitlab-foss/doc/user/infrastructure/clusters/connect/new_eks_cluster.md

stage	group	info
Configure	Configure	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

Learn how to create a new cluster on Amazon Elastic Kubernetes Service (EKS) through Infrastructure as Code (IaC).

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.

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.

Prerequisites:

• An Amazon Web Services (AWS) account, with a set of configured security credentials.
• Configured GitLab Runners to run the infrastructure pipeline from GitLab CI/CD.

Steps:

1. Import the example project.
2. Register the Agent.
3. Configure your project.
4. 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.

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

This project provides you with the following resources:

• An Amazon Virtual Private Cloud (VPC).
• An Amazon Elastic Kubernetes Service (EKS) cluster.
• The GitLab agent for Kubernetes installed into the cluster.

Register the Agent

To create an Agent in GitLab:

1. From your project's sidebar, select Infrastructure > Kubernetes clusters.
2. Select Actions.
3. From the Select an Agent dropdown list, select eks-agent and select Register an Agent.
4. GitLab generates a registration token for this Agent. Securely store this secret token, as you will need it to configure your project below.
5. GitLab provides you with a KAS address, which will also be needed when configuring your project below.

Configure your project

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 AWS_ACCESS_KEY_ID to your AWS access key ID.
4. Set the variable AWS_SECRET_ACCESS_KEY to your AWS secret access key.
5. Set the variable TF_VAR_agent_token to the Agent token displayed in the previous step.
6. Set the variable TF_VAR_kas_address to the KAS address displayed in the previous step.

Optional configuration:

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

• TF_VAR_region: Set your cluster's region.
• TF_VAR_cluster_name: Set your cluster's name.
• TF_VAR_cluster_version: Set the version of Kubernetes.
• TF_VAR_instance_type: Set the instance type for the Kubernetes nodes.
• TF_VAR_instance_count: Set the number of Kubernetes nodes.
• 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 and the Kubernetes Terraform provider 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.
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:

• In AWS: from the EKS console select Amazon EKS > Clusters.
• In GitLab: from your project's sidebar, select Infrastructure > Kubernetes clusters.

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

To remove all resources:

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

   stages:
     - init
     - validate
     - build
     - deploy
     - cleanup
   
   destroy:
     extends: .destroy
     needs: []
   

2. From your project's sidebar, go to CI/CD > Pipelines and select the most recent pipeline.

3. Click the play icon ({play}) for the destroy job.