diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-07-20 18:40:28 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-07-20 18:40:28 +0300 |
commit | b595cb0c1dec83de5bdee18284abe86614bed33b (patch) | |
tree | 8c3d4540f193c5ff98019352f554e921b3a41a72 /doc/install | |
parent | 2f9104a328fc8a4bddeaa4627b595166d24671d0 (diff) |
Add latest changes from gitlab-org/gitlab@15-2-stable-eev15.2.0-rc42
Diffstat (limited to 'doc/install')
-rw-r--r-- | doc/install/aws/eks_clusters_aws.md | 2 | ||||
-rw-r--r-- | doc/install/aws/gitlab_sre_for_aws.md | 16 | ||||
-rw-r--r-- | doc/install/aws/index.md | 22 | ||||
-rw-r--r-- | doc/install/aws/manual_install_aws.md | 234 | ||||
-rw-r--r-- | doc/install/docker.md | 9 | ||||
-rw-r--r-- | doc/install/installation.md | 38 | ||||
-rw-r--r-- | doc/install/requirements.md | 34 |
7 files changed, 191 insertions, 164 deletions
diff --git a/doc/install/aws/eks_clusters_aws.md b/doc/install/aws/eks_clusters_aws.md index 342740994a1..c939bac888c 100644 --- a/doc/install/aws/eks_clusters_aws.md +++ b/doc/install/aws/eks_clusters_aws.md @@ -48,4 +48,4 @@ Read how to [use the GitLab Runner Helm Chart](https://docs.gitlab.com/runner/in ## Runner Cache -Since the EKS Quick Start provides for EFS provisioning, the best approach is to use EFS for runner caching. Eventually we will publish information on using an S3 bucket for runner caching here. +Because the EKS Quick Start provides for EFS provisioning, the best approach is to use EFS for runner caching. Eventually we will publish information on using an S3 bucket for runner caching here. diff --git a/doc/install/aws/gitlab_sre_for_aws.md b/doc/install/aws/gitlab_sre_for_aws.md index cb7703835fa..2e7de6cf2d4 100644 --- a/doc/install/aws/gitlab_sre_for_aws.md +++ b/doc/install/aws/gitlab_sre_for_aws.md @@ -23,15 +23,15 @@ If you would like to understand the underlying rationale on why GitLab had to in ### Gitaly and Praefect elections -As part of Gitaly cluster consistency, Praefect nodes will occasionally need to vote on what data copy is the most accurate. This requires an uneven number of Praefect nodes to avoid stalemates. This means that for HA, Gitaly and Praefect require a minimum of three nodes. +As part of Gitaly cluster consistency, Praefect nodes must occasionally vote on what data copy is the most accurate. This requires an uneven number of Praefect nodes to avoid stalemates. This means that for HA, Gitaly and Praefect require a minimum of three nodes. ### Gitaly performance monitoring -Complete performance metrics should be collected for Gitaly instances for identification of bottlenecks, as they could have to do with disk IO, network IO or memory. +Complete performance metrics should be collected for Gitaly instances for identification of bottlenecks, as they could have to do with disk IO, network IO, or memory. ### Gitaly performance guidelines -Gitaly functions as the primary Git Repository Storage in GitLab. However, it's not simply a streaming file server. It also does a lot of demanding computing work, such as preparing and caching Git pack files which informs some of the performance recommendations below. +Gitaly functions as the primary Git Repository Storage in GitLab. However, it's not a streaming file server. It also does a lot of demanding computing work, such as preparing and caching Git pack files which informs some of the performance recommendations below. NOTE: All recommendations are for production configurations, including performance testing. For test configurations, like training or functional testing, you can use less expensive options. However, you should adjust or rebuild if performance is an issue. @@ -45,7 +45,7 @@ All recommendations are for production configurations, including performance tes #### CPU and memory recommendations -- The general GitLab Gitaly node recommendations for CPU and Memory assume relatively even loading across repositories. GPT testing of any non-characteristic repositories and/or SRE monitoring of Gitaly metrics may inform when to choose memory and/or CPU higher than general recommendations. +- The general GitLab Gitaly node recommendations for CPU and Memory assume relatively even loading across repositories. GitLab Performance Tool (GPT) testing of any non-characteristic repositories and/or SRE monitoring of Gitaly metrics may inform when to choose memory and/or CPU higher than general recommendations. **To accommodate:** @@ -54,9 +54,9 @@ All recommendations are for production configurations, including performance tes #### Disk I/O recommendations -- Use only SSD storage and the [class of EBS storage](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volume-types.html) that suites your durability and speed requirements. +- Use only SSD storage and the [class of Elastic Block Store (EBS) storage](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volume-types.html) that suites your durability and speed requirements. - When not using provisioned EBS IO, EBS volume size determines the I/O level, so provisioning volumes that are much larger than needed can be the least expensive way to improve EBS IO. -- If Gitaly performance monitoring shows signs of disk stress then one of the provisioned IOPs levels can be chosen. Note that EBS IOPs levels also have enhanced durability which may be appealing for some implementations aside from performance considerations. +- If Gitaly performance monitoring shows signs of disk stress then one of the provisioned IOPs levels can be chosen. EBS IOPs levels also have enhanced durability which may be appealing for some implementations aside from performance considerations. **To accommodate:** @@ -66,7 +66,7 @@ All recommendations are for production configurations, including performance tes #### Network I/O recommendations -- Use only instance types [from the list of ones that support ENA advanced networking]( https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html#instance-type-summary-table) to ensure that cluster replication latency is not due to instance level network I/O bottlenecks. +- Use only instance types [from the list of ones that support Elastic Network Adapter (ENA) advanced networking](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html#instance-type-summary-table) to ensure that cluster replication latency is not due to instance level network I/O bottlenecks. - Choose instances with sizes with more than 10 Gbps - but only if needed and only when having proven a node level network bottleneck with monitoring and/or stress testing. **To accommodate:** @@ -93,4 +93,4 @@ The [AWS GitLab Cloud Native Hybrid on EKS Quick Start](gitlab_hybrid_on_aws.md# ### Gitaly long term management -Gitaly node disk sizes will need to be monitored and increased to accommodate Git repository growth and Gitaly temporary and caching storage needs. The storage configuration on all nodes should be kept identical. +Gitaly node disk sizes must be monitored and increased to accommodate Git repository growth and Gitaly temporary and caching storage needs. The storage configuration on all nodes should be kept identical. diff --git a/doc/install/aws/index.md b/doc/install/aws/index.md index f54bc979152..1227dd43369 100644 --- a/doc/install/aws/index.md +++ b/doc/install/aws/index.md @@ -11,7 +11,7 @@ type: index GitLab [Reference Architectures](../../administration/reference_architectures/index.md) give qualified and tested guidance on the recommended ways GitLab can be configured to meet the performance requirements of various workloads. Reference Architectures are purpose-designed to be non-implementation specific so they can be extrapolated to as many environments as possible. This generally means they have a highly-granular "machine" to "server role" specification and focus on system elements that impact performance. This is what enables Reference Architectures to be adaptable to the broadest number of supported implementations. -Implementation patterns are built on the foundational information and testing done for Reference Architectures and allow architects and implementers at GitLab, GitLab Customers, and GitLab Partners to build out deployments with less experimentation and a higher degree of confidence that the results will perform as expected. A more thorough discussion of implementation patterns is below in [Additional details on implementation patterns](#additional-details-on-implementation-patterns). +Implementation patterns are built on the foundational information and testing done for Reference Architectures and allow architects and implementers at GitLab, GitLab Customers, and GitLab Partners to build out deployments with less experimentation and a higher degree of confidence that the results perform as expected. A more thorough discussion of implementation patterns is below in [Additional details on implementation patterns](#additional-details-on-implementation-patterns). ## AWS Implementation patterns information @@ -19,7 +19,7 @@ The following are the currently available implementation patterns for GitLab whe ### GitLab Site Reliability Engineering (SRE) for AWS -[GitLab Site Reliability Engineering (SRE) for AWS](gitlab_sre_for_aws.md) - information for planning, implementing, upgrading and long term management of GitLab instances and runners on AWS. +[GitLab Site Reliability Engineering (SRE) for AWS](gitlab_sre_for_aws.md) - information for planning, implementing, upgrading, and long term management of GitLab instances and runners on AWS. ### Patterns to Install GitLab Cloud Native Hybrid on AWS EKS (HA) @@ -33,7 +33,7 @@ The following are the currently available implementation patterns for GitLab whe [EKS Cluster Provisioning Patterns](eks_clusters_aws.md) - considerations for setting up EKS cluster for runners and for integrating. -### Patterns for Scaling HA GitLab Runner on AWS EC2 ASG +### Patterns for Scaling HA GitLab Runner on AWS EC2 Auto Scaling group (ASG) The following repository is self-contained in regard to enabling this pattern: [GitLab HA Scaling Runner Vending Machine for AWS EC2 ASG](https://gitlab.com/guided-explorations/aws/gitlab-runner-autoscaling-aws-asg/). The [feature list for this implementation pattern](https://gitlab.com/guided-explorations/aws/gitlab-runner-autoscaling-aws-asg/-/blob/main/FEATURES.md) is good to review to understand the complete value it can deliver. @@ -47,23 +47,23 @@ The following repository is self-contained in regard to enabling this pattern: [ ## AWS known issues list -Known issues are gathered from within GitLab and from customer reported issues. Customers successfully implement GitLab with a variety of "as a Service" components that GitLab has not specifically been designed for, nor has ongoing testing for. While GitLab does take partner technologies very seriously, the highlighting of known issues here is a convenience for implementers and it does not imply that GitLab has targeted compatibility with, nor carries any type of guarantee of running on the partner technology where the issues occur. Please consult individual issues to understand GitLabs stance and plans on any given known issue. +Known issues are gathered from within GitLab and from customer reported issues. Customers successfully implement GitLab with a variety of "as a Service" components that GitLab has not specifically been designed for, nor has ongoing testing for. While GitLab does take partner technologies very seriously, the highlighting of known issues here is a convenience for implementers and it does not imply that GitLab has targeted compatibility with, nor carries any type of guarantee of running on the partner technology where the issues occur. Consult individual issues to understand the GitLab stance and plans on any given known issue. See the [GitLab AWS known issues list](https://gitlab.com/gitlab-com/alliances/aws/public-tracker/-/issues?label_name%5B%5D=AWS+Known+Issue) for a complete list. ## Official GitLab releases as AMIs -GitLab produces AMI images during the regular release process. The AMIs can be used for single instance GitLab installation or, by configuring `/etc/gitlab/gitlab.rb`, can be specialized for specific GitLab service roles (for example a Gitaly server). Older releases remain available and can be used to migrate an older GitLab server to AWS. +GitLab produces Amazon Machine Images (AMI) during the regular release process. The AMIs can be used for single instance GitLab installation or, by configuring `/etc/gitlab/gitlab.rb`, can be specialized for specific GitLab service roles (for example a Gitaly server). Older releases remain available and can be used to migrate an older GitLab server to AWS. Currently the Amazon AMI uses the Amazon prepared Ubuntu AMI (x86 and ARM are available) as its starting point. NOTE: -When deploying a GitLab instance using the official AMI, the root password to the instance will be the EC2 **Instance** ID (NOT the AMI ID). This way of setting the root account password is specific to official GitLab published AMIs ONLY. +When deploying a GitLab instance using the official AMI, the root password to the instance is the EC2 **Instance** ID (not the AMI ID). This way of setting the root account password is specific to official GitLab published AMIs ONLY. -Instances running on Community Edition (CE) require a migration to Enterprise Edition (EE) in order to subscribe to the GitLab Premium or Ultimate plan. If you want to pursue a subscription, using the Free-forever plan of Enterprise Edition is the least disruptive method. +Instances running on Community Edition (CE) require a migration to Enterprise Edition (EE) to subscribe to the GitLab Premium or Ultimate plan. If you want to pursue a subscription, using the Free-forever plan of Enterprise Edition is the least disruptive method. NOTE: -Since any given GitLab upgrade might involve data disk updates or database schema upgrades, simply swapping out the AMI is not sufficient for taking upgrades. +Because any given GitLab upgrade might involve data disk updates or database schema upgrades, swapping out the AMI is not sufficient for taking upgrades. 1. Log in to the AWS Web Console, so that clicking the links in the following step take you directly to the AMI list. 1. Pick the edition you want: @@ -72,9 +72,9 @@ Since any given GitLab upgrade might involve data disk updates or database schem - [GitLab Community Edition](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#Images:visibility=public-images;ownerAlias=782774275127;search=GitLab%20CE;sort=desc:name): The open source version of GitLab. - [GitLab Premium or Ultimate Marketplace (Prelicensed)](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#Images:visibility=public-images;source=Marketplace;search=GitLab%20EE;sort=desc:name): 5 user license built into per-minute billing. -1. AMI IDs are unique per region, so once you've loaded one of the above, select the desired target region in the upper right of the console to see the appropriate AMIs. +1. AMI IDs are unique per region, so after you've loaded one of the above, select the desired target region in the upper right of the console to see the appropriate AMIs. 1. After the console is loaded, you can add additional search criteria to narrow further. For instance, type `13.` to find only 13.x versions. -1. To launch an EC2 Machine with one of the listed AMIs, check the box at the start of the relevant row, and select the "Launch" button near the top of left of the page. +1. To launch an EC2 Machine with one of the listed AMIs, check the box at the start of the relevant row, and select **Launch** near the top of left of the page. NOTE: If you are trying to restore from an older version of GitLab while moving to AWS, find the @@ -88,7 +88,7 @@ GitLab implementation patterns build upon [GitLab Reference Architectures](../.. Testing-backed architectural qualification is a fundamental concept behind implementation patterns: -- Implementation patterns maintain GitLab Reference Architecture compliance and provide [GitLab Performance Tool](https://gitlab.com/gitlab-org/quality/performance) (gpt) reports to demonstrate adherence to them. +- Implementation patterns maintain GitLab Reference Architecture compliance and provide [GitLab Performance Tool](https://gitlab.com/gitlab-org/quality/performance) (GPT) reports to demonstrate adherence to them. - Implementation patterns may be qualified by and/or contributed to by the technology vendor. For instance, an implementation pattern for AWS may be officially reviewed by AWS. - Implementation patterns may specify and test Cloud Platform PaaS services for suitability for GitLab. This testing can be coordinated and help qualify these technologies for Reference Architectures. For instance, qualifying compatibility with and availability of runtime versions of top level PaaS such as those for PostgreSQL and Redis. - Implementation patterns can provided qualified testing for platform limitations, for example, ensuring Gitaly Cluster can work correctly on specific Cloud Platform availability zone latency and throughput characteristics or qualifying what levels of available platform partner local disk performance is workable for Gitaly server to operate with integrity. diff --git a/doc/install/aws/manual_install_aws.md b/doc/install/aws/manual_install_aws.md index 25973220170..7494dc1e95e 100644 --- a/doc/install/aws/manual_install_aws.md +++ b/doc/install/aws/manual_install_aws.md @@ -32,23 +32,23 @@ For the Cloud Native Hybrid architectures there are two Infrastructure as Code o ## Introduction -For the most part, we'll make use of Omnibus GitLab in our setup, but we'll also leverage native AWS services. Instead of using the Omnibus bundled PostgreSQL and Redis, we will use Amazon RDS and ElastiCache. +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'll go through a multi-node setup where we'll start by +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 within an auto scaling group with custom +cluster to finally manage them in an auto scaling group with custom scaling policies. ## Requirements -In addition to having a basic familiarity with [AWS](https://docs.aws.amazon.com/) and [Amazon EC2](https://docs.aws.amazon.com/ec2/), you will need: +In addition to having a basic familiarity with [AWS](https://docs.aws.amazon.com/) and [Amazon EC2](https://docs.aws.amazon.com/ec2/), you need: - [An AWS account](https://console.aws.amazon.com/console/home) - [To create or upload an SSH key](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) 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](https://aws.amazon.com/certificate-manager/)(ACM) for use with the [Elastic Load Balancer](#load-balancer) we'll create. +- 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](https://aws.amazon.com/certificate-manager/)(ACM) for use with the [Elastic Load Balancer](#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. @@ -79,11 +79,11 @@ GitLab uses the following AWS services, with links to pricing information: ## Create an IAM EC2 instance role and profile -As we'll be using [Amazon S3 object storage](#amazon-s3-object-storage), our EC2 instances need to have read, write, and list permissions for our S3 buckets. To avoid embedding AWS keys in our GitLab configuration, we'll make use of an [IAM Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) to allow our GitLab instance with this access. We'll need to create an IAM policy to attach to our IAM role: +As we are using [Amazon S3 object storage](#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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) 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. Navigate to the IAM dashboard and select **Policies** in the left menu. +1. Go to the IAM dashboard and select **Policies** in the left menu. 1. Select **Create policy**, select the `JSON` tab, and add a policy. We want to [follow security best practices and grant _least privilege_](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#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: @@ -114,7 +114,7 @@ As we'll be using [Amazon S3 object storage](#amazon-s3-object-storage), our EC2 } ``` -1. Select **Review policy**, give your policy a name (we'll use `gl-s3-policy`), and select **Create policy**. +1. Select **Review policy**, give your policy a name (we use `gl-s3-policy`), and select **Create policy**. ### Create an IAM Role @@ -124,20 +124,20 @@ As we'll be using [Amazon S3 object storage](#amazon-s3-object-storage), our EC2 **Next: Permissions**. 1. In the policy filter, search for the `gl-s3-policy` we created above, select it, and select **Tags**. 1. Add tags if needed and select **Review**. -1. Give the role a name (we'll use `GitLabS3Access`) and select **Create Role**. +1. Give the role a name (we use `GitLabS3Access`) and select **Create Role**. -We'll use this role when we [create a launch configuration](#create-a-launch-configuration) later on. +We use this role when we [create a launch configuration](#create-a-launch-configuration) later on. ## Configuring the network -We'll start by creating a VPC for our GitLab cloud infrastructure, then +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)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html). Public subnets will require a Route Table keep and an associated +two [Availability Zones (AZs)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html). Public subnets require a Route Table keep and an associated Internet Gateway. ### Creating the Virtual Private Cloud (VPC) -We'll now create a VPC, a virtual networking environment that you'll control: +We now create a VPC, a virtual networking environment that you control: 1. Sign in to [Amazon Web Services](https://console.aws.amazon.com/vpc/home). 1. Select **Your VPCs** from the left menu and then select **Create VPC**. @@ -153,15 +153,15 @@ We'll now create a VPC, a virtual networking environment that you'll control: 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 will also -allow us to enable multi AZ for redundancy. +that CIDR blocks don't overlap. This also +allows us to enable multi AZ for redundancy. -We will create private and public subnets to match load balancers and +We create private and public subnets to match load balancers and RDS instances as well: 1. Select **Subnets** from the left menu. 1. 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'll use `us-west-2a`), + 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`: ![Create subnet](img/create_subnet.png) @@ -186,7 +186,7 @@ create a new one: 1. Select **Internet Gateways** from the left menu. 1. Select **Create internet gateway**, give it the name `gitlab-gateway` and select **Create**. -1. Select it from the table, and then under the **Actions** dropdown choose +1. Select it from the table, and then under the **Actions** dropdown list choose "Attach to VPC". ![Create gateway](img/create_gateway.png) @@ -195,11 +195,11 @@ create a new one: ### Create NAT Gateways -Instances deployed in our private subnets need to connect to the internet for updates, but should not be reachable from the public internet. To achieve this, we'll make use of [NAT Gateways](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html) deployed in each of our public subnets: +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](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html) deployed in each of our public subnets: -1. Navigate to the VPC dashboard and select **NAT Gateways** in the left menu bar. +1. Go to the VPC dashboard and select **NAT Gateways** in the left menu bar. 1. Select **Create NAT Gateway** and complete the following: - 1. **Subnet**: Select `gitlab-public-10.0.0.0` from the dropdown. + 1. **Subnet**: Select `gitlab-public-10.0.0.0` from the dropdown list. 1. **Elastic IP Allocation ID**: Enter an existing Elastic IP or select **Allocate Elastic IP address** to allocate a new IP to your NAT gateway. 1. Add tags if needed. 1. Select **Create NAT Gateway**. @@ -210,7 +210,7 @@ Create a second NAT gateway but this time place it in the second public subnet, #### Public Route Table -We need to create a route table for our public subnets to reach the internet via the internet gateway we created in the previous step. +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: @@ -219,7 +219,7 @@ On the VPC dashboard: 1. At the "Name tag" enter `gitlab-public` and choose `gitlab-vpc` under "VPC". 1. Select **Create**. -We now need to add our internet gateway as a new target and have +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` @@ -235,7 +235,7 @@ Next, we must associate the **public** subnets to the route table: #### Private Route Tables -We also need to 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. +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. 1. 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. @@ -247,30 +247,30 @@ We also need to create two private route tables so that instances in each privat ## Load Balancer -We'll create a load balancer to evenly distribute inbound traffic on ports `80` and `443` across our GitLab application servers. Based the on the [scaling policies](#create-an-auto-scaling-group) we'll create later, instances will be added to or removed from our load balancer as needed. Additionally, the load balance will perform health checks on our instances. +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](#create-an-auto-scaling-group) 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**. - 1. Give it a name (we'll use `gitlab-loadbalancer`) and for the **Create LB Inside** option, select `gitlab-vpc` from the dropdown menu. + 1. Give it a name (we use `gitlab-loadbalancer`) and for the **Create LB Inside** option, select `gitlab-vpc` from the dropdown list. 1. 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 will configure GitLab to listen on port 80 [later in the guide](#add-support-for-proxied-ssl)) + - 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](#add-support-for-proxied-ssl)) 1. In the **Select Subnets** section, select both public subnets from the list so that the load balancer can route traffic to both availability zones. -1. We'll 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'll 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 will allow users to perform Git actions over SSH. +1. 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. 1. Select **Configure Security Settings** and set the following: 1. Select an SSL/TLS certificate from ACM or upload a certificate to IAM. - 1. Under **Select a Cipher**, pick a predefined security policy from the dropdown. You can see a breakdown of [Predefined SSL Security Policies for Classic Load Balancers](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-security-policy-table.html) in the AWS docs. Check the GitLab codebase for a list of [supported SSL ciphers and protocols](https://gitlab.com/gitlab-org/gitlab/-/blob/9ee7ad433269b37251e0dd5b5e00a0f00d8126b4/lib/support/nginx/gitlab-ssl#L97-99). + 1. 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](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-security-policy-table.html) in the AWS documentation. Check the GitLab codebase for a list of [supported SSL ciphers and protocols](https://gitlab.com/gitlab-org/gitlab/-/blob/9ee7ad433269b37251e0dd5b5e00a0f00d8126b4/lib/support/nginx/gitlab-ssl#L97-99). 1. Select **Configure Health Check** and set up a health check for your EC2 instances. 1. For **Ping Protocol**, select HTTP. 1. For **Ping Port**, enter 80. - 1. For **Ping Path** - we recommend that you [use the Readiness check endpoint](../../administration/load_balancer.md#readiness-check). You'll need to add [the VPC IP Address Range (CIDR)](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-security-groups.html#elb-vpc-nacl) to the [IP allowlist](../../administration/monitoring/ip_whitelist.md) for the [Health Check endpoints](../../user/admin_area/monitoring/health_check.md) + 1. For **Ping Path** - we recommend that you [use the Readiness check endpoint](../../administration/load_balancer.md#readiness-check). You must add [the VPC IP Address Range (CIDR)](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-security-groups.html#elb-vpc-nacl) to the [IP allowlist](../../administration/monitoring/ip_whitelist.md) for the [Health Check endpoints](../../user/admin_area/monitoring/health_check.md) 1. Keep the default **Advanced Details** or adjust them according to your needs. -1. Select **Add EC2 Instances** - don't add anything as we will create an Auto Scaling Group later to manage instances for us. +1. Select **Add EC2 Instances** - don't add anything as we create an Auto Scaling Group later to manage instances for us. 1. Select **Add Tags** and add any tags you need. 1. Select **Review and Create**, review all your settings, and select **Create** if you're happy. @@ -288,28 +288,28 @@ On the Route 53 dashboard, select **Hosted zones** in the left navigation bar: 1. **Type:** Select **A - IPv4 address**. 1. **Alias:** Defaults to **No**. Select **Yes**. 1. **Alias Target:** Find the **ELB Classic Load Balancers** section and select the classic load balancer we created earlier. - 1. **Routing Policy:** We'll use **Simple** but you can choose a different policy based on your use case. - 1. **Evaluate Target Health:** We'll set this to **No** but you can choose to have the load balancer route traffic based on target health. + 1. **Routing Policy:** We use **Simple** but you can choose a different policy based on your use case. + 1. **Evaluate Target Health:** We set this to **No** but you can choose to have the load balancer route traffic based on target health. 1. Select **Create**. -1. If you registered your domain through Route 53, you're done. If you used a different domain registrar, you need to update your DNS records with your domain registrar. You'll need to: +1. 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. - 1. You'll 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. + 1. 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 will use Amazon RDS for PostgreSQL which offers Multi AZ -for redundancy (Aurora is **not** supported). First we'll create a security group and subnet group, then we'll +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 will allow inbound traffic from the instances we'll deploy in our `gitlab-loadbalancer-sec-group` later on: +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. 1. Select **Create security group**. -1. Give it a name (we'll use `gitlab-rds-sec-group`), a description, and select the `gitlab-vpc` from the **VPC** dropdown. +1. Give it a name (we use `gitlab-rds-sec-group`), a description, and select the `gitlab-vpc` from the **VPC** dropdown list. 1. In the **Inbound rules** section, select **Add rule** and set the following: 1. **Type:** search for and select the **PostgreSQL** rule. 1. **Source type:** set as "Custom". @@ -318,11 +318,11 @@ We need a security group for our database that will allow inbound traffic from t ### RDS Subnet Group -1. Navigate to the RDS dashboard and select **Subnet Groups** from the left menu. +1. Go to the RDS dashboard and select **Subnet Groups** from the left menu. 1. Select **Create DB Subnet Group**. -1. Under **Subnet group details**, enter a name (we'll use `gitlab-rds-group`), a description, and choose the `gitlab-vpc` from the VPC dropdown. -1. From the **Availability Zones** dropdown, select the Availability Zones that include the subnets you've configured. In our case, we'll add `eu-west-2a` and `eu-west-2b`. -1. From the **Subnets** dropdown, select the two private subnets (`10.0.1.0/24` and `10.0.3.0/24`) as we defined them in the [subnets section](#subnets). +1. Under **Subnet group details**, enter a name (we use `gitlab-rds-group`), a description, and choose the `gitlab-vpc` from the VPC dropdown list. +1. 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`. +1. 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](#subnets). 1. Select **Create** when ready. ### Create the database @@ -332,30 +332,30 @@ Avoid using burstable instances (t class instances) for the database as this cou Now, it's time to create the database: -1. Navigate to the RDS dashboard, select **Databases** from the left menu, and select **Create database**. +1. Go to the RDS dashboard, select **Databases** from the left menu, and select **Create database**. 1. Select **Standard Create** for the database creation method. 1. Select **PostgreSQL** as the database engine and select the minimum PostgreSQL version as defined for your GitLab version in our [database requirements](../../install/requirements.md#postgresql-requirements). -1. Since this is a production server, let's choose **Production** from the **Templates** section. -1. Under **Settings**, set a DB instance identifier, a master username, and a master password. We'll use `gitlab-db-ha`, `gitlab`, and a very secure password respectively. Make a note of these as we'll need them later. -1. For the DB instance size, select **Standard classes** and select an instance size that meets your requirements from the dropdown menu. We'll use a `db.m4.large` instance. +1. Because this is a production server, let's choose **Production** from the **Templates** section. +1. Under **Settings**, set a DB instance identifier, a master username, and a master password. We use `gitlab-db-ha`, `gitlab`, and a very secure password respectively. Make a note of these as we need them later. +1. For the DB instance size, select **Standard classes** and select an instance size that meets your requirements from the dropdown list. We use a `db.m4.large` instance. 1. Under **Storage**, configure the following: - 1. Select **Provisioned IOPS (SSD)** from the storage type dropdown menu. Provisioned IOPS (SSD) storage is best suited for this use (though you can choose General Purpose (SSD) to reduce the costs). Read more about it at [Storage for Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_Storage.html). - 1. Allocate storage and set provisioned IOPS. We'll use the minimum values, `100` and `1000`, respectively. + 1. Select **Provisioned IOPS (SSD)** from the storage type dropdown list. Provisioned IOPS (SSD) storage is best suited for this use (though you can choose General Purpose (SSD) to reduce the costs). Read more about it at [Storage for Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_Storage.html). + 1. Allocate storage and set provisioned IOPS. We use the minimum values, `100` and `1000`, respectively. 1. Enable storage autoscaling (optional) and set a maximum storage threshold. 1. Under **Availability & durability**, select **Create a standby instance** to have a standby RDS instance provisioned in a different [Availability Zone](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.MultiAZ.html). 1. Under **Connectivity**, configure the following: - 1. Select the VPC we created earlier (`gitlab-vpc`) from the **Virtual Private Cloud (VPC)** dropdown menu. + 1. Select the VPC we created earlier (`gitlab-vpc`) from the **Virtual Private Cloud (VPC)** dropdown list. 1. Expand the **Additional connectivity configuration** section and select the subnet group (`gitlab-rds-group`) we created earlier. 1. Set public accessibility to **No**. - 1. Under **VPC security group**, select **Choose existing** and select the `gitlab-rds-sec-group` we create above from the dropdown. + 1. Under **VPC security group**, select **Choose existing** and select the `gitlab-rds-sec-group` we create above from the dropdown list. 1. Leave the database port as the default `5432`. 1. For **Database authentication**, select **Password authentication**. 1. Expand the **Additional configuration** section and complete the following: - 1. The initial database name. We'll use `gitlabhq_production`. + 1. The initial database name. We use `gitlabhq_production`. 1. Configure your preferred backup settings. - 1. The only other change we'll make here is to disable auto minor version updates under **Maintenance**. + 1. The only other change we make here is to disable auto minor version updates under **Maintenance**. 1. Leave all the other settings as is or tweak according to your needs. - 1. Once you're happy, select **Create database**. + 1. If you're happy, select **Create database**. Now that the database is created, let's move on to setting up Redis with ElastiCache. @@ -366,17 +366,17 @@ persistence and is used to store session data, temporary cache information, and ### Create a Redis Security Group -1. Navigate to the EC2 dashboard. +1. Go to the EC2 dashboard. 1. Select **Security Groups** from the left menu. -1. Select **Create security group** and fill in the details. Give it a name (we'll use `gitlab-redis-sec-group`), +1. Select **Create security group** and fill in the details. Give it a name (we use `gitlab-redis-sec-group`), add a description, and choose the VPC we created previously 1. In the **Inbound rules** section, select **Add rule** and add a **Custom TCP** rule, set port `6379`, and set the "Custom" source as the `gitlab-loadbalancer-sec-group` we created earlier. 1. When done, select **Create security group**. ### Redis Subnet Group -1. Navigate to the ElastiCache dashboard from your AWS console. -1. Go to **Subnet Groups** in the left menu, and create a new subnet group (we'll name ours `gitlab-redis-group`). +1. Go to the ElastiCache dashboard from your AWS console. +1. Go to **Subnet Groups** in the left menu, and create a new subnet group (we name ours `gitlab-redis-group`). Make sure to select our VPC and its [private subnets](#subnets). 1. Select **Create** when ready. @@ -384,14 +384,14 @@ persistence and is used to store session data, temporary cache information, and ### Create the Redis Cluster -1. Navigate back to the ElastiCache dashboard. +1. Go back to the ElastiCache dashboard. 1. Select **Redis** on the left menu and select **Create** to create a new Redis cluster. Do not enable **Cluster Mode** as it is [not supported](../../administration/redis/replication_and_failover_external.md#requirements). Even without cluster mode on, you still get the chance to deploy Redis in multiple availability zones. 1. In the settings section: 1. Give the cluster a name (`gitlab-redis`) and a description. 1. For the version, select the latest. - 1. Leave the port as `6379` since this is what we used in our Redis security group above. + 1. Leave the port as `6379` because this is what we used in our Redis security group above. 1. Select the node type (at least `cache.t3.medium`, but adjust to your needs) and the number of replicas. 1. In the advanced settings section: 1. Select the multi-AZ auto-failover option. @@ -418,20 +418,20 @@ If you do not want to maintain bastion hosts, you can set up [AWS Systems Manage ### Create Bastion Host A -1. Navigate to the EC2 Dashboard and select **Launch instance**. +1. Go to the EC2 Dashboard and select **Launch instance**. 1. Select the **Ubuntu Server 18.04 LTS (HVM)** AMI. -1. Choose an instance type. We'll use a `t2.micro` as we'll only use the bastion host to SSH into our other instances. +1. Choose an instance type. We use a `t2.micro` as we only use the bastion host to SSH into our other instances. 1. Select **Configure Instance Details**. - 1. Under **Network**, select the `gitlab-vpc` from the dropdown menu. + 1. Under **Network**, select the `gitlab-vpc` from the dropdown list. 1. Under **Subnet**, select the public subnet we created earlier (`gitlab-public-10.0.0.0`). 1. Double check that under **Auto-assign Public IP** you have **Use subnet setting (Enable)** selected. 1. Leave everything else as default and select **Add Storage**. -1. For storage, we'll leave everything as default and only add an 8GB root volume. We won't store anything on this instance. +1. For storage, we leave everything as default and only add an 8GB root volume. We do not store anything on this instance. 1. Select **Add Tags** and on the next screen select **Add Tag**. - 1. We'll only set `Key: Name` and `Value: Bastion Host A`. + 1. We only set `Key: Name` and `Value: Bastion Host A`. 1. Select **Configure Security Group**. - 1. Select **Create a new security group**, enter a **Security group name** (we'll use `bastion-sec-group`), and add a description. - 1. We'll enable SSH access from anywhere (`0.0.0.0/0`). If you want stricter security, specify a single IP address or an IP address range in CIDR notation. + 1. Select **Create a new security group**, enter a **Security group name** (we use `bastion-sec-group`), and add a description. + 1. We enable SSH access from anywhere (`0.0.0.0/0`). If you want stricter security, specify a single IP address or an IP address range in CIDR notation. 1. Select **Review and Launch** 1. Review all your settings and, if you're happy, select **Launch**. 1. Acknowledge that you have access to an existing key pair or create a new one. Select **Launch Instance**. @@ -447,18 +447,18 @@ Confirm that you can SSH into the instance: 1. Create an EC2 instance following the same steps as above with the following changes: 1. For the **Subnet**, select the second public subnet we created earlier (`gitlab-public-10.0.2.0`). - 1. Under the **Add Tags** section, we'll set `Key: Name` and `Value: Bastion Host B` so that we can easily identify our two instances. + 1. Under the **Add Tags** section, we set `Key: Name` and `Value: Bastion Host B` so that we can easily identify our two instances. 1. For the security group, select the existing `bastion-sec-group` we created above. ### Use SSH Agent Forwarding -EC2 instances running Linux use private key files for SSH authentication. You'll connect to your bastion host using an SSH client and the private key file stored on your client. Since the private key file is not present on the bastion host, you will not be able to connect to your instances in private subnets. +EC2 instances running Linux use private key files for SSH authentication. You connect to your bastion host using an SSH client and the private key file stored on your client. Because the private key file is not present on the bastion host, you are not able to connect to your instances in private subnets. Storing private key files on your bastion host is a bad idea. To get around this, use SSH agent forwarding on your client. See [Securely Connect to Linux Instances Running in a Private Amazon VPC](https://aws.amazon.com/blogs/security/securely-connect-to-linux-instances-running-in-a-private-amazon-vpc/) for a step-by-step guide on how to use SSH agent forwarding. ## Install GitLab and create custom AMI -We will need a preconfigured, custom GitLab AMI to use in our launch configuration later. As a starting point, we will use the official GitLab AMI to create a GitLab instance. Then, we'll add our custom configuration for PostgreSQL, Redis, and Gitaly. If you prefer, instead of using the official GitLab AMI, you can also spin up an EC2 instance of your choosing and [manually install GitLab](https://about.gitlab.com/install/). +We need a preconfigured, custom GitLab AMI to use in our launch configuration later. As a starting point, we use the official GitLab AMI to create a GitLab instance. Then, we add our custom configuration for PostgreSQL, Redis, and Gitaly. If you prefer, instead of using the official GitLab AMI, you can also spin up an EC2 instance of your choosing and [manually install GitLab](https://about.gitlab.com/install/). ### Install GitLab @@ -467,12 +467,12 @@ From the EC2 dashboard: 1. Use the section below titled "[Find official GitLab-created AMI IDs on AWS](#find-official-gitlab-created-ami-ids-on-aws)" to find the correct AMI to launch. 1. After clicking **Launch** on the desired AMI, select an instance type based on your workload. Consult the [hardware requirements](../../install/requirements.md#hardware-requirements) to choose one that fits your needs (at least `c5.xlarge`, which is sufficient to accommodate 100 users). 1. Select **Configure Instance Details**: - 1. In the **Network** dropdown, select `gitlab-vpc`, the VPC we created earlier. - 1. In the **Subnet** dropdown, select `gitlab-private-10.0.1.0` from the list of subnets we created earlier. + 1. In the **Network** dropdown list, select `gitlab-vpc`, the VPC we created earlier. + 1. In the **Subnet** dropdown list, select `gitlab-private-10.0.1.0` from the list of subnets we created earlier. 1. Double check that **Auto-assign Public IP** is set to `Use subnet setting (Disable)`. 1. Select **Add Storage**. - 1. The root volume is 8GiB by default and should be enough given that we won't store any data there. -1. Select **Add Tags** and add any tags you may need. In our case, we'll only set `Key: Name` and `Value: GitLab`. + 1. The root volume is 8GiB by default and should be enough given that we do not store any data there. +1. Select **Add Tags** and add any tags you may need. In our case, we only set `Key: Name` and `Value: GitLab`. 1. Select **Configure Security Group**. Check **Select an existing security group** and select the `gitlab-loadbalancer-sec-group` we created earlier. 1. Select **Review and launch** followed by **Launch** if you're happy with your settings. 1. Finally, acknowledge that you have access to the selected private key file or create a new one. Select **Launch Instances**. @@ -483,7 +483,7 @@ Connect to your GitLab instance via **Bastion Host A** using [SSH Agent Forwardi #### Disable Let's Encrypt -Since we're adding our SSL certificate at the load balancer, we do not need the GitLab built-in support for Let's Encrypt. Let's Encrypt [is enabled by default](https://docs.gitlab.com/omnibus/settings/ssl.html#lets-encrypt-integration) when using an `https` domain in GitLab 10.7 and later, so we need to explicitly disable it: +Because we're adding our SSL certificate at the load balancer, we do not need the GitLab built-in support for Let's Encrypt. Let's Encrypt [is enabled by default](https://docs.gitlab.com/omnibus/settings/ssl.html#lets-encrypt-integration) when using an `https` domain in GitLab 10.7 and later, so we must explicitly disable it: 1. Open `/etc/gitlab/gitlab.rb` and disable it: @@ -501,7 +501,7 @@ Since we're adding our SSL certificate at the load balancer, we do not need the From your GitLab instance, connect to the RDS instance to verify access and to install the required `pg_trgm` and `btree_gist` extensions. -To find the host or endpoint, navigate to **Amazon RDS > Databases** and select the database you created earlier. Look for the endpoint under the **Connectivity & security** tab. +To find the host or endpoint, go to **Amazon RDS > Databases** and select the database you created earlier. Look for the endpoint under the **Connectivity & security** tab. Do not to include the colon and port number: @@ -523,10 +523,10 @@ gitlab=# \q #### Configure GitLab to connect to PostgreSQL and Redis 1. Edit `/etc/gitlab/gitlab.rb`, find the `external_url 'http://<domain>'` option - and change it to the `https` domain you will be using. + and change it to the `https` domain you are using. 1. Look for the GitLab database settings and uncomment as necessary. In - our current case we'll specify the database adapter, encoding, host, name, + our current case we specify the database adapter, encoding, host, name, username, and password: ```ruby @@ -542,7 +542,7 @@ gitlab=# \q gitlab_rails['db_host'] = "<rds-endpoint>" ``` -1. Next, we need to configure the Redis section by adding the host and +1. Next, we must configure the Redis section by adding the host and uncommenting the port: ```ruby @@ -560,7 +560,7 @@ gitlab=# \q sudo gitlab-ctl reconfigure ``` -1. You might also find it useful to run a check and a service status to make sure +1. You can also run a check and a service status to make sure everything has been setup correctly: ```shell @@ -578,21 +578,21 @@ Gitaly is a service that provides high-level RPC access to Git repositories. It should be enabled and configured on a separate EC2 instance in one of the [private subnets](#subnets) we configured previously. -Let's create an EC2 instance where we'll install Gitaly: +Let's create an EC2 instance where we install Gitaly: 1. From the EC2 dashboard, select **Launch instance**. -1. Choose an AMI. In this example, we'll select the **Ubuntu Server 18.04 LTS (HVM), SSD Volume Type**. -1. Choose an instance type. We'll pick a `c5.xlarge`. +1. Choose an AMI. In this example, we select the **Ubuntu Server 18.04 LTS (HVM), SSD Volume Type**. +1. Choose an instance type. We pick a `c5.xlarge`. 1. Select **Configure Instance Details**. - 1. In the **Network** dropdown, select `gitlab-vpc`, the VPC we created earlier. - 1. In the **Subnet** dropdown, select `gitlab-private-10.0.1.0` from the list of subnets we created earlier. + 1. In the **Network** dropdown list, select `gitlab-vpc`, the VPC we created earlier. + 1. In the **Subnet** dropdown list, select `gitlab-private-10.0.1.0` from the list of subnets we created earlier. 1. Double check that **Auto-assign Public IP** is set to `Use subnet setting (Disable)`. 1. Select **Add Storage**. 1. Increase the Root volume size to `20 GiB` and change the **Volume Type** to `Provisioned IOPS SSD (io1)`. (This is an arbitrary size. Create a volume big enough for your repository storage requirements.) 1. For **IOPS** set `1000` (20 GiB x 50 IOPS). You can provision up to 50 IOPS per GiB. If you select a larger volume, increase the IOPS accordingly. Workloads where many small files are written in a serialized manner, like `git`, requires performant storage, hence the choice of `Provisioned IOPS SSD (io1)`. -1. Select **Add Tags** and add your tags. In our case, we'll only set `Key: Name` and `Value: Gitaly`. +1. Select **Add Tags** and add your tags. In our case, we only set `Key: Name` and `Value: Gitaly`. 1. Select **Configure Security Group** and let's **Create a new security group**. - 1. Give your security group a name and description. We'll use `gitlab-gitaly-sec-group` for both. + 1. Give your security group a name and description. We use `gitlab-gitaly-sec-group` for both. 1. Create a **Custom TCP** rule and add port `8075` to the **Port Range**. For the **Source**, select the `gitlab-loadbalancer-sec-group`. 1. Also add an inbound rule for SSH from the `bastion-sec-group` so that we can connect using [SSH Agent Forwarding](#use-ssh-agent-forwarding) from the Bastion hosts. 1. Select **Review and launch** followed by **Launch** if you're happy with your settings. @@ -611,11 +611,11 @@ Remember to run `sudo gitlab-ctl reconfigure` after saving the changes to the `g #### Fast lookup of authorized SSH keys -The public SSH keys for users allowed to access GitLab are stored in `/var/opt/gitlab/.ssh/authorized_keys`. Typically we'd use shared storage so that all the instances are able to access this file when a user performs a Git action over SSH. Since we do not have shared storage in our setup, we'll update our configuration to authorize SSH users via indexed lookup in the GitLab database. +The public SSH keys for users allowed to access GitLab are stored in `/var/opt/gitlab/.ssh/authorized_keys`. Typically we'd use shared storage so that all the instances are able to access this file when a user performs a Git action over SSH. Because we do not have shared storage in our setup, we update our configuration to authorize SSH users via indexed lookup in the GitLab database. Follow the instructions at [Setting up fast lookup via GitLab Shell](../../administration/operations/fast_ssh_key_lookup.md#setting-up-fast-lookup-via-gitlab-shell) to switch from using the `authorized_keys` file to the database. -If you do not configure fast lookup, Git actions over SSH will result in the following error: +If you do not configure fast lookup, Git actions over SSH results in the following error: ```shell Permission denied (publickey). @@ -629,7 +629,7 @@ and the repository exists. Ordinarily we would manually copy the contents (primary and public keys) of `/etc/ssh/` on the primary application server to `/etc/ssh` on all secondary servers. This prevents false man-in-the-middle-attack alerts when accessing servers in your cluster behind a load balancer. -We'll automate this by creating static host keys as part of our custom AMI. As these host keys are also rotated every time an EC2 instance boots up, "hard coding" them into our custom AMI serves as a handy workaround. +We automate this by creating static host keys as part of our custom AMI. As these host keys are also rotated every time an EC2 instance boots up, "hard coding" them into our custom AMI serves as a workaround. On your GitLab instance run the following: @@ -650,16 +650,16 @@ HostKey /etc/ssh_static/ssh_host_ed25519_key #### Amazon S3 object storage -Since we're not using NFS for shared storage, we will use [Amazon S3](https://aws.amazon.com/s3/) buckets to store backups, artifacts, LFS objects, uploads, merge request diffs, container registry images, and more. Our documentation includes [instructions on how to configure object storage](../../administration/object_storage.md) for each of these data types, and other information about using object storage with GitLab. +Because we're not using NFS for shared storage, we use [Amazon S3](https://aws.amazon.com/s3/) buckets to store backups, artifacts, LFS objects, uploads, merge request diffs, container registry images, and more. Our documentation includes [instructions on how to configure object storage](../../administration/object_storage.md) for each of these data types, and other information about using object storage with GitLab. NOTE: -Since we are using the [AWS IAM profile](#create-an-iam-role) we created earlier, be sure to omit the AWS access key and secret access key/value pairs when configuring object storage. Instead, use `'use_iam_profile' => true` in your configuration as shown in the object storage documentation linked above. +Because we are using the [AWS IAM profile](#create-an-iam-role) we created earlier, be sure to omit the AWS access key and secret access key/value pairs when configuring object storage. Instead, use `'use_iam_profile' => true` in your configuration as shown in the object storage documentation linked above. Remember to run `sudo gitlab-ctl reconfigure` after saving the changes to the `gitlab.rb` file. --- -That concludes the configuration changes for our GitLab instance. Next, we'll create a custom AMI based on this instance to use for our launch configuration and auto scaling group. +That concludes the configuration changes for our GitLab instance. Next, we create a custom AMI based on this instance to use for our launch configuration and auto scaling group. ### Log in for the first time @@ -672,7 +672,7 @@ Depending on how you installed GitLab and if you did not change the password by To change the default password, log in as the `root` user with the default password and [change it in the user profile](../../user/profile#change-your-password). -When our [auto scaling group](#create-an-auto-scaling-group) spins up new instances, we'll be able to log in with username `root` and the newly created password. +When our [auto scaling group](#create-an-auto-scaling-group) spins up new instances, we are able to log in with username `root` and the newly created password. ### Create custom AMI @@ -680,10 +680,10 @@ On the EC2 dashboard: 1. Select the `GitLab` instance we [created earlier](#install-gitlab). 1. Select **Actions**, scroll down to **Image** and select **Create Image**. -1. Give your image a name and description (we'll use `GitLab-Source` for both). +1. Give your image a name and description (we use `GitLab-Source` for both). 1. Leave everything else as default and select **Create Image** -Now we have a custom AMI that we'll use to create our launch configuration the next step. +Now we have a custom AMI that we use to create our launch configuration the next step. ## Deploy GitLab inside an auto scaling group @@ -694,11 +694,11 @@ From the EC2 dashboard: 1. Select **Launch Configurations** from the left menu and select **Create launch configuration**. 1. Select **My AMIs** from the left menu and select the `GitLab` custom AMI we created above. 1. Select an instance type best suited for your needs (at least a `c5.xlarge`) and select **Configure details**. -1. Enter a name for your launch configuration (we'll use `gitlab-ha-launch-config`). +1. Enter a name for your launch configuration (we use `gitlab-ha-launch-config`). 1. **Do not** check **Request Spot Instance**. -1. From the **IAM Role** dropdown, pick the `GitLabAdmin` instance role we [created earlier](#create-an-iam-ec2-instance-role-and-profile). +1. From the **IAM Role** dropdown list, pick the `GitLabAdmin` instance role we [created earlier](#create-an-iam-ec2-instance-role-and-profile). 1. Leave the rest as defaults and select **Add Storage**. -1. The root volume is 8GiB by default and should be enough given that we won't store any data there. Select **Configure Security Group**. +1. The root volume is 8GiB by default and should be enough given that we do not store any data there. Select **Configure Security Group**. 1. Check **Select and existing security group** and select the `gitlab-loadbalancer-sec-group` we created earlier. 1. Select **Review**, review your changes, and select **Create launch configuration**. 1. Acknowledge that you have access to the private key or create a new one. Select **Create launch configuration**. @@ -706,16 +706,16 @@ From the EC2 dashboard: ### Create an auto scaling group 1. After the launch configuration is created, select **Create an Auto Scaling group using this launch configuration** to start creating the auto scaling group. -1. Enter a **Group name** (we'll use `gitlab-auto-scaling-group`). -1. For **Group size**, enter the number of instances you want to start with (we'll enter `2`). -1. Select the `gitlab-vpc` from the **Network** dropdown. +1. Enter a **Group name** (we use `gitlab-auto-scaling-group`). +1. For **Group size**, enter the number of instances you want to start with (we enter `2`). +1. Select the `gitlab-vpc` from the **Network** dropdown list. 1. Add both the private [subnets we created earlier](#subnets). 1. Expand the **Advanced Details** section and check the **Receive traffic from one or more load balancers** option. -1. From the **Classic Load Balancers** dropdown, select the load balancer we created earlier. +1. From the **Classic Load Balancers** dropdown list, select the load balancer we created earlier. 1. For **Health Check Type**, select **ELB**. -1. We'll leave our **Health Check Grace Period** as the default `300` seconds. Select **Configure scaling policies**. +1. We leave our **Health Check Grace Period** as the default `300` seconds. Select **Configure scaling policies**. 1. Check **Use scaling policies to adjust the capacity of this group**. -1. For this group we'll scale between 2 and 4 instances where one instance will be added if CPU +1. For this group we scale between 2 and 4 instances where one instance is added if CPU utilization is greater than 60% and one instance is removed if it falls to less than 45%. @@ -724,9 +724,9 @@ to less than 45%. 1. Finally, configure notifications and tags as you see fit, review your changes, and create the auto scaling group. -As the auto scaling group is created, you'll see your new instances spinning up in your EC2 dashboard. You'll also see the new instances added to your load balancer. Once the instances pass the heath check, they are ready to start receiving traffic from the load balancer. +As the auto scaling group is created, you see your new instances spinning up in your EC2 dashboard. You also see the new instances added to your load balancer. After the instances pass the heath check, they are ready to start receiving traffic from the load balancer. -Since our instances are created by the auto scaling group, go back to your instances and terminate the [instance we created manually above](#install-gitlab). We only needed this instance to create our custom AMI. +Because our instances are created by the auto scaling group, go back to your instances and terminate the [instance we created manually above](#install-gitlab). We only needed this instance to create our custom AMI. ## Health check and monitoring with Prometheus @@ -753,11 +753,11 @@ and restore its Git data, database, attachments, LFS objects, and so on. Some important things to know: -- The backup/restore tool **does not** store some configuration files, like secrets; you'll - need to [configure this yourself](../../raketasks/backup_restore.md#storing-configuration-files). +- The backup/restore tool **does not** store some configuration files, like secrets; you + must [configure this yourself](../../raketasks/backup_gitlab.md#storing-configuration-files). - By default, the backup files are stored locally, but you can - [backup GitLab using S3](../../raketasks/backup_restore.md#using-amazon-s3). -- You can [exclude specific directories form the backup](../../raketasks/backup_restore.md#excluding-specific-directories-from-the-backup). + [backup GitLab using S3](../../raketasks/backup_gitlab.md#using-amazon-s3). +- You can [exclude specific directories form the backup](../../raketasks/backup_gitlab.md#excluding-specific-directories-from-the-backup). ### Backing up GitLab @@ -777,7 +777,7 @@ For GitLab 12.1 and earlier, use `gitlab-rake gitlab:backup:create`. To restore GitLab, first review the [restore documentation](../../raketasks/backup_restore.md#restore-gitlab), and primarily the restore prerequisites. Then, follow the steps under the -[Omnibus installations section](../../raketasks/backup_restore.md#restore-for-omnibus-gitlab-installations). +[Omnibus installations section](../../raketasks/restore_gitlab.md#restore-for-omnibus-gitlab-installations). ## Updating GitLab @@ -825,7 +825,7 @@ to request additional material: GitLab supports several different types of clustering. - [Geo replication](../../administration/geo/index.md): Geo is the solution for widely distributed development teams. -- [Omnibus GitLab](https://docs.gitlab.com/omnibus/) - Everything you need to know +- [Omnibus GitLab](https://docs.gitlab.com/omnibus/) - Everything you must know about administering your GitLab instance. - [Add a license](../../user/admin_area/license.md): Activate all GitLab Enterprise Edition functionality with a license. @@ -835,9 +835,9 @@ to request additional material: ### Instances are failing health checks -If your instances are failing the load balancer's health checks, verify that they are returning a status `200` from the health check endpoint we configured earlier. Any other status, including redirects like status `302`, will cause the health check to fail. +If your instances are failing the load balancer's health checks, verify that they are returning a status `200` from the health check endpoint we configured earlier. Any other status, including redirects like status `302`, causes the health check to fail. -You may have to set a password on the `root` user to prevent automatic redirects on the sign-in endpoint before health checks will pass. +You may have to set a password on the `root` user to prevent automatic redirects on the sign-in endpoint before health checks pass. ### "The change you requested was rejected (422)" diff --git a/doc/install/docker.md b/doc/install/docker.md index 058233520ca..356c025e168 100644 --- a/doc/install/docker.md +++ b/doc/install/docker.md @@ -272,6 +272,10 @@ Here's an example that deploys GitLab with four runners as a [stack](https://doc docker stack deploy --compose-file docker-compose.yml mystack ``` +### Install the product documentation + +This is an optional step. See how to [self-host the product documentation](../administration/docs_self_host.md#self-host-the-product-documentation-with-docker). + ## Configuration This container uses the official Omnibus GitLab package, so all configuration @@ -529,6 +533,11 @@ The following steps assume that you are upgrading the same version. replace `ce` with `ee` in your `docker run` command or `docker-compose.yml` file. However, reuse the CE container name, port and file mappings, and version. +### Upgrade the product documentation + +This is an optional step. If you [installed the documentation site](#install-the-product-documentation), +see how to [upgrade to another version](../administration/docs_self_host.md#upgrade-using-docker). + ## Back up GitLab You can create a GitLab backup with: diff --git a/doc/install/installation.md b/doc/install/installation.md index cc2e57aac96..2f2ae016edd 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -27,20 +27,20 @@ following the ## Consider the Omnibus package installation -Since an installation from source is a lot of work and error prone we strongly recommend the fast and reliable [Omnibus package installation](https://about.gitlab.com/install/) (deb/rpm). +Because an installation from source is a lot of work and error prone we strongly recommend the fast and reliable [Omnibus package installation](https://about.gitlab.com/install/) (deb/rpm). One reason the Omnibus package is more reliable is its use of runit to restart any of the GitLab processes in case one crashes. On heavily used GitLab instances the memory usage of the Sidekiq background worker grows over time. Omnibus packages solve this by [letting the Sidekiq terminate gracefully](../administration/operations/sidekiq_memory_killer.md) if it uses too much memory. After this termination runit detects Sidekiq is not running and starts it. -Since installations from source don't use runit for process supervision, Sidekiq +Because installations from source don't use runit for process supervision, Sidekiq can't be terminated and its memory usage grows over time. ## Select a version to install Make sure you view [this installation guide](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/install/installation.md) from the branch (version) of GitLab you would like to install (for example, `11-7-stable`). -You can select the branch in the version dropdown in the top left corner of GitLab (below the menu bar). +You can select the branch in the version dropdown list in the top left corner of GitLab (below the menu bar). If the highest number stable branch is unclear, check the [GitLab blog](https://about.gitlab.com/blog/) for installation guide links by version. @@ -51,7 +51,7 @@ If the highest number stable branch is unclear, check the [GitLab blog](https:// | [Ruby](#2-ruby) | `2.7` | From GitLab 13.6, Ruby 2.7 is required. Ruby 3.0 is not supported yet (see [the relevant epic](https://gitlab.com/groups/gitlab-org/-/epics/5149) for the current status). You must use the standard MRI implementation of Ruby. We love [JRuby](https://www.jruby.org/) and [Rubinius](https://github.com/rubinius/rubinius#the-rubinius-language-platform), but GitLab needs several Gems that have native extensions. | | [Go](#3-go) | `1.16` | | | [Git](#git) | `2.33.x` | From GitLab 14.4, Git 2.33.x and later is required. It's highly recommended that you use the [Git version provided by Gitaly](#git). | -| [Node.js](#4-node) | `14.15.0` | GitLab uses [webpack](https://webpack.js.org/) to compile frontend assets. Node.js 16.x is recommended, as it's faster. You can check which version you're running with `node -v`. You need to update it to a newer version if needed. | +| [Node.js](#4-node) | `14.15.0` | GitLab uses [webpack](https://webpack.js.org/) to compile frontend assets. Node.js 16.x is recommended, as it's faster. You can check which version you're running with `node -v`. You must update it to a newer version if needed. | ## GitLab directory structure @@ -179,7 +179,7 @@ the Git path: ### GraphicsMagick For the [Custom Favicon](../user/admin_area/appearance.md#favicon) to work, GraphicsMagick -needs to be installed. +must be installed. ```shell sudo apt-get install -y graphicsmagick @@ -187,7 +187,7 @@ sudo apt-get install -y graphicsmagick ### Mail server -In order to receive mail notifications, make sure to install a mail server. +To receive mail notifications, make sure to install a mail server. By default, Debian is shipped with `exim4` but this [has problems](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/12754) while Ubuntu does not ship with one. The recommended mail server is `postfix` and you @@ -264,7 +264,7 @@ requirements for these are: In many distributions, the versions provided by the official package repositories are out of date, so -we need to install through the following commands: +we must install through the following commands: ```shell # install node v16.x @@ -298,7 +298,7 @@ In GitLab 12.1 and later, only PostgreSQL is supported. In GitLab 14.0 and later ``` For Ubuntu 18.04 and earlier, the available PostgreSQL doesn't meet the minimum - version requirement. You need to add PostgreSQL's repository: + version requirement. You must add PostgreSQL's repository: ```shell wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add - @@ -426,7 +426,7 @@ sudo usermod -aG redis git ### Supervise Redis with systemd If your distribution uses systemd init and the output of the following command is `notify`, -you do not need to make any changes: +you must not make any changes: ```shell systemctl show --value --property=Type redis-server.service @@ -678,7 +678,7 @@ sudo -u git -H bundle exec rake "gitlab:indexer:install[/home/git/gitlab-elastic ``` The source code first is fetched to the path specified by the first parameter. Then a binary is built under its `bin` directory. -You then need to update `gitlab.yml`'s `production -> elasticsearch -> indexer_path` setting to point to that binary. +You must then update `gitlab.yml`'s `production -> elasticsearch -> indexer_path` setting to point to that binary. ### Install GitLab Pages @@ -740,7 +740,7 @@ sudo systemctl daemon-reload The units provided by GitLab make very little assumptions about where you are running Redis and PostgreSQL. -If you installed GitLab in another directory or as a user other than the default, you need to change these values in the units as well. +If you installed GitLab in another directory or as a user other than the default, you must change these values in the units as well. For example, if you're running Redis and PostgreSQL on the same machine as GitLab, you should: @@ -853,7 +853,7 @@ sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production force=yes # When done, you see 'Administrator account created:' ``` -You can set the Administrator/root password and email by supplying them in environmental variables, `GITLAB_ROOT_PASSWORD` and `GITLAB_ROOT_EMAIL` respectively, as seen below. If you don't set the password (and it is set to the default one), wait to expose GitLab to the public internet until the installation is done and you've logged into the server the first time. During the first login, you'll be forced to change the default password. An Enterprise Edition license may also be installed at this time by supplying a full path in the `GITLAB_LICENSE_FILE` environment variable. +You can set the Administrator/root password and email by supplying them in environmental variables, `GITLAB_ROOT_PASSWORD` and `GITLAB_ROOT_EMAIL` respectively, as seen below. If you don't set the password (and it is set to the default one), wait to expose GitLab to the public internet until the installation is done and you've logged into the server the first time. During the first login, you are forced to change the default password. An Enterprise Edition license may also be installed at this time by supplying a full path in the `GITLAB_LICENSE_FILE` environment variable. ```shell sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production GITLAB_ROOT_PASSWORD=yourpassword GITLAB_ROOT_EMAIL=youremail GITLAB_LICENSE_FILE="/path/to/license" @@ -942,7 +942,7 @@ to use. Read all about the needed configuration at the If you want to use HTTPS, replace the `gitlab` NGINX configuration with `gitlab-ssl`. See [Using HTTPS](#using-https) for HTTPS configuration details. -For the NGINX to be able to read the GitLab-Workhorse socket, you need to make sure, that the `www-data` user can read the socket, which will be owned by the GitLab user. This is most easily achieved, if it is world-readable, for example that it has permissions `0755`, which is the default. `www-data` also needs to be able to list the parent directories. +For the NGINX to be able to read the GitLab-Workhorse socket, you must make sure, that the `www-data` user can read the socket, which is owned by the GitLab user. This is achieved, if it is world-readable, for example that it has permissions `0755`, which is the default. `www-data` also must be able to list the parent directories. ### Test Configuration @@ -999,8 +999,8 @@ Supply the `SANITIZE=true` environment variable to `gitlab:check` to omit projec Visit YOUR_SERVER in your web browser for your first GitLab login. If you didn't [provide a root password during setup](#initialize-database-and-activate-advanced-features), -you'll be redirected to a password reset screen to provide the password for the -initial administrator account. Enter your desired password and you'll be +you are redirected to a password reset screen to provide the password for the +initial administrator account. Enter your desired password and you are redirected back to the login screen. The default account's username is **root**. Provide the password you created @@ -1013,6 +1013,10 @@ To start and stop GitLab when using: - systemd units: use `sudo systemctl start gitlab.target` or `sudo systemctl stop gitlab.target`. - The SysV init script: use `sudo service gitlab start` or `sudo service gitlab stop`. +### Install the product documentation + +This is an optional step. See how to [self-host the product documentation](../administration/docs_self_host.md). + ## Advanced Setup Tips ### Relative URL support @@ -1110,7 +1114,7 @@ host localhost # Give your setup a name (here: override localhost) hostname 127.0.0.1; # Your server name or IP ``` -You also need to change the corresponding options (for example, `ssh_user`, `ssh_host`, `admin_uri`) in the `config/gitlab.yml` file. +You must also change the corresponding options (for example, `ssh_user`, `ssh_host`, `admin_uri`) in the `config/gitlab.yml` file. ### Additional Markup Styles @@ -1119,7 +1123,7 @@ Apart from the always supported Markdown style, there are other rich text files ### Using Sidekiq instead of Sidekiq Cluster As of GitLab 12.10, Source installations are using `bin/sidekiq-cluster` for managing Sidekiq processes. -Using Sidekiq directly is still supported until 14.0. So if you're experiencing issues, please: +Using Sidekiq directly is still supported until 14.0. So if you're experiencing issues: 1. Edit the system `init.d` script to remove the `SIDEKIQ_WORKERS` flag. If you have `/etc/default/gitlab`, then you should edit it instead. 1. Restart GitLab. diff --git a/doc/install/requirements.md b/doc/install/requirements.md index d01860cb24f..27148e06ccb 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -26,22 +26,22 @@ For the installation options, see [the main installation page](index.md). - macOS Installation of GitLab on these operating systems is possible, but not supported. -Please see the [installation from source guide](installation.md) and the [installation guides](https://about.gitlab.com/install/) for more information. +See the [installation from source guide](installation.md) and the [installation guides](https://about.gitlab.com/install/) for more information. -Please see [OS versions that are no longer supported](../administration/package_information/supported_os.md#os-versions-that-are-no-longer-supported) for Omnibus installs page +See [OS versions that are no longer supported](../administration/package_information/supported_os.md#os-versions-that-are-no-longer-supported) for Omnibus installs page for a list of supported and unsupported OS versions as well as the last support GitLab version for that OS. ### Microsoft Windows GitLab is developed for Linux-based operating systems. It does **not** run on Microsoft Windows, and we have no plans to support it in the near future. For the latest development status view this [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/22337). -Please consider using a virtual machine to run GitLab. +Consider using a virtual machine to run GitLab. ## Software requirements ### Redis versions -GitLab 13.0 and later requires Redis version 4.0 or higher. +GitLab 13.0 and later requires Redis version 5.0 or higher. Redis version 6.0 or higher is recommended, as this is what ships with [Omnibus GitLab](https://docs.gitlab.com/omnibus/) packages starting with GitLab 13.9. @@ -61,7 +61,7 @@ Apart from a local hard drive you can also mount a volume that supports the netw If you have enough RAM and a recent CPU the speed of GitLab is mainly limited by hard drive seek times. Having a fast drive (7200 RPM and up) or a solid state drive (SSD) improves the responsiveness of GitLab. NOTE: -Since file system performance may affect the overall performance of GitLab, +Because file system performance may affect the overall performance of GitLab, [we don't recommend using cloud-based file systems for storage](../administration/nfs.md#avoid-using-cloud-based-file-systems). NOTE: @@ -94,6 +94,14 @@ if your available memory changes. We also recommend configuring the kernel's swa to a low value like `10` to make the most of your RAM while still having the swap available when needed. +NOTE: +Although excessive swapping is undesired and degrades performance, it is an +extremely important last resort against out-of-memory conditions. During +unexpected system load, such as OS updates or other services on the same host, +peak memory load spikes could be much higher than average. Having plenty of swap +helps avoid the Linux OOM killer unsafely terminating a potentially critical +process, such as PostgreSQL, which can have disastrous consequences. + ## Database PostgreSQL is the only supported database, which is bundled with the Omnibus GitLab package. @@ -112,7 +120,7 @@ the following table) as these were used for development and testing: | GitLab version | Minimum PostgreSQL version | |----------------|----------------------------| | 13.0 | 11 | -| 14.0 | 12.10 | +| 14.0 | 12.7 | | 15.0 | 12.10 | | 16.0 (planned) | 13.6 | @@ -125,6 +133,12 @@ GitLab database. [Read more about this requirement, and troubleshooting](postgre | `btree_gist` | 13.1 | | `plpgsql` | 11.7 | +The following managed PostgreSQL services are known to be incompatible and should not be used: + +| GitLab version | Managed service | +|----------------|-------------------------------------------------------| +| 14.4+ | Amazon Aurora (see [14.4.0](../update/index.md#1440)) | + NOTE: Support for [PostgreSQL 9.6 and 10 was removed in GitLab 13.0](https://about.gitlab.com/releases/2020/05/22/gitlab-13-0-released/#postgresql-11-is-now-the-minimum-required-version-to-install-gitlab) so that GitLab can benefit from PostgreSQL 11 improvements, such as partitioning. @@ -251,9 +265,9 @@ works. ### Puma per worker maximum memory -By default, each Puma worker will be limited to 1024 MB of memory. +By default, each Puma worker is limited to 1024 MB of memory. This setting [can be adjusted](../administration/operations/puma.md#change-the-memory-limit-setting) and should be considered -if you need to increase the number of Puma workers. +if you must increase the number of Puma workers. ## Redis and Sidekiq @@ -279,7 +293,7 @@ to install GitLab on. Depending on how you decide to configure GitLab Runner and what tools you use to exercise your application in the CI environment, GitLab Runner can consume significant amount of available memory. -Memory consumption calculations, that are available above, won't be valid if +Memory consumption calculations, that are available above, are not valid if you decide to run GitLab Runner and the GitLab Rails application on the same machine. @@ -295,7 +309,7 @@ The GitLab Runner server requirements depend on: - Resources required to run build jobs. - Job concurrency settings. -Since the nature of the jobs varies for each use case, you need to experiment by adjusting the job concurrency to get the optimum setting. +Because the nature of the jobs varies for each use case, you must experiment by adjusting the job concurrency to get the optimum setting. For reference, the [SaaS runners on Linux](../ci/runners/saas/linux_saas_runner.md) are configured so that a **single job** runs in a **single instance** with: |