Configure the GitLab chart with an external Redis

This document intends to provide documentation on how to configure this Helm chart with an external Redis service.

If you don’t have Redis configured, for on-premise or deployment to VM, consider using our Omnibus GitLab package.

Configure the chart

Disable the redis chart and the Redis service it provides, and point the other services to the external service.

You must set the following parameters:

  • redis.install: Set to false to disable including the Redis chart.
  • Set to the hostname of the external Redis, can be a domain or an IP address.
  • global.redis.password.enabled: Set to false if the external Redis does not require a password.
  • global.redis.password.secret: The name of the secret which contains the token for authentication.
  • global.redis.password.key: The key in the secret, which contains the token content.

Items below can be further customized if you are not using the defaults:

  • global.redis.port: The port the database is available on, defaults to 6379.

For example, pass these values via Helm’s --set flag while deploying:

helm install gitlab gitlab/gitlab  \
  --set redis.install=false \
  --set \
  --set global.redis.password.secret=gitlab-redis \
  --set global.redis.password.key=redis-password \

If you are connecting to a Redis HA cluster that has Sentinel servers running, the attribute needs to be set to the name of the Redis instance group (such as mymaster or resque), as specified in the sentinel.conf. Sentinel servers can be referenced using the global.redis.sentinels[0].host and global.redis.sentinels[0].port values for the --set flag. The index is zero based.

Use multiple Redis instances

GitLab supports splitting several of the resource intensive Redis operations across multiple Redis instances. This chart supports distributing those persistence classes to other Redis instances.

More detailed information on configuring the chart for using multiple Redis instances can be found in the globals documentation.

Specify secure Redis scheme (SSL)

To connect to Redis using SSL, use the rediss (note the double s) scheme parameter:

--set global.redis.scheme=rediss

redis.yml override

If you want to override the contents of the redis.yml config file introduced in GitLab 15.8 you can do so by defining values under global.redis.redisYmlOverride. All values and sub-values under that key will be rendered into redis.yml as-is.

The global.redis.redisYmlOverride setting is intended for use with external Redis services. You must set redis.install to false. See configure Redis settings for further details.


  install: false
        password: <%='/path/to/secret').strip.to_json %>
          nested: value

Assuming /path/to/secret contains THE SECRET, his will cause the following to be rendered in redis.yml:

    password: "THE SECRET"
      nested: value

Things to look out for

The flip side of the flexibility of redisYmlOverride is that it is less user friendly. For example:

  1. To insert passwords into redis.yml you must write correct ERB <%='/path/to/secret').strip.to_json %> statements yourself, using whatever path the secret is mounted in the container at.
  2. In redisYmlOverride you must follow the naming conventions of GitLab Rails. For example, the “SharedState” instance is not called sharedState but shared_state.
  3. There is no inheritance of configuration values. For example, if you have three Redis instances that share a single set of Sentinels, you have to repeat the Sentinel configuration three times.
  4. The CNG images expect a valid resque.yml and cable.yml so you still need to configure at least to get a resque.yml file.