Refactor update info for Geo 9.0

[ci skip]

doc/gitlab-geo/updating_the_geo_nodes.md

@@ -4,58 +4,110 @@ In order to update the GitLab Geo nodes when a new GitLab version is released,
 all you need to do is update GitLab itself:
 
 1. Log into each node (primary and secondaries)
-1. [Update GitLab](../update/README.md)
+1. [Update GitLab][update]
 1. Test primary and secondary nodes, and check version in each.
 
-# Upgrade to 9.0.x
+## Special update notes for 9.0.x
 
-> **IMPORTANT**: 9.0 requires manual steps in the secondary nodes,
-because we are upgrading PostgreSQL to 9.6 on the primary and Postgres
-doesn't support upgrading secondary nodes while keeping the
-Streaming Replication working.
+> **IMPORTANT**:
+With GitLab 9.0, the PostgreSQL version is upgraded to 9.6 and manual steps are
+required in order to update the secondary nodes and keep the Streaming
+Replication working. Downtime is required, so plan ahead.
 
-Before starting the upgrade to 9.0 on both **primary** and **secondary** nodes,
-stop all service in each secondary nodes: `gitlab-ctl stop` and make a backup of
-the `recovery.conf` located at: `/var/opt/gitlab/postgresql/data/recovery.conf`
+The following steps apply only if you upgrade from a 8.17 GitLab version to
+9.0+. For previous versions, update to GitLab 8.17 first before attempting to
+upgrade to 9.0+.
 
-Follow regular upgrade instruction for 9.0 on the primary node.
+---
 
-At the end of the upgrade procedures your primary node will be running with
-PostgreSQL on 9.6.x branch. To prevent a desynchronization of the repository
-replication, follow these steps to stop all services but the `postgresql` as
-we will use it to re-initialize the secondary node's database:
+Make sure to follow the steps in the exact order as they appear below and pay
+extra attention in what node (primary/secondary) you execute them! Each step
+is prepended with the relevant node for better clarity:
 
-**Run in the primary node:**
+1. **[secondary]** Login to **all** your secondary nodes and stop all services:
 
-```
-sudo gitlab-ctl stop
-sudo gitlab-ctl start postgresql
-```
+    ```ruby
+    sudo gitlab-ctl stop
+    ```
 
-**Run in the secondary node:**
+1. **[secondary]** Make a backup of the `recovery.conf` file on **all**
+   secondary nodes to preserve PostgreSQL's credentials:
 
-Follow the instructions [here](https://docs.gitlab.com/ee/gitlab-geo/database.html#step-3-initiate-the-replication-process)
-to Create the `replica.sh` script and execute the instructions below:
+    ```
+    sudo cp /var/opt/gitlab/postgresql/data/recovery.conf /var/opt/gitlab/
+    ```
 
-```
-gitlab-ctl stop
+1. **[primary]** Update the primary node to GitLab 9.0 following the
+   [regular update docs][update]. At the end of the update, the primary node
+   will be running with PostgreSQL 9.6.
 
-# backup the recovery.conf from postgresql to preserv credentials
-sudo cp /var/opt/gitlab/postgresql/data/recovery.conf /var/opt/gitlab
+1. **[primary]** To prevent a de-synchronization of the repository replication,
+   stop all services except `postgresql` as we will use it to re-initialize the
+   secondary node's database:
 
-# prevent running database migrations on the secondary node:
-touch /etc/gitlab/skip-auto-migrations
+    ```
+    sudo gitlab-ctl stop
+    sudo gitlab-ctl start postgresql
+    ```
 
-# let's disable the old database:
-mv /var/opt/gitlab/postgresql{,.bak}
+1. **[secondary]** Run the following steps on each of the secondaries:
 
-gitlab-ctl reconfigure
-gitlab-ctl pg-upgrade
+    1. **[secondary]** Create the `replica.sh` script as described in the
+       [database configuration document](database.md#step-3-initiate-the-replication-process).
 
-# see the stored credentials for the database, that you will need to re-initialize replication:
-grep -s primary_conninfo /var/opt/gitlab/recovery.conf
+    1. **[secondary]**  Stop all services:
 
-# run the recovery script with the credentials above
-bash /tmp/replica.sh
-```
+        ```
+        sudo gitlab-ctl stop
+        ```
 
+    1. **[secondary]** Prevent running database migrations:
+
+        ```
+        sudo touch /etc/gitlab/skip-auto-migrations
+        ```
+
+    1. **[secondary]** Move the old database to another directory:
+
+        ```
+        sudo mv /var/opt/gitlab/postgresql{,.bak}
+        ```
+
+    1. **[secondary]** Update to GitLab 9.0 following the [regular update docs][update].
+       At the end of the update, the node will be running with PostgreSQL 9.6.
+
+    1. **[secondary]** Reconfigure GitLab:
+
+        ```
+        sudo gitlab-ctl reconfigure
+        ```
+
+    1. **[secondary]** Run the PostgreSQL upgrade command:
+
+          ```
+          sudo gitlab-ctl pg-upgrade
+          ```
+
+    1. **[secondary]** See the stored credentials for the database that you will
+       need to re-initialize the replication:
+
+        ```
+        sudo grep -s primary_conninfo /var/opt/gitlab/recovery.conf
+        ```
+
+    1. **[secondary]** Run the recovery script using the credentials from the
+       previous step:
+
+        ```
+        sudo bash /tmp/replica.sh
+        ```
+
+    1. **[secondary]** Start all services:
+
+        ```
+        sudo gitlab-ctl start
+        ```
+
+    1. **[secondary]** Repeat the steps for the rest of the secondaries.
+
+[update]: ../update/README.md