Reference architecture: Up to 20 RPS or 1,000 users

Tier: Free, Premium, Ultimate Offering: Self-managed

This page describes the GitLab reference architecture designed to target a peak load of 20 requests per second (RPS), the typical peak load of up to 1,000 users, both manual and automated, based on real data.

For a full list of reference architectures, see Available reference architectures.

Users Configuration GCP AWS Azure
Up to 1,000 or 20 RPS 8 vCPU, 16 GB memory n1-standard-81 c5.2xlarge F8s v2

Footnotes:

  1. For GCP, the closest and equivalent standard machine type has been selected that matches the recommended requirement of 8 vCPU and 16 GB of RAM. A custom machine type can also be used if desired.

The diagram above shows that while GitLab can be installed on a single server, it is internally composed of multiple services. As a GitLab instance is scaled, each of these services are broken out and independently scaled according to the demands placed on them. In some cases PaaS can be leveraged for some services (for example, Cloud Object Storage for some file systems). For the sake of redundancy some of the services become clusters of nodes storing the same data. In a horizontal configuration of GitLab there are various ancillary services required to coordinate clusters or discover of resources (for example, PgBouncer for PostgreSQL connection management, Consul for Prometheus end point discovery).

Requirements

Before starting, see the requirements for reference architectures.

caution
The node’s specifications are based on high percentiles of both usage patterns and repository sizes in good health. However, if you have large monorepos (larger than several gigabytes) or additional workloads these can significantly impact the performance of the environment and further adjustments may be required. If this applies to you, we strongly recommended referring to the linked documentation as well as reaching out to your Customer Success Manager or our Support team for further guidance.

Testing methodology

The 1k architecture is designed to cover a large majority of workflows and is regularly smoke and performance tested by the Test Platform team against the following endpoint throughput targets:

  • API: 20 RPS
  • Web: 2 RPS
  • Git (Pull): 2 RPS
  • Git (Push): 1 RPS

The above targets were selected based on real customer data of total environmental loads corresponding to the user count, including CI and other workloads.

If you have metrics to suggest that you have regularly higher throughput against the above endpoint targets, large monorepos or notable additional workloads these can notably impact the performance environment and further adjustments may be required. If this applies to you, we strongly recommended referring to the linked documentation as well as reaching out to your Customer Success Manager or our Support team for further guidance.

Testing is done regularly via our GitLab Performance Tool (GPT) and its dataset, which is available for anyone to use. The results of this testing are available publicly on the GPT wiki. For more information on our testing strategy refer to this section of the documentation.

Setup instructions

To install GitLab for this default reference architecture, use the standard installation instructions.

You can also optionally configure GitLab to use an external PostgreSQL service or an external object storage service for added performance and reliability at an increased complexity cost.

Tier: Premium, Ultimate Offering: Self-managed

You can leverage Elasticsearch and enable advanced search for faster, more advanced code search across your entire GitLab instance.

Elasticsearch cluster design and requirements are dependent on your specific data. For recommended best practices about how to set up your Elasticsearch cluster alongside your instance, read how to choose the optimal cluster configuration.

Cloud Native Hybrid reference architecture with Helm Charts

Cloud Native Hybrid Reference Architecture is an alternative approach where select stateless components are deployed in Kubernetes via our official Helm Charts, and stateful components are deployed in compute VMs with the Linux package.

The 2k or 40 RPS GitLab Cloud Native Hybrid (non HA) and 3k or 60 RPS GitLab Cloud Native Hybrid (HA) reference architectures are the smallest we recommend in Kubernetes. For environments that serve fewer users or a lower RPS, you can lower the node specs. Depending on your user count, you can lower all suggested node specs as desired. However, it’s recommended that you don’t go lower than the general requirements.

Next steps

After following this guide you should now have a fresh GitLab environment with core functionality configured accordingly.

You may want to configure additional optional features of GitLab depending on your requirements. See Steps after installing GitLab for more information.

note
Depending on your environment and requirements, additional hardware requirements or adjustments may be required to set up additional features as desired. Refer to the individual pages for more information.