Merge branch 'cat-document-geo-verify-ca-and-certificate-requirements' into 'master'

Document Geo PG auto-generated certificate sslmode and workaround

See merge request gitlab-org/gitlab!85416

doc/administration/geo/replication/troubleshooting.md

@@ -419,6 +419,21 @@ sudo gitlab-ctl reconfigure
 To help us resolve this problem, consider commenting on
 [the issue](https://gitlab.com/gitlab-org/gitlab/-/issues/4489).
 
+### Message: `FATAL:  could not connect to the primary server: server certificate for "PostgreSQL" does not match host name`
+
+This happens because the PostgreSQL certificate that the Omnibus GitLab package automatically creates contains
+the Common Name `PostgreSQL`, but the replication is connecting to a different host and GitLab attempts to use
+the `verify-full` SSL mode by default.
+
+In order to fix this, you can either:
+
+- Use the `--sslmode=verify-ca` argument with the `replicate-geo-database` command.
+- For an already replicated database, change `sslmode=verify-full` to `sslmode=verify-ca`
+  in `/var/opt/gitlab/postgresql/data/gitlab-geo.conf` and run `gitlab-ctl restart postgresql`.
+- [Configure SSL for PostgreSQL](https://docs.gitlab.com/omnibus/settings/database.html#configuring-ssl)
+  with a custom certificate (including the host name that's used to connect to the database in the CN or SAN)
+  instead of using the automatically generated certificate.
+
 ### Message: `LOG:  invalid CIDR mask in address`
 
 This happens on wrongly-formatted addresses in `postgresql['md5_auth_cidr_addresses']`.

doc/administration/geo/setup/database.md

@@ -300,6 +300,24 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o
    need it when setting up the **secondary** node! The certificate is not sensitive
    data.
 
+   However, this certificate is created with a generic `PostgreSQL` Common Name. For this,
+   you must use the `verify-ca` mode when replicating the database, otherwise,
+   the hostname mismatch will cause errors.
+
+1. Optional. Generate your own SSL certificate and manually
+   [configure SSL for PostgreSQL](https://docs.gitlab.com/omnibus/settings/database.html#configuring-ssl),
+   instead of using the generated certificate.
+
+   You will need at least the SSL certificate and key, and set the `postgresql['ssl_cert_file']` and
+   `postgresql['ssl_key_file']` values to their full paths, as per the Database SSL docs.
+
+   This allows you to use the `verify-full` SSL mode when replicating the database
+   and get the extra benefit of verifying the full hostname in the CN.
+
+   You can use this certificate (that you have also set in `postgresql['ssl_cert_file']`) instead
+   of the certificate from the point above going forward. This will allow you to use `verify-full`
+   without replication errors if the CN matches.
+
 #### Step 2. Configure the **secondary** server
 
 1. SSH into your GitLab **secondary** server and login as root:
@@ -367,6 +385,12 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o
       -h <primary_node_ip>
    ```
 
+   NOTE:
+   If you are using manually generated certificates and plan on using
+   `sslmode=verify-full` to benefit of the full hostname verification,
+   make sure to replace `verify-ca` to `verify-full` when
+   running the command.
+
    When prompted enter the password you set in the first step for the
    `gitlab_replicator` user. If all worked correctly, you should see
    the list of **primary** node's databases.
@@ -455,6 +479,7 @@ data before running `pg_basebackup`.
    gitlab-ctl replicate-geo-database \
       --slot-name=<secondary_node_name> \
       --host=<primary_node_ip>
+      --sslmode=verify-ca
    ```
 
    NOTE:
@@ -463,6 +488,13 @@ data before running `pg_basebackup`.
    When prompted, enter the _plaintext_ password you set up for the `gitlab_replicator`
    user in the first step.
 
+   NOTE:
+   If you have generated custom PostgreSQL certificates, you will want to use
+   `--sslmode=verify-full` (or omit the `sslmode` line entirely), to benefit from the extra
+   validation of the full host name in the certificate CN / SAN for additional security.
+   Otherwise, using the automatically created certificate with `verify-full` will fail,
+   as it has a generic `PostgreSQL` CN which will not match the `--host` value in this command.
+
    This command also takes a number of additional options. You can use `--help`
    to list them all, but here are a couple of tips: