From 9524c64a6cb565a8eaa152ca60ca424eb4512bbc Mon Sep 17 00:00:00 2001
From: Justin Tobler <jtobler@gitlab.com>
Date: Mon, 22 May 2023 23:02:00 +0000
Subject: [PATCH] doc/praefect: Replication factor recommendations

The default replication factor replicates repositories to every storage
in the Gitaly Cluster deployment. This is problematic for large
deployments because replica repositories put additional pressure on the
primary repository during replication events.

This change updates replication factor documentation to recommend
setting the configuration explicitly instead of relying on the default
for large deployments.
---
 doc/administration/gitaly/praefect.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md
index 51201ec442fa4..745b0c02ed7a7 100644
--- a/doc/administration/gitaly/praefect.md
+++ b/doc/administration/gitaly/praefect.md
@@ -1466,7 +1466,10 @@ You can configure:
   ```
 
 If `default_replication_factor` is unset, the repositories are always replicated on every node defined in `virtual_storages`. If a new
-node is introduced to the virtual storage, both new and existing repositories are replicated to the node automatically.
+node is introduced to the virtual storage, both new and existing repositories are replicated to the node automatically. For large Gitaly
+Cluster deployments with many Gitaly nodes, replicating a repository to every storage is often not sensible and can cause problems.
+The higher the replication factor, the higher the pressure on the primary repository. You should explicitly set the default
+replication factor for large Gitaly Cluster deployments.
 
 ### Repository storage recommendations
 
-- 
GitLab