Repository files navigation

• Ansible 2.1+
• Compatible with most versions of Ubuntu/Debian and RHEL/CentOS 6.x

1. Installation
2. Getting Started
3. Single Redis node
4. Master-Slave Replication
5. Redis Sentinel
6. Advanced Options
7. Verifying checksums
8. Install from local tarball
9. Building 32-bit binaries
10. Role Variables

$ ansible-galaxy install davidwittman.redis

Below are a few example playbooks and configurations for deploying a variety of Redis architectures.

This role expects to be run as root or as a user with sudo privileges.

Deploying a single Redis server node is pretty trivial; just add the role to your playbook and go. Here's an example which we'll make a little more exciting by setting the bind address to 127.0.0.1:

----hosts:redis01.example.comvars:    -redis_bind:127.0.0.1roles:    -davidwittman.redis

$ ansible-playbook -i redis01.example.com, redis.yml

Note: You may have noticed above that I just passed a hostname in as the Ansible inventory file. This is an easy way to run Ansible without first having to create an inventory file, you just need to suffix the hostname with a comma so Ansible knows what to do with it.

That's it! You'll now have a Redis server listening on 127.0.0.1 on redis01.example.com. By default, the Redis binaries are installed under /opt/redis, though this can be overridden by setting theredis_install_dir variable.

Configuringreplication in Redis is accomplished by deploying multiple nodes, and setting theredis_slaveof variable on the slave nodes, just as you would in the redis.conf. In the example that follows, we'll deploy a Redis master with three slaves.

In this example, we're going to use groups to separate the master and slave nodes. Let's start with the inventory file:

[redis-master]redis-master.example.com[redis-slave]redis-slave0[1:3].example.com

And here's the playbook:

----name:configure the master redis serverhosts:redis-masterroles:    -davidwittman.redis-name:configure redis slaveshosts:redis-slavevars:    -redis_slaveof:redis-master.example.com 6379roles:    -davidwittman.redis

In this case, I'm assuming you have DNS records set up for redis-master.example.com, but that's not always the case. You can pretty much go crazy with whatever you need this to be set to. In many cases, I tell Ansible to use the eth1 IP address for the master. Here's a more flexible value for the sake of posterity:

redis_slaveof:"{{ hostvars['redis-master.example.com'].ansible_eth1.ipv4.address }} {{ redis_port }}"

Now you're cooking with gas! Running this playbook should have you ready to go with a Redis master and three slaves.

Using Master-Slave replication is great for durability and distributing reads and writes, but not so much for high availability. If the master node fails, a slave must be manually promoted to master, and connections will need to be redirected to the new master. The solution for this problem isRedis Sentinel, a distributed system which uses Redis itself to communicate and handle automatic failover in a Redis cluster.

Sentinel itself uses the same redis-server binary that Redis uses, but runs with the--sentinel flag and with a different configuration file. All of this, of course, is abstracted with this Ansible role, but it's still good to know.

To add a Sentinel node to an existing deployment, assign this sameredis role to it, and set the variableredis_sentinel to True on that particular host. This can be done in any number of ways, and for the purposes of this example I'll extend on the inventory file used above in the Master/Slave configuration:

[redis-master]redis-master.example.com[redis-slave]redis-slave0[1:3].example.com[redis-sentinel]redis-sentinel0[1:3].example.comredis_sentinel=True

Above, we've added three more hosts in theredis-sentinel group (though this group serves no purpose within the role, it's merely an identifier), and set theredis_sentinel variable inline within the inventory file.

Now, all we need to do is set theredis_sentinel_monitors variable to define the Redis masters which Sentinel should monitor. In this case, I'm going to do this within the playbook:

-name:configure the master redis serverhosts:redis-masterroles:    -davidwittman.redis-name:configure redis slaveshosts:redis-slavevars:    -redis_slaveof:redis-master.example.com 6379roles:    -davidwittman.redis-name:configure redis sentinel nodeshosts:redis-sentinelvars:    -redis_sentinel_monitors:      -name:master01host:redis-master.example.comport:6379roles:    -davidwittman.redis

This will configure the Sentinel nodes to monitor the master we created above using the identifiermaster01. By default, Sentinel will use a quorum of 2, which means that at least 2 Sentinels must agree that a master is down in order for a failover to take place. This value can be overridden by setting thequorum key within your monitor definition. See theSentinel docs for more details.

Along with the variables listed above, Sentinel has a number of its own configurables just as Redis server does. These are prefixed withredis_sentinel_, and are enumerated in theRole Variables section below.

Set theredis_verify_checksum variable to true to use the checksum verification option forget_url. Note that this will only verify checksums when Redis is downloaded from a URL, not when one is provided in a tarball withredis_tarball.

When using Ansible 2.x, this role will verify the sha1 checksum of the download against checksums defined in theredis_checksums variable invars/main.yml. If your version is not defined in here or you wish to override the checksum with one of your own, simply set theredis_checksum variable. As in the example below, you will need to prefix the checksum with the type of hash which you are using.

-name:install redis on ansible 1.x and verify checksumshosts:allroles:    -role:davidwittman.redisredis_version:3.0.7redis_verify_checksum:trueredis_checksum:"sha256:b2a791c4ea3bb7268795c45c6321ea5abcc24457178373e6a6e3be6372737f23"

If the environment your server resides in does not allow downloads (i.e. if the machine is sitting in a dmz) set the variableredis_tarball to the path of a locally downloaded Redis tarball to use instead of downloading over HTTP from redis.io.

Do not forget to set the version variable to the same version of the tarball to avoid confusion! For example:

vars:redis_version:2.8.14redis_tarball:/path/to/redis-2.8.14.tar.gz

In this case the source archive is copied to the server over SSH rather than downloaded.

To build 32-bit binaries of Redis (which can be used formemory optimization), setredis_make_32bit: true. This installs the necessary dependencies (x86 glibc) on RHEL/Debian/SuSE and sets the option '32bit' when running make.

Here is a list of all the default variables for this role, which are also available in defaults/main.yml. One of these days I'll format these into a table or something.

---## Installation optionsredis_version:2.8.24redis_install_dir:/opt/redisredis_dir:/var/lib/redis/{{ redis_port }}redis_download_url:"http://download.redis.io/releases/redis-{{ redis_version }}.tar.gz"# Set this to true to validate redis tarball checksum against vars/main.ymlredis_verify_checksum:false# Set this value to a local path of a tarball to use for installation instead of downloadingredis_tarball:false# Set this to true to build 32-bit binaries of Redisredis_make_32bit:falseredis_user:redisredis_group:"{{ redis_user }}"# The open file limit for Redis/Sentinelredis_nofile_limit:16384## Role options# Configure Redis as a service# This creates the init scripts for Redis and ensures the process is running# Also applies for Redis Sentinelredis_as_service:true# Add local facts to /etc/ansible/facts.d for Redisredis_local_facts:true# Service nameredis_service_name:"redis_{{ redis_port }}"## Networking/connection optionsredis_bind:0.0.0.0redis_port:6379redis_password:false# Slave replication optionsredis_min_slaves_to_write:0redis_min_slaves_max_lag:10redis_tcp_backlog:511redis_tcp_keepalive:0# Max connected clients at a timeredis_maxclients:10000redis_timeout:0# Socket options# Set socket_path to the desired path to the socket. E.g. /var/run/redis/{{ redis_port }}.sockredis_socket_path:falseredis_socket_perm:755## Replication options# Set slaveof just as you would in redis.conf. (e.g. "redis01 6379")redis_slaveof:false# Make slaves read-only. "yes" or "no"redis_slave_read_only:"yes"redis_slave_priority:100redis_repl_backlog_size:false## Loggingredis_logfile:'""'# Enable syslog. "yes" or "no"redis_syslog_enabled:"yes"redis_syslog_ident:"{{ redis_service_name }}"# Syslog facility. Must be USER or LOCAL0-LOCAL7redis_syslog_facility:USER## General configurationredis_daemonize:"yes"redis_pidfile:/var/run/redis/{{ redis_port }}.pid# Number of databases to allowredis_databases:16redis_loglevel:notice# Log queries slower than this many milliseconds. -1 to disableredis_slowlog_log_slower_than:10000# Maximum number of slow queries to saveredis_slowlog_max_len:128# Redis memory limit (e.g. 4294967296, 4096mb, 4gb)redis_maxmemory:falseredis_maxmemory_policy:noevictionredis_rename_commands:[]redis_db_filename:dump.rdb# How frequently to snapshot the database to disk# e.g. "900 1" => 900 seconds if at least 1 key changedredis_save:  -900 1  -300 10  -60 10000redis_stop_writes_on_bgsave_error:"yes"redis_rdbcompression:"yes"redis_rdbchecksum:"yes"redis_appendonly:"no"redis_appendfilename:"appendonly.aof"redis_appendfsync:"everysec"redis_no_appendfsync_on_rewrite:"no"redis_auto_aof_rewrite_percentage:"100"redis_auto_aof_rewrite_min_size:"64mb"redis_notify_keyspace_events:'""'## Redis sentinel configs# Set this to true on a host to configure it as a Sentinelredis_sentinel:falseredis_sentinel_dir:/var/lib/redis/sentinel_{{ redis_sentinel_port }}redis_sentinel_bind:0.0.0.0redis_sentinel_port:26379redis_sentinel_password:falseredis_sentinel_pidfile:/var/run/redis/sentinel_{{ redis_sentinel_port }}.pidredis_sentinel_logfile:'""'redis_sentinel_syslog_ident:sentinel_{{ redis_sentinel_port }}redis_sentinel_monitors:  -name:master01host:localhostport:6379quorum:2auth_pass:ant1r3zdown_after_milliseconds:30000parallel_syncs:1failover_timeout:180000notification_script:falseclient_reconfig_script:false

The following facts are accessible in your inventory or tasks outside of this role.

• {{ ansible_local.redis.bind }}
• {{ ansible_local.redis.port }}
• {{ ansible_local.redis.sentinel_bind }}
• {{ ansible_local.redis.sentinel_port }}
• {{ ansible_local.redis.sentinel_monitors }}

To disable these facts, setredis_local_facts to a false value.