redis

Table of Contents

1. Overview - What is the redis module?
2. Setup - The basics of getting started with redis
   • Beginning with redis - Installation
   • Run multiple instances on same host
   • [Create a cluster-enabled instance](#Create a cluster-enable instance)
   • Setting up sentinel with two monitors
3. Usage - The class and defined types available for configuration
   • Classes and Defined Types
     • Class: redis::install
     • Defined Type: redis::server
     • Defined Type: redis::sentinel
4. Limitations - OS compatibility, etc.
5. Contributing to the redis module

Overview

This module installs and makes basic configs for multiple redis instances on the same node. It installs redis via REPO or from source. (http://redis.io/) It also can configure the monitoring server Sentinel.

Setup

What redis affects:

• packages/configuration to compile and install redis from source
• services/configuration files to run multiple redis and sentinels

Beginning with redis

To just compile and install redis binaries. As default the latest stable release will be used.

  class { 'redis::install': }

To install a specific redis version use the following parameters. Most of the time you will only need redis_version.

  class { 'redis::install':
    redis_version     => '2.8.8',
    redis_build_dir   => '/opt',
    redis_install_dir => '/usr/bin'
  }

To install redis from package use the following parameters. You will need redis_version and redis_package.

  class { 'redis::install':
    redis_version  => '2.8.18-1.el6.remi',
    redis_package  => true,
  }

Run multiple instances on same host

As example run two redis instances on port 6379 and 6380.

node 'redis.my.domain' {

  # install latest stable build.
  class { 'redis::install': }

  redis::server {
    'instance1':
      redis_memory    => '1g',
      redis_ip        => '0.0.0.0',
      redis_port      => 6379,
      redis_mempolicy => 'allkeys-lru',
      redis_timeout   => 0,
      redis_nr_dbs    => 16,
      redis_loglevel  => 'notice',
      running         => true,
      enabled         => true
  }

  redis::server {
    'secondRedis':
      redis_memory    => '112m',
      redis_ip        => '0.0.0.0',
      redis_port      => 6380,
      redis_mempolicy => 'allkeys-lru',
      redis_timeout   => 0,
      redis_nr_dbs    => 2,
      redis_loglevel  => 'warning',
      running         => true,
      enabled         => true
  }
}

Run highly available on different hosts

As example of running a high availability cluster with authentication enabled.

node 'redis-master.my.domain' {

  # install latest stable build.
  class { 'redis::install': }

  redis::server {
    'master':
      redis_memory               => '1g',
      redis_ip                   => '0.0.0.0',
      redis_port                 => 6379,
      running                    => true,
      enabled                    => true,
      requirepass                => 'some_really_long_random_password',
      client_output_buffer_limit => {
        'normal' => '0 0 0',
        'slave'  => '500000000 300000000 60',
      },
  }
}

node 'redis-slave.my.domain' {

  # install latest stable build.
  class { 'redis::install': }

  redis::server {
    'slave':
      redis_memory    => '1g',
      redis_ip        => '0.0.0.0',
      redis_port      => 6379,
      running         => true,
      enabled         => true,
      requirepass     => 'some_really_long_random_password',
      slaveof         => 'redis-master.my.domain 6379',
      masterauth      => 'some_really_long_random_password',
  }
}

Create a cluster-enable instance

Please note that right now you can only create cluster-enabled instances but you cannot configure a Redis Cluster only with this module. You should still use redis-trib.rb from Redis source distribution or configure it by hand with redis cluster commands. Moreover, the cluster mode will be enabled only for Redis >= 3.0

A simple example of a cluster-enabled instance, with a timeout of 5 seconds to detect if another node is dead.

node 'redis-cluster.my.domain' {

  # install latest stable build.
  class { 'redis::install': }

  redis::server {
    'cluster-instance':
      redis_memory         => '1g',
      redis_ip             => '0.0.0.0',
      redis_port           => 6379,
      running              => true,
      enabled              => true,
      cluster_enabled      => true,
      cluster_node_timeout => '5000',
  }
}

Example using Hiera

redis::install::redis_package: true
redis::install::redis_version: '2:2.8.17-1+deb8u1'
redis::servers:
  'name_server':
    requirepass: 'strongpass'
    enabled: true
    redis_ip: '0.0.0.0'
    redis_port: '6800'
    redis_log_dir: '/var/log/redis/'

Setting up sentinel with two monitors

You can create multiple sentinels on one node. But most of the time you will want to create a sentinel with one or more monitors configured.

node 'sentinel.my.domain' {

  # install latest stable build.
  class { 'redis::install': redis_version => '2.8.8' }

  redis::sentinel {'clusters':
    monitors => {
      'mymaster' => {
        master_host             => '127.0.0.1',
        master_port             => 6378,
        quorum                  => 2,
        down_after_milliseconds => 30000,
        parallel-syncs          => 1,
        failover_timeout        => 180000
      },
      'securetRedisCluster' => {
        master_host             => '10.20.30.1',
        master_port             => 6379,
        quorum                  => 2,
        down_after_milliseconds => 30000,
        parallel-syncs          => 5,
        failover_timeout        => 180000,
        auth-pass => 'secret_Password',
        notification-script => '/tmp/notify.sh',
        client-reconfig-script => '/tmp/reconfig.sh'
      }
    }
  }

Usage

Classes and Defined Types

This module compiles and installs redis with the class redis::install. The redis service(s) are configured with the defined type redis::server.

Class: redis::install

This class downloads, compiles and installs redis. It does not configure any redis services. This is done by defined type redis::server.

Parameters within redis::install:

redis_version

The redis version to be installed. By default, the latest stable build will be installed.

redis_build_dir

Default is '/opt/' (string) The dir to store redis source code. This will result in a directoy like '/opt/redis-2.8.8/'

redis_install_dir

Default is '/usr/bin' (string). The dir to which the newly built redis binaries are copied.

redis_user

Redis system user. Default: undef (string) Default 'undef' results to 'root' as redis system user

Some redis install packages create the redis system user by default (at least SLES and Ubuntu provide redis install packages). Normally the log directory and the pid directory are created also by the redis install package. Therefor, these values must be adjusted too.

redis_group

Redis system group. Default: undef (string) Default 'undef' results to 'root' as redis system group

download_base

Url where to find the source tar.gz. Default value is 'http://download.redis.io/releases'

Defined Type: redis::server

Used to configure redis instances. You can setup multiple redis servers on the same node. See the setup examples.

**Parameters within redis::server

redis_name

Name of Redis instance. Default: call name of the function. The name is used to create the init script(s), which follows the pattern redis-server_${redis_name}

redis_memory

Default is '100mb' (string). Sets amount of memory used. eg. 100mb or 4g.

redis_ip

Default is '127.0.0.1' (string). Listen IP of redis.

redis_port

Listen port of Redis. Default: 6379

redis_usesocket

To enable unixsocket options. Default: false

redis_socket

Unix socket to use. Default: /tmp/redis.sock

redis_socketperm

Permission of socket file. Default: 755

redis_mempolicy

Algorithm used to manage keys. See Redis docs for possible values. Default: allkeys-lru

redis_memsamples

Number of samples to use for LRU policies. Default: 3

redis_timeout

Default: 0

redis_nr_dbs

Number of databases provided by redis. Default: 1

redis_dbfilename

Name of database dump file. Default: dump.rdb

redis_dir

Default is '/var/lib' (string) Path for persistent data. Path is <redisdir>/redis<redis_name>/.

redis_pid_dir

Default is '/var/run' (string). Path for pidfile. Full pidfile path is <redispid_dir>/redis<redis_name>.pid.

redis_log_dir

Default is '/var/log' (string). Path for log. Full log path is <redislog_dir>/redis<redis_name>.log.

redis_loglevel

Loglevel of Redis. Default: 'notice' (string)

running

Configure if Redis should be running or not. Default: true (boolean)

enabled

Configure if Redis is started at boot. Default: true (boolean)

requirepass

Supply a password if you want authentication with Redis. Default: undef (string)

maxclients

Max clients of Redis instance. Default: undef (number)

appendfsync_on_rewrite

Configure the no-appendfsync-on-rewrite variable. Set to yes to enable the option. Defaults off. Default: false (boolean)

redis_disable_commands

List of commands to disable on the server. Default: []

aof_rewrite_percentage

Configure the percentage size difference between the last aof filesize and the newest to trigger a rewrite. Default 100

aof_rewrite_minsize

Configure the minimum size in mb of the aof file to trigger size comparisons for rewriting. Default: 64

redis_appendfsync

Configure the value for when an fsync should happen. Values are either everysec, always, or no. Default: everysec

redis_append_enable

Enable or disable the appendonly file option. Default: false (boolean)

redis_enabled_append_file

Enable custom append file. Default: false (boolean)

redis_append_file

Define the path for the append file. Optional. Default: undef

save

Configure Redis save snapshotting. Example: [[900, 1], [300, 10]]. Default: []

force_rewrite

Boolean. Default: false

Configure if the redis config is overwritten by puppet followed by a restart. Since redis automatically rewrite their config since version 2.8 setting this to true will trigger a redis restart on each puppet run with redis 2.8 or later.

client_output_buffer_limit

Hash containing 3 possible classes as keys (normal, slave, pubsub) and with the values set to the hard limit, soft limit and seconds. Default: empty

manage_logrotate

Configure logrotate rules for redis server. Default: true

High Availability Options

slaveof

Configure Redis Master on a slave. Default: undef (string)

masterauth

Password used when connecting to a master server which requires authentication. Default: undef (string)

slave_server_stale_data

Configure Redis slave to server stale data. Default: true (boolean)

slave_read_only

Configure Redis slave to be in read-only mode. Default: true (boolean)

repl_timeout

Configure Redis slave replication timeout in seconds. Default: 60 (number)

repl_backlog_size

Configure Redis slave backlog size in bytes. Default: undef

repl_ping_slave_period

Configure Redis replication ping slave period in seconds. Default: 10 (number)

Cluster Options

cluster_enabled

Enable Redis Cluster. Supported only in Redis 3.x. Default: false

cluster_node_timeout

Timeout in ms to declare a node as failed.

cluster_slave_validity_factor

Configure slave validity factor. Please read the Redis documentation to learn more about this parameter.

cluster_migration_barrier

Slaves migrate to orphaned masters only if there are still at least this given number of other working slaves for their old master.

cluster_require_full_coverage

By default Redis Cluster nodes stop accepting queries if they detect there is at least an hash slot uncovered.

Defined Type: redis::sentinel

Used to configure sentinel instances. You can setup multiple sentinel servers on the same node. And you can configure multiple monitors within a sentinel. See the setup examples.

**Parameters within redis::sentinel

sentinel_name

Name of Redis instance. Default: call name of the function. The name is used to create the init script(s), which follows the pattern redis-sentinel_${sentinel_name}

sentinel_ip

Listen IP of sentinel. Default: 6379

sentinel_port

Listen port of sentinel. Default: 6379

sentinel_log_dir

Default is '/var/log' (string). Path for log. Full log path is sentinel_log_dir/sentinel_sentinel_name.log.

sentinel_pid_dir

Default is '/var/run' (string). Path for pid file. Full pid file path is sentinel_pid_dir/sentinel_sentinel_name.pid.

sentinel_run_dir

Default: /var/run/redis (string) Since sentinels automatically rewrite their config since version 2.8 the puppet managed config will be copied to this directory and than sentinel will start with this copy.

monitors

Default is

{
  'mymaster' => {
    master_host             => '127.0.0.1',
    master_port             => 6379,
    quorum                  => 2,
    down_after_milliseconds => 30000,
    parallel-syncs          => 1,
    failover_timeout        => 180000,
    ### optional
    auth-pass => 'secret_Password',
    notification-script => '/var/redis/notify.sh',
    client-reconfig-script => '/var/redis/reconfig.sh'
  },
}

Hashmap of monitors.

running

Configure if Redis should be running or not. Default: true (boolean)

enabled

Configure if Redis is started at boot. Default: true (boolean)

force_rewrite

Boolean. Default: false

Configure if the sentinels config is overwritten by puppet followed by a sentinel restart. Since sentinels automatically rewrite their config since version 2.8 setting this to true will trigger a sentinel restart on each puppet run with redis 2.8 or later.

manage_logrotate

Configure logrotate rules for redis server. Default: true

Limitations

This module is tested on CentOS 6.5 and Debian 7 (Wheezy) and should also run without problems on

• RHEL/CentOS/Scientific 6+
• Debian 6+
• Ubunutu 10.04 and newer
• SLES 11 SP3

Limitation on SLES:

• Installation from source is not tested
• Redis sentinel configuration/management is not tested

Contributing

Echocat modules are open projects. So if you want to make this module even better, you can contribute to this module on Github.

2018-02-01 - 2.1.0 (Feature/Bugfix release)

Features:

• Add redis_disable_commands parameter to redis::server

Bugfixes:

• Fix systemd Ubuntu
• Systemd: fix permission issue with redis_run_dir / sentinel_run_dir
• Some more fixes for init.d

2016-11-15 - 2.0.0 (Feature/Bugfix release)

Bugfixes:

• Fix broken systemd part for Debian
• Fix cluster coverage error in redis.conf template
• Add required update-rc.d headers to debian init.d scripts
• Fix ensure_packages expects an array

Features:

• Redis, Sentinel: allow turning off protected mode
• Server: Added option to redis.conf: client-output-buffer-limit, as a hash
• Server: Added option to redis.conf: repl_backlog_size, a simple value
• Server: add include parameter for config
• allows for compatibility with Amazon Linux
• Add cluster params documentation + enable cluster support
• Add redis_disable_commands

2016-06-24 - 1.9.0 (Feature/Bugfix release)

Bugfixes:

• (734defe) redis-check-dump was renamed to redis-check-rdb in redis version 3.2

Features:

• (123f474) Add initial cluster support to redis::server

2016-04-08 - 1.8.1 (Bugfix release)

Bugfixes:

• (318d2cb) RedHat 7: fix systemd scripts for Server and Sentinel

2016-04-05 - 1.8.0 (Feature/Bugfix release)

Features:

• (e37283e) Add the possibility to exclude logrotate
• (316f492) RedHat 7: add systemd support
• (316f492) Sentinel: add parameter sentinel_ip for binding address
• (3fdbca0) Server::install: add parameter download_base at install class to specify download url of source tar.gz
• (e47fc28) Gentoo: add support for Gentoo

Bugfixes:

• (6dea873) fix source entry for forge api in metadata.json

2015-12-02 - 1.7.0 (Feature/Bugfix release)

Features:

• (3236f41) #33 add Scientific Linux support
• (ad5d3c1) #37 Server: add parameters redis_usesocket redis_socket redis_socketperm redis_memsamples
• (edf870b) #31 Server: add parameters force_rewrite
• (e1c2011) #53 Server: add parameters hash_max_ziplist_entries and hash_max_ziplist_value
• (f1006e2) #48 Server: add parameters redis_user and redis_group
• (42bb23f) #44 Sentinel: explititly define sentinel pidfile

Bugfixes:

• (3e920e3) #35 Server: correct usage of redis_timeout in servers
• (f8e44b2) #39 avoid conflicts build-essential
• (75cffe8) #51 prevent default redis-server from automatically start

2015-05-11 - 1.6.0 (Feature/Bugfix release)

Features:

• Issue #22 Sentinel: add force_rewrite parameter for sentinel.conf
• Issue #22 Sentinel: add parameter sentinel_pid_dir

Bugfixes:

• Fixes #22 fix sentinel pid and log locations in init script
• Fixes #23 RedHat: fix stop in initscript (remove signal -QUIT)

2015-04-21 - 1.5.0 (Feature release)

Features:

• Issue #20 use curl instead of wget for download

2015-04-14 - 1.4.0 (Feature release)

Features:

• Issue #18 add support for SLES
• Issue #17 better support for old redis 2.4.x

2015-02-26 - 1.3.0 (Feature/Bugfix release)

Features:

• Issue #16 add ability to set save db values

Bugfixes:

• fix duplication directory error, if multiple redis are on the same node

2015-02-11 - 1.2.4 (Bugfix release)

Bugfixes:

• remove Modulefile
• add basic rspec tests
• fix license
• add support for non default redis directory creation

2014-12-05 - 1.2.3 (Bugfix release)

Bugfixes:

• Debian: fix package name to redis-server

2014-12-03 - 1.2.2 (Bugfix release)

Bugfixes:

• use ensure_packages to avoid redeclares
• update stdlib version requirement, because of ensure_packages
• small fix in README examples

2014-11-28 - 1.2.1 (Bugfix release)

Bugfixes:

• add missing dependency for puppetlabs/stdlib
• some puppet linting

2014-11-08 - 1.2.0 (Feature release)

Features:

• support install via REPO instead of compile from source
• new examples in README
• lots of new parameters for master/slave
• lots of new parameters for aof and co

2014-04-11 - 1.1.0 (Feature release)

Features:

• add support for sentinel. See redis::sentinel

2014-04-09 - 1.0.0

Features:

• download, compile, install redis
• install multiple redis instances