From a5c1e2e55e6345192cf01dc422c07b894195a0d2 Mon Sep 17 00:00:00 2001
From: Gabriel Mazetto <gabriel@gitlab.com>
Date: Thu, 14 Jul 2016 03:57:47 +0200
Subject: Added Redis Sentinel support documentation

---
 doc/administration/high_availability/redis.md | 107 ++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)

(limited to 'doc/administration/high_availability')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index f6153216f33..1adc681e98b 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -3,6 +3,113 @@
 You can choose to install and manage Redis yourself, or you can use GitLab
 Omnibus packages to help.
 
+## Experimental Redis Sentinel support
+
+Since 8.10 release, you can configure a list of Redis Sentinel servers that 
+will monitor a group of Redis servers to provide you with a standard failover
+support.
+
+There is currently one exception to the Sentinel support: **mail_room**, the
+component that process incoming emails.
+
+It doesn't support Sentinel yet, but we hope to integrate a future release 
+that does support it.
+
+To get a better understanding on how to correctly setup Sentinel, please read
+[Redis Sentinel documentation](http://redis.io/topics/sentinel) first, as
+faling to configure it correctly can lead to data-loss.
+
+### Redis setup
+
+You must have at least 2 Redis servers: 1 Master, 1 or more Slaves.
+They should be configured the same way and with similar server specs, as
+in a failover situation, any Slave can be elected as the new Master by
+the Sentinels servers.
+
+In a minimal setup, the only required change for the slaves in `redis.conf` 
+is the addition of a `slaveof` line pointing to the initial master like this:
+
+```conf
+slaveof 192.168.1.1 6379
+```
+
+You can increase the security by defining a `requirepass` configuration in
+the master:
+
+```conf
+requirepass "<password>
+```
+
+and adding this line to all the slave servers:
+
+```conf
+masterauth "<password>"
+```
+
+> **Note** This setup is not safe to be used by a machine accessible by the 
+internet. Use it in combination with tight firewall rules.
+
+### Sentinel setup
+
+The support for Sentinel in ruby have some [caveats](https://github.com/redis/redis-rb/issues/531). 
+While you can give any name for the `master-group-name` part of the 
+configuration, as in this example: 
+
+```conf
+sentinel monitor <master-group-name> <ip> <port> <quorum>`
+```
+
+For it to work in ruby, you have to use the "hostname" of the master redis
+server otherwhise you will get an error message like this one: 
+`Redis::CannotConnectError: No sentinels available.`.
+
+
+Here is an example configuration file (`sentinel.conf`) for a Sentinel node:
+ 
+```conf
+port 26379
+sentinel monitor master-redis.example.com 10.10.10.10 6379 1
+sentinel down-after-milliseconds master-redis.example.com 10000
+sentinel config-epoch master-redis.example.com 0
+sentinel leader-epoch locmaster-redis.example.comalhost 0
+```
+
+### GitLab setup
+
+You can enable or disable sentinel support at any time in new or existing
+installs. From the GitLab application perspective, all it requires is
+the correct credentials for the Master redis and for a few Sentinels nodes.
+
+It doesn't require a list of all sentinel nodes, as in case of a failure,
+the application will need to query only one of them.
+
+For a source based install, you must change `/home/git/gitlab/config/resque.yml`,
+following the example in `/home/git/gitlab/config/resque.yml.example` and
+uncommenting the sentinels line, changing to the correct server credentials,
+and resstart GitLab. 
+
+For a Omnibus install you have to add/change this lines from the 
+`/etc/gitlab/gitlab.rb` configuration file:
+ 
+```ruby
+gitlab['gitlab-rails']['redis_host'] = "master-redis.example.com"
+gitlab['gitlab-rails']['redis_port'] = 6379
+gitlab['gitlab-rails']['redis_password'] = "redis-secure-password-here"
+gitlab['gitlab-rails']['redis_socket'] = nil
+gitlab['gitlab-rails']['redis_sentinels'] = [
+  {'host' => '10.10.10.1', 'port' => 26379},
+  {'host' => '10.10.10.2', 'port' => 26379},
+  {'host' => '10.10.10.3', 'port' => 26379}
+]
+```
+
+After the change run the reconfigure command:
+
+```bash
+sudo gitlab-ctl reconfigure
+
+```
+
 ## Configure your own Redis server
 
 If you're hosting GitLab on a cloud provider, you can optionally use a
-- 
cgit v1.2.1