auto_devops_with_eks.md

stage: Deploy
group: Environments
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments

Use Auto DevOps to deploy an application to Amazon Elastic Kubernetes Service (EKS)

In this tutorial, we'll help you to get started with Auto DevOps through an example of how to deploy an application to Amazon Elastic Kubernetes Service (EKS).

The tutorial uses the GitLab native Kubernetes integration, so you don't need to create a Kubernetes cluster manually using the AWS console.

You can also follow this tutorial on a self-managed instance. Ensure your own runners are configured.

To deploy a project to EKS:

1. Configure your Amazon account
2. Create a Kubernetes cluster and deploy the agent
3. Create a new project from a template
4. Configure the agent
5. Install Ingress
6. Configure Auto DevOps
7. Enable Auto DevOps and run the pipeline
8. Deploy the application

Configure your Amazon account

Before you create and connect your Kubernetes cluster to your GitLab project, you need an Amazon Web Services account. Sign in with an existing Amazon account or create a new one.

Create a Kubernetes cluster

To create an new cluster on Amazon EKS:

• Follow the steps in Create an Amazon EKS cluster.

If you prefer, you can also create a cluster manually using eksctl.

Create an application project from a template

Use a GitLab project template to get started. As the name suggests, those projects provide a bare-bones application built on some well-known frameworks.

WARNING: Create the application project in the group hierarchy at the same level or below the project for cluster management. Otherwise, it fails to authorize the agent.

1. On the left sidebar, at the top, select Create new ({plus}) and New project/repository.
2. Select Create from template.
3. Select the Ruby on Rails template.
4. Give your project a name, optionally a description, and make it public so that you can take advantage of the features available in the GitLab Ultimate plan.
5. Select Create project.

Now you have an application project you are going to deploy to the EKS cluster.

Configure the agent

Next, we'll configure the GitLab agent for Kubernetes so we can use it to deploy the application project.

1. Go to the project we created to manage the cluster.
2. Navigate to the agent configuration file (.gitlab/agents/eks-agent/config.yaml) and edit it.
3. Configure ci_access:projects attribute. Use the application project path as id:

ci_access:
  projects:
    - id: path/to/application-project

Install Ingress

After your cluster is running, you must install NGINX Ingress Controller as a load balancer to route traffic from the internet to your application. Install the NGINX Ingress Controller through the GitLab Cluster management project template, or manually via the command line:

1. Ensure you have kubectl and Helm installed on your machine.

2. Create an IAM role to access the cluster.

3. Create an access token to access the cluster.

4. Use kubectl to connect to your cluster:

   helm upgrade --install ingress-nginx ingress-nginx \
   --repo https://kubernetes.github.io/ingress-nginx \
   --namespace gitlab-managed-apps --create-namespace
   
   # Check that the ingress controller is installed successfully
   kubectl get service ingress-nginx-controller -n gitlab-managed-apps

Configure Auto DevOps

Follow these steps to configure the base domain and other settings required for Auto DevOps.

1. A few minutes after you install NGINX, the load balancer obtains an IP address, and you can get the external IP address with the following command:

   kubectl get all -n gitlab-managed-apps --selector app.kubernetes.io/instance=ingress-nginx

   Replace gitlab-managed-apps if you have overwritten your namespace.

   Next, find the actual external IP address for your cluster with the following command:

   nslookup [External IP]

   Where the [External IP] is the hostname found with the previous command.

   The IP address might be listed in the Non-authoritative answer: section of the response.

   Copy this IP address, as you need it in the next step.

2. Go back to the application project.

3. On the left sidebar, select Settings > CI/CD and expand Variables.

   • Add a key called KUBE_INGRESS_BASE_DOMAIN with the application deployment domain as the value. For this example, use the domain <IP address>.nip.io.
   • Add a key called KUBE_NAMESPACE with a value of the Kubernetes namespace for your deployments to target. You can use different namespaces per environment. Configure the environment, use the environment scope.
   • Add a key called KUBE_CONTEXT with a value like path/to/agent/project:eks-agent. Select the environment scope of your choice.
   • Select Save changes.

Enable Auto DevOps and run the pipeline

While Auto DevOps is enabled by default, Auto DevOps can be disabled at both the instance level (for self-managed instances) and the group level. Complete these steps to enable Auto DevOps if it's disabled: