manual_install_aws.md

stage: Systems
group: Distribution
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

{::options parse_block_html="true" /}

Installing a GitLab POC on Amazon Web Services (AWS) (FREE SELF)

This page offers a walkthrough of a common configuration for GitLab on AWS using the official GitLab Linux package. You should customize it to accommodate your needs.

NOTE: For organizations with 1,000 users or less, the recommended AWS installation method is to launch an EC2 single box Omnibus Installation and implement a snapshot strategy for backing up the data. See the 1,000 user reference architecture for more information.

Getting started for production-grade GitLab

NOTE: This document is an installation guide for a proof of concept instance. It is not a reference architecture and it does not result in a highly available configuration.

Following this guide exactly results in a proof of concept instance that roughly equates to a scaled down version of a two availability zone implementation of the Non-HA Omnibus 2000 User Reference Architecture. The 2K reference architecture is not HA because it is primarily intended to provide some scaling while keeping costs and complexity low. The 3000 User Reference Architecture is the smallest size that is GitLab HA. It has additional service roles to achieve HA, most notably it uses Gitaly Cluster to achieve HA for Git repository storage and specifies triple redundancy.

GitLab maintains and tests two main types of Reference Architectures. The Omnibus architectures are implemented on instance compute while Cloud Native Hybrid architectures maximize the use of a Kubernetes cluster. Cloud Native Hybrid reference architecture specifications are addendum sections to the Reference Architecture size pages that start by describing the Omnibus architecture. For example, the 3000 User Cloud Native Reference Architecture is in the subsection titled Cloud Native Hybrid reference architecture with Helm Charts (alternative) in the 3000 User Reference Architecture page.

Getting started for production-grade Omnibus GitLab

The Infrastructure as Code tooling GitLab Environment Tool (GET) is the best place to start for building Omnibus GitLab on AWS and most especially if you are targeting an HA setup. While it does not automate everything, it does complete complex setups like Gitaly Cluster for you. GET is open source so anyone can build on top of it and contribute improvements to it.

Getting started for production-grade Cloud Native Hybrid GitLab

For the Cloud Native Hybrid architectures there are two Infrastructure as Code options which are compared in GitLab Cloud Native Hybrid on AWS EKS implementation pattern in the section Available Infrastructure as Code for GitLab Cloud Native Hybrid. It compares the GitLab Environment Toolkit to the AWS Quick Start for GitLab Cloud Native Hybrid on EKS which was co-developed by GitLab and AWS. GET and the AWS Quick Start are both open source so anyone can build on top of them and contribute improvements to them.

Introduction

For the most part, we make use of Omnibus GitLab in our setup, but we also leverage native AWS services. Instead of using the Omnibus bundled PostgreSQL and Redis, we use Amazon RDS and ElastiCache.

In this guide, we go through a multi-node setup where we start by configuring our Virtual Private Cloud and subnets to later integrate services such as RDS for our database server and ElastiCache as a Redis cluster to finally manage them in an auto scaling group with custom scaling policies.

Requirements

In addition to having a basic familiarity with AWS and Amazon EC2, you need:

• An AWS account
• To create or upload an SSH key to connect to the instance via SSH
• A domain name for the GitLab instance
• An SSL/TLS certificate to secure your domain. If you do not already own one, you can provision a free public SSL/TLS certificate through AWS Certificate Manager(ACM) for use with the Elastic Load Balancer we create.

NOTE: It can take a few hours to validate a certificate provisioned through ACM. To avoid delays later, request your certificate as soon as possible.

Architecture

Below is a diagram of the recommended architecture.

AWS costs

GitLab uses the following AWS services, with links to pricing information:

• EC2: GitLab is deployed on shared hardware, for which on-demand pricing applies. If you want to run GitLab on a dedicated or reserved instance, see the EC2 pricing page for information about its cost.
• S3: GitLab uses S3 (pricing page) to store backups, artifacts, and LFS objects.
• ELB: A Classic Load Balancer (pricing page), used to route requests to the GitLab instances.
• RDS: An Amazon Relational Database Service using PostgreSQL (pricing page).
• ElastiCache: An in-memory cache environment (pricing page), used to provide a Redis configuration.

Create an IAM EC2 instance role and profile

As we are using Amazon S3 object storage, our EC2 instances must have read, write, and list permissions for our S3 buckets. To avoid embedding AWS keys in our GitLab configuration, we make use of an IAM Role to allow our GitLab instance with this access. We must create an IAM policy to attach to our IAM role:

Create an IAM Policy

1. Go to the IAM dashboard and select Policies in the left menu.

2. Select Create policy, select the JSON tab, and add a policy. We want to follow security best practices and grant least privilege, giving our role only the permissions needed to perform the required actions.

   1. Assuming you prefix the S3 bucket names with gl- as shown in the diagram, add the following policy:

   {   "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "s3:PutObject",
                   "s3:GetObject",
                   "s3:DeleteObject",
                   "s3:PutObjectAcl"
               ],
               "Resource": "arn:aws:s3:::gl-*/*"
           },
           {
               "Effect": "Allow",
               "Action": [
                   "s3:ListBucket",
                   "s3:AbortMultipartUpload",
                   "s3:ListMultipartUploadParts",
                   "s3:ListBucketMultipartUploads"
               ],
               "Resource": "arn:aws:s3:::gl-*"
           }
       ]
   }

3. Select Review policy, give your policy a name (we use gl-s3-policy), and select Create policy.

Create an IAM Role

1. Still on the IAM dashboard, select Roles in the left menu, and select Create role.
2. Create a new role by selecting AWS service > EC2, then select Next: Permissions.
3. In the policy filter, search for the gl-s3-policy we created above, select it, and select Tags.
4. Add tags if needed and select Review.
5. Give the role a name (we use GitLabS3Access) and select Create Role.

We use this role when we create a launch configuration later on.

Configuring the network

We start by creating a VPC for our GitLab cloud infrastructure, then we can create subnets to have public and private instances in at least two Availability Zones (AZs). Public subnets require a Route Table keep and an associated Internet Gateway.

Creating the Virtual Private Cloud (VPC)

We now create a VPC, a virtual networking environment that you control:

1. Sign in to Amazon Web Services.

2. Select Your VPCs from the left menu and then select Create VPC. At the "Name tag" enter gitlab-vpc and at the "IPv4 CIDR block" enter 10.0.0.0/16. If you don't require dedicated hardware, you can leave "Tenancy" as default. Select Yes, Create when ready.

   

3. Select the VPC, select Actions, select Edit DNS resolution, and enable DNS resolution. Select Save when done.

Subnets

Now, let's create some subnets in different Availability Zones. Make sure that each subnet is associated to the VPC we just created and that CIDR blocks don't overlap. This also allows us to enable multi AZ for redundancy.

We create private and public subnets to match load balancers and RDS instances as well:

1. Select Subnets from the left menu.

2. Select Create subnet. Give it a descriptive name tag based on the IP, for example gitlab-public-10.0.0.0, select the VPC we created previously, select an availability zone (we use us-west-2a), and at the IPv4 CIDR block let's give it a 24 subnet 10.0.0.0/24:

   

3. Follow the same steps to create all subnets:

   Name tag	Type	Availability Zone	CIDR block
   gitlab-public-10.0.0.0	public	us-west-2a	10.0.0.0/24
   gitlab-private-10.0.1.0	private	us-west-2a	10.0.1.0/24
   gitlab-public-10.0.2.0	public	us-west-2b	10.0.2.0/24
   gitlab-private-10.0.3.0	private	us-west-2b	10.0.3.0/24

4. Once all the subnets are created, enable Auto-assign IPv4 for the two public subnets:

   1. Select each public subnet in turn, select Actions, and select Modify auto-assign IP settings. Enable the option and save.

Internet Gateway

Now, still on the same dashboard, go to Internet Gateways and create a new one:

1. Select Internet Gateways from the left menu.

2. Select Create internet gateway, give it the name gitlab-gateway and select Create.

3. Select it from the table, and then under the Actions dropdown list choose "Attach to VPC".

   

4. Choose gitlab-vpc from the list and hit Attach.

Create NAT Gateways

Instances deployed in our private subnets must connect to the internet for updates, but should not be reachable from the public internet. To achieve this, we make use of NAT Gateways deployed in each of our public subnets:

1. Go to the VPC dashboard and select NAT Gateways in the left menu bar.
2. Select Create NAT Gateway and complete the following:
   1. Subnet: Select gitlab-public-10.0.0.0 from the dropdown list.
   2. Elastic IP Allocation ID: Enter an existing Elastic IP or select Allocate Elastic IP address to allocate a new IP to your NAT gateway.
   3. Add tags if needed.
   4. Select Create NAT Gateway.

Create a second NAT gateway but this time place it in the second public subnet, gitlab-public-10.0.2.0.

Route Tables

Public Route Table

We must create a route table for our public subnets to reach the internet via the internet gateway we created in the previous step.

On the VPC dashboard:

1. Select Route Tables from the left menu.
2. Select Create Route Table.
3. At the "Name tag" enter gitlab-public and choose gitlab-vpc under "VPC".
4. Select Create.

We now must add our internet gateway as a new target and have it receive traffic from any destination.

1. Select Route Tables from the left menu and select the gitlab-public route to show the options at the bottom.
2. Select the Routes tab, select Edit routes > Add route and set 0.0.0.0/0 as the destination. In the target column, select the gitlab-gateway we created previously. Select Save routes when done.

Next, we must associate the public subnets to the route table:

1. Select the Subnet Associations tab and select Edit subnet associations.
2. Check only the public subnets and select Save.

Private Route Tables

We also must create two private route tables so that instances in each private subnet can reach the internet via the NAT gateway in the corresponding public subnet in the same availability zone.

1. Follow the same steps as above to create two private route tables. Name them gitlab-private-a and gitlab-private-b respectively.
2. Next, add a new route to each of the private route tables where the destination is 0.0.0.0/0 and the target is one of the NAT gateways we created earlier.
   1. Add the NAT gateway we created in gitlab-public-10.0.0.0 as the target for the new route in the gitlab-private-a route table.
   2. Similarly, add the NAT gateway in gitlab-public-10.0.2.0 as the target for the new route in the gitlab-private-b.
3. Lastly, associate each private subnet with a private route table.
   1. Associate gitlab-private-10.0.1.0 with gitlab-private-a.
   2. Associate gitlab-private-10.0.3.0 with gitlab-private-b.

Load Balancer

We create a load balancer to evenly distribute inbound traffic on ports 80 and 443 across our GitLab application servers. Based on the scaling policies we create later, instances are added to or removed from our load balancer as needed. Additionally, the load balancer performs health checks on our instances.

On the EC2 dashboard, look for Load Balancer in the left navigation bar:

1. Select Create Load Balancer.
   1. Choose the Classic Load Balancer.
   2. Give it a name (we use gitlab-loadbalancer) and for the Create LB Inside option, select gitlab-vpc from the dropdown list.
   3. In the Listeners section, set the following listeners:
      • HTTP port 80 for both load balancer and instance protocol and ports
      • TCP port 22 for both load balancer and instance protocols and ports
      • HTTPS port 443 for load balancer protocol and ports, forwarding to HTTP port 80 on the instance (we configure GitLab to listen on port 80 later in the guide)
   4. In the Select Subnets section, select both public subnets from the list so that the load balancer can route traffic to both availability zones.
2. We add a security group for our load balancer to act as a firewall to control what traffic is allowed through. Select Assign Security Groups and select Create a new security group, give it a name (we use gitlab-loadbalancer-sec-group) and description, and allow both HTTP and HTTPS traffic from anywhere (0.0.0.0/0, ::/0). Also allow SSH traffic, select a custom source, and add a single trusted IP address or an IP address range in CIDR notation. This allows users to perform Git actions over SSH.
3. Select Configure Security Settings and set the following:
   1. Select an SSL/TLS certificate from ACM or upload a certificate to IAM.
   2. Under Select a Cipher, pick a predefined security policy from the dropdown list. You can see a breakdown of Predefined SSL Security Policies for Classic Load Balancers in the AWS documentation. Check the GitLab codebase for a list of supported SSL ciphers and protocols.
4. Select Configure Health Check and set up a health check for your EC2 instances.
   1. For Ping Protocol, select HTTP.
   2. For Ping Port, enter 80.
   3. For Ping Path - we recommend that you use the Readiness check endpoint. You must add the VPC IP Address Range (CIDR) to the IP allowlist for the Health Check endpoints
   4. Keep the default Advanced Details or adjust them according to your needs.
5. Select Add EC2 Instances - don't add anything as we create an Auto Scaling Group later to manage instances for us.
6. Select Add Tags and add any tags you need.
7. Select Review and Create, review all your settings, and select Create if you're happy.

After the Load Balancer is up and running, you can revisit your Security Groups to refine the access only through the ELB and any other requirements you might have.

Configure DNS for Load Balancer

On the Route 53 dashboard, select Hosted zones in the left navigation bar:

1. Select an existing hosted zone or, if you do not already have one for your domain, select Create Hosted Zone, enter your domain name, and select Create.
2. Select Create Record Set and provide the following values:
   1. Name: Use the domain name (the default value) or enter a subdomain.
   2. Type: Select A - IPv4 address.
   3. Alias: Defaults to No. Select Yes.
   4. Alias Target: Find the ELB Classic Load Balancers section and select the classic load balancer we created earlier.
   5. Routing Policy: We use Simple but you can choose a different policy based on your use case.
   6. Evaluate Target Health: We set this to No but you can choose to have the load balancer route traffic based on target health.
   7. Select Create.
3. If you registered your domain through Route 53, you're done. If you used a different domain registrar, you must update your DNS records with your domain registrar. You must:
   1. Select Hosted zones and select the domain you added above.
   2. You see a list of NS records. From your domain registrar's administrator panel, add each of these as NS records to your domain's DNS records. These steps may vary between domain registrars. If you're stuck, Google "name of your registrar" add DNS records and you should find a help article specific to your domain registrar.

The steps for doing this vary depending on which registrar you use and is beyond the scope of this guide.

PostgreSQL with RDS

For our database server we use Amazon RDS for PostgreSQL which offers Multi AZ for redundancy (Aurora is not supported). First we create a security group and subnet group, then we create the actual RDS instance.

RDS Security Group

We need a security group for our database that allows inbound traffic from the instances we deploy in our gitlab-loadbalancer-sec-group later on:

1. From the EC2 dashboard, select Security Groups from the left menu bar.
2. Select Create security group.
3. Give it a name (we use gitlab-rds-sec-group), a description, and select the gitlab-vpc from the VPC dropdown list.
4. In the Inbound rules section, select Add rule and set the following:
   1. Type: search for and select the PostgreSQL rule.
   2. Source type: set as "Custom".
   3. Source: select the gitlab-loadbalancer-sec-group we created earlier.
5. When done, select Create security group.

RDS Subnet Group

1. Go to the RDS dashboard and select Subnet Groups from the left menu.
2. Select Create DB Subnet Group.
3. Under Subnet group details, enter a name (we use gitlab-rds-group), a description, and choose the gitlab-vpc from the VPC dropdown list.
4. From the Availability Zones dropdown list, select the Availability Zones that include the subnets you've configured. In our case, we add eu-west-2a and eu-west-2b.
5. From the Subnets dropdown list, select the two private subnets (10.0.1.0/24 and 10.0.3.0/24) as we defined them in the subnets section.
6. Select Create when ready.

Create the database

WARNING: Avoid using burstable instances (t class instances) for the database as this could lead to performance issues due to CPU credits running out during sustained periods of high load.

Now, it's time to create the database: