Docs: Clarify secrets usage and PG settings for Praefect

doc/administration/gitaly/praefect.md

@@ -72,9 +72,11 @@ We need to manage the following secrets and make them match across hosts:
 1. `PRAEFECT_SQL_PASSWORD`: this password is used by Praefect to connect to
     PostgreSQL.
 
+We will note in the instructions below where these secrets are required.
+
 #### Network addresses
 
-1. `POSTGRESQL_SERVER`: the host name or IP address of your PostgreSQL server
+1. `POSTGRESQL_SERVER_ADDRESS`: the host name or IP address of your PostgreSQL server
 
 #### PostgreSQL
 
@@ -91,7 +93,7 @@ Below we assume that you have administrative access as the `postgres`
 user. First open a `psql` session as the `postgres` user:
 
 ```shell
-/opt/gitlab/embedded/bin/psql -h POSTGRESQL_SERVER -U postgres -d template1
+/opt/gitlab/embedded/bin/psql -h POSTGRESQL_SERVER_ADDRESS -U postgres -d template1
 ```
 
 Once you are connected, run the following command. Replace
@@ -107,7 +109,7 @@ Now connect as the `praefect` user to create the database. This has
 the side effect of verifying that you have access:
 
 ```shell
-/opt/gitlab/embedded/bin/psql -h POSTGRESQL_SERVER -U praefect -d template1
+/opt/gitlab/embedded/bin/psql -h POSTGRESQL_SERVER_ADDRESS -U praefect -d template1
 ```
 
 Once you have connected as the `praefect` user, run:
@@ -125,6 +127,12 @@ Gitaly node that will be connected to Praefect as members of the `praefect` hash
 In the example below, the Gitaly nodes are named `gitaly-N`. Note that one
 node is designated as primary by setting the primary to `true`.
 
+If you are using an uncrypted connection to Postgres, set `praefect['database_sslmode']` to false.
+
+If you are using an encrypted connection with a client certificate,
+`praefect['database_sslcert']` and `praefect['database_sslkey']` will need to be set.
+If you are using a custom CA, also set `praefect['database_sslrootcert']`:
+
 ```ruby
 # /etc/gitlab/gitlab.rb on praefect server
 
@@ -174,7 +182,7 @@ praefect['virtual_storages'] = {
 }
 
 # Replace POSTGRESQL_SERVER below with a real IP/host address of the database.
-praefect['database_host'] = 'POSTGRESQL_SERVER'
+praefect['database_host'] = 'POSTGRESQL_SERVER_ADDRESS'
 praefect['database_port'] = 5432
 praefect['database_user'] = 'praefect'
 # Replace PRAEFECT_SQL_PASSWORD below with a real password of the database.
@@ -195,6 +203,9 @@ praefect['database_dbname'] = 'praefect_production'
 # praefect['database_sslrootcert'] = '/path/to/rootcert'
 ```
 
+Replace `POSTGRESQL_SERVER_ADDRESS`, `PRAEFECT_EXTERNAL_TOKEN`, `PRAEFECT_INTERNAL_TOKEN`,
+and `PRAEFECT_SQL_PASSWORD` with their respective values.
+
 Save the file and [reconfigure Praefect](../restart_gitlab.md#omnibus-gitlab-reconfigure).
 
 After you reconfigure, verify that Praefect can reach PostgreSQL:
@@ -260,6 +271,9 @@ git_data_dirs({
 })
 ```
 
+Replace `GITLAB_SHELL_SECRET_TOKEN` and `PRAEFECT_INTERNAL_TOKEN`
+with their respective values.
+
 For more information on Gitaly server configuration, see our [Gitaly documentation](index.md#3-gitaly-server-configuration).
 
 When finished editing the configuration file for each Gitaly server, run the
@@ -302,6 +316,9 @@ git_data_dirs({
 gitlab_shell['secret_token'] = 'GITLAB_SHELL_SECRET_TOKEN'
 ```
 
+Replace `GITLAB_SHELL_SECRET_TOKEN` and `PRAEFECT_EXTERNAL_TOKEN`
+with their respective values.
+
 Note that the storage name used is the same as the `praefect['virtual_storage_name']` set
 on the Praefect node.