Merge branch 'docs/promote-sec-ext-psql-db' into 'master'

Docs - Promote Geo secondary nodes on external PostgreSQL databases

See merge request gitlab-org/gitlab!28188

doc/administration/geo/disaster_recovery/index.md

@@ -167,6 +167,44 @@ do this manually.
    previously for the **secondary**.
 1. Success! The **secondary** has now been promoted to **primary**.
 
+#### Promoting a **secondary** node with an external PostgreSQL database
+
+The `gitlab-ctl promote-to-primary-node` command cannot be used in conjunction with
+an external PostgreSQL database, as it can only perform changes on a **secondary**
+node with GitLab and the database on the same machine. As a result, a manual process is
+required. For example, PostgreSQL databases hosted on Amazon RDS:
+
+1. Promote the replica database associated with the **secondary** site. This will
+   set the database to read-write:
+   - Amazon RDS - [Promoting a Read Replica to Be a Standalone DB Instance](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ReadRepl.html#USER_ReadRepl.Promote)
+
+1. Edit `/etc/gitlab/gitlab.rb` on every node in the **secondary** site to
+   reflect its new status as **primary** by removing any lines that enabled the
+   `geo_secondary_role`:
+
+   ```ruby
+   ## In GitLab 11.4 and earlier, remove this line.
+   geo_secondary_role['enable'] = true
+
+   ## In GitLab 11.5 and later, remove this line.
+   roles ['geo_secondary_role']
+   ```
+
+   After making these changes [Reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure)
+   on each node so the changes take effect.
+
+1. Promote the **secondary** to **primary**. SSH into a single secondary application
+   node and execute:
+
+   ```shell
+   sudo gitlab-rake geo:set_secondary_as_primary
+   ```
+
+1. Verify you can connect to the newly promoted **primary** site using the URL used
+   previously for the **secondary** site.
+
+Success! The **secondary** site has now been promoted to **primary**.
+
 ### Step 4. (Optional) Updating the primary domain DNS record
 
 Updating the DNS records for the primary domain to point to the **secondary** node