Merge branch 'mk/mitigate-some-geo-ha-setup-pitfalls-docs' into 'master'

Mitigate a few Geo HA setup pitfalls in the documentation

Closes #7601

See merge request gitlab-org/gitlab-ee!8117

doc/administration/geo/disaster_recovery/index.md

@@ -83,7 +83,14 @@ must disable the primary.
    [update the primary domain DNS record](#step-4-optional-updating-the-primary-domain-dns-record),
    you may wish to lower the TTL now to speed up propagation.
 
-### Step 3. Promoting a secondary Geo replica
+### Step 3. Promoting a **secondary** node
+
+NOTE: **Note:**
+A new **secondary** should not be added at this time. If you want to add a new
+**secondary**, do this after you have completed the entire process of promoting
+the **secondary** to the **primary**.
+
+#### Promoting a **secondary** node running on a single machine
 
 1. SSH in to your **secondary** and login as root:
 
@@ -91,43 +98,66 @@ must disable the primary.
     sudo -i
     ```
 
-1. Edit `/etc/gitlab/gitlab.rb` to reflect its new status as primary by
-   removing the following line:
+1. Edit `/etc/gitlab/gitlab.rb` to reflect its new status as **primary** by
+   removing any lines that enabled the `geo_secondary_role`:
 
     ```ruby
-    ## REMOVE THIS LINE
+    ## In pre-11.5 documentation, the role was enabled as follows. Remove this line.
     geo_secondary_role['enable'] = true
-    ```
 
-    A new secondary should not be added at this time. If you want to add a new
-    secondary, do this after you have completed the entire process of promoting
-    the secondary to the primary.
+    ## In 11.5+ documentation, the role was enabled as follows. Remove this line.
+    roles ['geo_secondary_role']
+    ```
 
-1. Promote the secondary to primary. Execute:
+1. Promote the **secondary** to **primary**. Execute:
 
     ```bash
     gitlab-ctl promote-to-primary-node
     ```
 
-1. Verify you can connect to the newly promoted primary using the URL used
-   previously for the secondary.
-1. Success! The secondary has now been promoted to primary.
+1. Verify you can connect to the newly promoted **primary** using the URL used
+   previously for the **secondary**.
+1. Success! The **secondary** has now been promoted to **primary**.
 
-#### Promoting a node with HA
+#### Promoting a **secondary** node with HA
 
-The `gitlab-ctl promote-to-primary-node` command cannot be used yet in conjunction with
-High Availability or with multiple machines, as it can only perform changes on
-a single one.
+The `gitlab-ctl promote-to-primary-node` command cannot be used yet in
+conjunction with High Availability or with multiple machines, as it can only
+perform changes on a **secondary** with only a single machine. Instead, you must
+do this manually.
 
-The command above does the following changes:
+1. SSH in to the database node in the **secondary** and trigger PostgreSQL to
+   promote to read-write:
 
-- Promotes the PostgreSQL secondary to primary
-- Executes `gitlab-ctl reconfigure` to apply the changes in `/etc/gitlab/gitlab.rb`
-- Runs `gitlab-rake geo:set_secondary_as_primary`
+    ```bash
+    sudo gitlab-pg-ctl promote
+    ```
+
+1. Edit `/etc/gitlab/gitlab.rb` on every machine in the **secondary** to
+   reflect its new status as **primary** by removing any lines that enabled the
+   `geo_secondary_role`:
+
+    ```ruby
+    ## In pre-11.5 documentation, the role was enabled as follows. Remove this line.
+    geo_secondary_role['enable'] = true
+
+    ## In 11.5+ documentation, the role was enabled as follows. Remove this line.
+    roles ['geo_secondary_role']
+    ```
+
+    After making these changes [Reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) each
+    machine so the changes take effect.
+
+1. Promote the **secondary** to **primary**. SSH into a single application
+   server and execute:
+
+    ```bash
+    sudo gitlab-rake geo:set_secondary_as_primary
+    ```
 
-You need to make sure all the affected machines no longer have `geo_secondary_role['enable'] = true` in
-`/etc/gitlab/gitlab.rb`, that you execute the database promotion on the required database nodes
-and you execute the `gitlab-rake geo:set_secondary_as_primary` in a machine running the application server.
+1. Verify you can connect to the newly promoted **primary** using the URL used
+   previously for the **secondary**.
+1. Success! The **secondary** has now been promoted to **primary**.
 
 ### Step 4. (Optional) Updating the primary domain DNS record
 
@@ -198,7 +228,7 @@ and after that you also need two extra steps.
 
     ```ruby
     ## Enable a Geo Primary role (if you haven't yet)
-    geo_primary_role['enable'] = true
+    roles ['geo_primary_role']
 
     ##
     # Primary and Secondary addresses

doc/administration/geo/replication/database.md

@@ -3,7 +3,7 @@
 NOTE: **Note:**
 This is the documentation for the Omnibus GitLab packages. For installations
 from source, follow the
-[**database replication for installations from source**][database-source] guide.
+[Geo database replication (source)](database_source.md) guide.
 
 NOTE: **Note:**
 If your GitLab installation uses external PostgreSQL, the Omnibus roles
@@ -104,7 +104,9 @@ The following guide assumes that:
 
     If you are using an external database not managed by Omnibus GitLab, you need
     to create the replicator user and define a password to it manually.
-    Check [How to create replication user][database-source-primary] documentation. 
+    For information on how to create a replication user, refer to the
+    [appropriate step](database_source.md#step-1-configure-the-primary-server)
+    in [Geo database replication (source)](database_source.md).
 
 1. Configure PostgreSQL to listen on network interfaces
 
@@ -161,7 +163,7 @@ The following guide assumes that:
     ## Geo Primary role
     ## - configure dependent flags automatically to enable Geo
     ##
-    geo_primary_role['enable'] = true
+    roles ['geo_primary_role']
 
     ##
     ## Primary address
@@ -325,7 +327,7 @@ The following guide assumes that:
     ## Geo Secondary role
     ## - configure dependent flags automatically to enable Geo
     ##
-    geo_secondary_role['enable'] = true 
+    roles ['geo_secondary_role']
 
     ##
     ## Secondary address
@@ -348,7 +350,7 @@ The following guide assumes that:
     ```
 
     For external PostgreSQL instances, [see additional instructions][external postgresql].
-    If you bring a former primary back online to serve as a secondary then you also need to remove `geo_primary_role['enable'] = true`.
+    If you bring a former **primary** node back online to serve as a **secondary** node, then you also need to remove `roles ['geo_primary_role']` or `geo_primary_role['enable'] = true`.
 
 1. Reconfigure GitLab for the changes to take effect:
 
@@ -621,8 +623,6 @@ Read the [troubleshooting document](troubleshooting.md).
 [tracking]: database_source.md#enable-tracking-database-on-the-secondary-server
 [FDW]: https://www.postgresql.org/docs/9.6/static/postgres-fdw.html
 [toc]: index.md#using-omnibus-gitlab
-[database-source]: database_source.md
-[database-source-primary]: database_source.md#step-1-configure-the-primary-server
 [rake-maintenance]: ../../raketasks/maintenance.md
 [pg-docs-ssl]: https://www.postgresql.org/docs/9.6/static/libpq-ssl.html#LIBPQ-SSL-PROTECTION
 [pg-docs-runtime-conn]: https://www.postgresql.org/docs/9.6/static/runtime-config-connection.html