Skip to content

redis.md

Latest commit

 

History

History
416 lines (286 loc) · 13.7 KB

redis.md

File metadata and controls

416 lines (286 loc) · 13.7 KB
Raw
stage GitLab Delivery
group Operate
info To determine the technical writer assigned to the Stage/Group associated with this page, see <https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments>
title Configuring Redis

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed

{{< /details >}}

Using an alternate local Redis instance

Linux package installations include Redis by default. To direct the GitLab application to your own locally running Redis instance:

  1. Edit /etc/gitlab/gitlab.rb:

    # Disable the bundled Redis
redis['enable'] = false

# Redis via TCP
gitlab_rails['redis_host'] = '127.0.0.1'
gitlab_rails['redis_port'] = 6379

# OR Redis via Unix domain sockets
gitlab_rails['redis_socket'] = '/tmp/redis.sock' # defaults to /var/opt/gitlab/redis/redis.socket

# Password to Authenticate to alternate local Redis if required
gitlab_rails['redis_password'] = '<redis_password>'

  2. Reconfigure GitLab for the changes to take effect:

    sudo gitlab-ctl reconfigure

Making the bundled Redis reachable via TCP

Use the following settings if you want to make the Redis instance managed by the Linux package reachable via TCP:

  1. Edit /etc/gitlab/gitlab.rb:

    redis['port'] = 6379
redis['bind'] = '127.0.0.1'
redis['password'] = 'redis-password-goes-here'

  2. Save the file and reconfigure GitLab for the changes to take effect:

    sudo gitlab-ctl reconfigure

Setting up a Redis-only server using the Linux package

If you'd like to set up Redis in a separate server than the GitLab application, you can use the bundled Redis from a Linux package installation.

Running with multiple Redis instances

See https://docs.gitlab.com/administration/redis/replication_and_failover/#running-multiple-redis-clusters.

Redis Sentinel

See https://docs.gitlab.com/administration/redis/replication_and_failover/.

Using Redis in a failover setup

See https://docs.gitlab.com/administration/redis/replication_and_failover/.

Using Google Cloud Memorystore

Google Cloud Memorystore does not support the Redis CLIENT command. By default, Sidekiq will attempt to set the CLIENT for debugging purposes. This can be disabled via the following configuration setting:

gitlab_rails['redis_enable_client'] = false

Increasing the number of Redis connections beyond the default

By default Redis will only accept 10,000 client connections. If you need more that 10,000 connections set the maxclients attribute to suit your needs. Be advised that adjusting the maxclients attribute means that you will also need to take into account your systems settings for fs.file-max (for example sysctl -w fs.file-max=20000)

redis['maxclients'] = 20000

Tuning the TCP stack for Redis

The following settings are to enable a more performant Redis server instance. tcp_timeout is a value set in seconds that the Redis server waits before terminating an idle TCP connection. The tcp_keepalive is a tunable setting in seconds to TCP ACKs to clients in absence of communication.

redis['tcp_timeout'] = "60"
redis['tcp_keepalive'] = "300"

Announce IP from hostname

Currently the only way to enable hostnames in Redis is by setting redis['announce_ip']. However, this would need to be set uniquely per Redis instance. announce_ip_from_hostname is a boolean that allows us to turn this on or off. It fetches the hostname dynamically, inferring the hostname from hostname -f command.

redis['announce_ip_from_hostname'] = true

Setting the Redis Cache instance as an LRU

Using multiple Redis instances allows you to configure Redis as a Least Recently Used cache. Note you should only do this for the Redis cache, rate-limiting, and repository cache instances; the Redis queues, shared state instances, and tracechunks instances should never be configured as an LRU, since they contain data (e.g. Sidekiq jobs) that is expected to be persistent.

To cap memory usage at 32 GB, you can use:

redis['maxmemory'] = "32gb"
redis['maxmemory_policy'] = "allkeys-lru"
redis['maxmemory_samples'] = 5

Using Secure Sockets Layer (SSL)

You can configure Redis to run behind SSL.

Running Redis server behind SSL

  1. To run Redis server behind SSL, you can use the following settings in /etc/gitlab/gitlab.rb. See the TLS/SSL section of redis.conf.erb to learn about the possible values:

    redis['tls_port']
redis['tls_cert_file']
redis['tls_key_file']

  2. After specifying the required values, reconfigure GitLab for the changes to take effect:

    sudo gitlab-ctl reconfigure

Note

Some redis-cli binaries are not built with support for directly connecting to a Redis server over TLS. If your redis-cli doesn't support the --tls flag, you will have to use something like stunnel to connect to the Redis server using redis-cli for any debugging purposes.

Make GitLab client connect to Redis server over SSL

To activate GitLab client support for SSL:

  1. Add the following line to /etc/gitlab/gitlab.rb:

    gitlab_rails['redis_ssl'] = true

  2. Reconfigure GitLab for the changes to take effect:

    sudo gitlab-ctl reconfigure

SSL certificates

If you're using custom SSL certificates for Redis, be sure to add them to the trusted certificates.

Renamed commands

By default, the KEYS command is disabled as a security measure.

If you'd like to obfuscate or disable this command, or other commands, edit the redis['rename_commands'] setting in /etc/gitlab/gitlab.rb to look like:

redis['rename_commands'] = {
  'KEYS': '',
  'OTHER_COMMAND': 'VALUE'
}
  • OTHER_COMMAND is the command you want to modify
  • VALUE should be one of:
    1. A new command name.
    2. '', which completely disables the command.

To disable this functionality:

  1. Set redis['rename_commands'] = {} in your /etc/gitlab/gitlab.rb file
  2. Run sudo gitlab-ctl reconfigure

Lazy freeing

Redis 4 introduced lazy freeing. This can improve performance when freeing large values.

This setting defaults to false. To enable it, you can use:

redis['lazyfree_lazy_eviction'] = true
redis['lazyfree_lazy_expire'] = true
redis['lazyfree_lazy_server_del'] = true
redis['replica_lazy_flush'] = true

Threaded I/O

Redis 6 introduced threaded I/O. This allow writes to scale across multiple cores.

This setting is disabled by default. To enable it, you can use:

redis['io_threads'] = 4
redis['io_threads_do_reads'] = true

Client Timeouts

By default, the Ruby client for Redis uses a 1-second default for the connect, read, and write timeouts. You may need to tune these values to account for local network latency. For example, if you see Connection timed out - user specified timeout errors, you may need to raise connect_timeout:

gitlab_rails['redis_connect_timeout'] = 3
gitlab_rails['redis_read_timeout'] = 1
gitlab_rails['redis_write_timeout'] = 1

Provide sensitive configuration to Redis clients without plain text storage

For more information, see the example in configuration documentation.

Using Valkey instead of Redis

{{< history >}}

{{< /history >}}

Valkey is a Redis-compatible key-value store that can be used as a drop-in replacement for Redis. Valkey is compatible with Redis OSS 7.2 and all earlier open source Redis versions.

When using Valkey:

  • The service name remains redis. Use gitlab-ctl restart redis to manage the service, not gitlab-ctl restart valkey.

  • Log files are written to /var/log/gitlab/redis/, not a separate valkey directory.

  • The data directory remains /var/opt/gitlab/redis/.

  • The configuration file remains redis.conf.

  • gitlab-ctl toolings still use redis-cli for Redis interactions.

  • When using valkey-cli for troubleshooting, use the same socket, host, and port as you would with redis-cli:

    sudo /opt/gitlab/embedded/bin/valkey-cli -s /var/opt/gitlab/redis/redis.socket

For more information about migrating from Redis to Valkey, see the Valkey migration documentation.

Switch to Valkey

To use Valkey instead of Redis:

  1. Edit /etc/gitlab/gitlab.rb:

    redis['backend'] = 'valkey'

  2. Reconfigure GitLab for the changes to take effect:

    sudo gitlab-ctl reconfigure

When redis['backend'] is set to valkey:

  • The Redis service uses valkey-server instead of redis-server.
  • The Sentinel service uses valkey-sentinel instead of redis-sentinel.
  • All other Redis settings (ports, passwords, paths, etc.) remain the same.

Service management

To ensure backward compatibility and a seamless transition, the service structure remains consistent regardless of whether you use Redis or Valkey as the backend:

  • The service name is redis. Use gitlab-ctl restart redis to manage the service.

  • Log files are written to /var/log/gitlab/redis/.

  • The data directory is /var/opt/gitlab/redis/.

  • The configuration file is redis.conf.

  • gitlab-ctl commands use the appropriate CLI tool (redis-cli or valkey-cli) based on the configured backend.

  • For troubleshooting, use the wrapper script which automatically detects the active backend:

    sudo gitlab-redis-cli

For more information about migrating from Redis to Valkey, see the Valkey migration documentation.

Troubleshooting

x509: certificate signed by unknown authority

This error message suggests that the SSL certificates have not been properly added to the list of trusted certificates for the server. To check whether this is an issue:

  1. Check Workhorse logs in /var/log/gitlab/gitlab-workhorse/current.

  2. If you see messages that look like:

    2018-11-14_05:52:16.71123 time="2018-11-14T05:52:16Z" level=info msg="redis: dialing" address="redis-server:6379" scheme=rediss
2018-11-14_05:52:16.74397 time="2018-11-14T05:52:16Z" level=error msg="unknown error" error="keywatcher: x509: certificate signed by unknown authority"

    The first line should show rediss as the scheme with the address of the Redis server. The second line indicates the certificate is not properly trusted on this server. See the previous section.

  3. Verify that the SSL certificate is working via these troubleshooting steps.

NOAUTH Authentication required

A Redis server may require a password sent via an AUTH message before commands are accepted. A NOAUTH Authentication required error message suggests the client is not sending a password. GitLab logs may help troubleshoot this error:

  1. Check Workhorse logs in /var/log/gitlab/gitlab-workhorse/current.

  2. If you see messages that look like:

    2018-11-14_06:18:43.81636 time="2018-11-14T06:18:43Z" level=info msg="redis: dialing" address="redis-server:6379" scheme=rediss
2018-11-14_06:18:43.86929 time="2018-11-14T06:18:43Z" level=error msg="unknown error" error="keywatcher: pubsub receive: NOAUTH Authentication required."

  3. Check that the Redis client password specified in /etc/gitlab/gitlab.rb is correct:

    gitlab_rails['redis_password'] = 'your-password-here'

  4. If you are using the Linux package-provided Redis server, check that the server has the same password:

    redis['password'] = 'your-password-here'

Redis connection reset (ECONNRESET)

If you see Redis::ConnectionError: Connection lost (ECONNRESET) in the GitLab Rails logs (/var/log/gitlab-rails/production.log), this might indicate that the server is expecting SSL but the client is not configured to use it.

  1. Check that the server is actually listening to the port via SSL. For example:

    /opt/gitlab/embedded/bin/openssl s_client -connect redis-server:6379

  2. Check /var/opt/gitlab/gitlab-rails/etc/resque.yml. You should see something like:

    production:
  url: rediss://:mypassword@redis-server:6379/

  3. If redis:// is present instead of rediss://, the redis_ssl parameter may not have been configured properly, or the reconfigure step may not have been run.

Connecting to Redis via the CLI

When connecting to Redis for troubleshooting you can use:

  • Redis via Unix domain sockets:

    sudo /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket

  • Redis via TCP:

    sudo /opt/gitlab/embedded/bin/redis-cli -h 127.0.0.1 -p 6379

  • Password to authenticate to Redis if required:

    sudo /opt/gitlab/embedded/bin/redis-cli -h 127.0.0.1 -p 6379 -a <password>