Merge branch 'docs-geo-markdown-1' into 'master'

Docs: Clean up markdown spacing in geo docs

See merge request gitlab-org/gitlab-ce!30112

doc/administration/geo/disaster_recovery/background_verification.md

@@ -143,7 +143,9 @@ If the **primary** and **secondary** nodes have a checksum verification mismatch
 1. On the project admin page get the **Gitaly storage name**, and **Gitaly relative path**:
    ![Project admin page](img/checksum-differences-admin-project-page.png)
 
-1. Navigate to the project's repository directory on both **primary** and **secondary** nodes (the path is usually `/var/opt/gitlab/git-data/repositories`). Note that if `git_data_dirs` is customized, check the directory layout on your server to be sure.
+1. Navigate to the project's repository directory on both **primary** and **secondary** nodes
+   (the path is usually `/var/opt/gitlab/git-data/repositories`). Note that if `git_data_dirs`
+   is customized, check the directory layout on your server to be sure.
 
    ```sh
    cd /var/opt/gitlab/git-data/repositories

doc/administration/geo/disaster_recovery/bring_primary_back.md

@@ -25,16 +25,16 @@ To bring the former **primary** node up to date:
    sudo gitlab-ctl start
    ```
 
-    > **Note 1:** If you [disabled the **primary** node permanently][disaster-recovery-disable-primary],
-    > you need to undo those steps now. For Debian/Ubuntu you just need to run
-    > `sudo systemctl enable gitlab-runsvdir`. For CentOS 6, you need to install
-    > the GitLab instance from scratch and set it up as a **secondary** node by
-    > following [Setup instructions][setup-geo]. In this case, you don't need to follow the next step.
-    >
-    > **Note 2:** If you [changed the DNS records](index.md#step-4-optional-updating-the-primary-domain-dns-record)
-    > for this node during disaster recovery procedure you may need to [block
-    > all the writes to this node](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/doc/gitlab-geo/planned-failover.md#block-primary-traffic)
-    > during this procedure.
+   NOTE: **Note:** If you [disabled the **primary** node permanently][disaster-recovery-disable-primary],
+   you need to undo those steps now. For Debian/Ubuntu you just need to run
+   `sudo systemctl enable gitlab-runsvdir`. For CentOS 6, you need to install
+   the GitLab instance from scratch and set it up as a **secondary** node by
+   following [Setup instructions][setup-geo]. In this case, you don't need to follow the next step.
+   
+   NOTE: **Note:** If you [changed the DNS records](index.md#step-4-optional-updating-the-primary-domain-dns-record)
+   for this node during disaster recovery procedure you may need to [block
+   all the writes to this node](planned_failover.md#prevent-updates-to-the-primary-node)
+   during this procedure.
 
 1. [Setup database replication][database-replication]. Note that in this
    case, **primary** node refers to the current **primary** node, and **secondary** node refers to the

doc/administration/geo/disaster_recovery/index.md

@@ -49,17 +49,19 @@ must disable the **primary** node.
    sudo systemctl disable gitlab-runsvdir
    ```
 
-    > **CentOS only**: In CentOS 6 or older, there is no easy way to prevent GitLab from being
-    > started if the machine reboots isn't available (see [gitlab-org/omnibus-gitlab#3058]).
-    > It may be safest to uninstall the GitLab package completely:
+   NOTE: **Note:**
+   (**CentOS only**) In CentOS 6 or older, there is no easy way to prevent GitLab from being
+   started if the machine reboots isn't available (see [gitlab-org/omnibus-gitlab#3058]).
+   It may be safest to uninstall the GitLab package completely:
 
    ```sh
    yum remove gitlab-ee
    ```
 
-    > **Ubuntu 14.04 LTS**: If you are using an older version of Ubuntu
-    > or any other distro based on the Upstart init system, you can prevent GitLab
-    > from starting if the machine reboots by doing the following:
+   NOTE: **Note:**
+   (**Ubuntu 14.04 LTS**) If you are using an older version of Ubuntu
+   or any other distro based on the Upstart init system, you can prevent GitLab
+   from starting if the machine reboots by doing the following:
 
    ```sh
    initctl stop gitlab-runsvvdir
@@ -71,6 +73,7 @@ must disable the **primary** node.
    prevent it from rebooting by any means at your disposal.
    Since there are many ways you may prefer to accomplish this, we will avoid a
    single recommendation. You may need to:
+
    - Reconfigure the load balancers.
    - Change DNS records (e.g., point the primary DNS record to the **secondary**
      node in order to stop usage of the **primary** node).
@@ -79,8 +82,7 @@ must disable the **primary** node.
    - Revoke object storage permissions from the **primary** node.
    - Physically disconnect a machine.
 
-1. If you plan to
-   [update the primary domain DNS record](#step-4-optional-updating-the-primary-domain-dns-record),
+1. If you plan to [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** node
@@ -255,7 +257,6 @@ and after that you also need two extra steps.
    ## (until PostgreSQL is restarted and listening on the private address).
    ##
    gitlab_rails['auto_migrate'] = false
-
    ```
 
    (For more details about these settings you can read [Configure the primary server][configure-the-primary-server])

doc/administration/geo/disaster_recovery/planned_failover.md

@@ -187,6 +187,7 @@ access to the **primary** node during the maintenance window.
    before it is completed will cause the work to be lost.
 1. On the **primary** node, navigate to **Admin Area > Geo** and wait for the
    following conditions to be true of the **secondary** node you are failing over to:
+   
    - All replication meters to each 100% replicated, 0% failures.
    - All verification meters reach 100% verified, 0% failures.
    - Database replication lag is 0ms.

doc/administration/geo/replication/configuration.md

@@ -16,11 +16,10 @@ The basic steps of configuring a **secondary** node are to:
 You are encouraged to first read through all the steps before executing them
 in your testing/production environment.
 
-> **Notes:**
-> - **Do not** setup any custom authentication for the **secondary** nodes. This will be
-  handled by the **primary** node.
-> - Any change that requires access to the **Admin Area** needs to be done in the
-  **primary** node because the **secondary** node is a read-only replica.
+NOTE: **Note:**
+**Do not** set up any custom authentication for the **secondary** nodes. This will be handled by the **primary** node.  
+Any change that requires access to the **Admin Area** needs to be done in the
+**primary** node because the **secondary** node is a read-only replica.
 
 ### Step 1. Manually replicate secret GitLab values
 
@@ -151,7 +150,7 @@ keys must be manually replicated to the **secondary** node.
    for file in /etc/ssh/ssh_host_*_key.pub; do ssh-keygen -lf $file; done
    ```
 
-    NOTE: **Note**:
+   NOTE: **Note:**
    The output for private keys and public keys command should generate the same fingerprint.
 
 1. Restart sshd on your **secondary** node:
@@ -250,8 +249,7 @@ The two most obvious issues that can become apparent in the dashboard are:
 1. Database replication not working well.
 1. Instance to instance notification not working. In that case, it can be
    something of the following:
-     - You are using a custom certificate or custom CA (see the
-       [troubleshooting document]).
+   - You are using a custom certificate or custom CA (see the [troubleshooting document](troubleshooting.md)).
    - The instance is firewalled (check your firewall rules).
 
 Please note that disabling a **secondary** node will stop the synchronization process.
@@ -304,5 +302,4 @@ See the [troubleshooting document](troubleshooting.md).
 [gitlab-org/gitlab-ee#3789]: https://gitlab.com/gitlab-org/gitlab-ee/issues/3789
 [gitlab-com/infrastructure#2821]: https://gitlab.com/gitlab-com/infrastructure/issues/2821
 [omnibus-ssl]: https://docs.gitlab.com/omnibus/settings/ssl.html
-[troubleshooting document]: troubleshooting.md
 [using-geo]: using_a_geo_server.md

doc/administration/geo/replication/database.md

@@ -115,7 +115,9 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o
    For security reasons, PostgreSQL does not listen on any network interfaces
    by default. However, Geo requires the **secondary** node to be able to
    connect to the **primary** node's database. For this reason, we need the address of
-    each node. Note: For external PostgreSQL instances, see [additional instructions](external_database.md).
+   each node.
+   
+   NOTE: **Note:** For external PostgreSQL instances, see [additional instructions](external_database.md).
 
    If you are using a cloud provider, you can lookup the addresses for each
    Geo node through your cloud provider's management console.
@@ -266,7 +268,7 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o
    gitlab-ctl stop sidekiq
    ```
 
-    NOTE: **Note**:
+   NOTE: **Note:**
    This step is important so we don't try to execute anything before the node is fully configured.
 
 1. [Check TCP connectivity][rake-maintenance] to the **primary** node's PostgreSQL server:
@@ -275,7 +277,7 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o
    gitlab-rake gitlab:tcp_check[<primary_node_ip>,5432]
    ```
 
-    NOTE: **Note**:
+   NOTE: **Note:**
    If this step fails, you may be using the wrong IP address, or a firewall may
    be preventing access to the server. Check the IP address, paying close
    attention to the difference between public and private addresses and ensure
@@ -404,6 +406,7 @@ data before running `pg_basebackup`.
    name as shown in the commands below.
 
 1. Execute the command below to start a backup/restore and begin the replication
+
    CAUTION: **Warning:** Each Geo **secondary** node must have its own unique replication slot name.
    Using the same slot name between two secondaries will break PostgreSQL replication.
 
@@ -418,6 +421,7 @@ data before running `pg_basebackup`.
 
    This command also takes a number of additional options. You can use `--help`
    to list them all, but here are a couple of tips:
+
    - If PostgreSQL is listening on a non-standard port, add `--port=` as well.
    - If your database is too large to be transferred in 30 minutes, you will need
       to increase the timeout, e.g., `--backup-timeout=3600` if you expect the

doc/administration/geo/replication/external_database.md

@@ -4,7 +4,7 @@ This document is relevant if you are using a PostgreSQL instance that is *not
 managed by Omnibus*. This includes cloud-managed instances like AWS RDS, or
 manually installed and configured PostgreSQL instances.
 
-NOTE: **Note**:
+NOTE: **Note:**
 We strongly recommend running Omnibus-managed instances as they are actively
 developed and tested. We aim to be compatible with most external
 (not managed by Omnibus) databases but we do not guarantee compatibility.
@@ -121,6 +121,7 @@ To configure the connection to the external read-replica database and enable Log
    gitlab_rails['db_username'] = 'gitlab'
    gitlab_rails['db_host'] = '<database_read_replica_host>'
    ```
+
 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure)
 
 ### Configure the tracking database
@@ -173,8 +174,7 @@ the tracking database on port 5432.
    gitlab-rake geo:db:migrate
    ```
 
-1. Configure the
-    [PostgreSQL FDW](https://www.postgresql.org/docs/9.6/static/postgres-fdw.html)
+1. Configure the [PostgreSQL FDW](https://www.postgresql.org/docs/9.6/static/postgres-fdw.html)
    connection and credentials:
 
    Save the script below in a file, ex. `/tmp/geo_fdw.sh` and modify the connection

doc/administration/geo/replication/remove_geo_node.md

@@ -13,6 +13,7 @@ Once removed from the Geo admin page, you must stop and uninstall the **secondar
    ```bash
    sudo gitlab-ctl stop
    ```
+
 1. On the **secondary** node, uninstall GitLab:
 
    ```bash

doc/administration/geo/replication/troubleshooting.md

@@ -188,7 +188,7 @@ log data to build up in `pg_xlog`. Removing the unused slots can reduce the amou
    sudo gitlab-psql gitlabhq_production
    ```
 
-    > Note that using `gitlab-rails dbconsole` will not work, because managing replication slots requires superuser permissions.
+   Note: **Note:** Using `gitlab-rails dbconsole` will not work, because managing replication slots requires superuser permissions.
 
 1. View your replication slots with:
 
@@ -280,8 +280,8 @@ to start again from scratch, there are a few steps that can help you:
    Any uploaded content like file attachments, avatars or LFS objects are stored in a
    subfolder in one of the two paths below:
 
-    1. /var/opt/gitlab/gitlab-rails/shared
-    1. /var/opt/gitlab/gitlab-rails/uploads
+   - /var/opt/gitlab/gitlab-rails/shared
+   - /var/opt/gitlab/gitlab-rails/uploads
 
    To rename all of them:
 
@@ -354,10 +354,8 @@ To check the configuration:
 
    ```sql
    gitlabhq_geo_production=# SELECT * from information_schema.foreign_tables;
-      foreign_table_catalog  | foreign_table_schema |               foreign_table_name                | foreign_server_catalog  | foreign_server_n
-    ame
-    -------------------------+----------------------+-------------------------------------------------+-------------------------+-----------------
-    ----
+     foreign_table_catalog  | foreign_table_schema |               foreign_table_name                | foreign_server_catalog  | foreign_server_name
+   -------------------------+----------------------+-------------------------------------------------+-------------------------+---------------------
     gitlabhq_geo_production | gitlab_secondary     | abuse_reports                                   | gitlabhq_geo_production | gitlab_secondary
     gitlabhq_geo_production | gitlab_secondary     | appearances                                     | gitlabhq_geo_production | gitlab_secondary
     gitlabhq_geo_production | gitlab_secondary     | application_setting_terms                       | gitlabhq_geo_production | gitlab_secondary

doc/administration/geo/replication/updating_the_geo_nodes.md

@@ -236,12 +236,12 @@ instructions below.
 When in doubt, it does not hurt to do a resync. The easiest way to do this in
 Omnibus is the following:
 
-  1. Make sure you have Omnibus GitLab on the **primary** server.
-  1. Run `gitlab-ctl reconfigure` and `gitlab-ctl restart postgresql`. This will enable replication slots on the **primary** database.
-  1. Check the steps about defining `postgresql['sql_user_password']`, `gitlab_rails['db_password']`.
-  1. Make sure `postgresql['max_replication_slots']` matches the number of **secondary** Geo nodes locations.
-  1. Install GitLab on the **secondary** server.
-  1. Re-run the [database replication process][database-replication].
+1. Make sure you have Omnibus GitLab on the **primary** server.
+1. Run `gitlab-ctl reconfigure` and `gitlab-ctl restart postgresql`. This will enable replication slots on the **primary** database.
+1. Check the steps about defining `postgresql['sql_user_password']`, `gitlab_rails['db_password']`.
+1. Make sure `postgresql['max_replication_slots']` matches the number of **secondary** Geo nodes locations.
+1. Install GitLab on the **secondary** server.
+1. Re-run the [database replication process][database-replication].
 
 ## Special update notes for 9.0.x
 
@@ -334,10 +334,7 @@ is prepended with the relevant node for better clarity:
       sudo grep -s primary_conninfo /var/opt/gitlab/recovery.conf
       ```
 
-    1. **[secondary]** Create the `replica.sh` script as described in the
-       [database configuration document][database-source-replication].
-
-    1. 1. **[secondary]** Save the snippet below in a file, let's say `/tmp/replica.sh`. Modify the
+   1. **[secondary]** Save the snippet below in a file, let's say `/tmp/replica.sh`. Modify the
       embedded paths if necessary:
 
       ```