This document assumes you already have your own PostgreSQL database.
To use an external database with the
gitlab chart, there are a few prerequisites.
- GitLab requires PostgreSQL 11.x or newer
- An empty database to use, named by default:
gitlabhq_production. See below how to change the default name.
btree_gistextensions must be available. GitLab will attempt to load both extensions if not present. If not providing an account with Superuser flag to GitLab, please ensure this extension is loaded prior to proceeding with the database installation.
- A user with full access granted to the database above.
- A Kubernetes Secret with the password for the user above.
- Ensure that the database is reachable from the cluster. Be sure firewall policies are in place to allow traffic.
btree_gistextensions need to be added to the GitLab database. This means that the
CREATE EXTENSIONcommand should be executed while connected to the GitLab database (by default named
gitlabhq_production) and not the PostgreSQL default database.
If planning to use PostgreSQL as a load balancing cluster and using Kubernetes
DNS for service discovery, then when installing the
it is recommended to install the chart with
This will properly setup the PostgreSQL secondary service as a headless service to
allow DNS A records to be created for each secondary instance. Please examine the
for an example of using Kubernetes DNS for service discovery.
You need to set the following parameters:
postgresql.install: Set to
falseto disable the embedded database.
global.psql.host: Set to the hostname of the external database, can be a domain or an IP address.
global.psql.password.secret: The name of the secret which contains the database password for the
global.psql.password.key: The key within the secret, which contains the password.
Items below can be further customized if you are not using the defaults:
global.psql.port: The port the database is available on, defaults to
global.psql.database: The name of the database.
global.psql.username: The user with access to the database.
If you use a mutual TLS connection to the database:
global.psql.ssl.secret: A secret containing client certificate, key and certificate authority.
global.psql.ssl.serverCA: The key inside the secret referring the certificate authority (CA).
global.psql.ssl.clientCertificate: The key inside the secret referring the client certificate.
global.psql.ssl.clientKey: The client inside the secret.
For example, pass these values via Helm’s
--set flag while deploying:
helm install gitlab gitlab/gitlab --set postgresql.install=false --set global.psql.host=psql.example --set global.psql.password.secret=gitlab-postgresql-password --set global.psql.password.key=postgres-password