Merge branch '4150-geo-docfix' into 'master'

Clarify firewall test and fix postgresql test command

Closes #4150

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

doc/gitlab-geo/database.md

@@ -223,9 +223,6 @@ will not be able to perform all necessary configuration steps. Refer to
     match your database replication requirements. Consult the [PostgreSQL - Replication documentation](https://www.postgresql.org/docs/9.6/static/runtime-config-replication.html)
     for more information.
 
-1. Check to make sure your firewall rules are set so that the secondary nodes
-   can access port `5432` on the primary node.
-
 1. Save the file and [reconfigure GitLab][] for the database listen changes to
    take effect.
 
@@ -319,18 +316,23 @@ primary before the database is replicated.
 1. Test that the remote connection to the primary server works.
 
     ```
-    # Certificate and key currently used by GitLab
-    sudo -u gitlab-psql /opt/gitlab/embedded/bin/psql -h primary.geo.example.com -U gitlab_replicator -d "dbname=gitlabhq_production sslmode=verify-ca" -W
+    # Certificate and key currently used by GitLab, and connecting by FQDN
+    sudo -u gitlab-psql /opt/gitlab/embedded/bin/psql -h primary.geo.example.com -U gitlab_replicator -d "dbname=gitlabhq_production sslmode=verify-full" -W
 
 
-    # Self-signed certificate and key
-    sudo -u gitlab-psql /opt/gitlab/embedded/bin/psql -h 1.2.3.4 -U gitlab_replicator -d "dbname=gitlabhq_production sslmode=verify-full" -W
+    # Self-signed certificate and key, or connecting by IP address
+    sudo -u gitlab-psql /opt/gitlab/embedded/bin/psql -h 1.2.3.4 -U gitlab_replicator -d "dbname=gitlabhq_production sslmode=verify-ca" -W
     ```
 
     When prompted enter the password you set in the first step for the
     `gitlab_replicator` user. If all worked correctly, you should see the
     database prompt.
 
+    A failure to connect here indicates that the TLS or networking configuration
+    is incorrect. Ensure that you've used the correct certificates and IP
+    addresses / FQDNs throughout. If you have a firewall, ensure that the
+    secondary is permitted to access the primary on port 5432.
+
 1. Exit the PostgreSQL console:
 
     ```
@@ -391,10 +393,10 @@ data before running `pg_basebackup`.
 1. Execute the command below to start a backup/restore and begin the replication:
 
     ```
-    # Certificate and key currently used by GitLab
+    # Certificate and key currently used by GitLab, and connecting by FQDN
     gitlab-ctl replicate-geo-database --host=primary.geo.example.com --slot-name=secondary_example
 
-    # Self-signed certificate and key
+    # Self-signed certificate and key, or connecting by IP
     gitlab-ctl replicate-geo-database --host=1.2.3.4 --slot-name=secondary_example --sslmode=verify-ca
     ```
 

doc/gitlab-geo/database_source.md

@@ -270,22 +270,24 @@ primary before the database is replicated.
 
 1. Test that the remote connection to the primary server works:
 
-    If you're using a CA-issued certificate and connecting by FQDN:
 
     ```
+    # Certificate and key currently used by GitLab, and connecting by FQDN
     sudo -u postgres psql -h primary.geo.example.com -U gitlab_replicator -d "dbname=gitlabhq_production sslmode=verify-ca" -W
-    ```
-
-    If you're using a self-signed certificate or connecting by IP address:
 
-    ```
-    sudo -u postgres psql -h 1.2.3.4 -U gitlab_replicator -d "dbname=gitlabhq_production sslmode=verify-full" -W
+    # Self-signed certificate and key, or connecting by IP address
+    sudo -u postgres psql -h 1.2.3.4 -U gitlab_replicator -d "dbname=gitlabhq_production sslmode=verify-ca" -W
     ```
 
     When prompted enter the password you set in the first step for the
     `gitlab_replicator` user. If all worked correctly, you should see the
     database prompt.
 
+    A failure to connect here indicates that the TLS or networking configuration
+    is incorrect. Ensure that you've used the correct certificates and IP
+    addresses / FQDNs throughout. If you have a firewall, ensure that the
+    secondary is permitted to access the primary on port 5432.
+
 1. Exit the PostgreSQL console:
 
     ```