Parameters

The REDIS module has 22 parameters: 19 for Redis/Valkey deployment and configuration, and 3 for removal.

Parameter Overview

The REDIS parameter group is used for Redis cluster deployment and configuration, including identity, instance definitions, operating mode, memory configuration, persistence, and monitoring.

The REDIS_REMOVE parameter group controls Redis instance removal behavior.

The REDIS module contains 19 deployment parameters and 3 removal parameters.

#redis_cluster:             <CLUSTER> # Redis cluster name, required identity parameter
#redis_node: 1              <NODE>    # Redis node number, unique in cluster
#redis_instances: {}        <NODE>    # Redis instance definitions on this node
redis_fs_main: /data/redis            # Redis main data directory, `/data/redis` by default
redis_exporter_enabled: true          # Enable Redis Exporter?
redis_exporter_port: 9121             # Redis Exporter listen port
redis_exporter_options: ''            # Redis Exporter CLI arguments
redis_type: redis                     # Server engine: redis or valkey
redis_mode: standalone                # Redis mode: standalone, cluster, sentinel
redis_conf: redis.conf                # Redis config template, except sentinel
redis_bind_address: '0.0.0.0'         # Redis bind address, defaults to `0.0.0.0`; empty uses host IP
redis_max_memory: 1GB                 # Max memory for each Redis instance
redis_mem_policy: allkeys-lru         # Redis memory eviction policy
redis_password: ''                    # Redis password, empty disables password
redis_rdb_save: ['1200 1']            # Redis RDB save directives, empty disables RDB
redis_aof_enabled: false              # Enable Redis AOF?
redis_rename_commands: {}             # Rename dangerous Redis commands
redis_cluster_replicas: 1             # Replicas per master in Redis native cluster
redis_sentinel_monitor: []            # Master list for Sentinel, sentinel mode only

# REDIS_REMOVE
redis_safeguard: false                # Refuse removal unconditionally when true
redis_rm_data: true                   # Remove Redis data directory when removing?
redis_rm_pkg: false                   # Uninstall the selected engine and redis-exporter?

redis_cluster

Parameter: redis_cluster, Type: string, Level: C

Redis cluster name, a required identity parameter that must be explicitly configured at the cluster level. It serves as the namespace for resources within the cluster.

Must follow the naming pattern [a-z][a-z0-9-]* to comply with various identity constraints. Using redis- as a cluster name prefix is recommended.

redis_node

Parameter: redis_node, Type: int, Level: I

Redis node sequence number, a required identity parameter that must be explicitly configured at the node (Host) level.

A positive integer that should be unique within the cluster, used to distinguish and identify different nodes. Assign starting from 0 or 1.

redis_instances

Parameter: redis_instances, Type: dict, Level: I

Redis instance definitions on the current node, a required parameter that must be explicitly configured at the node (Host) level.

Format is a JSON key-value object where keys are numeric port numbers and values are instance-specific JSON configuration items.

redis-test: # redis native cluster: 3m x 3s
  hosts:
    10.10.10.12: { redis_node: 1 ,redis_instances: { 6379: { } ,6380: { } ,6381: { } } }
    10.10.10.13: { redis_node: 2 ,redis_instances: { 6379: { } ,6380: { } ,6381: { } } }
  vars: { redis_cluster: redis-test ,redis_password: 'redis.test' ,redis_mode: cluster, redis_max_memory: 32MB }

Each Redis instance listens on a unique port on its node. The replica_of field in instance configuration sets the upstream master address to establish replication:

redis_instances:
    6379: {}
    6380: { replica_of: '10.10.10.13 6379' }
    6381: { replica_of: '10.10.10.13 6379' }

redis_fs_main

Parameter: redis_fs_main, Type: path, Level: C

Main data directory for Redis, default is /data/redis.

Deployment does not allow the legacy value /data (redis role identity assert fails fast). For backward compatibility during removal, redis-rm.yml treats redis_fs_main=/data as /data/redis.

The data directory is owned by the redis OS user. See FHS: Redis for internal structure details.

redis_exporter_enabled

Parameter: redis_exporter_enabled, Type: bool, Level: C

Enable Redis Exporter monitoring component?

Enabled by default, deploying one exporter per Redis node, listening on redis_exporter_port 9121 by default. It scrapes metrics from all Redis instances on the node.

When set to false, roles/redis/tasks/exporter.yml still renders config files but skips starting the redis_exporter systemd service (the redis_exporter_launch task has when: redis_exporter_enabled|bool), allowing manually configured exporters to remain. redis_register still writes this node’s VictoriaMetrics file-discovery target. If you do not provide your own exporter on the same port, handle that target as well to avoid continuous scrape failures.

redis_exporter_port

Parameter: redis_exporter_port, Type: port, Level: C

Redis Exporter listen port, default value: 9121

redis_exporter_options

Parameter: redis_exporter_options, Type: string, Level: C/I

Extra CLI arguments for Redis Exporter, rendered to /etc/default/redis_exporter (see roles/redis/tasks/exporter.yml), default is empty string. REDIS_EXPORTER_OPTS is appended to the systemd service’s ExecStart=/bin/redis_exporter $REDIS_EXPORTER_OPTS, useful for configuring extra scrape targets or filtering behavior.

redis_type

Parameter: redis_type, Type: enum, Level: G/C

Select the server implementation used by the REDIS module. Allowed values are redis and valkey; the default is redis.

The role installs the package with the selected name and calls /bin/redis-server / /bin/redis-cli or /bin/valkey-server / /bin/valkey-cli from instance systemd units. Configuration paths, data directories, instance service names, exporter behavior, and monitoring labels retain the redis namespace for compatibility with existing inventories and operational entry points.

Set the same value for every member at cluster level. Changing redis_type only changes the package and binaries selected by the role; it does not validate cross-version RDB/AOF, replication, Sentinel, or Cluster compatibility. Rehearse the change and prepare a rollback before switching an existing cluster.

redis_mode

Parameter: redis_mode, Type: enum, Level: C

Redis cluster operating mode, three options: standalone, cluster, sentinel. Default: standalone

• standalone: Default, independent Redis master-slave mode
• cluster: Redis native cluster mode
• sentinel: Redis high availability component: Sentinel

When using standalone mode, Pigsty sets up Redis replication based on the replica_of parameter.

When using cluster mode, Pigsty creates a native Redis cluster using all defined instances based on the redis_cluster_replicas parameter.

When redis_mode=sentinel, redis.yml runs the redis-ha phase to distribute targets from redis_sentinel_monitor to all sentinels. When redis_mode=cluster, it also runs redis-join, using the redis-cli or valkey-cli selected by the engine to execute --cluster create. Both phases run automatically during a normal ./redis.yml -l <cluster> and can also be selected with -t redis-ha or -t redis-join.

redis_conf

Parameter: redis_conf, Type: string, Level: C

Redis config template path, except for Sentinel.

Default: redis.conf, a template file at roles/redis/templates/redis.conf.

To use your own Redis config template, place it in the templates/ directory and set this parameter to the template filename.

Note: Redis Sentinel uses a different template file: roles/redis/templates/redis-sentinel.conf.

redis_bind_address

Parameter: redis_bind_address, Type: ip, Level: C

IP address Redis server binds to. Empty string uses the hostname defined in the inventory.

Default: 0.0.0.0, binding to all available IPv4 addresses on the host.

For security in production environments, bind only to internal IPs by setting this to empty string ''.

When empty, the template roles/redis/templates/redis.conf uses inventory_hostname to render bind <ip>, binding to the management address declared in the inventory.

redis_max_memory

Parameter: redis_max_memory, Type: size, Level: C/I

Maximum memory for each Redis instance, default: 1GB.

redis_mem_policy

Parameter: redis_mem_policy, Type: enum, Level: C

Redis memory eviction policy, default: allkeys-lru

• noeviction: Don’t save new values when memory limit is reached; only applies to primary when using replication
• allkeys-lru: Keep most recently used keys; remove least recently used (LRU) keys
• allkeys-lfu: Keep frequently used keys; remove least frequently used (LFU) keys
• volatile-lru: Remove least recently used keys with expire field set
• volatile-lfu: Remove least frequently used keys with expire field set
• allkeys-random: Randomly remove keys to make space for new data
• volatile-random: Randomly remove keys with expire field set
• volatile-ttl: Remove keys with expire field set and shortest remaining TTL

See Redis Eviction Policy for details.

redis_password

Parameter: redis_password, Type: password, Level: C/N

Redis password. Empty string disables password, which is the default behavior.

Note that due to redis_exporter implementation limitations, you can only set one redis_password per node. This is usually not a problem since Pigsty doesn’t allow deploying two different Redis clusters on the same node.

Pigsty automatically writes this password to /etc/default/redis_exporter (REDIS_PASSWORD=...) and passes it through REDISCLI_AUTH to the redis-cli / valkey-cli selected by redis-ha and redis-join, keeping the password out of command-line arguments.

Use a strong password in production environments

redis_rdb_save

Parameter: redis_rdb_save, Type: string[], Level: C

Redis RDB save directives. Use empty list to disable RDB.

Default is ["1200 1"]: dump dataset to disk every 20 minutes if at least 1 key changed.

See Redis Persistence for details.

redis_aof_enabled

Parameter: redis_aof_enabled, Type: bool, Level: C

Enable Redis AOF? Default is false, meaning AOF is not used.

redis_rename_commands

Parameter: redis_rename_commands, Type: dict, Level: C

Rename dangerous Redis commands. A k:v dictionary where old is the command to rename and new is the new name.

Default: {}. You can hide dangerous commands like FLUSHDB and FLUSHALL. Example:

{
  "keys": "op_keys",
  "flushdb": "op_flushdb",
  "flushall": "op_flushall",
  "config": "op_config"
}

redis_cluster_replicas

Parameter: redis_cluster_replicas, Type: int, Level: C

Number of replicas per master/primary in Redis native cluster. Default: 1, meaning one replica per master.

redis_sentinel_monitor

Parameter: redis_sentinel_monitor, Type: master[], Level: C

List of masters for Redis Sentinel to monitor, used only on sentinel clusters. Each managed master is defined as:

redis_sentinel_monitor:  # primary list for redis sentinel, use cls as name, primary ip:port
  - { name: redis-src, host: 10.10.10.45, port: 6379 ,password: redis.src, quorum: 1 }
  - { name: redis-dst, host: 10.10.10.48, port: 6379 ,password: redis.dst, quorum: 1 }

name and host are required; port, password, and quorum are optional. quorum sets the number of sentinels needed to agree on master failure, typically more than half of sentinel instances (default is 1).

Starting from Pigsty 4.0, you can add remove: true to an entry, causing the redis-ha phase to only execute SENTINEL REMOVE <name>, useful for cleaning up targets no longer needed.

REDIS_REMOVE

The following parameters are used by the redis_remove role, invoked by the redis-rm.yml playbook, controlling Redis instance removal behavior.

redis_safeguard

Parameter: redis_safeguard, Type: bool, Level: G/C/A

Redis deletion safeguard, default false. When set to true, redis-rm.yml aborts before deregistration, service shutdown, or deletion. This is a static Boolean switch and does not probe whether a Redis instance is running.

Override with CLI argument -e redis_safeguard=false to force removal.

redis_rm_data

Parameter: redis_rm_data, Type: bool, Level: G/C/A

Remove Redis data directory when removing Redis instances? Default is true.

The data directory (default /data/redis/, i.e. redis_fs_main) contains Redis RDB and AOF files. If not removed, newly deployed Redis instances will load data from these backup files.

Set to false to preserve data directories for later recovery.

redis_rm_pkg

Parameter: redis_rm_pkg, Type: bool, Level: G/C/A

When removing a Redis node, also uninstall the engine selected by redis_type and the redis-exporter package? Default is false. Removing a single instance with redis_port never uninstalls shared packages.

Typically not needed to uninstall packages; only enable when completely cleaning up a node.