diff options
Diffstat (limited to 'doc/administration/reference_architectures')
9 files changed, 534 insertions, 171 deletions
diff --git a/doc/administration/reference_architectures/10k_users.md b/doc/administration/reference_architectures/10k_users.md index 9f522e0d599..216d3867d0a 100644 --- a/doc/administration/reference_architectures/10k_users.md +++ b/doc/administration/reference_architectures/10k_users.md @@ -2,7 +2,7 @@ reading_time: true stage: Enablement group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Reference architecture: up to 10,000 users **(PREMIUM ONLY)** @@ -24,8 +24,8 @@ full list of reference architectures, see | Internal load balancing node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | | Redis - Cache | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | | Redis - Queues / Shared State | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7 GB memory | g1-small | t2.small | B1MS | -| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7 GB memory | g1-small | t2.small | B1MS | +| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7 GB memory | g1-small | t3.small | B1MS | +| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7 GB memory | g1-small | t3.small | B1MS | | Gitaly | 2 (minimum) | 16 vCPU, 60 GB memory | n1-standard-16 | m5.4xlarge | D16s v3 | | Sidekiq | 4 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | | GitLab Rails | 3 | 32 vCPU, 28.8 GB memory | n1-highcpu-32 | c5.9xlarge | F32s v2 | @@ -33,6 +33,81 @@ full list of reference architectures, see | Object storage | n/a | n/a | n/a | n/a | n/a | | NFS server | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +```mermaid +stateDiagram-v2 + [*] --> LoadBalancer + LoadBalancer --> ApplicationServer + + ApplicationServer --> BackgroundJobs + ApplicationServer --> Gitaly + ApplicationServer --> Redis_Cache + ApplicationServer --> Redis_Queues + ApplicationServer --> PgBouncer + PgBouncer --> Database + ApplicationServer --> ObjectStorage + BackgroundJobs --> ObjectStorage + + ApplicationMonitoring -->ApplicationServer + ApplicationMonitoring -->PgBouncer + ApplicationMonitoring -->Database + ApplicationMonitoring -->BackgroundJobs + + ApplicationServer --> Consul + + Consul --> Database + Consul --> PgBouncer + Redis_Cache --> Consul + Redis_Queues --> Consul + BackgroundJobs --> Consul + + state Consul { + "Consul_1..3" + } + + state Database { + "PG_Primary_Node" + "PG_Secondary_Node_1..2" + } + + state Redis_Cache { + "R_Cache_Primary_Node" + "R_Cache_Replica_Node_1..2" + "R_Cache_Sentinel_1..3" + } + + state Redis_Queues { + "R_Queues_Primary_Node" + "R_Queues_Replica_Node_1..2" + "R_Queues_Sentinel_1..3" + } + + state Gitaly { + "Gitaly_1..2" + } + + state BackgroundJobs { + "Sidekiq_1..4" + } + + state ApplicationServer { + "GitLab_Rails_1..3" + } + + state LoadBalancer { + "LoadBalancer_1" + } + + state ApplicationMonitoring { + "Prometheus" + "Grafana" + } + + state PgBouncer { + "Internal_Load_Balancer" + "PgBouncer_1..3" + } +``` + The Google Cloud Platform (GCP) architectures were built and tested using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) CPU platform. On different hardware you may find that adjustments, either lower @@ -241,7 +316,7 @@ The following IPs will be used as an example: - `10.6.0.12`: Consul 2 - `10.6.0.13`: Consul 3 -NOTE: **Note:** +NOTE: The configuration processes for the other servers in your reference architecture will use the `/etc/gitlab/gitlab-secrets.json` file from your Consul server to connect with the other servers. @@ -962,7 +1037,7 @@ servers. The following IPs will be used as an example: - `10.6.0.72`: Sentinel - Cache 2 - `10.6.0.73`: Sentinel - Cache 3 -NOTE: **Note:** +NOTE: If you're using an external Redis Sentinel instance, be sure to exclude the `requirepass` parameter from the Sentinel configuration. This parameter causes clients to report `NOAUTH Authentication required.`. @@ -1226,7 +1301,7 @@ servers. The following IPs will be used as an example: - `10.6.0.82`: Sentinel - Queues 2 - `10.6.0.83`: Sentinel - Queues 3 -NOTE: **Note:** +NOTE: If you're using an external Redis Sentinel instance, be sure to exclude the `requirepass` parameter from the Sentinel configuration. This parameter causes clients to report `NOAUTH Authentication required.`. @@ -1347,7 +1422,7 @@ To configure the Sentinel Queues server: ## Configure Gitaly -NOTE: **Note:** +NOTE: [Gitaly Cluster](../gitaly/praefect.md) support for the Reference Architectures is being worked on as a [collaborative effort](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/1) between the Quality Engineering and Gitaly teams. When this component has been verified @@ -1356,19 +1431,17 @@ and improved designed. [Gitaly](../gitaly/index.md) server node requirements are dependent on data, specifically the number of projects and those projects' sizes. It's recommended -that a Gitaly server node stores no more than 5 TB of data. Although this -reference architecture includes a recommendation for the number of Gitaly server -nodes to use, depending on your storage requirements, you may require additional -Gitaly server nodes. +that a Gitaly server node stores no more than 5 TB of data. Depending on your +repository storage requirements, you may require additional Gitaly server nodes. Due to Gitaly having notable input and output requirements, we strongly -recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should -have a throughput of at least 8,000 input/output operations per second (IOPS) -for read operations and 2,000 IOPS for write operations. These IOPS values are -initial recommendations, and may be adjusted to greater or lesser values -depending on the scale of your environment's workload. If you're running the -environment on a Cloud provider, refer to their documentation about how to -configure IOPS correctly. +recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs +should have a throughput of at least 8,000 +input/output operations per second (IOPS) for read operations and 2,000 IOPS for +write operations. These IOPS values are initial recommendations, and may be +adjusted to greater or lesser values depending on the scale of your +environment's workload. If you're running the environment on a Cloud provider, +refer to their documentation about how to configure IOPS correctly. Be sure to note the following items: @@ -1376,14 +1449,14 @@ Be sure to note the following items: [repository storage paths](../repository_storage_paths.md). - A Gitaly server can host one or more storage paths. - A GitLab server can use one or more Gitaly server nodes. -- Gitaly addresses must be specified to be correctly resolvable for _all_ - Gitaly clients. +- Gitaly addresses must be specified to be correctly resolvable for all Gitaly + clients. - Gitaly servers must not be exposed to the public internet, as Gitaly's network traffic is unencrypted by default. The use of a firewall is highly recommended to restrict access to the Gitaly server. Another option is to [use TLS](#gitaly-tls-support). -NOTE: **Note:** +NOTE: The token referred to throughout the Gitaly documentation is an arbitrary password selected by the administrator. This token is unrelated to tokens created for the GitLab API or other similar web API tokens. @@ -1406,8 +1479,8 @@ On each node: 1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page, and _do not_ provide the `EXTERNAL_URL` value. -1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable - the network listener, and configure the token: +1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure + storage paths, enable the network listener, and to configure the token: <!-- updates to following example must also be made at @@ -1501,7 +1574,7 @@ nodes (including the Gitaly node using the certificate) and on all client nodes that communicate with it following the procedure described in [GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -NOTE: **Note:** +NOTE: The self-signed certificate must specify the address you use to access the Gitaly server. If you are addressing the Gitaly server by a hostname, you can either use the Common Name field for this, or add it as a Subject Alternative @@ -1677,7 +1750,7 @@ To configure the Sidekiq nodes, on each one: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -TIP: **Tip:** +NOTE: You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_processes.md). <div align="right"> @@ -1690,12 +1763,6 @@ You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_proces This section describes how to configure the GitLab application (Rails) component. -In our architecture, we run each GitLab Rails node using the Puma webserver, and -have its number of workers set to 90% of available CPUs, with four threads. For -nodes running Rails with other components, the worker value should be reduced -accordingly. We've determined that a worker value of 50% achieves a good balance, -but this is dependent on workload. - The following IPs will be used as an example: - `10.6.0.111`: GitLab application 1 @@ -1999,7 +2066,7 @@ on what features you intend to use: |Object storage type|Supported by consolidated configuration?| |-------------------|----------------------------------------| -| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage)|No| +| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage) | No | | [Job artifacts](../job_artifacts.md#using-object-storage) including archived job logs | Yes | | [LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage) | Yes | | [Uploads](../uploads.md#using-object-storage) | Yes | diff --git a/doc/administration/reference_architectures/1k_users.md b/doc/administration/reference_architectures/1k_users.md index 0cb7b8868c3..5b75c7ac9c4 100644 --- a/doc/administration/reference_architectures/1k_users.md +++ b/doc/administration/reference_architectures/1k_users.md @@ -1,7 +1,7 @@ --- stage: Enablement group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Reference architecture: up to 1,000 users **(CORE ONLY)** diff --git a/doc/administration/reference_architectures/25k_users.md b/doc/administration/reference_architectures/25k_users.md index b106f7bced1..c5a8c3927c0 100644 --- a/doc/administration/reference_architectures/25k_users.md +++ b/doc/administration/reference_architectures/25k_users.md @@ -2,7 +2,7 @@ reading_time: true stage: Enablement group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Reference architecture: up to 25,000 users **(PREMIUM ONLY)** @@ -24,8 +24,8 @@ full list of reference architectures, see | Internal load balancing node | 1 | 4 vCPU, 3.6GB memory | n1-highcpu-4 | c5.large | F2s v2 | | Redis - Cache | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | | Redis - Queues / Shared State | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7 GB memory | g1-small | t2.small | B1MS | -| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7 GB memory | g1-small | t2.small | B1MS | +| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7 GB memory | g1-small | t3.small | B1MS | +| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7 GB memory | g1-small | t3.small | B1MS | | Gitaly | 2 (minimum) | 32 vCPU, 120 GB memory | n1-standard-32 | m5.8xlarge | D32s v3 | | Sidekiq | 4 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | | GitLab Rails | 5 | 32 vCPU, 28.8 GB memory | n1-highcpu-32 | c5.9xlarge | F32s v2 | @@ -33,6 +33,81 @@ full list of reference architectures, see | Object storage | n/a | n/a | n/a | n/a | n/a | | NFS server | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +```mermaid +stateDiagram-v2 + [*] --> LoadBalancer + LoadBalancer --> ApplicationServer + + ApplicationServer --> BackgroundJobs + ApplicationServer --> Gitaly + ApplicationServer --> Redis_Cache + ApplicationServer --> Redis_Queues + ApplicationServer --> PgBouncer + PgBouncer --> Database + ApplicationServer --> ObjectStorage + BackgroundJobs --> ObjectStorage + + ApplicationMonitoring -->ApplicationServer + ApplicationMonitoring -->PgBouncer + ApplicationMonitoring -->Database + ApplicationMonitoring -->BackgroundJobs + + ApplicationServer --> Consul + + Consul --> Database + Consul --> PgBouncer + Redis_Cache --> Consul + Redis_Queues --> Consul + BackgroundJobs --> Consul + + state Consul { + "Consul_1..3" + } + + state Database { + "PG_Primary_Node" + "PG_Secondary_Node_1..2" + } + + state Redis_Cache { + "R_Cache_Primary_Node" + "R_Cache_Replica_Node_1..2" + "R_Cache_Sentinel_1..3" + } + + state Redis_Queues { + "R_Queues_Primary_Node" + "R_Queues_Replica_Node_1..2" + "R_Queues_Sentinel_1..3" + } + + state Gitaly { + "Gitaly_1..2" + } + + state BackgroundJobs { + "Sidekiq_1..4" + } + + state ApplicationServer { + "GitLab_Rails_1..5" + } + + state LoadBalancer { + "LoadBalancer_1" + } + + state ApplicationMonitoring { + "Prometheus" + "Grafana" + } + + state PgBouncer { + "Internal_Load_Balancer" + "PgBouncer_1..3" + } +``` + The Google Cloud Platform (GCP) architectures were built and tested using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) CPU platform. On different hardware you may find that adjustments, either lower @@ -241,7 +316,7 @@ The following IPs will be used as an example: - `10.6.0.12`: Consul 2 - `10.6.0.13`: Consul 3 -NOTE: **Note:** +NOTE: The configuration processes for the other servers in your reference architecture will use the `/etc/gitlab/gitlab-secrets.json` file from your Consul server to connect with the other servers. @@ -962,7 +1037,7 @@ servers. The following IPs will be used as an example: - `10.6.0.72`: Sentinel - Cache 2 - `10.6.0.73`: Sentinel - Cache 3 -NOTE: **Note:** +NOTE: If you're using an external Redis Sentinel instance, be sure to exclude the `requirepass` parameter from the Sentinel configuration. This parameter causes clients to report `NOAUTH Authentication required.`. @@ -1226,7 +1301,7 @@ servers. The following IPs will be used as an example: - `10.6.0.82`: Sentinel - Queues 2 - `10.6.0.83`: Sentinel - Queues 3 -NOTE: **Note:** +NOTE: If you're using an external Redis Sentinel instance, be sure to exclude the `requirepass` parameter from the Sentinel configuration. This parameter causes clients to report `NOAUTH Authentication required.`. @@ -1347,7 +1422,7 @@ To configure the Sentinel Queues server: ## Configure Gitaly -NOTE: **Note:** +NOTE: [Gitaly Cluster](../gitaly/praefect.md) support for the Reference Architectures is being worked on as a [collaborative effort](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/1) between the Quality Engineering and Gitaly teams. When this component has been verified @@ -1356,19 +1431,17 @@ and improved designed. [Gitaly](../gitaly/index.md) server node requirements are dependent on data, specifically the number of projects and those projects' sizes. It's recommended -that a Gitaly server node stores no more than 5 TB of data. Although this -reference architecture includes a recommendation for the number of Gitaly server -nodes to use, depending on your storage requirements, you may require additional -Gitaly server nodes. +that a Gitaly server node stores no more than 5 TB of data. Depending on your +repository storage requirements, you may require additional Gitaly server nodes. Due to Gitaly having notable input and output requirements, we strongly -recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should -have a throughput of at least 8,000 input/output operations per second (IOPS) -for read operations and 2,000 IOPS for write operations. These IOPS values are -initial recommendations, and may be adjusted to greater or lesser values -depending on the scale of your environment's workload. If you're running the -environment on a Cloud provider, refer to their documentation about how to -configure IOPS correctly. +recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs +should have a throughput of at least 8,000 +input/output operations per second (IOPS) for read operations and 2,000 IOPS for +write operations. These IOPS values are initial recommendations, and may be +adjusted to greater or lesser values depending on the scale of your +environment's workload. If you're running the environment on a Cloud provider, +refer to their documentation about how to configure IOPS correctly. Be sure to note the following items: @@ -1376,14 +1449,14 @@ Be sure to note the following items: [repository storage paths](../repository_storage_paths.md). - A Gitaly server can host one or more storage paths. - A GitLab server can use one or more Gitaly server nodes. -- Gitaly addresses must be specified to be correctly resolvable for _all_ - Gitaly clients. +- Gitaly addresses must be specified to be correctly resolvable for all Gitaly + clients. - Gitaly servers must not be exposed to the public internet, as Gitaly's network traffic is unencrypted by default. The use of a firewall is highly recommended to restrict access to the Gitaly server. Another option is to [use TLS](#gitaly-tls-support). -NOTE: **Note:** +NOTE: The token referred to throughout the Gitaly documentation is an arbitrary password selected by the administrator. This token is unrelated to tokens created for the GitLab API or other similar web API tokens. @@ -1406,8 +1479,8 @@ On each node: 1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page, and _do not_ provide the `EXTERNAL_URL` value. -1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable - the network listener, and configure the token: +1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure + storage paths, enable the network listener, and to configure the token: <!-- updates to following example must also be made at @@ -1501,7 +1574,7 @@ nodes (including the Gitaly node using the certificate) and on all client nodes that communicate with it following the procedure described in [GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -NOTE: **Note:** +NOTE: The self-signed certificate must specify the address you use to access the Gitaly server. If you are addressing the Gitaly server by a hostname, you can either use the Common Name field for this, or add it as a Subject Alternative @@ -1677,7 +1750,7 @@ To configure the Sidekiq nodes, on each one: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -TIP: **Tip:** +NOTE: You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_processes.md). <div align="right"> @@ -1690,12 +1763,6 @@ You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_proces This section describes how to configure the GitLab application (Rails) component. -In our architecture, we run each GitLab Rails node using the Puma webserver, and -have its number of workers set to 90% of available CPUs, with four threads. For -nodes running Rails with other components, the worker value should be reduced -accordingly. We've determined that a worker value of 50% achieves a good balance, -but this is dependent on workload. - The following IPs will be used as an example: - `10.6.0.111`: GitLab application 1 @@ -1999,7 +2066,7 @@ on what features you intend to use: |Object storage type|Supported by consolidated configuration?| |-------------------|----------------------------------------| -| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage)|No| +| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage) | No | | [Job artifacts](../job_artifacts.md#using-object-storage) including archived job logs | Yes | | [LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage) | Yes | | [Uploads](../uploads.md#using-object-storage) | Yes | diff --git a/doc/administration/reference_architectures/2k_users.md b/doc/administration/reference_architectures/2k_users.md index f4842a8568b..c341ff5baec 100644 --- a/doc/administration/reference_architectures/2k_users.md +++ b/doc/administration/reference_architectures/2k_users.md @@ -2,7 +2,7 @@ reading_time: true stage: Enablement group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Reference architecture: up to 2,000 users **(CORE ONLY)** @@ -26,6 +26,46 @@ For a full list of reference architectures, see | Object storage | n/a | n/a | n/a | n/a | n/a | | NFS server (optional, not recommended) | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +```mermaid +stateDiagram-v2 + [*] --> LoadBalancer + LoadBalancer --> ApplicationServer + + ApplicationServer --> Gitaly + ApplicationServer --> Redis + ApplicationServer --> Database + ApplicationServer --> ObjectStorage + + ApplicationMonitoring -->ApplicationServer + ApplicationMonitoring -->Redis + ApplicationMonitoring -->Database + + + state Database { + "PG_Node" + } + state Redis { + "Redis_Node" + } + + state Gitaly { + "Gitaly" + } + + state ApplicationServer { + "AppServ_1..2" + } + + state LoadBalancer { + "LoadBalancer" + } + + state ApplicationMonitoring { + "Prometheus" + "Grafana" + } +``` + The Google Cloud Platform (GCP) architectures were built and tested using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) CPU platform. On different hardware you may find that adjustments, either lower @@ -356,7 +396,7 @@ are supported and can be added if needed. ## Configure Gitaly -NOTE: **Note:** +NOTE: [Gitaly Cluster](../gitaly/praefect.md) support for the Reference Architectures is being worked on as a [collaborative effort](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/1) between the Quality Engineering and Gitaly teams. When this component has been verified @@ -391,7 +431,7 @@ Be sure to note the following items: to restrict access to the Gitaly server. Another option is to [use TLS](#gitaly-tls-support). -NOTE: **Note:** +NOTE: The token referred to throughout the Gitaly documentation is an arbitrary password selected by the administrator. This token is unrelated to tokens created for the GitLab API or other similar web API tokens. @@ -485,7 +525,7 @@ nodes (including the Gitaly node using the certificate) and on all client nodes that communicate with it following the procedure described in [GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -NOTE: **Note:** +NOTE: The self-signed certificate must specify the address you use to access the Gitaly server. If you are addressing the Gitaly server by a hostname, you can either use the Common Name field for this, or add it as a Subject Alternative @@ -858,7 +898,7 @@ on what features you intend to use: |Object storage type|Supported by consolidated configuration?| |-------------------|----------------------------------------| -| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage)|No| +| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage) | No | | [Job artifacts](../job_artifacts.md#using-object-storage) including archived job logs | Yes | | [LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage) | Yes | | [Uploads](../uploads.md#using-object-storage) | Yes | diff --git a/doc/administration/reference_architectures/3k_users.md b/doc/administration/reference_architectures/3k_users.md index b5b3e4e0300..370247ed856 100644 --- a/doc/administration/reference_architectures/3k_users.md +++ b/doc/administration/reference_architectures/3k_users.md @@ -2,7 +2,7 @@ reading_time: true stage: Enablement group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Reference architecture: up to 3,000 users **(PREMIUM ONLY)** @@ -11,7 +11,7 @@ This page describes GitLab reference architecture for up to 3,000 users. For a full list of reference architectures, see [Available reference architectures](index.md#available-reference-architectures). -NOTE: **Note:** +NOTE: This reference architecture is designed to help your organization achieve a highly-available GitLab deployment. If you do not have the expertise or need to maintain a highly-available environment, you can have a simpler and less @@ -37,6 +37,62 @@ costly-to-operate environment by using the | Object storage | n/a | n/a | n/a | n/a | n/a | | NFS server (optional, not recommended) | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +```mermaid +stateDiagram-v2 + [*] --> LoadBalancer + LoadBalancer --> ApplicationServer + + ApplicationServer --> BackgroundJobs + ApplicationServer --> Gitaly + ApplicationServer --> Redis + ApplicationServer --> PgBouncer + PgBouncer --> Database + ApplicationServer --> ObjectStorage + BackgroundJobs --> ObjectStorage + + ApplicationMonitoring -->ApplicationServer + ApplicationMonitoring -->Redis + ApplicationMonitoring -->PgBouncer + ApplicationMonitoring -->Database + ApplicationMonitoring -->BackgroundJobs + + state Database { + "PG_Primary_Node" + "PG_Secondary_Node_1..2" + } + state Redis { + "R_Primary_Node" + "R_Replica_Node_1..2" + "R_Consul/Sentinel_1..3" + } + + state Gitaly { + "Gitaly_1..2" + } + + state BackgroundJobs { + "Sidekiq_1..4" + } + + state ApplicationServer { + "GitLab_Rails_1..3" + } + + state LoadBalancer { + "LoadBalancer_1" + } + + state ApplicationMonitoring { + "Prometheus" + "Grafana" + } + + state PgBouncer { + "Internal_Load_Balancer" + "PgBouncer_1..3" + } +``` + The Google Cloud Platform (GCP) architectures were built and tested using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) CPU platform. On different hardware you may find that adjustments, either lower @@ -444,7 +500,7 @@ servers. The following IPs will be used as an example: - `10.6.0.12`: Consul/Sentinel 2 - `10.6.0.13`: Consul/Sentinel 3 -NOTE: **Note:** +NOTE: If you're using an external Redis Sentinel instance, be sure to exclude the `requirepass` parameter from the Sentinel configuration. This parameter causes clients to report `NOAUTH Authentication required.`. @@ -1058,7 +1114,7 @@ Refer to your preferred Load Balancer's documentation for further guidance. ## Configure Gitaly -NOTE: **Note:** +NOTE: [Gitaly Cluster](../gitaly/praefect.md) support for the Reference Architectures is being worked on as a [collaborative effort](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/1) between the Quality Engineering and Gitaly teams. When this component has been verified @@ -1067,19 +1123,17 @@ and improved designed. [Gitaly](../gitaly/index.md) server node requirements are dependent on data, specifically the number of projects and those projects' sizes. It's recommended -that a Gitaly server node stores no more than 5 TB of data. Although this -reference architecture includes a recommendation for the number of Gitaly server -nodes to use, depending on your storage requirements, you may require additional -Gitaly server nodes. +that a Gitaly server node stores no more than 5 TB of data. Depending on your +repository storage requirements, you may require additional Gitaly server nodes. Due to Gitaly having notable input and output requirements, we strongly -recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should -have a throughput of at least 8,000 input/output operations per second (IOPS) -for read operations and 2,000 IOPS for write operations. These IOPS values are -initial recommendations, and may be adjusted to greater or lesser values -depending on the scale of your environment's workload. If you're running the -environment on a Cloud provider, refer to their documentation about how to -configure IOPS correctly. +recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs +should have a throughput of at least 8,000 +input/output operations per second (IOPS) for read operations and 2,000 IOPS for +write operations. These IOPS values are initial recommendations, and may be +adjusted to greater or lesser values depending on the scale of your +environment's workload. If you're running the environment on a Cloud provider, +refer to their documentation about how to configure IOPS correctly. Be sure to note the following items: @@ -1087,14 +1141,14 @@ Be sure to note the following items: [repository storage paths](../repository_storage_paths.md). - A Gitaly server can host one or more storage paths. - A GitLab server can use one or more Gitaly server nodes. -- Gitaly addresses must be specified to be correctly resolvable for _all_ - Gitaly clients. +- Gitaly addresses must be specified to be correctly resolvable for all Gitaly + clients. - Gitaly servers must not be exposed to the public internet, as Gitaly's network traffic is unencrypted by default. The use of a firewall is highly recommended to restrict access to the Gitaly server. Another option is to [use TLS](#gitaly-tls-support). -NOTE: **Note:** +NOTE: The token referred to throughout the Gitaly documentation is an arbitrary password selected by the administrator. This token is unrelated to tokens created for the GitLab API or other similar web API tokens. @@ -1117,8 +1171,8 @@ On each node: 1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page, and _do not_ provide the `EXTERNAL_URL` value. -1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable - the network listener, and configure the token: +1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure + storage paths, enable the network listener, and to configure the token: <!-- updates to following example must also be made at @@ -1244,7 +1298,7 @@ nodes (including the Gitaly node using the certificate) and on all client nodes that communicate with it following the procedure described in [GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -NOTE: **Note:** +NOTE: The self-signed certificate must specify the address you use to access the Gitaly server. If you are addressing the Gitaly server by a hostname, you can either use the Common Name field for this, or add it as a Subject Alternative @@ -1412,7 +1466,7 @@ To configure the Sidekiq nodes, one each one: run: sidekiq: (pid 30142) 77351s; run: log: (pid 29638) 77386s ``` -TIP: **Tip:** +NOTE: You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_processes.md). <div align="right"> @@ -1425,12 +1479,6 @@ You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_proces This section describes how to configure the GitLab application (Rails) component. -In our architecture, we run each GitLab Rails node using the Puma webserver, and -have its number of workers set to 90% of available CPUs, with four threads. For -nodes running Rails with other components, the worker value should be reduced -accordingly. We've determined that a worker value of 50% achieves a good balance, -but this is dependent on workload. - On each node perform the following: 1. If you're [using NFS](#configure-nfs-optional): @@ -1734,7 +1782,7 @@ on what features you intend to use: |Object storage type|Supported by consolidated configuration?| |-------------------|----------------------------------------| -| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage)|No| +| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage) | No | | [Job artifacts](../job_artifacts.md#using-object-storage) including archived job logs | Yes | | [LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage) | Yes | | [Uploads](../uploads.md#using-object-storage) | Yes | diff --git a/doc/administration/reference_architectures/50k_users.md b/doc/administration/reference_architectures/50k_users.md index 152eb9cb90d..f76c8a8a877 100644 --- a/doc/administration/reference_architectures/50k_users.md +++ b/doc/administration/reference_architectures/50k_users.md @@ -2,7 +2,7 @@ reading_time: true stage: Enablement group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Reference architecture: up to 50,000 users **(PREMIUM ONLY)** @@ -24,8 +24,8 @@ full list of reference architectures, see | Internal load balancing node | 1 | 8 vCPU, 7.2 GB memory | n1-highcpu-8 | c5.2xlarge | F8s v2 | | Redis - Cache | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | | Redis - Queues / Shared State | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7 GB memory | g1-small | t2.small | B1MS | -| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7 GB memory | g1-small | t2.small | B1MS | +| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7 GB memory | g1-small | t3.small | B1MS | +| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7 GB memory | g1-small | t3.small | B1MS | | Gitaly | 2 (minimum) | 64 vCPU, 240 GB memory | n1-standard-64 | m5.16xlarge | D64s v3 | | Sidekiq | 4 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | | GitLab Rails | 12 | 32 vCPU, 28.8 GB memory | n1-highcpu-32 | c5.9xlarge | F32s v2 | @@ -33,6 +33,81 @@ full list of reference architectures, see | Object storage | n/a | n/a | n/a | n/a | n/a | | NFS server | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +```mermaid +stateDiagram-v2 + [*] --> LoadBalancer + LoadBalancer --> ApplicationServer + + ApplicationServer --> BackgroundJobs + ApplicationServer --> Gitaly + ApplicationServer --> Redis_Cache + ApplicationServer --> Redis_Queues + ApplicationServer --> PgBouncer + PgBouncer --> Database + ApplicationServer --> ObjectStorage + BackgroundJobs --> ObjectStorage + + ApplicationMonitoring -->ApplicationServer + ApplicationMonitoring -->PgBouncer + ApplicationMonitoring -->Database + ApplicationMonitoring -->BackgroundJobs + + ApplicationServer --> Consul + + Consul --> Database + Consul --> PgBouncer + Redis_Cache --> Consul + Redis_Queues --> Consul + BackgroundJobs --> Consul + + state Consul { + "Consul_1..3" + } + + state Database { + "PG_Primary_Node" + "PG_Secondary_Node_1..2" + } + + state Redis_Cache { + "R_Cache_Primary_Node" + "R_Cache_Replica_Node_1..2" + "R_Cache_Sentinel_1..3" + } + + state Redis_Queues { + "R_Queues_Primary_Node" + "R_Queues_Replica_Node_1..2" + "R_Queues_Sentinel_1..3" + } + + state Gitaly { + "Gitaly_1..2" + } + + state BackgroundJobs { + "Sidekiq_1..4" + } + + state ApplicationServer { + "GitLab_Rails_1..12" + } + + state LoadBalancer { + "LoadBalancer_1" + } + + state ApplicationMonitoring { + "Prometheus" + "Grafana" + } + + state PgBouncer { + "Internal_Load_Balancer" + "PgBouncer_1..3" + } +``` + The Google Cloud Platform (GCP) architectures were built and tested using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) CPU platform. On different hardware you may find that adjustments, either lower @@ -241,7 +316,7 @@ The following IPs will be used as an example: - `10.6.0.12`: Consul 2 - `10.6.0.13`: Consul 3 -NOTE: **Note:** +NOTE: The configuration processes for the other servers in your reference architecture will use the `/etc/gitlab/gitlab-secrets.json` file from your Consul server to connect with the other servers. @@ -962,7 +1037,7 @@ servers. The following IPs will be used as an example: - `10.6.0.72`: Sentinel - Cache 2 - `10.6.0.73`: Sentinel - Cache 3 -NOTE: **Note:** +NOTE: If you're using an external Redis Sentinel instance, be sure to exclude the `requirepass` parameter from the Sentinel configuration. This parameter causes clients to report `NOAUTH Authentication required.`. @@ -1226,7 +1301,7 @@ servers. The following IPs will be used as an example: - `10.6.0.82`: Sentinel - Queues 2 - `10.6.0.83`: Sentinel - Queues 3 -NOTE: **Note:** +NOTE: If you're using an external Redis Sentinel instance, be sure to exclude the `requirepass` parameter from the Sentinel configuration. This parameter causes clients to report `NOAUTH Authentication required.`. @@ -1347,7 +1422,7 @@ To configure the Sentinel Queues server: ## Configure Gitaly -NOTE: **Note:** +NOTE: [Gitaly Cluster](../gitaly/praefect.md) support for the Reference Architectures is being worked on as a [collaborative effort](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/1) between the Quality Engineering and Gitaly teams. When this component has been verified @@ -1356,19 +1431,17 @@ and improved designed. [Gitaly](../gitaly/index.md) server node requirements are dependent on data, specifically the number of projects and those projects' sizes. It's recommended -that a Gitaly server node stores no more than 5 TB of data. Although this -reference architecture includes a recommendation for the number of Gitaly server -nodes to use, depending on your storage requirements, you may require additional -Gitaly server nodes. +that a Gitaly server node stores no more than 5 TB of data. Depending on your +repository storage requirements, you may require additional Gitaly server nodes. Due to Gitaly having notable input and output requirements, we strongly -recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should -have a throughput of at least 8,000 input/output operations per second (IOPS) -for read operations and 2,000 IOPS for write operations. These IOPS values are -initial recommendations, and may be adjusted to greater or lesser values -depending on the scale of your environment's workload. If you're running the -environment on a Cloud provider, refer to their documentation about how to -configure IOPS correctly. +recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs +should have a throughput of at least 8,000 +input/output operations per second (IOPS) for read operations and 2,000 IOPS for +write operations. These IOPS values are initial recommendations, and may be +adjusted to greater or lesser values depending on the scale of your +environment's workload. If you're running the environment on a Cloud provider, +refer to their documentation about how to configure IOPS correctly. Be sure to note the following items: @@ -1376,14 +1449,14 @@ Be sure to note the following items: [repository storage paths](../repository_storage_paths.md). - A Gitaly server can host one or more storage paths. - A GitLab server can use one or more Gitaly server nodes. -- Gitaly addresses must be specified to be correctly resolvable for _all_ - Gitaly clients. +- Gitaly addresses must be specified to be correctly resolvable for all Gitaly + clients. - Gitaly servers must not be exposed to the public internet, as Gitaly's network traffic is unencrypted by default. The use of a firewall is highly recommended to restrict access to the Gitaly server. Another option is to [use TLS](#gitaly-tls-support). -NOTE: **Note:** +NOTE: The token referred to throughout the Gitaly documentation is an arbitrary password selected by the administrator. This token is unrelated to tokens created for the GitLab API or other similar web API tokens. @@ -1406,8 +1479,8 @@ On each node: 1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page, and _do not_ provide the `EXTERNAL_URL` value. -1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable - the network listener, and configure the token: +1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure + storage paths, enable the network listener, and to configure the token: <!-- updates to following example must also be made at @@ -1501,7 +1574,7 @@ nodes (including the Gitaly node using the certificate) and on all client nodes that communicate with it following the procedure described in [GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -NOTE: **Note:** +NOTE: The self-signed certificate must specify the address you use to access the Gitaly server. If you are addressing the Gitaly server by a hostname, you can either use the Common Name field for this, or add it as a Subject Alternative @@ -1677,7 +1750,7 @@ To configure the Sidekiq nodes, on each one: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -TIP: **Tip:** +NOTE: You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_processes.md). <div align="right"> @@ -1690,12 +1763,6 @@ You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_proces This section describes how to configure the GitLab application (Rails) component. -In our architecture, we run each GitLab Rails node using the Puma webserver, and -have its number of workers set to 90% of available CPUs, with four threads. For -nodes running Rails with other components, the worker value should be reduced -accordingly. We've determined that a worker value of 50% achieves a good balance, -but this is dependent on workload. - The following IPs will be used as an example: - `10.6.0.111`: GitLab application 1 @@ -1999,7 +2066,7 @@ on what features you intend to use: |Object storage type|Supported by consolidated configuration?| |-------------------|----------------------------------------| -| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage)|No| +| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage) | No | | [Job artifacts](../job_artifacts.md#using-object-storage) including archived job logs | Yes | | [LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage) | Yes | | [Uploads](../uploads.md#using-object-storage) | Yes | diff --git a/doc/administration/reference_architectures/5k_users.md b/doc/administration/reference_architectures/5k_users.md index f023971bdc0..6a0547aeaf9 100644 --- a/doc/administration/reference_architectures/5k_users.md +++ b/doc/administration/reference_architectures/5k_users.md @@ -2,7 +2,7 @@ reading_time: true stage: Enablement group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Reference architecture: up to 5,000 users **(PREMIUM ONLY)** @@ -11,7 +11,7 @@ This page describes GitLab reference architecture for up to 5,000 users. For a full list of reference architectures, see [Available reference architectures](index.md#available-reference-architectures). -NOTE: **Note:** +NOTE: This reference architecture is designed to help your organization achieve a highly-available GitLab deployment. If you do not have the expertise or need to maintain a highly-available environment, you can have a simpler and less @@ -37,6 +37,63 @@ costly-to-operate environment by using the | Object storage | n/a | n/a | n/a | n/a | n/a | | NFS server (optional, not recommended) | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +```mermaid +stateDiagram-v2 + [*] --> LoadBalancer + LoadBalancer --> ApplicationServer + + ApplicationServer --> BackgroundJobs + ApplicationServer --> Gitaly + ApplicationServer --> Redis + ApplicationServer --> PgBouncer + PgBouncer --> Database + ApplicationServer --> ObjectStorage + BackgroundJobs --> ObjectStorage + + ApplicationMonitoring -->ApplicationServer + ApplicationMonitoring -->Redis + ApplicationMonitoring -->PgBouncer + ApplicationMonitoring -->Database + ApplicationMonitoring -->BackgroundJobs + + state Database { + "PG_Primary_Node" + "PG_Secondary_Node_1..2" + } + + state Redis { + "R_Primary_Node" + "R_Replica_Node_1..2" + "R_Consul/Sentinel_1..3" + } + + state Gitaly { + "Gitaly_1..2" + } + + state BackgroundJobs { + "Sidekiq_1..4" + } + + state ApplicationServer { + "GitLab_Rails_1..3" + } + + state LoadBalancer { + "LoadBalancer_1" + } + + state ApplicationMonitoring { + "Prometheus" + "Grafana" + } + + state PgBouncer { + "Internal_Load_Balancer" + "PgBouncer_1..3" + } +``` + The Google Cloud Platform (GCP) architectures were built and tested using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) CPU platform. On different hardware you may find that adjustments, either lower @@ -444,7 +501,7 @@ servers. The following IPs will be used as an example: - `10.6.0.12`: Consul/Sentinel 2 - `10.6.0.13`: Consul/Sentinel 3 -NOTE: **Note:** +NOTE: If you're using an external Redis Sentinel instance, be sure to exclude the `requirepass` parameter from the Sentinel configuration. This parameter causes clients to report `NOAUTH Authentication required.`. @@ -1057,7 +1114,7 @@ Refer to your preferred Load Balancer's documentation for further guidance. ## Configure Gitaly -NOTE: **Note:** +NOTE: [Gitaly Cluster](../gitaly/praefect.md) support for the Reference Architectures is being worked on as a [collaborative effort](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/1) between the Quality Engineering and Gitaly teams. When this component has been verified @@ -1066,19 +1123,17 @@ and improved designed. [Gitaly](../gitaly/index.md) server node requirements are dependent on data, specifically the number of projects and those projects' sizes. It's recommended -that a Gitaly server node stores no more than 5 TB of data. Although this -reference architecture includes a recommendation for the number of Gitaly server -nodes to use, depending on your storage requirements, you may require additional -Gitaly server nodes. +that a Gitaly server node stores no more than 5 TB of data. Depending on your +repository storage requirements, you may require additional Gitaly server nodes. Due to Gitaly having notable input and output requirements, we strongly -recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should -have a throughput of at least 8,000 input/output operations per second (IOPS) -for read operations and 2,000 IOPS for write operations. These IOPS values are -initial recommendations, and may be adjusted to greater or lesser values -depending on the scale of your environment's workload. If you're running the -environment on a Cloud provider, refer to their documentation about how to -configure IOPS correctly. +recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs +should have a throughput of at least 8,000 +input/output operations per second (IOPS) for read operations and 2,000 IOPS for +write operations. These IOPS values are initial recommendations, and may be +adjusted to greater or lesser values depending on the scale of your +environment's workload. If you're running the environment on a Cloud provider, +refer to their documentation about how to configure IOPS correctly. Be sure to note the following items: @@ -1086,14 +1141,14 @@ Be sure to note the following items: [repository storage paths](../repository_storage_paths.md). - A Gitaly server can host one or more storage paths. - A GitLab server can use one or more Gitaly server nodes. -- Gitaly addresses must be specified to be correctly resolvable for _all_ - Gitaly clients. +- Gitaly addresses must be specified to be correctly resolvable for all Gitaly + clients. - Gitaly servers must not be exposed to the public internet, as Gitaly's network traffic is unencrypted by default. The use of a firewall is highly recommended to restrict access to the Gitaly server. Another option is to [use TLS](#gitaly-tls-support). -NOTE: **Note:** +NOTE: The token referred to throughout the Gitaly documentation is an arbitrary password selected by the administrator. This token is unrelated to tokens created for the GitLab API or other similar web API tokens. @@ -1116,8 +1171,8 @@ On each node: 1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page, and _do not_ provide the `EXTERNAL_URL` value. -1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable - the network listener, and configure the token: +1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure + storage paths, enable the network listener, and to configure the token: <!-- updates to following example must also be made at @@ -1243,7 +1298,7 @@ nodes (including the Gitaly node using the certificate) and on all client nodes that communicate with it following the procedure described in [GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -NOTE: **Note:** +NOTE: The self-signed certificate must specify the address you use to access the Gitaly server. If you are addressing the Gitaly server by a hostname, you can either use the Common Name field for this, or add it as a Subject Alternative @@ -1411,7 +1466,7 @@ To configure the Sidekiq nodes, one each one: run: sidekiq: (pid 30142) 77351s; run: log: (pid 29638) 77386s ``` -TIP: **Tip:** +NOTE: You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_processes.md). <div align="right"> @@ -1424,12 +1479,6 @@ You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_proces This section describes how to configure the GitLab application (Rails) component. -In our architecture, we run each GitLab Rails node using the Puma webserver, and -have its number of workers set to 90% of available CPUs, with four threads. For -nodes running Rails with other components, the worker value should be reduced -accordingly. We've determined that a worker value of 50% achieves a good balance, -but this is dependent on workload. - On each node perform the following: 1. If you're [using NFS](#configure-nfs-optional): @@ -1733,7 +1782,7 @@ on what features you intend to use: |Object storage type|Supported by consolidated configuration?| |-------------------|----------------------------------------| -| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage)|No| +| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage) | No | | [Job artifacts](../job_artifacts.md#using-object-storage) including archived job logs | Yes | | [LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage) | Yes | | [Uploads](../uploads.md#using-object-storage) | Yes | diff --git a/doc/administration/reference_architectures/index.md b/doc/administration/reference_architectures/index.md index 8816d0eecf4..6b04dad9baf 100644 --- a/doc/administration/reference_architectures/index.md +++ b/doc/administration/reference_architectures/index.md @@ -2,14 +2,14 @@ type: reference, concepts stage: Enablement group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Reference architectures You can set up GitLab on a single server or scale it up to serve many users. This page details the recommended Reference Architectures that were built and -verified by GitLab's Quality and Support teams. +verified by the GitLab Quality and Support teams. Below is a chart representing each architecture tier and the number of users they can handle. As your number of users grow with time, it’s recommended that @@ -18,8 +18,8 @@ you scale GitLab accordingly.  <!-- Internal link: https://docs.google.com/spreadsheets/d/1obYP4fLKkVVDOljaI3-ozhmCiPtEeMblbBKkf2OADKs/edit#gid=1403207183 --> -Testing on these reference architectures were performed with -[GitLab's Performance Tool](https://gitlab.com/gitlab-org/quality/performance) +Testing on these reference architectures was performed with the +[GitLab Performance Tool](https://gitlab.com/gitlab-org/quality/performance) at specific coded workloads, and the throughputs used for testing were calculated based on sample customer data. Select the [reference architecture](#available-reference-architectures) that matches your scale. @@ -36,8 +36,8 @@ the [default setup](#automated-backups) by [installing GitLab](../../install/README.md) on a single machine to minimize maintenance and resource costs. -If your organization has more than 2,000 users, the recommendation is to scale -GitLab's components to multiple machine nodes. The machine nodes are grouped by +If your organization has more than 2,000 users, the recommendation is to scale the +GitLab components to multiple machine nodes. The machine nodes are grouped by components. The addition of these nodes increases the performance and scalability of to your GitLab instance. @@ -47,7 +47,7 @@ When scaling GitLab, there are several factors to consider: - A load balancer is added in front to distribute traffic across the application nodes. - The application nodes connects to a shared file server and PostgreSQL and Redis services on the backend. -NOTE: **Note:** +NOTE: Depending on your workflow, the following recommended reference architectures may need to be adapted accordingly. Your workload is influenced by factors including how active your users are, how much automation you use, mirroring, @@ -68,6 +68,11 @@ The following reference architectures are available: - [Up to 25,000 users](25k_users.md) - [Up to 50,000 users](50k_users.md) +A GitLab [Premium or Ultimate](https://about.gitlab.com/pricing/#self-managed) license is required +to get assistance from Support with troubleshooting the [2,000 users](2k_users.md) +and higher reference architectures. +[Read more about our definition of scaled architectures](https://about.gitlab.com/support/#definition-of-scaled-architecture). + ## Availability Components GitLab comes with the following components for your use, listed from least to @@ -151,7 +156,27 @@ is recommended. instance to other geographical locations as a read-only fully operational instance that can also be promoted in case of disaster. -## Configuring select components with Cloud Native Helm +## Deviating from the suggested reference architectures + +As a general rule of thumb, the further away you move from the Reference Architectures, +the harder it will be get support for it. With any deviation, you're introducing +a layer of complexity that will add challenges to finding out where potential +issues might lie. + +The reference architectures use the official GitLab Linux packages (Omnibus +GitLab) to install and configure the various components (with one notable exception being the suggested select Cloud Native installation method described below). The components are +installed on separate machines (virtualized or bare metal), with machine hardware +requirements listed in the "Configuration" column and equivalent VM standard sizes listed +in GCP/AWS/Azure columns of each [available reference architecture](#available-reference-architectures). + +Running components on Docker (including Compose) with the same specs should be fine, as Docker is well known in terms of support. +However, it is still an additional layer and may still add some support complexities, such as not being able to run `strace` easily in containers. + +Other technologies, like [Docker swarm](https://docs.docker.com/engine/swarm/) +are not officially supported, but can be implemented at your own risk. In that +case, GitLab Support will not be able to help you. + +### Configuring select components with Cloud Native Helm We also provide [Helm charts](https://docs.gitlab.com/charts/) as a Cloud Native installation method for GitLab. For the reference architectures, select components can be set up in this diff --git a/doc/administration/reference_architectures/troubleshooting.md b/doc/administration/reference_architectures/troubleshooting.md index db2e9b89ba2..406ff57c66d 100644 --- a/doc/administration/reference_architectures/troubleshooting.md +++ b/doc/administration/reference_architectures/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Enablement group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Troubleshooting a reference architecture setup @@ -434,13 +434,13 @@ If the monitoring node is not receiving any data, check that the exporters are capturing data. ```shell -curl http[s]://localhost:<EXPORTER LISTENING PORT>/metric +curl "http[s]://localhost:<EXPORTER LISTENING PORT>/metric" ``` or ```shell -curl http[s]://localhost:<EXPORTER LISTENING PORT>/-/metric +curl "http[s]://localhost:<EXPORTER LISTENING PORT>/-/metric" ``` ## Troubleshooting PgBouncer |