Merge branch 'eread/refactor-mixed-config-docs' into 'master'

Move mixed config info into new section

See merge request gitlab-org/gitlab!35088

doc/administration/gitaly/index.md

@@ -387,31 +387,9 @@ Gitaly makes the following assumptions:
   clients, and that Gitaly server can read and write to `/mnt/gitlab/storage2`.
 - Your `gitaly1.internal` and `gitaly2.internal` Gitaly servers can reach each other.
 
-Note you can't a use mixed setup, with at least one of your Gitaly servers configured as a local
-server with the `path` setting provided. This is because other Gitaly instances can't communicate
-with it. The following setup is _incorrect_, because:
-
-- You must replace `path` with `gitaly_address` containing a proper value.
-- The address must be reachable from the other two addresses provided.
-
-```ruby
-git_data_dirs({
-  'default' => { 'gitaly_address' => 'tcp://gitaly1.internal:8075' },
-  'storage1' => { 'path' => '/var/opt/gitlab/git-data' },
-  'storage2' => { 'gitaly_address' => 'tcp://gitaly2.internal:8075' },
-})
-```
-
-You should use configuration similar to the following:
-
-```ruby
-git_data_dirs({
-  'default' => { 'gitaly_address' => 'tcp://gitaly1.internal:8075' },
-  # this should be the IP address of the GitLab server that has Gitaly running on it
-  'storage1' => { 'gitaly_address' => 'tcp://gitlab.internal:8075' },
-  'storage2' => { 'gitaly_address' => 'tcp://gitaly2.internal:8075' },
-})
-```
+You can't define Gitaly servers with some as a local directory (with `path`) and some as remote
+server (with `gitaly_address`). However, local and remote Gitaly services can be used together. See
+[mixed configuration](#mixed-configuration) for more information.
 
 **For Omnibus GitLab**
 
@@ -475,6 +453,34 @@ If you have [server hooks](../server_hooks.md) configured, either per repository
 must move these to the Gitaly servers. If you have multiple Gitaly servers, copy your server hooks
 to all Gitaly servers.
 
+#### Mixed configuration
+
+GitLab can reside on the same server as one of many Gitaly servers, but doesn't support
+configuration that mixes local and remote configuration. The following setup is incorrect, because:
+
+- `path` is invalid for some of the Gitaly servers.
+- All addresses must be reachable from the other Gitaly servers.
+
+```ruby
+git_data_dirs({
+  'default' => { 'gitaly_address' => 'tcp://gitaly1.internal:8075' },
+  'storage1' => { 'path' => '/var/opt/gitlab/git-data' },
+  'storage2' => { 'gitaly_address' => 'tcp://gitaly2.internal:8075' },
+})
+```
+
+To combine local and remote Gitaly servers, use an external address for the local Gitaly server. For
+example:
+
+```ruby
+git_data_dirs({
+  'default' => { 'gitaly_address' => 'tcp://gitaly1.internal:8075' },
+  # Address of the GitLab server that has Gitaly running on it
+  'storage1' => { 'gitaly_address' => 'tcp://gitlab.internal:8075' },
+  'storage2' => { 'gitaly_address' => 'tcp://gitaly2.internal:8075' },
+})
+```
+
 ### Disable Gitaly where not required (optional)
 
 If you are running Gitaly [as a remote service](#run-gitaly-on-its-own-server) you may want to