diff --git a/doc/administration/database/app_configuration.md b/doc/administration/database/app_configuration.md new file mode 100644 index 0000000000000000000000000000000000000000..2d3d35c720f675d72acb3386f4392dd4bde1ce73 --- /dev/null +++ b/doc/administration/database/app_configuration.md @@ -0,0 +1,106 @@ +--- +type: reference +--- + +# Application services client database connection settings + +The Unicorn and Sidekiq application services are the primary database clients +in a GitLab instance. + +## Configuring statement timeout + +The amount of time that Unicorn or Sidekiq will wait for a database transaction +to complete before timing out can now be adjusted: + +**For Omnibus installations** + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['db_statement_timeout'] = 45000 # Specified in milliseconds + ``` + +1. Save the file and [reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) + GitLab for the changes to take effect. + +If `gitlab_rails['db_statement_timeout']` is not specified, Omnibus GitLab +uses the value of `postgresql['statement_timeout']` if present. Otherwise, a +default value of `60000` (60 seconds) is used. + +## Connecting to a PostgreSQL service over TCP/IP + +**For Omnibus installations** + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['db_adapter'] = 'postgresql' + gitlab_rails['db_encoding'] = 'utf8' + gitlab_rails['db_host'] = '10.1.0.5' # IP or hostname of PostgreSQL server + gitlab_rails['db_port'] = 5432 + gitlab_rails['db_username'] = 'gitlab' + gitlab_rails['db_password'] = 'database_password' + ``` + + NOTE: **Note:** + `/etc/gitlab/gitlab.rb` should have file permissions `0600` because it contains + plain-text passwords. + +1. Save the file and [reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) + GitLab for the changes to take effect. + +**For installations from source** + +Follow the [Configure GitLab DB Settings](../../install/installation.md#configure-gitlab-db-settings) section in the +installation from source documentation. + +### Verify server SSL certificate against CA bundle + +The application services can be configured to verify the PostgreSQL server +certificate against a CA bundle to prevent spoofing. + +**For Omnibus installations** + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['db_sslmode'] = 'verify-full' + gitlab_rails['db_sslrootcert'] = 'your-full-ca-bundle.pem' + ``` + + NOTE: **Note:** + The CA bundle that is specified in `gitlab_rails['db_sslrootcert']` must + contain both the root and intermediate certificates. + + NOTE: **Note:** + If you are using Amazon RDS for your PostgreSQL server, ensure you download + and use the [combined CA bundle](https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem) + for `gitlab_rails['db_sslrootcert']`. More information on this can be found + in the [Using SSL to Encrypt a Connection to a DB instance](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.SSL.html) + article on AWS. + +1. Save the file and [reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) + GitLab to apply the configuration changes. + +1. Restart PostgreSQL for the changes to take effect: + + ```shell + sudo gitlab-ctl restart postgresql + ``` + +## Disable automatic database migration + +If you have multiple GitLab servers sharing a database, you will want to limit +the number of nodes that are performing the migration steps during +reconfiguration. To do this: + +**For Omnibus installations** + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['auto_migrate'] = false + ``` + +The next time a reconfigure is triggered, the migration steps will not be +performed. diff --git a/doc/administration/database/external_database.md b/doc/administration/database/external_database.md new file mode 100644 index 0000000000000000000000000000000000000000..e0f4c60d05f1df757a42665b194ec67d6b708018 --- /dev/null +++ b/doc/administration/database/external_database.md @@ -0,0 +1,124 @@ +--- +type: reference +--- + +# Using an external PostgreSQL service with GitLab + +If you're hosting GitLab on a cloud provider, you can optionally use a +managed service for PostgreSQL. For example, AWS offers a managed Relational +Database Service (RDS) that runs PostgreSQL. + +Alternatively, you may opt to manage your own PostgreSQL instance or cluster +separate from the GitLab Omnibus package. + +## Setup + +### Requirements + +Your external PostgreSQL service needs to be set up according to the GitLab +[database requirements documentation](../../install/requirements.md#postgresql-requirements). + +You will also need to set up a user (Omnibus GitLab uses `gitlab` by default) +with a password of your choice. This user needs privileges to create the +`gitlabhq_production` database. + +### Configure application client services + +**For Omnibus installations** + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['db_adapter'] = 'postgresql' + gitlab_rails['db_encoding'] = 'utf8' + gitlab_rails['db_host'] = '10.1.0.5' # IP/hostname of database server + gitlab_rails['db_port'] = 5432 + gitlab_rails['db_username'] = 'gitlab' + gitlab_rails['db_password'] = 'database_password' + ``` + +1. Save the file and [reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) + GitLab for the changes to take effect. + +**For installations from source** + +Follow the [Configure GitLab DB Settings](../../install/installation.md#configure-gitlab-db-settings) section in the +installation from source documentation. + +NOTE: **Note:** +Additional application client service database connection options can be found +in the [application services database client configuration](app_configuration.md) +documentation. + +### Initialize the database (for fresh installs only) + +CAUTION: **Caution:** +This will drop your existing database and recreate it as though a fresh GitLab +install. Do not run it on a database with existing production data! + +**For Omnibus installations** + +Omnibus GitLab will not automatically seed your external database. Run the +following command to import the database schema and create the first admin user: + +```shell +sudo gitlab-rake gitlab:setup +``` + +**For installations from source** + +Follow the [Initialize Database](../../install/installation.md#initialize-database-and-activate-advanced-features) section in the +installation from source documentation. + +## Backup and restore using rake task + +When using the [rake backup create and restore task](../../raketasks/backup_restore.md), +GitLab will attempt to use the packaged `pg_dump` command to craete a database +backup file and the packaged `psql` command to restore a backup. This will only +work if they are the correct versions. To check the versions of the packaged +`pg_dump` and `psql`: + +```shell +/opt/gitlab/embedded/bin/pg_dump --version +/opt/gitlab/embedded/bin/psql --version +``` + +If these versions are different from your external PostgreSQL service, you will +need to install tools that match your database version and then follow the +steps below. There are multiple ways to install PostgreSQL client tools. See +the [PostgreSQL downloads page](https://www.postgresql.org/download/) for options. + +Once the correct `psql` and `pg_dump` tools are available on your system, +follow these steps, using the correct path to the location you installed the +new tools: + +1. Add symbolic links to the non-packaged versions: + + ```shell + ln -s /path/to/new/pg_dump /path/to/new/psql /opt/gitlab/bin/ + ``` + +1. Check the versions: + + ```shell + /opt/gitlab/bin/pg_dump --version + /opt/gitlab/bin/psql --version + ``` + + They should now be the same as your external PostgreSQL service. + +After this is done, ensure that the backup and restore tasks are using the +correct executables by running both the +[backup](../../raketasks/backup_restore.md#creating-a-backup-of-the-gitlab-system) +and [restore](../../raketasks/backup_restore.md#restore) tasks. + +## Upgrading the external PostgreSQL service + +From time to time, GitLab will require the use of a more recent major version +of PostgreSQL. When upgrading your external PostgreSQL service, you will also +need to run the `ANALYZE VERBOSE;` query against your database to recreate +query plans. + +CAUTION: **Caution:** +If you neglect to do so, you may see extremely high (near 100%) CPU utilization +following a major PostgreSQL version upgrade. diff --git a/doc/administration/database/index.md b/doc/administration/database/index.md new file mode 100644 index 0000000000000000000000000000000000000000..6ed895204f4c53b41ce58d8e067ecf64852ab694 --- /dev/null +++ b/doc/administration/database/index.md @@ -0,0 +1,392 @@ +--- +type: reference +--- + +# Database + +GitLab supports only the use of PostgreSQL as its database. + +NOTE: **Note:** +Prior to GitLab 12.1, MySQL was supported for Enterprise Edition licensed +instances. If you're using MySQL, you need to [migrate to PostgreSQL](../../update/mysql_to_postgresql.md) +before upgrade to 12.1 and beyond. + +This page documents administration tasks for the Omnibus-bundled PostgreSQL +service. For details on other aspects of GitLab database administration, please +read: + +- [Configuring the GitLab application services' database client](app_configuration.md) +- [Using an external database with GitLab](external_database.md) +- [Standalone PostgreSQL server using Omnibus GitLab](standalone_database.md) + +## Omnibus-bundled PostgreSQL + +### Connecting to the bundled PostgreSQL database + +If you need to connect to the bundled PostgreSQL database, you can +connect as the application user: + +```shell +sudo gitlab-rails dbconsole +``` + +or as a PostgreSQL superuser: + +```shell +sudo gitlab-psql -d gitlabhq_production +``` + +### Configuration + +#### Storing PostgreSQL data in a different directory + +CAUTION: **Caution:** +This is an intrusive operation. It cannot be done without downtime on an +existing installation. + +By default, Omnibus GitLab stores PostgreSQL-related data in the +`/var/opt/gitlab/postgresql` directory. To change it: + +1. Stop GitLab: + + ```shell + sudo gitlab-ctl stop + ``` + +1. If you have existing PostgreSQL data, copy them from the old location to the + new location. + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + postgresql['dir'] = '/path/to/postgresql' + ``` + +1. Save the file and [reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) + GitLab for the changes to take effect. + +1. Start GitLab: + + ```shell + sudo gitlab-ctl start + ``` + +Note that changing the setting affects the following items: + +- The actual PostgreSQL data, by default stored in `/var/opt/gitlab/postgresql/data`, + will now be stored in this directory in a `data` sub-directory. +- The Unix socket used to connect to PostgreSQL, by default located at + `/var/opt/gitlab/postgresql/.s.PGSQL.5432`, will be located in this directory. + This can be configured separately with the `postgresql['unix_socket_directory']` + configuration directive. +- The `HOME` directory of the `gitlab-psql` system will be set to this + directory. This can be configured separately with the `postgresql['home']` + configuration directive. + +#### Allowing PostgreSQL service to listen over TCP/IP + +The packaged PostgreSQL server can be configured to listen for TCP/IP +connections, with the caveat that some non-critical scripts expect UNIX sockets +and may misbehave. To enable it: + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + postgresql['listen_address'] = '0.0.0.0' + postgresql['port'] = 5432 + + # Configure the username and MD5 username-password hash used to access the + # GitLab database + postgresql['sql_user'] = 'gitlab' + postgresql['sql_user_password'] = 'database_password' + + # Configure the list of CIDR address blocks allowed to connect after password + # authentication + postgresql['md5_auth_cidr_addresses'] = %w(10.200.0.1/24 10.300.0.1/24) + + # Configure the list of CIDR address blocks allowed to connect without + # authentication of any kind. Be very careful with this with. It is suggested + # to limit this to the loopback address of 17.0.0.1/24 or even 127.0.0.1/32. + postgresql['trust_auth_cidr_addresses'] = %w(127.0.0.1/24) + ``` + +1. Save the file and [reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) + GitLab for the changes to take effect. + +#### Configuring PostgreSQL SSL mode + +Omnibus GitLab automatically enables SSL on the PostgreSQL service, but will +accept both encrypted and unencrypted connections by default. This behavior can +be adjusted by changing the [SSL mode](https://www.postgresql.org/docs/9.6/libpq-ssl.html#LIBPQ-SSL-PROTECTION) +that the PostgreSQL service runs in. To set this: + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + postgresql['db_sslmode'] = 'require' + ``` + +1. Save the file and [reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) + GitLab to apply the configuration changes. + +1. Restart PostgreSQL for the changes to take effect: + + ```shell + sudo gitlab-ctl restart postgresql + ``` + +If PostgreSQL fails to start, check the logs at `/var/log/gitlab/postgresql/current` +for more details. + +#### Configuring PostgreSQL to use a custom SSL certificate + +Omnibus GitLab automatically generates a self-signed certificate and private key +and stores them in the `/var/opt/gitlab/postgresql/data` directory by default. + +If you'd prefer to use a CA-signed certificate, you'll need: + +1. The public SSL certificate for the database (`server.crt`). +1. The corresponding private key for the SSL certificate (`server.key`). +1. A root certificate bundle that validates the server's certificate + (`cacert.pem`). By default, Omnibus GitLab will use the embedded certificate + bundle in `/opt/gitlab/embedded/ssl/certs/cacert.pem`. + +For more details, see the [PostgreSQL documentation](https://www.postgresql.org/docs/9.6/ssl-tcp.html). + +Note that `server.crt` and `server.key` may be different from the default SSL +certificates used to access GitLab. For example, suppose the external hostname +of your database is `database.example.com`, and your external GitLab hostname +is `gitlab.example.com`. You will either need a wildcard certificate for +`*.example.com` or two different SSL certificates. + +With these files in hand, enable SSL: + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + postgresql['ssl_cert_file'] = '/custom/path/to/server.crt' + postgresql['ssl_key_file'] = '/custom/path/to/server.key' + postgresql['ssl_ca_file'] = '/custom/path/to/cacert.pem' + postgresql['internal_certificate'] = "-----BEGIN CERTIFICATE----- + ...base64-encoded certificate... + -----END CERTIFICATE----- + " + postgresql['internal_key'] = "-----BEGIN RSA PRIVATE KEY----- + ...base64-encoded private key... + -----END RSA PRIVATE KEY----- + " + ``` + + Relative paths will be rooted from the PostgreSQL data directory + (`/var/opt/gitlab/postgresql/data` by default). + + NOTE: **Note:** + You must ensure that the `gitlab-psql` user can access the directory the + files are placed in and can read the private key. Omnibus will automatically + manage the permissions of the files for you. + +1. Save the file and [reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) + GitLab to apply the configuration changes. + +1. Restart PostgreSQL for the changes to take effect: + + ```shell + sudo gitlab-ctl restart postgresql + ``` + +### Verifying that SSL is being used + +To check whether SSL is being used by clients, you can run: + +```shell +sudo gitlab-rails dbconsole +``` + +At startup, you should see a banner as the following: + +```shell +psql (9.6.5) +SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: on) +Type "help" for help. +``` + +To check whether clients are using SSL, you can issue this SQL query: + +```sql +SELECT * FROM pg_stat_ssl; +``` + +For example: + +```sql +gitlabhq_production=> SELECT * FROM pg_stat_ssl; + pid | ssl | version | cipher | bits | compression | clientdn +-------+-----+---------+-----------------------------+------+-------------+---------- + 47506 | t | TLSv1.2 | ECDHE-RSA-AES256-GCM-SHA384 | 256 | t | + 47509 | t | TLSv1.2 | ECDHE-RSA-AES256-GCM-SHA384 | 256 | t | + 47510 | t | TLSv1.2 | ECDHE-RSA-AES256-GCM-SHA384 | 256 | t | + 47527 | t | TLSv1.2 | ECDHE-RSA-AES256-GCM-SHA384 | 256 | t | + 47528 | f | | | | | + 47537 | t | TLSv1.2 | ECDHE-RSA-AES256-GCM-SHA384 | 256 | t | + 47560 | f | | | | | + 47561 | f | | | | | + 47563 | t | TLSv1.2 | ECDHE-RSA-AES256-GCM-SHA384 | 256 | t | + 47564 | t | TLSv1.2 | ECDHE-RSA-AES256-GCM-SHA384 | 256 | t | + 47565 | f | | | | | + 47569 | f | | | | | + 47570 | t | TLSv1.2 | ECDHE-RSA-AES256-GCM-SHA384 | 256 | t | + 47573 | f | | | | | + 47585 | f | | | | | + 47586 | t | TLSv1.2 | ECDHE-RSA-AES256-GCM-SHA384 | 256 | t | + 47618 | t | TLSv1.2 | ECDHE-RSA-AES256-GCM-SHA384 | 256 | t | + 47628 | t | TLSv1.2 | ECDHE-RSA-AES256-GCM-SHA384 | 256 | t | + 55812 | t | TLSv1.2 | ECDHE-RSA-AES256-GCM-SHA384 | 256 | t | +(19 rows) +``` + +Rows that have `t` listed under the `ssl` column are enabled. + +### Upgrading + +Omnibus GitLab will automatically update PostgreSQL to the +[default shipped version](https://docs.gitlab.com/omnibus/package-information/postgresql_versions.md) +during package upgrades unless specifically opted out. + +To opt out of automatic PostgreSQL upgrade during GitLab package upgrades, run: + +```shell +sudo touch /etc/gitlab/disable-postgresql-upgrade +``` + +If you want to manually upgrade the PostgreSQL service, you can follow these +instructions: + +**Note:** + +- Fully read this section before running any commands. +- Plan ahead as upgrade involves downtime. +- If you encounter any problems during upgrade, please raise an issue with a + full description in the [Omnibus GitLab issue tracker](https://gitlab.com/gitlab-org/omnibus-gitlab). + +Before upgrading, check the following: + +- You're currently running the latest version of GitLab and it is working. +- If you recently upgraded, make sure that a [GitLab reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) + ran successfully before you proceed. +- You will need to have sufficiency disk space for two copies of your database. + **Do not attempt to upgrade unless you have enough free space available.** + Check your database size using `sudo su -sh /var/opt/gitlab/postgresql/data` + (or your database path, if customized) and space available using `sudo df -h`. + If the parition where the database resides does not have enough space, you can + pass the argument `--tmp-dir $DIR` to the command. + +NOTE: **Note:** +The upgrade requires downtime as the database must be down while the upgrade is +being performed. The length of downtime depends on the size of your database. If +you would rather avoid downtime, it is possible to upgrade to a new database +using [Slony](https://www.slony.info/). Please see our [guide](../../update/upgrading_postgresql_using_slony.md) +on how to perform the upgrade. + +Once you have confirmed that the above checklist is satisfied, you can proceed. +To perform the upgrade, run the command: + +```shell +sudo gitlab-ctl pg-upgrade +``` + +NOTE: **Note:** +In GitLab 12.8 or later, you can pass the `-V 11` flag to opt in to upgrading to PostgreSQL 11. + +This command performs the following steps: + +1. Checks to ensure the database is in a known good state +1. Shuts down the existing database, any unnecessary services, and enables the + GitLab deploy page. +1. Changes the symlinks in `/opt/gitlab/embedded/bin/` for PostgreSQL to point + to the newer version of the database +1. Creates a new directory containing a new, empty database with a locale + matching the existing database +1. Uses the `pg_upgrade` tool to copy the data from the old database to the new + database +1. Moves the old database out of the way +1. Moves the new database to the expected location +1. Calls `sudo gitlab-ctl reconfigure` to do the required configuration changes, + and start the new database server. +1. Start the remaining services, and remove the deploy page. +1. If any errors are detected during this process, it should immediately revert + to the old version of the database. + +Once this step is complete, verify everything is working as expected. + +Once this step is complete, verify everything is working as expected. + +**Once you have verified that your GitLab instance is running correctly**, +you can clean up the old database files with: + +```shell +sudo rm -rf /var/opt/gitlab/postgresql/data. +sudo rm -f /var/opt/gitlab/postgresql-version.old +``` + +You can find details of PostgreSQL versions shipped with various GitLab versions +in [PostgreSQL versions shipped with Omnibus GitLab](https://docs.gitlab.com/omnibus/package-information/postgresql_versions.md). +The following section details their update policy. + +#### GitLab 12.8 and later + +**As of GitLab 12.8, PostgreSQL 9.6.17, 10.12, and 11.7 are shipped with +Omnibus GitLab.** + +Automatically during package upgrades (unless opted out) and when user manually +runs `gitlab-ctl pg-upgrade`, `omnibus-gitlab` will still be attempting to +upgrade the database only to 10.x, while 11.x will be available for users to +manually upgrade to. To manually update PostgreSQL to version 11.x , the `pg-upgrade` +command has to be passed with a version argument (`-V` or `--target-version`) + +```shell +sudo gitlab-ctl pg-upgrade -V 11 +``` + +NOTE: **Note:** +We **DO NOT** recommend updating to PostgreSQL 11.x on GitLab instances making use of +GitLab Geo for replication, as we have not yet completed PostgreSQL 11 testing with GitLab +Geo. We will be [completing this work](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/4975) +in a future release. + +#### GitLab 12.0 and later + +**As of GitLab 12.0, PostgreSQL 9.6.11 and 10.7 are shipped with Omnibus +GitLab.** + +On upgrades, we will be automatically upgrading the database to 10.7 unless +specifically opted out as described above. + +#### GitLab 11.11 and later + +**As of GitLab 11.11, PostgreSQL 9.6.X and 10.7 are shipped with Omnibus +GitLab.** + +Fresh installs will be getting PostgreSQL 10.7 while GitLab package upgrades +will retain the existing version of PostgreSQL. Users can manually upgrade to +the 10.7 using the `pg-upgrade` command as mentioned above. + +### Downgrading + +On GitLab versions which ship multiple PostgreSQL versions, users can downgrade +an already upgraded PostgreSQL version to the earlier version using: + +```shell +sudo gitlab-ctl revert-pg-upgrade +``` + +This command also supports the `-V` flag to specify a target version for +scenarios where more than two PostgreSQL versions are shipped in the package. +For example, GitLab 12.8 ships with PostgreSQL 9.6.x, 10.x and 11.x. + +If the target version is not specified, it will use the version in +`/var/opt/gitlab/postgresql-version.old` if available. Otherwise, it falls back +to the default version shipped with GitLab. + +On other GitLab versions which ship only one PostgreSQL version, you can't +downgrade your PostgreSQL version. You must downgrade GitLab to an older version +to do this. diff --git a/doc/administration/database/standalone_database.md b/doc/administration/database/standalone_database.md new file mode 100644 index 0000000000000000000000000000000000000000..3366cba2c75203b7d697334c62aad680e3e61dfd --- /dev/null +++ b/doc/administration/database/standalone_database.md @@ -0,0 +1,60 @@ +# Standalone PostgreSQL server using Omnibus GitLab **(CORE ONLY)** + +You can use the GitLab Omnibus package to easily deploy the bundled PostgreSQL. + +1. SSH into the PostgreSQL server. +1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab + package you want using **steps 1 and 2** from the GitLab downloads page. + - Do not complete any other steps on the download page. +1. Generate a password hash for PostgreSQL. This assumes you will use the default + username of `gitlab` (recommended). The command will request a password + and confirmation. Use the value that is output by this command in the next + step as the value of `POSTGRESQL_PASSWORD_HASH`. + + ```shell + sudo gitlab-ctl pg-password-md5 gitlab + ``` + +1. Edit `/etc/gitlab/gitlab.rb` and add the contents below, updating placeholder + values appropriately. + + - `POSTGRESQL_PASSWORD_HASH` - The value output from the previous step + - `APPLICATION_SERVER_IP_BLOCKS` - A space delimited list of IP subnets or IP + addresses of the GitLab application servers that will connect to the + database. Example: `%w(123.123.123.123/32 123.123.123.234/32)` + + ```ruby + # Disable all components except PostgreSQL + roles ['postgres_role'] + repmgr['enable'] = false + consul['enable'] = false + prometheus['enable'] = false + alertmanager['enable'] = false + pgbouncer_exporter['enable'] = false + redis_exporter['enable'] = false + gitlab_exporter['enable'] = false + + postgresql['listen_address'] = '0.0.0.0' + postgresql['port'] = 5432 + + # Replace POSTGRESQL_PASSWORD_HASH with a generated md5 value + postgresql['sql_user_password'] = 'POSTGRESQL_PASSWORD_HASH' + + # Replace XXX.XXX.XXX.XXX/YY with Network Address + # ???? + postgresql['trust_auth_cidr_addresses'] = %w(APPLICATION_SERVER_IP_BLOCKS) + + # Disable automatic database migrations + gitlab_rails['auto_migrate'] = false + ``` + + NOTE: **Note:** The role `postgres_role` was introduced with GitLab 10.3 + +1. [Reconfigure GitLab] for the changes to take effect. +1. Note the PostgreSQL node's IP address or hostname, port, and + plain text password. These will be necessary when configuring the GitLab + application servers later. +1. [Enable monitoring] + +Advanced configuration options are supported and can be added if +needed. diff --git a/doc/administration/external_database.md b/doc/administration/external_database.md index ec2d30c82d1f6da6d3c97c9078c1efb37342ad5b..e50761d98cacaa3629d016e1fa138265a333251e 100644 --- a/doc/administration/external_database.md +++ b/doc/administration/external_database.md @@ -1,17 +1,3 @@ # Configure GitLab using an external PostgreSQL service -If you're hosting GitLab on a cloud provider, you can optionally use a -managed service for PostgreSQL. For example, AWS offers a managed Relational -Database Service (RDS) that runs PostgreSQL. - -Alternatively, you may opt to manage your own PostgreSQL instance or cluster -separate from the GitLab Omnibus package. - -If you use a cloud-managed service, or provide your own PostgreSQL instance: - -1. Set up PostgreSQL according to the - [database requirements document](../install/requirements.md#database). -1. Set up a `gitlab` username with a password of your choice. The `gitlab` user - needs privileges to create the `gitlabhq_production` database. -1. Configure the GitLab application servers with the appropriate details. - This step is covered in [Configuring GitLab for HA](high_availability/gitlab.md). +This content has been moved to the [database administration page](database/index.md). diff --git a/doc/administration/high_availability/database.md b/doc/administration/high_availability/database.md index 4362ed3e64b24c5b4b5d83cdf626ae9d3845622a..04c6dbc47d0e794da85c10df0a2fce527643c70f 100644 --- a/doc/administration/high_availability/database.md +++ b/doc/administration/high_availability/database.md @@ -2,95 +2,22 @@ type: reference --- -# Configuring PostgreSQL for Scaling and High Availability +# Configuring PostgreSQL for High Availability In this section, you'll be guided through configuring a PostgreSQL database to be used with GitLab in a highly available environment. ## Provide your own PostgreSQL instance **(CORE ONLY)** -If you're hosting GitLab on a cloud provider, you can optionally use a -managed service for PostgreSQL. For example, AWS offers a managed Relational -Database Service (RDS) that runs PostgreSQL. - -If you use a cloud-managed service, or provide your own PostgreSQL: - -1. Set up PostgreSQL according to the - [database requirements document](../../install/requirements.md#database). -1. Set up a `gitlab` username with a password of your choice. The `gitlab` user - needs privileges to create the `gitlabhq_production` database. -1. Configure the GitLab application servers with the appropriate details. - This step is covered in [Configuring GitLab for HA](gitlab.md). +This content has been moved to the [database administration page](../database/index.md). ## PostgreSQL in a Scaled and Highly Available Environment This section is relevant for [Scalable and Highly Available Setups](README.md). -### Provide your own PostgreSQL instance **(CORE ONLY)** - -If you want to use your own deployed PostgreSQL instance(s), -see [Provide your own PostgreSQL instance](#provide-your-own-postgresql-instance-core-only) -for more details. However, you can use the GitLab Omnibus package to easily -deploy the bundled PostgreSQL. - ### Standalone PostgreSQL using GitLab Omnibus **(CORE ONLY)** -1. SSH into the PostgreSQL server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page. - - Do not complete any other steps on the download page. -1. Generate a password hash for PostgreSQL. This assumes you will use the default - username of `gitlab` (recommended). The command will request a password - and confirmation. Use the value that is output by this command in the next - step as the value of `POSTGRESQL_PASSWORD_HASH`. - - ```shell - sudo gitlab-ctl pg-password-md5 gitlab - ``` - -1. Edit `/etc/gitlab/gitlab.rb` and add the contents below, updating placeholder - values appropriately. - - - `POSTGRESQL_PASSWORD_HASH` - The value output from the previous step - - `APPLICATION_SERVER_IP_BLOCKS` - A space delimited list of IP subnets or IP - addresses of the GitLab application servers that will connect to the - database. Example: `%w(123.123.123.123/32 123.123.123.234/32)` - - ```ruby - # Disable all components except PostgreSQL - roles ['postgres_role'] - repmgr['enable'] = false - consul['enable'] = false - prometheus['enable'] = false - alertmanager['enable'] = false - pgbouncer_exporter['enable'] = false - redis_exporter['enable'] = false - gitlab_exporter['enable'] = false - - postgresql['listen_address'] = '0.0.0.0' - postgresql['port'] = 5432 - - # Replace POSTGRESQL_PASSWORD_HASH with a generated md5 value - postgresql['sql_user_password'] = 'POSTGRESQL_PASSWORD_HASH' - - # Replace XXX.XXX.XXX.XXX/YY with Network Address - # ???? - postgresql['trust_auth_cidr_addresses'] = %w(APPLICATION_SERVER_IP_BLOCKS) - - # Disable automatic database migrations - gitlab_rails['auto_migrate'] = false - ``` - - NOTE: **Note:** The role `postgres_role` was introduced with GitLab 10.3 - -1. [Reconfigure GitLab] for the changes to take effect. -1. Note the PostgreSQL node's IP address or hostname, port, and - plain text password. These will be necessary when configuring the GitLab - application servers later. -1. [Enable monitoring](#enable-monitoring) - -Advanced configuration options are supported and can be added if -needed. +This content has been moved to the [database administration page](../database/index.md). ### High Availability with GitLab Omnibus **(PREMIUM ONLY)**