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

This reference architecture targets a peak load of 20 requests per second (RPS). Based on real data, this load typically corresponds to up to 1,000 users, which includes both manual and automated interactions.

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

• Target Load: API: 20 RPS, Web: 2 RPS, Git (Pull): 2 RPS, Git (Push): 1 RPS
• High Availability: No. For a high availability environment, follow a modified 3K reference architecture.
• Cost calculator template: For more information, see cost calculator templates.
• Cloud Native Hybrid: No. For a cloud native hybrid environment, you can follow a modified hybrid reference architecture.
• Unsure which Reference Architecture to use? For more information, see deciding which architecture to start with.

Footnotes:

1. Machine type examples are given for illustration purposes. These types are used in validation and testing but are not intended as prescriptive defaults. Switching to other machine types that meet the requirements as listed is supported, including ARM variants if available. See Supported machine types for more information.
2. 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 following diagram shows that while GitLab can be installed on a single server, it is internally composed of multiple services. When an instance scales, these services are separated and independently scaled according to their specific demands.

In some cases, you can leverage PaaS for some services. For example, you can use Cloud Object Storage for some file systems. For the sake of redundancy, some services become clusters of nodes and store the same data.

In a horizontally scaled GitLab configuration, various ancillary services are required to coordinate clusters or discover resources. For example, PgBouncer for PostgreSQL connection management, or Consul for Prometheus end point discovery.

@startuml 1k
card "**Prometheus**" as monitor #7FFFD4
package "GitLab Single Server" as gitlab-single-server {
together {
  card "**GitLab Rails**" as gitlab #32CD32
  card "**Gitaly**" as gitaly #FF8C00
  card "**PostgreSQL**" as postgres #4EA7FF
  card "**Redis**" as redis #FF6347
  card "**Sidekiq**" as sidekiq #ff8dd1
}
card "Local Storage" as local_storage #white
}

gitlab -[#32CD32]--> gitaly
gitlab -[#32CD32]--> postgres
gitlab -[#32CD32]--> redis
gitlab -[#32CD32]--> sidekiq
gitaly -[#32CD32]--> local_storage
postgres -[#32CD32]--> local_storage
sidekiq -[#32CD32]--> local_storage
gitlab -[#32CD32]--> local_storage

monitor .[#7FFFD4]u-> gitlab
monitor .[#7FFFD4]u-> sidekiq
monitor .[#7FFFD4]-> postgres
monitor .[#7FFFD4]-> gitaly
monitor .[#7FFFD4,norank]--> redis

@enduml

Requirements

Before proceeding, review the requirements for the reference architectures.

Testing methodology

The 20 RPS / 1k user reference architecture is designed to accommodate most common workflows. The Framework team regularly conducts smoke and performance testing against the following endpoint throughput targets:

These targets are based on actual customer data reflecting total environmental loads for the specified user count, including CI pipelines and other workloads.

Performance considerations

You may need additional adjustments if your environment has:

• Consistently higher throughput than the listed targets
• Large monorepos
• Significant additional workloads

In these cases, refer to scaling an environment for more information. If you believe these considerations may apply to you, contact us for additional guidance as required.

Testing tools and results

We use the GitLab Performance Tool (GPT) for testing, which includes a publicly available dataset. You can view detailed test results on the GPT wiki. For more information about our testing methodology, see the validation and test results section.

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 external object storage service. It improves performance and reliability, but at an increased complexity cost.

Configure advanced search

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

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

Cloud Native Hybrid reference architecture with Helm Charts

In the Cloud Native Hybrid reference architecture setup, the select stateless components are deployed in Kubernetes by using our official Helm Charts. The stateful components are deployed in compute VMs with the Linux package.

The smallest reference architecture available for use in Kubernetes is the 2k or 40 RPS GitLab Cloud Native Hybrid (non HA) and 3k or 60 RPS GitLab Cloud Native Hybrid (HA).

For environments that serve fewer users or a lower RPS, you can lower the node specification. Depending on your user count, you can lower all suggested node specifications as desired. However, you should not go lower than the general requirements.

Next steps

Now you have a fresh GitLab environment with core functionality configured accordingly. You might want to configure additional optional GitLab features depending on your requirements. See Steps after installing GitLab for more information.