Using the Praefect chart

The Praefect chart is used to manage a Gitaly cluster inside a GitLab installment deployed with the Helm charts.

Known Limitations

  1. Only a managed, default virtual storage is supported.
  2. TLS is not supported.
  3. The database has to be manually created.
  4. Migrating from an existing Gitaly setup to Praefect is not supported.


This chart depends on the resources in the Gitaly chart. By default, it will spin up 3 Gitaly Replicas.


The chart is disabled by default. To enable it as part of a chart deploy set global.praefect.enabled=true.

The default number of replicas to deploy is 3. This can be changed by setting global.praefect.gitalyReplicas to the desired number of replicas.

Creating the database

Praefect uses its own database to track its state. This has to be manually created in order for Praefect to be functional.

Note: These instructions assume you are using the bundled PostgreSQL server. If you are using your own server, there will be some variation in how you connect.
  1. Log into your database instance:

    kubectl exec -it $(kubectl get pods -l app=postgresql -o --no-headers) -- bash
    PGPASSWORD=$(cat $POSTGRES_POSTGRES_PASSWORD_FILE) psql -U postgres -d template1
  2. Create the database user:

    template1=# CREATE ROLE praefect WITH LOGIN;
  3. Set the database user password.

    By default, the shared-secrets chart will generate a secret for you.

    1. Fetch the password:

      kubectl get secret RELEASE_NAME-praefect-dbsecret -o jsonpath="{.data.secret}" | base64 --decode
    2. Set the password in the psql prompt:

      template1=# \password praefect
      Enter new password:
      Enter it again:
  4. Create the database:

    CREATE DATABASE praefect WITH OWNER praefect;

Installation command line options

The table below contains all the possible charts configurations that can be supplied to the helm install command using the --set flags.

Parameter Default Description
failover.enabled true Whether Praefect should perform failover on node failure
failover.readonlyAfter false Whether the nodes should be in read-only mode after failover
autoMigrate true Automatically run migrations on startup
electionStrategy sql See election strategy
image.repository The default image repository to use. Praefect is bundled as part of the Gitaly image praefect The name of the service to create
service.type ClusterIP The type of service to create
service.internalPort 8075 The internal port number that the Praefect pod will be listening on
service.externalPort 8075 The port number the Praefect service should expose in the cluster
logging.level   Log level
logging.format json Log format
logging.sentryDsn   Sentry DSN URL - Exceptions from Go server
logging.rubySentryDsn   Sentry DSN URL - Exceptions from gitaly-ruby
logging.sentryEnvironment   Sentry environment to be used for logging
metrics.enabled true  
metrics.port 9236  
securityContext.runAsUser 1000  
securityContext.fsGroup 1000