Preparing EKS resources

For a fully functional GitLab instance, you will 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.

Scripted cluster creation

A bootstrap script has been created to automate much of the setup process for users on EKS.

The script will:

  1. Create a new EKS cluster.
  2. Setup kubectl, and connect it to the cluster.
  3. Initialize Helm and install Tiller.

The script uses eksctl to initialize the cluster. If it cannot locate it in your PATH, it will install it to a temporary location.

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 an argument up or down for bootstrap and clean up respectively.

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.14
NUM_NODES The number of nodes required 2
MACHINE_TYPE The type of nodes to deploy m5.xlarge
SERVICE_ACCOUNT The service account name to use for Helm/Tiller tiller

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, GitLab 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.

You can fetch your ELB’s hostname to place in the CNAME record with the following: 

kubectl get ingress/RELEASE-webservice -ojsonpath='{.status.loadBalancer.ingress[0].hostname}'
Note: For environments where internal load balancers are required, Amazon’s Elastic Load Balancers require special annotations.

Next Steps

Continue with the installation of the chart once you have the cluster up and running, and the static IP and DNS entry ready.