diff --git a/doc/administration/reference_architectures/10k_users.md b/doc/administration/reference_architectures/10k_users.md index 4c547858b2530cf5c48596265bf67230a79ab760..2e208c4eca1fd68a8f28ecc25e9728984d822b23 100644 --- a/doc/administration/reference_architectures/10k_users.md +++ b/doc/administration/reference_architectures/10k_users.md @@ -28,7 +28,7 @@ full list of reference architectures, see | Internal load balancing node3 | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Redis/Sentinel - Cache2 | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | | Redis/Sentinel - Persistent2 | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | -| Gitaly5 6 | 3 | 16 vCPU, 60 GB memory | `n1-standard-16` | `m5.4xlarge` | +| Gitaly5 | 3 | 16 vCPU, 60 GB memory6 | `n1-standard-16` | `m5.4xlarge` | | Praefect5 | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Praefect PostgreSQL1 | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Sidekiq7 | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | @@ -43,10 +43,10 @@ full list of reference architectures, see - Redis is primarily single threaded. It's strongly recommended separating out the instances as specified into Cache and Persistent data to achieve optimum performance at this scale. 3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. 4. Should be run on reputable Cloud Provider or Self Managed solutions. See [Configure the object storage](#configure-the-object-storage) for more information. -5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. -6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large - repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to - [Large repositories](index.md#large-repositories) for more information. +5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. + Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. +6. Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health. + However, if you have [large monorepos](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#additional-workloads) these can *significantly* impact Git and Gitaly performance and further adjustments will likely be required. 7. Can be placed in Auto Scaling Groups (ASGs) as the component doesn't store any [stateful data](index.md#autoscaling-of-stateful-nodes). However, for GitLab Rails certain processes like [migrations](#gitlab-rails-post-configuration) and [Mailroom](../incoming_email.md) should be run on only one node. @@ -1155,6 +1155,11 @@ are supported and can be added if needed. repositories. In this configuration, every Git repository is stored on every Gitaly node in the cluster, with one being designated the primary, and failover occurs automatically if the primary node goes down. +WARNING: +**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.** +**However, if you have [large monorepos](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#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](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance. + Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). @@ -1165,12 +1170,6 @@ For guidance on: - Migrating existing repositories that aren't managed by Gitaly Cluster, see [migrate to Gitaly Cluster](../gitaly/index.md#migrate-to-gitaly-cluster). -NOTE: -Gitaly has been designed and tested with repositories of varying sizes that follow best practices. -However, large repositories or monorepos not following these practices can significantly -impact Gitaly performance and requirements. -Refer to [Large repositories](index.md#large-repositories) for more information. - The recommended cluster setup includes the following components: - 3 Gitaly nodes: Replicated storage of Git repositories. @@ -1495,16 +1494,10 @@ Updates to example must be made at: The [Gitaly](../gitaly/index.md) server nodes that make up the cluster have requirements that are dependent on data and load. -NOTE: -Increased specs for Gitaly nodes may be required in some circumstances such as -significantly large repositories or if any [additional workloads](index.md#additional-workloads), -such as [server hooks](../server_hooks.md), have been added. - -NOTE: -Gitaly has been designed and tested with repositories of varying sizes that follow best practices. -However, large repositories or monorepos not following these practices can significantly -impact Gitaly performance and requirements. -Refer to [large repositories](index.md#large-repositories) for more information. +WARNING: +**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.** +**However, if you have [large monorepos](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#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](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance. Due to Gitaly having notable input and output requirements, we strongly recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs @@ -2231,7 +2224,7 @@ to be complex. **This setup is only recommended** if you have strong working knowledge and experience in Kubernetes. The rest of this section assumes this. -NOTE: +WARNING: **Gitaly Cluster is not supported to be run in Kubernetes**. Refer to [epic 6127](https://gitlab.com/groups/gitlab-org/-/epics/6127) for more details. @@ -2265,7 +2258,7 @@ services where applicable): | Internal load balancing node3 | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Redis/Sentinel - Cache2 | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | | Redis/Sentinel - Persistent2 | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | -| Gitaly5 6 | 3 | 16 vCPU, 60 GB memory | `n1-standard-16` | `m5.4xlarge` | +| Gitaly5 | 3 | 16 vCPU, 60 GB memory6 | `n1-standard-16` | `m5.4xlarge` | | Praefect5 | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Praefect PostgreSQL1 | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Object storage4 | - | - | - | - | @@ -2277,10 +2270,10 @@ services where applicable): - Redis is primarily single threaded. It's strongly recommended separating out the instances as specified into Cache and Persistent data to achieve optimum performance at this scale. 3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. 4. Should be run on reputable Cloud Provider or Self Managed solutions. See [Configure the object storage](#configure-the-object-storage) for more information. -5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. -6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large - repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to - [Large repositories](index.md#large-repositories) for more information. +5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. + Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. +6. Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health. + However, if you have [large monorepos](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#additional-workloads) these can *significantly* impact Git and Gitaly performance and further adjustments will likely be required. NOTE: diff --git a/doc/administration/reference_architectures/1k_users.md b/doc/administration/reference_architectures/1k_users.md index 87a99173223b91dd94a89e4a8ce2f4a34f7e698f..2f7c8209a4464f2ed7661c1d571b279a4b7a31ff 100644 --- a/doc/administration/reference_architectures/1k_users.md +++ b/doc/administration/reference_architectures/1k_users.md @@ -28,7 +28,6 @@ many organizations. | Users | Configuration | GCP | AWS | Azure | |--------------|-------------------------|----------------|--------------|----------| -| Up to 500 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | | Up to 1,000 | 8 vCPU, 7.2 GB memory | `n1-highcpu-8` | `c5.2xlarge` | `F8s v2` | ```plantuml @@ -69,6 +68,11 @@ The diagram above shows that while GitLab can be installed on a single server, i Before starting, see the [requirements](index.md#requirements) for reference architectures. +WARNING: +**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](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#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](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance. + ## Setup instructions To install GitLab for this default reference architecture, use the standard diff --git a/doc/administration/reference_architectures/25k_users.md b/doc/administration/reference_architectures/25k_users.md index 5ac7ed330b9ba4e5462b5d7d55334d94965269de..355fe45cc2f08b46a684e8bdbd25c53bbb6750cf 100644 --- a/doc/administration/reference_architectures/25k_users.md +++ b/doc/administration/reference_architectures/25k_users.md @@ -28,7 +28,7 @@ full list of reference architectures, see | Internal load balancing node3 | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | | Redis/Sentinel - Cache2 | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | | Redis/Sentinel - Persistent2 | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | -| Gitaly5 6 | 3 | 32 vCPU, 120 GB memory | `n1-standard-32` | `m5.8xlarge` | +| Gitaly5 | 3 | 32 vCPU, 120 GB memory6 | `n1-standard-32` | `m5.8xlarge` | | Praefect5 | 3 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | | Praefect PostgreSQL1 | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Sidekiq7 | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | @@ -43,10 +43,10 @@ full list of reference architectures, see - Redis is primarily single threaded. It's strongly recommended separating out the instances as specified into Cache and Persistent data to achieve optimum performance at this scale. 3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. 4. Should be run on reputable Cloud Provider or Self Managed solutions. See [Configure the object storage](#configure-the-object-storage) for more information. -5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. -6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large - repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to - [Large repositories](index.md#large-repositories) for more information. +5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. + Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. +6. Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health. + However, if you have [large monorepos](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#additional-workloads) these can *significantly* impact Git and Gitaly performance and further adjustments will likely be required. 7. Can be placed in Auto Scaling Groups (ASGs) as the component doesn't store any [stateful data](index.md#autoscaling-of-stateful-nodes). However, for GitLab Rails certain processes like [migrations](#gitlab-rails-post-configuration) and [Mailroom](../incoming_email.md) should be run on only one node. @@ -1174,6 +1174,11 @@ are supported and can be added if needed. repositories. In this configuration, every Git repository is stored on every Gitaly node in the cluster, with one being designated the primary, and failover occurs automatically if the primary node goes down. +WARNING: +**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.** +**However, if you have [large monorepos](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#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](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance. + Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). @@ -1184,12 +1189,6 @@ For guidance on: - Migrating existing repositories that aren't managed by Gitaly Cluster, see [migrate to Gitaly Cluster](../gitaly/index.md#migrate-to-gitaly-cluster). -NOTE: -Gitaly has been designed and tested with repositories of varying sizes that follow best practices. -However, large repositories or monorepos not following these practices can significantly -impact Gitaly performance and requirements. -Refer to [Large repositories](index.md#large-repositories) for more information. - The recommended cluster setup includes the following components: - 3 Gitaly nodes: Replicated storage of Git repositories. @@ -1512,16 +1511,10 @@ the file of the same name on this server. If this is the first Linux package nod The [Gitaly](../gitaly/index.md) server nodes that make up the cluster have requirements that are dependent on data and load. -NOTE: -Increased specs for Gitaly nodes may be required in some circumstances such as -significantly large repositories or if any [additional workloads](index.md#additional-workloads), -such as [server hooks](../server_hooks.md), have been added. - -NOTE: -Gitaly has been designed and tested with repositories of varying sizes that follow best practices. -However, large repositories or monorepos not following these practices can significantly -impact Gitaly performance and requirements. -Refer to [Large repositories](index.md#large-repositories) for more information. +WARNING: +**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.** +**However, if you have [large monorepos](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#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](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance. Due to Gitaly having notable input and output requirements, we strongly recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs @@ -2250,7 +2243,7 @@ to be complex. **This setup is only recommended** if you have strong working knowledge and experience in Kubernetes. The rest of this section assumes this. -NOTE: +WARNING: **Gitaly Cluster is not supported to be run in Kubernetes**. Refer to [epic 6127](https://gitlab.com/groups/gitlab-org/-/epics/6127) for more details. @@ -2284,7 +2277,7 @@ services where applicable): | Internal load balancing node3 | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | | Redis/Sentinel - Cache2 | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | | Redis/Sentinel - Persistent2 | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | -| Gitaly5 6 | 3 | 32 vCPU, 120 GB memory | `n1-standard-32` | `m5.8xlarge` | +| Gitaly5 | 3 | 32 vCPU, 120 GB memory6 | `n1-standard-32` | `m5.8xlarge` | | Praefect5 | 3 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | | Praefect PostgreSQL1 | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Object storage4 | - | - | - | - | @@ -2296,10 +2289,10 @@ services where applicable): - Redis is primarily single threaded. It's strongly recommended separating out the instances as specified into Cache and Persistent data to achieve optimum performance at this scale. 3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. 4. Should be run on reputable Cloud Provider or Self Managed solutions. See [Configure the object storage](#configure-the-object-storage) for more information. -5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. -6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large - repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to - [Large repositories](index.md#large-repositories) for more information. +5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. + Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. +6. Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health. + However, if you have [large monorepos](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#additional-workloads) these can *significantly* impact Git and Gitaly performance and further adjustments will likely be required. NOTE: diff --git a/doc/administration/reference_architectures/2k_users.md b/doc/administration/reference_architectures/2k_users.md index b3c57ffefa480e0542bc735b26f2c617374b5c2e..9ad9e027c819918349d53ca784b34d00bda3f860 100644 --- a/doc/administration/reference_architectures/2k_users.md +++ b/doc/administration/reference_architectures/2k_users.md @@ -25,7 +25,7 @@ For a full list of reference architectures, see | Load balancer3 | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | | PostgreSQL1 | 1 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | `D2s v3` | | Redis2 | 1 | 1 vCPU, 3.75 GB memory | `n1-standard-1` | `m5.large` | `D2s v3` | -| Gitaly5 | 1 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | +| Gitaly | 1 | 4 vCPU, 15 GB memory5 | `n1-standard-4` | `m5.xlarge` | `D4s v3` | | GitLab Rails6 | 2 | 8 vCPU, 7.2 GB memory | `n1-highcpu-8` | `c5.2xlarge` | `F8s v2` | | Monitoring node | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | | Object storage4 | - | - | - | - | - | @@ -36,9 +36,9 @@ For a full list of reference architectures, see 3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. 4. Should be run on reputable Cloud Provider or Self Managed solutions. See [Configure the object storage](#configure-the-object-storage) for more information. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. -5. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large - repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to - [Large repositories](index.md#large-repositories) for more information. +5. Gitaly specifications are based on the use of normal-sized repositories in good health. + However, if you have large monorepos (larger than several gigabytes) this can **significantly** impact Git and Gitaly performance and an increase of specifications will likely be required. + Refer to [large monorepos](index.md#large-monorepos) for more information. 6. Can be placed in Auto Scaling Groups (ASGs) as the component doesn't store any [stateful data](index.md#autoscaling-of-stateful-nodes). However, for GitLab Rails certain processes like [migrations](#gitlab-rails-post-configuration) and [Mailroom](../incoming_email.md) should be run on only one node. @@ -393,16 +393,10 @@ are supported and can be added if needed. [Gitaly](../gitaly/index.md) server node requirements are dependent on data size, specifically the number of projects and those projects' sizes. -NOTE: -Increased specs for Gitaly nodes may be required in some circumstances such as -significantly large repositories or if any [additional workloads](index.md#additional-workloads), -such as [server hooks](../server_hooks.md), have been added. - -NOTE: -Gitaly has been designed and tested with repositories of varying sizes that follow best practices. -However, large repositories or monorepos not following these practices can significantly -impact Gitaly performance and requirements. -Refer to [Large repositories](index.md#large-repositories) for more information. +WARNING: +**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.** +**However, if you have [large monorepos](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#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](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance. Due to Gitaly having notable input and output requirements, we strongly recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs @@ -945,7 +939,7 @@ NOTE: The 2,000 reference architecture is not a highly-available setup. To achieve HA, you can follow a modified [3K reference architecture](3k_users.md#cloud-native-hybrid-reference-architecture-with-helm-charts-alternative). -NOTE: +WARNING: **Gitaly Cluster is not supported to be run in Kubernetes**. Refer to [epic 6127](https://gitlab.com/groups/gitlab-org/-/epics/6127) for more details. diff --git a/doc/administration/reference_architectures/3k_users.md b/doc/administration/reference_architectures/3k_users.md index 19f6fbd222eb9184b9e3176b1d7a1f087e39057b..3d2907ef9fadcf89af8786d660fefbaa116da33e 100644 --- a/doc/administration/reference_architectures/3k_users.md +++ b/doc/administration/reference_architectures/3k_users.md @@ -37,7 +37,7 @@ For a full list of reference architectures, see | PostgreSQL1 | 3 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | | PgBouncer1 | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Internal load balancing node3 | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | -| Gitaly5 6 | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| Gitaly5 | 3 | 4 vCPU, 15 GB memory6 | `n1-standard-4` | `m5.xlarge` | | Praefect5 | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Praefect PostgreSQL1 | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Sidekiq7 | 4 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | @@ -51,10 +51,10 @@ For a full list of reference architectures, see 2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Provide your own Redis instance](#provide-your-own-redis-instance) for more information. 3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. 4. Should be run on reputable Cloud Provider or Self Managed solutions. See [Configure the object storage](#configure-the-object-storage) for more information. -5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. -6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large - repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to - [Large repositories](index.md#large-repositories) for more information. +5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. + Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. +6. Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health. + However, if you have [large monorepos](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#additional-workloads) these can *significantly* impact Git and Gitaly performance and further adjustments will likely be required. 7. Can be placed in Auto Scaling Groups (ASGs) as the component doesn't store any [stateful data](index.md#autoscaling-of-stateful-nodes). However, for GitLab Rails certain processes like [migrations](#gitlab-rails-post-configuration) and [Mailroom](../incoming_email.md) should be run on only one node. @@ -1101,6 +1101,11 @@ The following IPs will be used as an example: repositories. In this configuration, every Git repository is stored on every Gitaly node in the cluster, with one being designated the primary, and failover occurs automatically if the primary node goes down. +WARNING: +**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.** +**However, if you have [large monorepos](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#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](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance. + Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). @@ -1111,12 +1116,6 @@ For guidance on: - Migrating existing repositories that aren't managed by Gitaly Cluster, see [migrate to Gitaly Cluster](../gitaly/index.md#migrate-to-gitaly-cluster). -NOTE: -Gitaly has been designed and tested with repositories of varying sizes that follow best practices. -However, large repositories or monorepos not following these practices can significantly -impact Gitaly performance and requirements. -Refer to [Large repositories](index.md#large-repositories) for more information. - The recommended cluster setup includes the following components: - 3 Gitaly nodes: Replicated storage of Git repositories. @@ -1438,16 +1437,10 @@ the file of the same name on this server. If this is the first Linux package nod The [Gitaly](../gitaly/index.md) server nodes that make up the cluster have requirements that are dependent on data and load. -NOTE: -Increased specs for Gitaly nodes may be required in some circumstances such as -significantly large repositories or if any [additional workloads](index.md#additional-workloads), -such as [server hooks](../server_hooks.md), have been added. - -NOTE: -Gitaly has been designed and tested with repositories of varying sizes that follow best practices. -However, large repositories or monorepos not following these practices can significantly -impact Gitaly performance and requirements. -Refer to the [Large repositories](index.md#large-repositories) for more information. +WARNING: +**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.** +**However, if you have [large monorepos](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#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](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance. Due to Gitaly having notable input and output requirements, we strongly recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs @@ -2237,7 +2230,7 @@ to be complex. **This setup is only recommended** if you have strong working knowledge and experience in Kubernetes. The rest of this section assumes this. -NOTE: +WARNING: **Gitaly Cluster is not supported to be run in Kubernetes**. Refer to [epic 6127](https://gitlab.com/groups/gitlab-org/-/epics/6127) for more details. @@ -2270,7 +2263,7 @@ services where applicable): | PostgreSQL1 | 3 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | | PgBouncer1 | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Internal load balancing node3 | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | -| Gitaly5 6 | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| Gitaly5 | 3 | 4 vCPU, 15 GB memory6 | `n1-standard-4` | `m5.xlarge` | | Praefect5 | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Praefect PostgreSQL1 | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Object storage4 | - | - | - | - | @@ -2281,10 +2274,10 @@ services where applicable): 2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Provide your own Redis instance](#provide-your-own-redis-instance) for more information. 3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. 4. Should be run on reputable Cloud Provider or Self Managed solutions. See [Configure the object storage](#configure-the-object-storage) for more information. -5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. -6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large - repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to - [Large repositories](index.md#large-repositories) for more information. +5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. + Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. +6. Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health. + However, if you have [large monorepos](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#additional-workloads) these can *significantly* impact Git and Gitaly performance and further adjustments will likely be required. NOTE: diff --git a/doc/administration/reference_architectures/50k_users.md b/doc/administration/reference_architectures/50k_users.md index 644bfbd04f95aef71c8e43bf09938f81a7b94fff..72ddd347856903e900645624efa640b24fd6290f 100644 --- a/doc/administration/reference_architectures/50k_users.md +++ b/doc/administration/reference_architectures/50k_users.md @@ -28,7 +28,7 @@ full list of reference architectures, see | Internal load balancing node3 | 1 | 8 vCPU, 7.2 GB memory | `n1-highcpu-8` | `c5.2xlarge` | | Redis/Sentinel - Cache2 | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | | Redis/Sentinel - Persistent2 | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | -| Gitaly5 6 | 3 | 64 vCPU, 240 GB memory | `n1-standard-64` | `m5.16xlarge` | +| Gitaly5 | 3 | 64 vCPU, 240 GB memory6 | `n1-standard-64` | `m5.16xlarge` | | Praefect5 | 3 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | | Praefect PostgreSQL1 | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Sidekiq7 | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | @@ -43,10 +43,10 @@ full list of reference architectures, see - Redis is primarily single threaded. It's strongly recommended separating out the instances as specified into Cache and Persistent data to achieve optimum performance at this scale. 3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. 4. Should be run on reputable Cloud Provider or Self Managed solutions. See [Configure the object storage](#configure-the-object-storage) for more information. -5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. -6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large - repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to - [Large repositories](index.md#large-repositories) for more information. +5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. + Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. +6. Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health. + However, if you have [large monorepos](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#additional-workloads) these can *significantly* impact Git and Gitaly performance and further adjustments will likely be required. 7. Can be placed in Auto Scaling Groups (ASGs) as the component doesn't store any [stateful data](index.md#autoscaling-of-stateful-nodes). However, for GitLab Rails certain processes like [migrations](#gitlab-rails-post-configuration) and [Mailroom](../incoming_email.md) should be run on only one node. @@ -1168,6 +1168,11 @@ Advanced [configuration options](https://docs.gitlab.com/omnibus/settings/redis. repositories. In this configuration, every Git repository is stored on every Gitaly node in the cluster, with one being designated the primary, and failover occurs automatically if the primary node goes down. +WARNING: +**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.** +**However, if you have [large monorepos](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#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](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance. + Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). @@ -1178,12 +1183,6 @@ For guidance on: - Migrating existing repositories that aren't managed by Gitaly Cluster, see [migrate to Gitaly Cluster](../gitaly/index.md#migrate-to-gitaly-cluster). -NOTE: -Gitaly has been designed and tested with repositories of varying sizes that follow best practices. -However, large repositories or monorepos not following these practices can significantly -impact Gitaly performance and requirements. -Refer to [Large repositories](index.md#large-repositories) for more information. - The recommended cluster setup includes the following components: - 3 Gitaly nodes: Replicated storage of Git repositories. @@ -1508,16 +1507,10 @@ the file of the same name on this server. If this is the first Linux package nod The [Gitaly](../gitaly/index.md) server nodes that make up the cluster have requirements that are dependent on data and load. -NOTE: -Increased specs for Gitaly nodes may be required in some circumstances such as -significantly large repositories or if any [additional workloads](index.md#additional-workloads), -such as [server hooks](../server_hooks.md), have been added. - -NOTE: -Gitaly has been designed and tested with repositories of varying sizes that follow best practices. -However, large repositories or monorepos not following these practices can significantly -impact Gitaly performance and requirements. -Refer to [Large repositories](index.md#large-repositories) for more information. +WARNING: +**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.** +**However, if you have [large monorepos](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#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](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance. Due to Gitaly having notable input and output requirements, we strongly recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs @@ -2249,7 +2242,7 @@ to be complex. **This setup is only recommended** if you have strong working knowledge and experience in Kubernetes. The rest of this section assumes this. -NOTE: +WARNING: **Gitaly Cluster is not supported to be run in Kubernetes**. Refer to [epic 6127](https://gitlab.com/groups/gitlab-org/-/epics/6127) for more details. @@ -2283,7 +2276,7 @@ services where applicable): | Internal load balancing node3 | 1 | 8 vCPU, 7.2 GB memory | `n1-highcpu-8` | `c5.2xlarge` | | Redis/Sentinel - Cache2 | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | | Redis/Sentinel - Persistent2 | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | -| Gitaly5 6 | 3 | 64 vCPU, 240 GB memory | `n1-standard-64` | `m5.16xlarge` | +| Gitaly5 | 3 | 64 vCPU, 240 GB memory6 | `n1-standard-64` | `m5.16xlarge` | | Praefect5 | 3 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | | Praefect PostgreSQL1 | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Object storage4 | - | - | - | - | @@ -2295,10 +2288,10 @@ services where applicable): - Redis is primarily single threaded. It's strongly recommended separating out the instances as specified into Cache and Persistent data to achieve optimum performance at this scale. 3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. 4. Should be run on reputable Cloud Provider or Self Managed solutions. See [Configure the object storage](#configure-the-object-storage) for more information. -5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. -6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large - repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to - [Large repositories](index.md#large-repositories) for more information. +5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. + Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. +6. Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health. + However, if you have [large monorepos](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#additional-workloads) these can *significantly* impact Git and Gitaly performance and further adjustments will likely be required. NOTE: diff --git a/doc/administration/reference_architectures/5k_users.md b/doc/administration/reference_architectures/5k_users.md index f011f0832f0dacd201accc4f98882e8c56f97a08..dc9cfdbe7b2893496781bfc4dbe63095adb517bd 100644 --- a/doc/administration/reference_architectures/5k_users.md +++ b/doc/administration/reference_architectures/5k_users.md @@ -34,7 +34,7 @@ costly-to-operate environment by using the | PostgreSQL1 | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | | PgBouncer1 | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Internal load balancing node3 | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | -| Gitaly5 6 | 3 | 8 vCPU, 30 GB memory | `n1-standard-8` | `m5.2xlarge` | +| Gitaly5 | 3 | 8 vCPU, 30 GB memory6 | `n1-standard-8` | `m5.2xlarge` | | Praefect5 | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Praefect PostgreSQL1 | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Sidekiq7 | 4 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | @@ -48,10 +48,10 @@ costly-to-operate environment by using the 2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Provide your own Redis instance](#provide-your-own-redis-instance) for more information. 3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. 4. Should be run on reputable Cloud Provider or Self Managed solutions. See [Configure the object storage](#configure-the-object-storage) for more information. -5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. -6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large - repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to - [Large repositories](index.md#large-repositories) for more information. +5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. + Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. +6. Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health. + However, if you have [large monorepos](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#additional-workloads) these can *significantly* impact Git and Gitaly performance and further adjustments will likely be required. 7. Can be placed in Auto Scaling Groups (ASGs) as the component doesn't store any [stateful data](index.md#autoscaling-of-stateful-nodes). However, for GitLab Rails certain processes like [migrations](#gitlab-rails-post-configuration) and [Mailroom](../incoming_email.md) should be run on only one node. @@ -1094,6 +1094,11 @@ The following IPs are used as an example: repositories. In this configuration, every Git repository is stored on every Gitaly node in the cluster, with one being designated the primary, and failover occurs automatically if the primary node goes down. +WARNING: +**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.** +**However, if you have [large monorepos](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#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](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance. + Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). @@ -1104,12 +1109,6 @@ For guidance on: - Migrating existing repositories that aren't managed by Gitaly Cluster, see [migrate to Gitaly Cluster](../gitaly/index.md#migrate-to-gitaly-cluster). -NOTE: -Gitaly has been designed and tested with repositories of varying sizes that follow best practices. -However, large repositories or monorepos not following these practices can significantly -impact Gitaly performance and requirements. -Refer to [Large repositories](index.md#large-repositories) for more information. - The recommended cluster setup includes the following components: - 3 Gitaly nodes: Replicated storage of Git repositories. @@ -1432,16 +1431,10 @@ the file of the same name on this server. If this is the first Linux package nod The [Gitaly](../gitaly/index.md) server nodes that make up the cluster have requirements that are dependent on data and load. -NOTE: -Increased specs for Gitaly nodes may be required in some circumstances such as -significantly large repositories or if any [additional workloads](index.md#additional-workloads), -such as [server hooks](../server_hooks.md), have been added. - -NOTE: -Gitaly has been designed and tested with repositories of varying sizes that follow best practices. -However, large repositories or monorepos not following these practices can significantly -impact Gitaly performance and requirements. -Refer to [Large repositories](index.md#large-repositories) for more information. +WARNING: +**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.** +**However, if you have [large monorepos](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#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](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance. Due to Gitaly having notable input and output requirements, we strongly recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs @@ -2205,7 +2198,7 @@ to be complex. **This setup is only recommended** if you have strong working knowledge and experience in Kubernetes. The rest of this section assumes this. -NOTE: +WARNING: **Gitaly Cluster is not supported to be run in Kubernetes**. Refer to [epic 6127](https://gitlab.com/groups/gitlab-org/-/epics/6127) for more details. @@ -2238,7 +2231,7 @@ services where applicable): | PostgreSQL1 | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | | PgBouncer1 | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Internal load balancing node3 | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | -| Gitaly5 6 | 3 | 8 vCPU, 30 GB memory | `n1-standard-8` | `m5.2xlarge` | +| Gitaly5 | 3 | 8 vCPU, 30 GB memory6 | `n1-standard-8` | `m5.2xlarge` | | Praefect5 | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Praefect PostgreSQL1 | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | | Object storage4 | - | - | - | - | @@ -2249,10 +2242,10 @@ services where applicable): 2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Provide your own Redis instance](#provide-your-own-redis-instance) for more information. 3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. 4. Should be run on reputable Cloud Provider or Self Managed solutions. See [Configure the object storage](#configure-the-object-storage) for more information. -5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. -6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large - repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to - [Large repositories](index.md#large-repositories) for more information. +5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. + Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. +6. Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health. + However, if you have [large monorepos](index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](index.md#additional-workloads) these can *significantly* impact Git and Gitaly performance and further adjustments will likely be required. NOTE: diff --git a/doc/administration/reference_architectures/index.md b/doc/administration/reference_architectures/index.md index d75f11e22dac734e64f74145723c494717a9861f..3793aeb72a4f0029b1867052c90fb44473772b16 100644 --- a/doc/administration/reference_architectures/index.md +++ b/doc/administration/reference_architectures/index.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Reference architectures **(FREE SELF)** The GitLab Reference Architectures have been designed and tested by the -GitLab Quality and Support teams to provide recommended deployments at scale. +GitLab Quality Engineering and Support teams to provide recommended deployments at scale. ## Available reference architectures @@ -51,6 +51,8 @@ Running any application in production is complex, and the same applies for GitLa As such, it's recommended that you have a working knowledge of running and maintaining applications in production when deciding on going down this route. If you aren't in this position, our [Professional Services](https://about.gitlab.com/services/#implementation-services) team offers implementation services, but for those who want a more managed solution long term, it's recommended to instead explore our other offerings such as [GitLab SaaS](../../subscriptions/gitlab_com/index.md) or [GitLab Dedicated](../../subscriptions/gitlab_dedicated/index.md). +If Self Managed is the approach you're considering, it's strongly encouraged to read through this page in full, in particular the [Deciding which architecture to use](#deciding-which-architecture-to-use), [Large monorepos](#large-monorepos) and [Additional workloads](#additional-workloads) sections. + ## Deciding which architecture to use The Reference Architectures are designed to strike a balance between two important factors--performance and resilience. @@ -122,6 +124,13 @@ a key requirement for your environment. You must also make additional decisions on how each site is configured, such as if each secondary site would be the same architecture as the primary, or if each site is configured for HA. +### Large monorepos / Additional workloads + +If you have any [large monorepos](#large-monorepos) or significant [additional workloads](#additional-workloads), these can affect the performance of the environment notably and adjustments may be required depending on the context. + +If either applies to you, it's encouraged for you to reach out to your [Customer Success Manager](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) +for further guidance. + ### Cloud provider services For all the previously described strategies, you can run select GitLab components on equivalent cloud provider services such as the PostgreSQL database or Redis. @@ -157,12 +166,17 @@ graph TD L2B --> L3A L3A -->|Yes| L4A L3A -->|No| L4D - - L5A("Do you need cross regional distribution or disaster recovery?") --> |Yes| L6A>Additional Recommendation

GitLab Geo] - L4A -.- L5A - L4B -.- L5A - L4C -.- L5A - L4D -.- L5A + L5A("Do you need cross regional distribution
or disaster recovery?") --> |Yes| L6A>Additional Recommendation

GitLab Geo] + L4A ~~~ L5A + L4B ~~~ L5A + L4C ~~~ L5A + L4D ~~~ L5A + + L5B("Do you have Large Monorepos or expect
to have substantial additional workloads?") --> |Yes| L6B>Additional Recommendation

Contact Customer Success Manager or Support] + L4A ~~~ L5B + L4B ~~~ L5B + L4C ~~~ L5B + L4D ~~~ L5B classDef default fill:#FCA326 linkStyle default fill:none,stroke:#7759C2 @@ -196,6 +210,24 @@ However, this does not constitute a guarantee for every potential permutation. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. +### Large Monorepos + +The reference architectures were tested with repositories of varying sizes that follow best practices. + +**However, [large monorepos](../../user/project/repository/managing_large_repositories.md) (several gigabytes or more) can significantly impact the performance of Git and in turn the environment itself.** +Their presence, as well as how they are used, can put a significant strain on the entire system from Gitaly through to the underlying infrastructure. + +WARNING: +If this applies to you, we strongly recommended referring to the linked documentation as well as reaching out to your [Customer Success Manager](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance. + +As such, large monorepos come with notable cost. If you have such a repository we strongly recommend +the following guidance is followed to ensure the best chance of good performance and to keep costs in check: + +- [Optimize the Large Monorepo](../../user/project/repository/managing_large_repositories.md#optimizing-large-repositories-for-gitlab). Using features such as [LFS](../../user/project/repository/managing_large_repositories.md#using-lfs-for-large-blobs) to not store binaries, and other approaches for reducing repository size, can dramatically improve performance and reduce costs. +- Depending on the monorepo, increased environment specifications may be required to compensate. Gitaly in particular will likely require additional resources along with Praefect, GitLab Rails, and Load Balancers. This depends notably on the monorepo itself and the usage against it. +- When the monorepo is significantly large (20 gigabytes or more) further additional strategies maybe required such as even further increased specifications or in some cases a separate Gitaly backend for the monorepo alone. +- Network and disk bandwidth is another potential consideration with large monorepos. In very heavy cases, it's possible to see bandwidth saturation if there's a high amount of concurrent clones (such as with CI). It's strongly recommended [reducing full clones wherever possible](../../user/project/repository/managing_large_repositories.md#reduce-concurrent-clones-in-cicd) in this scenario. Otherwise, additional environment specifications may be required to increase bandwidth, but this differs between cloud providers. + ### Additional workloads These reference architectures have been [designed and tested](index.md#validation-and-test-results) for standard GitLab @@ -212,39 +244,14 @@ You may need to adjust the suggested specifications to compensate if you use, fo - [System hooks](../system_hooks.md). As a general rule, you should have robust monitoring in place to measure the impact of any additional workloads to -inform any changes needed to be made. +inform any changes needed to be made. It's also strongly encouraged for you to reach out to your [Customer Success Manager](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) +for further guidance. ### No swap Swap is not recommended in the reference architectures. It's a failsafe that impacts performance greatly. The reference architectures are designed to have memory headroom to avoid needing swap. -### Large repositories - -The relevant reference architectures were tested with repositories of varying sizes that follow best practices. - -However, large repositories or monorepos (several gigabytes or more) can **significantly** impact the performance -of Git and in turn the environment itself if best practices aren't being followed such as not storing binary or blob -files in LFS. - -Repositories are at the core of any environment and the consequences can be wide-ranging when they are not optimized. -Some examples of this impact include: - -- [Git packing operations](https://git-scm.com/book/en/v2/Git-Internals-Packfiles) taking longer and consuming high CPU - and memory resources. -- Git checkouts taking longer that affect both users and CI/CD pipelines alike. - -As such, large repositories come with notable cost and typically require more resources to handle, (significantly more -in some cases). You should review large repositories to ensure they maintain good health and reduce their size wherever -possible. - -NOTE: -If best practices aren't followed and large repositories are present on the environment, increased Gitaly specs may be -required to ensure stable performance. - -Refer to the [Managing large repositories documentation](../../user/project/repository/managing_large_repositories.md) -for more information and guidance. - ### Praefect PostgreSQL [Praefect requires its own database server](../gitaly/praefect.md#postgresql) and diff --git a/doc/user/project/repository/managing_large_repositories.md b/doc/user/project/repository/managing_large_repositories.md index 1d5127b5e08ee8b9f41df1a9dca4461cced4c582..397913305040c1d837661c7e6f50386a35b5fdad 100644 --- a/doc/user/project/repository/managing_large_repositories.md +++ b/doc/user/project/repository/managing_large_repositories.md @@ -25,6 +25,8 @@ Large repositories pose a performance risk performance when used in GitLab, espe Git itself has performance limitations when it comes to handling monorepos. +Monorepos can also impact notably on hardware, in some cases hitting limitations such as vertical scaling and network or disk bandwidth limits. + [Gitaly](https://gitlab.com/gitlab-org/gitaly) is our Git storage service built on top of [Git](https://git-scm.com/). This means that any limitations of Git are experienced in Gitaly, and in turn by end users of GitLab. @@ -393,7 +395,7 @@ and does not require us to update each `.gitlab-ci.yml`. ### Reference architectures -Large repositories tend to be found in larger organisations with many users. The GitLab Quality and Support teams provide several [reference architectures](../../../administration/reference_architectures/index.md) that are the recommended way to deploy GitLab at scale. +Large repositories tend to be found in larger organisations with many users. The GitLab Quality Engineering and Support teams provide several [reference architectures](../../../administration/reference_architectures/index.md) that are the recommended way to deploy GitLab at scale. In these types of setups, the GitLab environment used should match a reference architecture to improve performance.