Merge branch 'jc-update-praefect-docs-setup' into 'master'

Update praefect git_data_dirs setup

Closes gitaly#2111

See merge request gitlab-org/gitlab!19040

doc/administration/gitaly/praefect.md

@@ -50,10 +50,9 @@ In their own machine, configure the Gitaly server as described in the
 
 #### Praefect
 
-Next, Praefect has to be enabled on its own node. Disable all other services,
-and add each Gitaly node that will be connected to Praefect. In the example below,
-the Gitaly nodes are named `praefect-git-X`. Note that one node is designated as
-primary, by setting the primary to `true`:
+Next, Praefect has to be enabled on its own node.
+
+##### Disable other services
 
 ```ruby
 # /etc/gitlab/gitlab.rb
@@ -67,27 +66,36 @@ unicorn['enable'] = false
 sidekiq['enable'] = false
 gitlab_workhorse['enable'] = false
 gitaly['enable'] = false
+```
+
+##### Set up Praefect and its Gitaly nodes
+
+In the example below, the Gitaly nodes are named `praefect-git-X`. Note that one node is designated as
+primary, by setting the primary to `true`:
+
+```ruby
+# /etc/gitlab/gitlab.rb
 
 # virtual_storage_name must match the same storage name given to praefect in git_data_dirs
 praefect['virtual_storage_name'] = 'praefect'
-praefect['auth_token'] = 'super_secret_abc'
+praefect['auth_token'] = 'abc123secret'
 praefect['enable'] = true
 praefect['storage_nodes'] = [
   {
     'storage' => 'praefect-git-1',
     'address' => 'tcp://praefect-git-1.internal',
-    'token'   => 'token1',
+    'token'   => 'xyz123secret',
     'primary' => true
   },
   {
     'storage' => 'praefect-git-2',
     'address' => 'tcp://praefect-git-2.internal',
-    'token'   => 'token2'
+    'token'   => 'xyz456secret',
   },
   {
     'storage' => 'praefect-git-3',
     'address' => 'tcp://praefect-git-3.internal',
-    'token'   => 'token3'
+    'token'   => 'xyz789secret',
   }
 ]
 ```
@@ -97,7 +105,28 @@ Save the file and [reconfigure Praefect](../restart_gitlab.md#omnibus-gitlab-rec
 #### GitLab
 
 When Praefect is running, it should be exposed as a storage to GitLab. This
-is done through setting the `git_data_dirs`. Assuming the default storage
+is done through setting the `git_data_dirs`.
+
+##### On a fresh GitLab installation
+
+On a fresh Gitlab installation, set up the `default` storage to point to praefect:
+
+```ruby
+git_data_dirs({
+  "default" => {
+    "gitaly_address" => "tcp://praefect.internal:2305"
+  },
+})
+```
+
+##### On an existing GitLab instance
+
+On an existing GitLab instance, the `default` storage is already being served by a
+Gitaly node, so an additional storage can be added. `praefect` is chosen in the example
+below, but it can be any name as long as it matches the `virtual_storage_name` in the
+praefect attributes above.
+
+Assuming the default storage
 configuration is used, there would be two storages available to GitLab:
 
 ```ruby