336 lines
10 KiB
Markdown
336 lines
10 KiB
Markdown
---
|
|
stage: Systems
|
|
group: Distribution
|
|
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
|
|
---
|
|
|
|
# Configuring Redis
|
|
|
|
DETAILS:
|
|
**Tier:** Free, Premium, Ultimate
|
|
**Offering:** Self-managed
|
|
|
|
## 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`:
|
|
|
|
```ruby
|
|
# 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>'
|
|
```
|
|
|
|
1. Reconfigure GitLab for the changes to take effect:
|
|
|
|
```shell
|
|
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`:
|
|
|
|
```ruby
|
|
redis['port'] = 6379
|
|
redis['bind'] = '127.0.0.1'
|
|
```
|
|
|
|
1. Save the file and reconfigure GitLab for the changes to take effect:
|
|
|
|
```shell
|
|
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](https://docs.gitlab.com/ee/administration/redis/standalone.html).
|
|
|
|
## Running with multiple Redis instances
|
|
|
|
See <https://docs.gitlab.com/ee/administration/redis/replication_and_failover.html#running-multiple-redis-clusters>.
|
|
|
|
## Redis Sentinel
|
|
|
|
See <https://docs.gitlab.com/ee/administration/redis/replication_and_failover.html>.
|
|
|
|
## Using Redis in a failover setup
|
|
|
|
See <https://docs.gitlab.com/ee/administration/redis/replication_and_failover.html>.
|
|
|
|
## Using Google Cloud Memorystore
|
|
|
|
Google Cloud Memorystore [does not support the Redis `CLIENT` command](https://cloud.google.com/memorystore/docs/redis/product-constraints#blocked_redis_commands).
|
|
By default, Sidekiq will attempt to set the `CLIENT` for debugging
|
|
purposes. This can be disabled via the following configuration setting:
|
|
|
|
```ruby
|
|
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`)
|
|
|
|
```ruby
|
|
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.
|
|
|
|
```ruby
|
|
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.
|
|
|
|
```ruby
|
|
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](https://redis.io/docs/latest/operate/rs/databases/memory-performance/eviction-policy/). 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 32GB, you can use:
|
|
|
|
```ruby
|
|
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`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/files/gitlab-cookbooks/redis/templates/default/redis.conf.erb)
|
|
to learn about the possible values:
|
|
|
|
```ruby
|
|
redis['tls_port']
|
|
redis['tls_cert_file']
|
|
redis['tls_key_file']
|
|
```
|
|
|
|
1. After specifying the required values, reconfigure GitLab for the changes to take
|
|
effect:
|
|
|
|
```shell
|
|
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`](https://redis.io/blog/stunnel-secure-redis-ssl/) 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`:
|
|
|
|
```ruby
|
|
gitlab_rails['redis_ssl'] = true
|
|
```
|
|
|
|
1. Reconfigure GitLab for the changes to take effect:
|
|
|
|
```shell
|
|
sudo gitlab-ctl reconfigure
|
|
```
|
|
|
|
## SSL certificates
|
|
|
|
If you're using custom SSL certificates for Redis, be sure to add them
|
|
to the [trusted certificates](../settings/ssl/index.md#install-custom-public-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:
|
|
|
|
```ruby
|
|
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.
|
|
1. `''`, which completely disables the command.
|
|
|
|
To disable this functionality:
|
|
|
|
1. Set `redis['rename_commands'] = {}` in your `/etc/gitlab/gitlab.rb` file
|
|
1. Run `sudo gitlab-ctl reconfigure`
|
|
|
|
## Lazy freeing
|
|
|
|
Redis 4 introduced [lazy freeing](http://antirez.com/news/93). This can improve performance when freeing large values.
|
|
|
|
This setting defaults to `false`. To enable it, you can use:
|
|
|
|
```ruby
|
|
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:
|
|
|
|
```ruby
|
|
redis['io_threads'] = 4
|
|
redis['io_threads_do_reads'] = true
|
|
```
|
|
|
|
## Provide sensitive configuration to Redis clients without plain text storage
|
|
|
|
For more information, see the example in [configuration documentation](../settings/configuration.md#provide-redis-password-to-client-components).
|
|
|
|
## 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`.
|
|
|
|
1. If you see messages that look like:
|
|
|
|
```plaintext
|
|
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](#ssl-certificates).
|
|
|
|
1. Verify that the SSL certificate is working via [these troubleshooting steps](../settings/ssl/ssl_troubleshooting.md#custom-certificates-missing-or-skipped).
|
|
|
|
### 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`.
|
|
|
|
1. If you see messages that look like:
|
|
|
|
```plaintext
|
|
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."
|
|
```
|
|
|
|
1. Check that the Redis client password specified in `/etc/gitlab/gitlab.rb` is correct:
|
|
|
|
```ruby
|
|
gitlab_rails['redis_password'] = 'your-password-here'
|
|
```
|
|
|
|
1. If you are using the Linux package-provided Redis server, check that the server has the same password:
|
|
|
|
```ruby
|
|
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:
|
|
|
|
```shell
|
|
/opt/gitlab/embedded/bin/openssl s_client -connect redis-server:6379
|
|
```
|
|
|
|
1. Check `/var/opt/gitlab/gitlab-rails/etc/resque.yml`. You
|
|
should see something like:
|
|
|
|
```yaml
|
|
production:
|
|
url: rediss://:mypassword@redis-server:6379/
|
|
```
|
|
|
|
1. 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:
|
|
|
|
```shell
|
|
sudo /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket
|
|
```
|
|
|
|
- Redis via TCP:
|
|
|
|
```shell
|
|
sudo /opt/gitlab/embedded/bin/redis-cli -h 127.0.0.1 -p 6379
|
|
```
|
|
|
|
- Password to authenticate to Redis if required:
|
|
|
|
```shell
|
|
sudo /opt/gitlab/embedded/bin/redis-cli -h 127.0.0.1 -p 6379 -a <password>
|
|
```
|