Installing GitLab on Kubernetes using AWS EKS

4 min readJan 8, 2021

How to perform a Cloud Native installation of GitLab running on EKS in AWS.

https://about.gitlab.com — The GitLab.com home page

GitLab is a web-based DevOps lifecycle tool that provides a Git-repository manager providing wiki, issue-tracking and continuous integration and deployment pipeline features, using an open-source license according to the Wikipedia. If you’ve not tried it out, you really should

This guide discusses setting up a public-facing GitLab running in a Managed Kubernetes cluster on AWS. The installation takes about an hour.

Prerequisites (20 minutes)

You will need the following in order to follow these instructions:

a public domain that you can register a DNS record with, and
some client-side tooling

You’ll need to specify a domain which will contain records to resolve GitLab. The easiest way is to register a public domain in Route 53. This is because by default the chart will install and configure cert-manager to obtain free TLS certificates.

You also need the following tooling installed on a client:

AWS CLI: AWS CLI needed to register control plane and clients and get credentials
Eksctl: EKS command line
Kubectl: Kubernetes client command line
Helm: a package manager for Kubernetes

On a Mac the easiest way is to first install Homebrew. Then use that to install the tooling like so:

brew tap weaveworks/tap
brew install awscli eksctl kubectl helm

Alternatively, each of the tools have installation instructions on their websites.

Create an EKS Cluster (20 minutes)

With your aws account configured for command line access the next step is to use eksctl to build the Kubernetes cluster. This is a single command that creates two m5.xlarge nodes in eu-west-2. A lot of the configuration below can be modified to suit your needs such as the region, name of the cluster etc. The GitLab documentation suggests at least two nodes of instance type m5.xlarge:

eksctl create cluster \
  --name gitlab \
  --region eu-west-2 \
  --version 1.18 \
  --managed \
  --nodegroup-name standard-workers \
  --node-type m5.xlarge \
  --nodes 2 \
  --nodes-min 2 \
  --nodes-max 2

To minimise undifferentiated heavy lifting we have chosen a managed node group. The minimum suggested version is 1.14 for EKS.

Install GitLab Software (10 minutes)

You first need to configure Helm to include the GitLab chart repository:

helm repo add gitlab https://charts.gitlab.io/
helm repo update

Then, run the GitLab deployment via Helm. You will need a domain and an email address to do this (no emails are sent to that address). The following command creates a deployment called gitlab using the gitlab/gitlab helm chart:

helm install gitlab gitlab/gitlab \
  --set global.hosts.domain="MYDOMAIN" \
  --set certmanager-issuer.email="MYEMAILADDRESS" \
  --set global.edition=ce

The global.hosts.domain and certmanager-issuer.email are needed for the SSL certificate registration and the global.edition specified Community Edition (ce) or Enterprise Edition (ee). There are many many configuration options in the documentation. For example, using an external Postgres Database (such as AWS RDS) or Redis (such as ElastiCache).

An alternative is to make a file containing the configuration such as values.yml containing the configuration. Helm can also supply this after an installation by issuing helm get values gitlab > values.yaml:

certmanager-issuer:
  email: MYEMAILADDRESSglobal:
  edition: ce  hosts:
    domain: MYDOMAIN

Register DNS Records (10 minutes)

After a few minutes, obtain the Ingress Load Balancer EXTERNAL-IP (name) by entering the command:

kubectl get svc -l app=nginx-ingress

which should display something like:

NAME                                      TYPE           CLUSTER-IP       EXTERNAL-IP                                                              PORT(S)                                   AGEgitlab-nginx-ingress-controller           LoadBalancer   172.20.71.90     a66bfac3657a040ec9fe5a784bf2a483-916339528.us-east-1.elb.amazonaws.com   80:31564/TCP,443:31599/TCP,22:31246/TCP   20hgitlab-nginx-ingress-controller-metrics   ClusterIP      172.20.1.224     <none>                                                                   9913/TCP                                  20hgitlab-nginx-ingress-controller-stats     ClusterIP      172.20.6.149     <none>                                                                   18080/TCP                                 20hgitlab-nginx-ingress-default-backend      ClusterIP      172.20.189.247   <none>                                                                   80/TCP                                    20h

Copy the EXTERNAL-IP (which will be a name) field for the gitlab-nginx-ingress-controller and create DNS alias / CNAME records in Amazon Route 53 for the following (on your public domain):

gitlab.MYDOMAIN
registry.MYDOMAIN
minio.MYDOMAIN

Administrator Login (10 mins)

An administrator (root) account will be created with a randomised password. The password can be obtained from Kubernetes secrets with (note that gitlab appears twice in the command):

kubectl get secret gitlab-gitlab-initial-root-password --ojsonpath=’{.data.password}’ | base64 — decode ; echo

You should be able to visit the website at https://gitlab.MYDOMAIN and login with the username root and the password output from the above command. This might not work immediately, you may have to wait 5 or 10 minutes for the certificates to become registered.

Outlook

This is a “basic” installation where GitLab has been split into multiple components but they are all running in the same Kubernetes cluster. It is possible to replace the existing Postgres database with an external database, to replace Redis with ElastiCache and replace Minio with S3. All to improve resilience. This is done by adding additional configuration to the Helm values.yml file.

But for now, you have a Cloud Native, self-healing installation of GitLab CE to get you started!