Preparing EKS resources for the GitLab chart

For a fully functional GitLab instance, you need a few resources before deploying the GitLab chart.

Creating the EKS cluster

To get started easier, a script is provided to automate the cluster creation. Alternatively, a cluster can be created manually as well.

Prerequisites:

Scripted cluster creation

A bootstrap script has been created to automate much of the setup process for users on EKS. You will need to clone this repository before executing the script.

The script will:

  1. Create a new EKS cluster.
  2. Setup kubectl, and connect it to the cluster.

To authenticate, eksctl uses the same options as the AWS command line. See the AWS documentation for how to use environment variables, or configuration files.

The script reads various parameters from environment variables, or command line arguments and the argument up for bootstrap or down for clean up.

The table below describes all variables.

Variable Description Default value
REGION The region where your cluster lives us-east-2
CLUSTER_NAME The name of the cluster gitlab-cluster
CLUSTER_VERSION The version of your EKS cluster 1.21
NUM_NODES The number of nodes required 2
MACHINE_TYPE The type of nodes to deploy m5.xlarge

Run the script, by passing in your desired parameters. It can work with the default parameters. 

./scripts/eks_bootstrap_script up

The script can also be used to clean up the created EKS resources: 

./scripts/eks_bootstrap_script down

Manual cluster creation

  • We recommend a cluster with 8vCPU and 30GB of RAM.

For the most up to date instructions, follow Amazon’s EKS getting started guide.

Administrators may also want to consider the new AWS Service Operator for Kubernetes to simplify this process.

note
Enabling the AWS Service Operator requires a method of managing roles within the cluster. The initial services handling that management task are provided by third party developers. Administrators should keep that in mind when planning for deployment.

Persistent Volume Management

There are two methods to manage volume claims on Kubernetes:

  • Manually create a persistent volume.
  • Automatic persistent volume creation through dynamic provisioning.

We currently recommend using manual provisioning of persistent volumes. Amazon EKS clusters default to spanning multiple zones. Dynamic provisioning, if not configured to use a storage class locked to a particular zone leads to a scenario where pods may exist in a different zone from storage volumes and be unable to access data.

Administrators who need to deploy in multiple zones should familiarize themselves with how to set up cluster storage and review Amazon’s own documentation on storage classes when defining their storage solution.

External Access to GitLab

By default, installing the GitLab chart will deploy an Ingress which will create an associated Elastic Load Balancer (ELB). Since the DNS names of the ELB cannot be known ahead of time, it’s difficult to utilize Let’s Encrypt to automatically provision HTTPS certificates.

We recommend using your own certificates, and then mapping your desired DNS name to the created ELB using a CNAME record. Since the ELB must be created first before its hostname can be retrieved, follow the next instructions to install GitLab.

note
For environments where AWS LoadBalancers are required, Amazon’s Elastic Load Balancers require specialized configuration. See Cloud provider LoadBalancers

Next Steps

Continue with the installation of the chart once you have the cluster up and running. Set the domain name via the global.hosts.domain option, but omit the static IP setting via the global.hosts.externalIP option unless you plan on using an existing Elastic IP.

After the Helm install, you can fetch your ELB’s hostname to place in the CNAME record with the following: 

kubectl get ingress/RELEASE-webservice-default -ojsonpath='{.status.loadBalancer.ingress[0].hostname}'

RELEASE should be substituted with the release name used in helm install <RELEASE>.