Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 144 lines (101 sloc) 9.004 kb
d9cf607 @ryanlecompte readme tweaks
authored
1 # Automatic Redis Failover Client / Node Manager
03af476 @ryanlecompte initial node manager / watcher implementation
authored
2
67af319 @ryanlecompte setup travis
authored
3 [![Build Status](https://secure.travis-ci.org/ryanlecompte/redis_failover.png?branch=master)](http://travis-ci.org/ryanlecompte/redis_failover)
4
8c73168 @ryanlecompte tweaks to README
authored
5 redis_failover attempts to provides a full automatic master/slave failover solution for Ruby. Redis does not provide
f6fe0a2 @ryanlecompte update readme
authored
6 an automatic failover capability when configured for master/slave replication. When the master node dies,
7 a new master must be manually brought online and assigned as the slave's new master. This manual
6284360 @ryanlecompte more readme updates
authored
8 switch-over is not desirable in high traffic sites where Redis is a critical part of the overall
9 architecture. The existing standard Redis client for Ruby also only supports configuration for a single
f6fe0a2 @ryanlecompte update readme
authored
10 Redis server. When using master/slave replication, it is desirable to have all writes go to the
11 master, and all reads go to one of the N configured slaves.
12
56c93ef @ryanlecompte readme updates for zookeeper
authored
13 This gem attempts to address these failover scenarios. A redis failover Node Manager daemon runs as a background
14 process and monitors all of your configured master/slave nodes. When the daemon starts up, it
15 automatically discovers the current master/slaves. Background watchers are setup for each of
fa80a02 @ryanlecompte honor slave-serve-stale-data configuration option to avoid reading from ...
authored
16 the redis nodes. As soon as a node is detected as being offline, it will be moved to an "unavailable" state.
6284360 @ryanlecompte more readme updates
authored
17 If the node that went offline was the master, then one of the slaves will be promoted as the new master.
18 All existing slaves will be automatically reconfigured to point to the new master for replication.
fa80a02 @ryanlecompte honor slave-serve-stale-data configuration option to avoid reading from ...
authored
19 All nodes marked as unavailable will be periodically checked to see if they have been brought back online.
56c93ef @ryanlecompte readme updates for zookeeper
authored
20 If so, the newly available nodes will be configured as slaves and brought back into the list of available
21 nodes. Note that detection of a node going down should be nearly instantaneous, since the mechanism
6ea7328 @ryanlecompte more updates
authored
22 used to keep tabs on a node is via a blocking Redis BLPOP call (no polling). This call fails nearly
088c142 @ryanlecompte readme updates
authored
23 immediately when the node actually goes offline. To avoid false positives (i.e., intermittent flaky
56c93ef @ryanlecompte readme updates for zookeeper
authored
24 network interruption), the Node Manager will only mark a node as unavailable if it fails to communicate with
654ccf0 @ryanlecompte add support for multiple node managers
authored
25 it 3 times (this is configurable via --max-failures, see configuration options below). Note that you can
26 deploy multiple Node Manager daemons for added redundancy.
f6fe0a2 @ryanlecompte update readme
authored
27
28 This gem provides a RedisFailover::Client wrapper that is master/slave aware. The client is configured
56c93ef @ryanlecompte readme updates for zookeeper
authored
29 with a list of ZooKeeper servers. The client will automatically contact the ZooKeeper cluster to find out
30 the current state of the world (i.e., who is the current master and who are the current slaves). The client
31 also sets up a ZooKeeper watcher for the set of redis nodes controlled by the Node Manager daemon. When the daemon
32 promotes a new master or detects a node as going down, ZooKeeper will notify the client near-instantaneously so
33 that it can rebuild its set of Redis connections. The client also acts as a load balancer in that it will automatically
cc9837e @ryanlecompte add max retries setting, node_watcher specs
authored
34 dispatch Redis read operations to one of N slaves, and Redis write operations to the master.
56c93ef @ryanlecompte readme updates for zookeeper
authored
35 If it fails to communicate with any node, it will go back and fetch the current list of available servers, and then
36 optionally retry the operation.
03af476 @ryanlecompte initial node manager / watcher implementation
authored
37
38 ## Installation
39
a8c1ffa @ryanlecompte more README tweaks
authored
40 redis_failover has an external dependency on ZooKeeper. You must have a running ZooKeeper cluster already available in order to use redis_failover. ZooKeeper provides redis_failover with its high availability and data consistency between Redis::Failover clients and the Node Manager daemon. Please see the requirements section below for more information on installing and setting up ZooKeeper if you don't have it running already.
9f1dbd3 @ryanlecompte more README updates
authored
41
03af476 @ryanlecompte initial node manager / watcher implementation
authored
42 Add this line to your application's Gemfile:
43
44 gem 'redis_failover'
45
46 And then execute:
47
48 $ bundle
49
50 Or install it yourself as:
51
52 $ gem install redis_failover
53
56c93ef @ryanlecompte readme updates for zookeeper
authored
54 ## Node Manager Daemon Usage
f6fe0a2 @ryanlecompte update readme
authored
55
56c93ef @ryanlecompte readme updates for zookeeper
authored
56 The Node Manager is a simple process that should be run as a background daemon. The daemon supports the
f6fe0a2 @ryanlecompte update readme
authored
57 following options:
58
56c93ef @ryanlecompte readme updates for zookeeper
authored
59 Usage: redis_node_manager [OPTIONS]
60 -p, --password password Redis password (optional)
61 -n, --nodes redis nodes Comma-separated redis host:port pairs (required)
dd46da1 @ryanlecompte better exception handling for reconnects
authored
62 -z zookeeper servers, Comma-separated ZooKeeper host:port pairs (required)
56c93ef @ryanlecompte readme updates for zookeeper
authored
63 --zkservers
a878fc6 @ryanlecompte add default znode path override option
authored
64 --znode-path path Znode path override for storing redis server list (optional)
56c93ef @ryanlecompte readme updates for zookeeper
authored
65 --max-failures count Max failures before manager marks node unavailable (default 3)
f6fe0a2 @ryanlecompte update readme
authored
66 -h, --help Display all options
67
56c93ef @ryanlecompte readme updates for zookeeper
authored
68 To start the daemon for a simple master/slave configuration, use the following:
f6fe0a2 @ryanlecompte update readme
authored
69
56c93ef @ryanlecompte readme updates for zookeeper
authored
70 redis_node_manager -n localhost:6379,localhost:6380 -z localhost:2181,localhost:2182,localhost:2183
f6fe0a2 @ryanlecompte update readme
authored
71
56c93ef @ryanlecompte readme updates for zookeeper
authored
72 The Node Manager will automatically discover the master/slaves upon startup. Note that it is
654ccf0 @ryanlecompte add support for multiple node managers
authored
73 a good idea to run more than one instance of the Node Manager daemon in your environment. At
74 any moment, a single Node Manager process will be designated to monitor the redis servers. If
75 this Node Manager process dies or becomes partitioned from the network, another Node Manager
76 will be promoted as the primary monitor of redis servers. You can run as many Node Manager
77 processes as you'd like for added redundancy.
f6fe0a2 @ryanlecompte update readme
authored
78
79 ## Client Usage
80
56c93ef @ryanlecompte readme updates for zookeeper
authored
81 The redis failover client must be used in conjunction with a running Node Manager daemon. The
82 client supports various configuration options, however the only mandatory option is the list of
83 ZooKeeper servers:
f6fe0a2 @ryanlecompte update readme
authored
84
56c93ef @ryanlecompte readme updates for zookeeper
authored
85 client = RedisFailover::Client.new(:zkservers => 'localhost:2181,localhost:2182,localhost:2183')
f6fe0a2 @ryanlecompte update readme
authored
86
87 The client actually employs the common redis and redis-namespace gems underneath, so this should be
88 a drop-in replacement for your existing pure redis client usage.
89
90 The full set of options that can be passed to RedisFailover::Client are:
91
dd46da1 @ryanlecompte better exception handling for reconnects
authored
92 :zkservers - comma-separated ZooKeeper host:port pairs (required)
a878fc6 @ryanlecompte add default znode path override option
authored
93 :znode_path - the Znode path override for redis server list (optional)
56c93ef @ryanlecompte readme updates for zookeeper
authored
94 :password - password for redis nodes (optional)
9679b7f @ryanlecompte add support for specifying :db option
authored
95 :db - db to use for redis nodes (optional)
56c93ef @ryanlecompte readme updates for zookeeper
authored
96 :namespace - namespace for redis nodes (optional)
97 :logger - logger override (optional)
f6fe0a2 @ryanlecompte update readme
authored
98 :retry_failure - indicate if failures should be retried (default true)
cc9837e @ryanlecompte add max retries setting, node_watcher specs
authored
99 :max_retries - max retries for a failure (default 3)
f6fe0a2 @ryanlecompte update readme
authored
100
dabdeae @ryanlecompte add requirements to readme
authored
101 ## Requirements
102
1bfe0aa @ryanlecompte add JRuby 1.6.7 (1.9 mode only) support
authored
103 - redis_failover is actively tested against MRI 1.9.2/1.9.3 and JRuby 1.6.7 (1.9 mode only). Other rubies may work, although I don't actively test against them. 1.8 is not supported.
089cd36 @ryanlecompte fix typos
authored
104 - redis_failover requires a ZooKeeper service cluster to ensure reliability and data consistency. ZooKeeper is very simple and easy to get up and running. Please refer to this [Quick ZooKeeper Guide](https://github.com/ryanlecompte/redis_failover/wiki/Quick-ZooKeeper-Guide) to get up and running quickly if you don't already have ZooKeeper as a part of your environment.
dabdeae @ryanlecompte add requirements to readme
authored
105
c8c49e3 @ryanlecompte add reconcile feature, incorporate code review comments from eric
authored
106 ## Considerations
107
e477ee3 @ryanlecompte update considerations
authored
108 - Note that by default the Node Manager will mark slaves that are currently syncing with their master as "available" based on the configuration value set for "slave-serve-stale-data" in redis.conf. By default this value is set to "yes" in the configuration, which means that slaves still syncing with their master will be available for servicing read requests. If you don't want this behavior, just set "slave-serve-stale-data" to "no" in your redis.conf file.
109
110 - Note that it's still possible for the RedisFailover::Client instances to see a stale list of servers for a very small window. In most cases this will not be the case due to how ZooKeeper handles distributed communication, but you should be aware that in the worst case the client could write to a "stale" master for a small period of time until the next watch event is received by the client via ZooKeeper.
6b6c973 @ryanlecompte add limitations section
authored
111
11ef378 @ryanlecompte add TODO to readme
authored
112 ## TODO
113
56c93ef @ryanlecompte readme updates for zookeeper
authored
114 - Rework specs to work against a set of real Redis/ZooKeeper nodes as opposed to stubs.
11ef378 @ryanlecompte add TODO to readme
authored
115
6284360 @ryanlecompte more readme updates
authored
116 ## Resources
117
56c93ef @ryanlecompte readme updates for zookeeper
authored
118 - To learn more about Redis master/slave replication, see the [Redis documentation](http://redis.io/topics/replication).
119 - To learn more about ZooKeeper, see the official [ZooKeeper](http://zookeeper.apache.org/) site.
e4a861b @ryanlecompte add link to new wiki page
authored
120 - See the [Quick ZooKeeper Guide](https://github.com/ryanlecompte/redis_failover/wiki/Quick-ZooKeeper-Guide) for a quick guide to getting ZooKeeper up and running with redis_failover.
d10d3f4 @ryanlecompte add link to zookeeper failure scenarios wiki page
authored
121 - To learn more about how ZooKeeper handles network partitions, see [ZooKeeper Failure Scenarios](http://wiki.apache.org/hadoop/ZooKeeper/FailureScenarios)
6284360 @ryanlecompte more readme updates
authored
122
f6fe0a2 @ryanlecompte update readme
authored
123 ## License
124
125 Please see LICENSE for licensing details.
126
127 ## Author
03af476 @ryanlecompte initial node manager / watcher implementation
authored
128
6eb4902 @ryanlecompte Update README.md
authored
129 Ryan LeCompte
5f7da19 @ryanlecompte Update README.md
authored
130
6eb4902 @ryanlecompte Update README.md
authored
131 [@ryanlecompte](https://twitter.com/ryanlecompte)
03af476 @ryanlecompte initial node manager / watcher implementation
authored
132
454f02a @ryanlecompte add acknowledgements section
authored
133 ## Acknowledgements
134
135 Special thanks to [Eric Lindvall](https://github.com/eric) and [Jonathan Simms](https://github.com/slyphon) for their invaluable ZooKeeper advice and guidance!
136
03af476 @ryanlecompte initial node manager / watcher implementation
authored
137 ## Contributing
138
139 1. Fork it
140 2. Create your feature branch (`git checkout -b my-new-feature`)
141 3. Commit your changes (`git commit -am 'Added some feature'`)
142 4. Push to the branch (`git push origin my-new-feature`)
143 5. Create new Pull Request
Something went wrong with that request. Please try again.