ansible-redis

• Works with Ansible 2.4 and above
• Compatible with most Ubuntu/Debian and RHEL/CentOS 6.x versions

Contents

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

Installation

$ ansible-galaxy install davidwittman.redis

Getting Started

Here are some example playbooks and settings to help you deploy different Redis setups.

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

Single Redis Node

Setting up a single Redis server is straightforward. Just include the role in your playbook. Here's an example where we set the bind address to 127.0.0.1:

---
- hosts: redis01.example.com
  vars:
    - redis_bind: 127.0.0.1
  roles:
    - davidwittman.redis

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

Note: You can see that I used just a hostname for the Ansible inventory file. This makes it easier to run Ansible without creating a separate inventory file. Just add a comma after the hostname.

Now you have a Redis server listening on 127.0.0.1 at redis01.example.com. By default, Redis binaries are installed in /opt/redis, which you can change by setting the redis_install_dir variable.

Master-Slave Replication

To set up replication in Redis, you deploy multiple nodes and set the redis_slaveof variable in slave nodes, just like in the redis.conf. In the example below, we will set up a Redis master with three slaves.

We'll use groups to separate the master and slave nodes. Here’s how the inventory file looks:

[redis-master]
redis-master.example.com

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

And here’s the playbook:

---
- name: Configure the master Redis server
  hosts: redis-master
  roles:
    - davidwittman.redis

- name: Configure Redis slaves
  hosts: redis-slave
  vars:
    - redis_slaveof: redis-master.example.com 6379
  roles:
    - davidwittman.redis

This assumes you have DNS for redis-master.example.com set up. You can also use the eth1 IP address for the master. Here’s a more flexible variable:

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

Running this playbook will give you one Redis master and three slaves.

Redis Sentinel

Introduction

Using Master-Slave replication is good for durability and distributing loads, but it doesn’t handle high availability well. If the master fails, a slave must be promoted to master manually, and connections redirected. This is where Redis Sentinel comes in. It’s a distributed system that helps manage automatic failovers in a Redis cluster.

Sentinel operates using the same redis-server binary but runs with the --sentinel flag and a different config file. This is managed through this Ansible role, but it's useful to know how it works.

Configuration

To add a Sentinel node to an existing setup, use the same redis role, setting the redis_sentinel variable to True for that host. We can extend our previous inventory file like this:

[redis-master]
redis-master.example.com

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

[redis-sentinel]
redis-sentinel0[1:3].example.com redis_sentinel=True

Next, we need to set the redis_sentinel_monitors variable in the playbook to define which Redis masters Sentinel should monitor:

- name: Configure the master Redis server
  hosts: redis-master
  roles:
    - davidwittman.redis

- name: Configure Redis slaves
  hosts: redis-slave
  vars:
    - redis_slaveof: redis-master.example.com 6379
  roles:
    - davidwittman.redis

- name: Configure Redis sentinel nodes
  hosts: redis-sentinel
  vars:
    - redis_sentinel_monitors:
      - name: master01
        host: redis-master.example.com
        port: 6379
  roles:
    - davidwittman.redis

This sets up the Sentinel nodes to monitor the master we set up before, assigned the name master01. By default, Sentinel needs at least 2 Sentinels to agree a master is down to trigger a failover. You can modify this with the quorum key in your monitor definition. Check the Sentinel docs for more details.

Sentinel has its own configurations similar to Redis server settings, prefixed with redis_sentinel_, which are further detailed in the Role Variables section below.

Multiple Role Inclusions

If you need to run the role multiple times, check out test/test_all.yml for guidance. See more information here and here.

Advanced Options

Verifying Checksums

You can enable checksum verification by setting the redis_verify_checksum variable to true. This checks the SHA-1 checksum when Redis is downloaded from a URL, not when provided in a tarball with redis_tarball.

For Ansible 2.x, this role will verify downloads against checksums in the redis_checksums variable in vars/main.yml. If your version isn't listed, or you want to use your own checksum, set the redis_checksum variable like this:

- name: Install Redis on Ansible 1.x and verify checksums
  hosts: all
  roles:
    - role: davidwittman.redis
      redis_version: 3.0.7
      redis_verify_checksum: true
      redis_checksum: "sha256:b2a791c4ea3bb7268795c45c6321ea5abcc24457178373e6a6e3be6372737f23"

Install from Local Tarball

If your server environment doesn’t allow downloads (like in a DMZ), set the redis_tarball variable to the path of a local Redis tarball instead of downloading it.

Make sure the version variable matches the tarball version to avoid confusion! For example:

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

This way, the source archive is copied via SSH rather than downloaded.

Building 32-bit Binaries

To create 32-bit binaries of Redis for memory optimization, set redis_make_32bit: true. This installs required dependencies (x86 glibc) on RHEL/Debian/SuSE and sets the '32bit' option when running make.

Building with TLS Support

To enable Redis with TLS support (added in version 6), set redis_make_tls: true. Ensure you have the OpenSSL development libraries installed (like libssl-dev on Debian/Ubuntu).

Role Variables

Here’s a list of default variables for this role, found in defaults/main.yml.

---
## Installation options
redis_version: 2.8.24
redis_install_dir: /opt/redis
redis_dir: /var/lib/redis/{{ redis_port }}
redis_config_file_name: "{{ redis_port }}.conf"
redis_download_url: "http://download.redis.io/releases/redis-{{ redis_version }}.tar.gz"
redis_verify_checksum: false
redis_tarball: false
redis_make_32bit: false
redis_make_tls: false

redis_user: redis
redis_group: "{{ redis_user }}"

redis_nofile_limit: 16384

## Role options
redis_as_service: true
redis_local_facts: true
redis_service_name: "redis_{{ redis_port }}"

## Networking/connection options
redis_bind: false
redis_port: 6379
redis_password: false
redis_min_slaves_to_write: 0
redis_min_slaves_max_lag: 10
redis_tcp_backlog: 511
redis_tcp_keepalive: 0
redis_maxclients: 10000
redis_timeout: 0
redis_socket_path: false
redis_socket_perm: 755

## Replication options
redis_slaveof: false
redis_slave_read_only: "yes"
redis_slave_priority: 100
redis_repl_backlog_size: false

## Logging
redis_logfile: '""'
redis_syslog_enabled: "yes"
redis_syslog_ident: "{{ redis_service_name }}"
redis_syslog_facility: USER

## General configuration
redis_daemonize: "yes"
redis_pidfile: /var/run/redis/{{ redis_port }}.pid
redis_databases: 16
redis_loglevel: notice
redis_slowlog_log_slower_than: 10000
redis_slowlog_max_len: 128
redis_maxmemory: false
redis_maxmemory_policy: noeviction
redis_rename_commands: []
redis_db_filename: dump.rdb
redis_save:
  - 900 1
  - 300 10
  - 60 10000
redis_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: '""'

## Additional configuration options
redis_config_additional: ""

## Redis sentinel configs
redis_sentinel: false
redis_sentinel_dir: /var/lib/redis/sentinel_{{ redis_sentinel_port }}
redis_sentinel_bind: 0.0.0.0
redis_sentinel_port: 26379
redis_sentinel_password: false
redis_sentinel_pidfile: /var/run/redis/sentinel_{{ redis_sentinel_port }}.pid
redis_sentinel_logfile: '""'
redis_sentinel_syslog_ident: sentinel_{{ redis_sentinel_port }}
redis_sentinel_monitors:
  - name: master01
    host: localhost
    port: 6379
    quorum: 2
    auth_pass: ant1r3z
    down_after_milliseconds: 30000
    parallel_syncs: 1
    failover_timeout: 180000
    notification_script: false
    client_reconfig_script: false
    rename_commands: []

Facts

You can access the following facts 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 }}

If you want to disable these facts, set redis_local_facts to false.