Cleanup database documention for HAadd-pgbouncer-documentation

* Add more details about password management.
* Consistently use the term `secondary` for the backupd database
instance.
* Remove faulty instructions for creating pg_trgm extension

3 files changed, 43 insertions, 97 deletions

diff --git a/doc/administration/high_availability/README.md b/doc/administration/high_availability/README.md
index b2b314d8ce5..d5a5aef7ec0 100644
--- a/doc/administration/high_availability/README.md
+++ b/doc/administration/high_availability/README.md
@@ -22,7 +22,6 @@ if the database, Redis and storage are also configured as such.
 Follow the steps below to configure an active/active setup:
 
 1. [Configure the database](database.md)
-1. [Configure PgBouncer](pgbouncer.md)
 1. [Configure Redis](redis.md)
 1. [Configure NFS](nfs.md)
 1. [Configure the GitLab application servers](gitlab.md)
diff --git a/doc/administration/high_availability/database.md b/doc/administration/high_availability/database.md
index 67fe5f8a288..dba1ce5a858 100644
--- a/doc/administration/high_availability/database.md
+++ b/doc/administration/high_availability/database.md
@@ -22,23 +22,31 @@ If you use a cloud-managed service, or provide your own PostgreSQL:
 
 ## Configure using Omnibus
 
-The recommended configuration for an Omnibus manage is:
-* A minimum of 2 database servers, a primary and a slave.
-* Use the bundled [pgbouncer](https://pgbouncer.github.io) to pool database connections
+The recommended configuration for an Omnibus managed PostgreSQL instance is:
+* A minimum of 2 database servers, a primary and a secondary.
+* Use of the bundled [pgbouncer](https://pgbouncer.github.io) to pool database connections on each node.
 
 ### Primary database server
 1. Download/install GitLab Omnibus using **steps 1 and 2** from
    [GitLab downloads](https://about.gitlab.com/downloads). Do not complete other
    steps on the download page.
+
+1. We need three accounts for the GitLab database, one for the application, and one for pgbouncer.
+   Each account needs a password, which we store in an md5 has when possible. The hash for a password can be
+   generated by running: `echo -n "${PASSWORD}${USERNAME}" | md5sum`.
+   * The default user for the application is `gitlab`. This password will be stored in plaintext so it **really should** be a unique password.
+     * On the database server, the hash should be stored in the attribute `postgresql['sql_user_password']`
+     * On the application server, the password is stored in the attribute `gitlab_rails['db_password']`
+   * The default user for replication is `gitlab_replicator`. Currently, its password is not managed by omnibus, and will be set in a manual step later.
+   * The default user for pgbouncer is `pgbouncer`, its password is stored as an md5 has in `postgresql['pgbouncer_user_password']`
+     for the database, and as part of the `pgbouncer['databases']` attribute for the pgbouncer instance.
+
 1. Create/edit `/etc/gitlab/gitlab.rb` and use the following configuration.
-   Be sure to change the `external_url` to match your eventual GitLab front-end
-   URL.
 
     ```ruby
-    external_url 'https://gitlab.example.com'
-
-    # Disable all components except PostgreSQL
+    # Disable all unecessary components
     postgresql['enable'] = true
+    gitlab_rails['enable'] = false
     bootstrap['enable'] = false
     nginx['enable'] = false
     unicorn['enable'] = false
@@ -46,10 +54,12 @@ The recommended configuration for an Omnibus manage is:
     redis['enable'] = false
     gitlab_workhorse['enable'] = false
     mailroom['enable'] = false
+    gitaly['enable'] = false
 
     # PostgreSQL configuration
-    gitlab_rails['db_password'] = 'DB password'
+    # This will be the list of hosts that can use md5 authentication to connect to the database.
     postgresql['md5_auth_cidr_addresses'] = ['0.0.0.0/0']
+    # This will be allowa host to connect to the database without authentication
     postgresql['trust_auth_cidr_addresses'] = ['127.0.0.0/24']
     postgresql['listen_address'] = '0.0.0.0'
     postgresql['sql_replication_user'] = 'gitlab_replicator'
@@ -76,9 +86,6 @@ The recommended configuration for an Omnibus manage is:
 
 1. Run `sudo gitlab-ctl reconfigure` to install and configure PostgreSQL.
 
-    > **Note**: This `reconfigure` step will result in some errors.
-      That's OK - don't be alarmed.
-
 1. Open a database prompt:
 
     ```
@@ -103,43 +110,34 @@ The recommended configuration for an Omnibus manage is:
     Enter it again:
     ```
 
-1. Similarly, set the password for the `gitlab` database user. Use the same
-   password that you specified in the `/etc/gitlab/gitlab.rb` file for
-   `gitlab_rails['db_password']`.
-
+1. Similarly, set the password for the `gitlab_replicator` database user.
     ```
-    \password gitlab
+    \password gitlab_replicator
 
     # Output:
 
     Enter new password:
     Enter it again:
     ```
+1. Give the `gitlab_replicator` user replication permissions:
+   ```
+   ALTER USER gitlab_replicator REPLICATION;
 
-1. Enable the `pg_trgm` extension:
-    ```
-    CREATE EXTENSION pg_trgm;
-
-    # Output:
-
-    CREATE EXTENSION
-    ```
+   # Output:
+   ALTER ROLE
+   ```
 1. Exit the database prompt by typing `\q` and Enter.
-1. Exit the `gitlab-psql` user by running `exit` twice.
-1. Run `sudo gitlab-ctl reconfigure` a final time.
 
-### Slave database server
+### Secondary database server
 1. Download/install GitLab Omnibus using **steps 1 and 2** from
    [GitLab downloads](https://about.gitlab.com/downloads). Do not complete other
    steps on the download page.
-1. Create/edit `/etc/gitlab/gitlab.rb` and use the following configuration.
-   Be sure to change the `external_url` to match your eventual GitLab front-end
-   URL.
 
-    ```ruby
-    external_url 'https://gitlab.example.com'
+1. You will need the same password hash for the `pgbouncer` user from the primary server.
 
-    # Disable all components except PostgreSQL
+1. Create/edit `/etc/gitlab/gitlab.rb` and use the following configuration.
+    ```ruby
+    # Disable all uncessary components
     postgresql['enable'] = true
     bootstrap['enable'] = false
     nginx['enable'] = false
@@ -148,6 +146,8 @@ The recommended configuration for an Omnibus manage is:
     redis['enable'] = false
     gitlab_workhorse['enable'] = false
     mailroom['enable'] = false
+    gitlab_rails['enable'] = false
+    gitaly['enable'] = false
 
     # PostgreSQL configuration
     gitlab_rails['auto_migrate'] = false
@@ -161,30 +161,34 @@ The recommended configuration for an Omnibus manage is:
       }
    }
    ```
+
 1. Run `sudo gitlab-ctl reconfigure` to install and configure PostgreSQL.
 
-   > **Note**: This `reconfigure` step will result in some errors.
-         That's OK - don't be alarmed.
 1. Stop the database by running `sudo gitlab-ctl stop postgresql`
+
 1. Remove the current database by running `sudo rm -rf /var/opt/gitlab/postgresl/data/*`
    > **WARNING**: Be absolutely sure you're running this on the correct server.
    Especially if you're working with an existing GitLab install
-1. Perform the initial data synchrinozation by running:
+
+1. Perform the initial data synchronization by running:
 ```bash
 su - gitlab-psql -c '/opt/gitlab/embedded/bin/pg_basebackup -h PRIMARY_DB_HOST -D /var/opt/gitlab/postgresql/data/ -P -U gitlab_replicator --xlog-method=stream'
 ```
 > **Note**: When prompted, enter the password for the `gitlab_replicator` user
+
 1. Create a file `/var/opt/gitlab/postgresql/data/recovery.conf` containing:
 ```
 standby_mode          = 'on'
-primary_conninfo      = 'host=PRIMARY_DB_HOST port=5432 user=gitlab_replicator password=password'
+primary_conninfo      = 'host=PRIMARY_DB_HOST port=5432 user=gitlab_replicator password=CLEARTEXT_PASSWORD'
 trigger_file = '/var/opt/gitlab/postgresql/data/trigger'
 ```
+
 1. Run `sudo gitlab-ctl reconfigure` a final time.
+
 1. If you are running with multiple standby servers, repeat these steps for each server.
 
 
-After the database servers are configured, move on to configuraint  the GitLab application servers with the appropriate details.
+After the database servers are configured, move on to configuring the GitLab application servers with the appropriate details.
 This step is covered in [Configuring GitLab for HA](gitlab.md).
 
 ---
diff --git a/doc/administration/high_availability/pgbouncer.md b/doc/administration/high_availability/pgbouncer.md
deleted file mode 100644
index 380bf515e85..00000000000
--- a/doc/administration/high_availability/pgbouncer.md
+++ /dev/null
@@ -1,57 +0,0 @@
-## Enabling PgBouncer
-
-PgBouncer is now bundled as part of the GitLab EE package, and can be used as a connection pooler for the built in PostgreSQL database.
-
-To enable pgbouncer do the following:
-
-__Note__: The password digests can be obtained by running: `echo -n 'PASSWORD + USERNAME' | md5sum`
-
-### On the database server ensure at least the following attributes are set:
-```ruby
-postgresql['listen_address'] = '0.0.0.0'
-postgresql['trust_auth_cidr_addresses'] = ['127.0.0.1/32']
-
-# CIDR should be the cidr address of the pgbouncer server that will be connecting to the database.
-postgresql['md5_auth_cidr_addresses'] = ['CIDR']
-
-# The default for postgresql['sql_user'] is `gitlab`, this is the account that the GitLab application uses to connect to the database.
-postgresql['sql_user_password'] = 'PASSWORD_HASH'
-
-# The default for `postgresql['pgbouncer_user']` is `pgbouncer`, this will be the user that the pgbouncer service uses to authenticate to the database.
-# Both `postgresql['pgbouncer_user']` and `postgresql['pgbouncer_user_password']` should match what is set in the next step for the pgbouncer server.
-postgresql['pgbouncer_user_password'] = 'PASSWORD_HASH'
-```
-
-### On the pgbouncer server, the following attributes should be set
-```ruby
-pgbouncer['enable'] = true
-pgbouncer['databases'] = {
-  # By default, this is `gitlabhq_production`.
-  # If you've changed `gitlab_rails['gitlabhq_production']` then this needs to be the same value.
-  your_database_name: {
-    host: HOSTNAME,
-    # The user, and the password hash should be the same as what is on the database server
-    user: USERNAME,
-    password: PASSWORD_HASH
-  }
-}
-```
-You can specify multiple databases in `pgbouncer['databases']` if required.
-
-### On the server which will be running gitlab-rails, ensure the following attributes are set:
-```ruby
-gitlab_rails['db_adapter'] = "postgresql"
-gitlab_rails['db_encoding'] = "utf8"
-gitlab_rails['db_host'] = 'IP_OF_PGBOUNCER'
-gitlab_rails['db_port'] = 6432
-gitlab_rails['db_username'] = "gitlab"
-
-# The plain text password you want to use for the database user.
-gitlab_rails['db_password'] = 'PASSWORD'
-```
-
-For security purposes, run the following to ensure that `/etc/gitlab/gitlab.rb` cannot be accessed by just anyone:
-1. `chown root:root /etc/gitlab/gitlab.rb`
-1. `chmod 0600 /etc/gitlab/gitlab.rb`
-
-Run `gitlab-ctl reconfigure` on all of the servers in order for GitLab to pick up the new settings.