Module: REDIS

• 1: Configuration
• 2: Parameters
• 3: Playbook
• 4: Administration
• 5: Monitoring
• 6: Metrics
• 7: FAQ

redis_type: redis   # default; valkey is also supported

1 - Configuration

Concept

The Redis entity model is similar to the PostgreSQL model. It includes Cluster and Instance entities. Here, Cluster does not mean native Redis Cluster mode.

REDIS uses a single-node multi-instance deployment. PGSQL uses a 1:1 deployment. Multiple Redis instances typically share one physical or virtual node to use multiple CPU cores. Thus, the procedures to configure and administer Redis instances differ slightly from PGSQL.

In Pigsty, each Redis node belongs to one cluster. You cannot deploy instances from two different Redis clusters on the same node.

You can still deploy multiple independent Redis primary-replica instances on one node. Some restrictions apply. For example, instances on the same node cannot use different passwords.

Choose the server implementation with redis_type: redis by default, or valkey. Set it consistently at cluster level. The role changes packages and the *-server / *-cli binaries. It retains /etc/redis, /data/redis, instance systemd unit names, and the redis monitoring namespace. Validate data compatibility and rollback independently before changing an existing cluster’s engine.

Identity Parameters

Redis identity parameters are required parameters when defining a Redis cluster.

• redis_cluster: Redis cluster name, serves as the top-level namespace for cluster resources.
• redis_node: Redis node number, an integer unique within the cluster to distinguish different nodes.
• redis_instances: JSON object where keys are instance port numbers and values are JSON objects containing other instance configurations.

Redis Mode

There are three different working modes for Redis, specified by the redis_mode parameter:

• standalone: Default standalone master-slave mode
• cluster: Redis native distributed cluster mode
• sentinel: Sentinel mode, providing high availability for standalone master-slave Redis

Here are three examples of Redis cluster definitions:

• A 1-node, one master & one slave Redis Standalone cluster: redis-ms
• A 1-node, 3-instance Redis Sentinel cluster: redis-sentinel
• A 2-node, 6-instance Redis Cluster: redis-cluster

redis-ms: # redis classic primary & replica
  hosts: { 10.10.10.10: { redis_node: 1 , redis_instances: { 6379: { }, 6380: { replica_of: '10.10.10.10 6379' } } } }
  vars: { redis_cluster: redis-ms ,redis_password: 'redis.ms' ,redis_max_memory: 64MB }

redis-meta: # redis sentinel x 3
  hosts: { 10.10.10.11: { redis_node: 1 , redis_instances: { 26379: { } ,26380: { } ,26381: { } } } }
  vars:
    redis_cluster: redis-meta
    redis_password: 'redis.meta'
    redis_mode: sentinel
    redis_max_memory: 16MB
    redis_sentinel_monitor: # primary list for redis sentinel, use cls as name, primary ip:port
      - { name: redis-ms, host: 10.10.10.10, port: 6379 ,password: redis.ms, quorum: 2 }

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 }

These examples omit redis_type and therefore use the default Redis engine. To deploy Valkey, add redis_type: valkey to the cluster’s vars. Do not mix engines within one logical cluster.

Limitations

• A Redis node can belong to only one Redis cluster. You cannot assign it to two clusters at the same time.
• On each Redis node, you need to assign a unique port number to each Redis instance to avoid port conflicts.
• A Redis cluster typically uses the same password for all instances. All instances on one node must share a password because redis_exporter supports only one.
• Redis Cluster includes HA. For standalone master-slave HA, configure Sentinel manually. Pigsty does not know whether you have deployed Sentinel.
• Use Sentinel to configure HA for standalone Redis. For details, see Administration - Configure HA with Sentinel.

Typical Configuration Examples

Here are some common Redis configuration examples for different scenarios:

Cache Cluster (Pure In-Memory)

For pure caching scenarios with no data persistence requirements:

redis-cache:
  hosts:
    10.10.10.10: { redis_node: 1 , redis_instances: { 6379: { }, 6380: { } } }
    10.10.10.11: { redis_node: 2 , redis_instances: { 6379: { }, 6380: { } } }
  vars:
    redis_cluster: redis-cache
    redis_password: 'cache.password'
    redis_max_memory: 2GB
    redis_mem_policy: allkeys-lru    # evict LRU keys when memory is full
    redis_rdb_save: []               # disable RDB persistence
    redis_aof_enabled: false         # disable AOF persistence

Session Store Cluster

For web application session storage with some persistence needs:

redis-session:
  hosts:
    10.10.10.10: { redis_node: 1 , redis_instances: { 6379: { }, 6380: { replica_of: '10.10.10.10 6379' } } }
  vars:
    redis_cluster: redis-session
    redis_password: 'session.password'
    redis_max_memory: 1GB
    redis_mem_policy: volatile-lru   # only evict keys with expire set
    redis_rdb_save: ['300 1']        # save every 5 minutes if at least 1 change
    redis_aof_enabled: false

Message Queue Cluster

For simple message queue scenarios requiring higher data reliability:

redis-queue:
  hosts:
    10.10.10.10: { redis_node: 1 , redis_instances: { 6379: { }, 6380: { replica_of: '10.10.10.10 6379' } } }
  vars:
    redis_cluster: redis-queue
    redis_password: 'queue.password'
    redis_max_memory: 4GB
    redis_mem_policy: noeviction     # reject writes when memory full, don't evict
    redis_rdb_save: ['60 1']         # save every minute if at least 1 change
    redis_aof_enabled: true          # enable AOF for better persistence

High Availability Master-Slave Cluster

Master-slave cluster with Sentinel automatic failover:

# Master-slave cluster
redis-ha:
  hosts:
    10.10.10.10: { redis_node: 1 , redis_instances: { 6379: { } } }                              # primary
    10.10.10.11: { redis_node: 2 , redis_instances: { 6379: { replica_of: '10.10.10.10 6379' } } } # replica 1
    10.10.10.12: { redis_node: 3 , redis_instances: { 6379: { replica_of: '10.10.10.10 6379' } } } # replica 2
  vars:
    redis_cluster: redis-ha
    redis_password: 'ha.password'
    redis_max_memory: 8GB

# Sentinel cluster (manages the above master-slave cluster)
redis-sentinel:
  hosts:
    10.10.10.10: { redis_node: 1 , redis_instances: { 26379: { } } }
    10.10.10.11: { redis_node: 2 , redis_instances: { 26379: { } } }
    10.10.10.12: { redis_node: 3 , redis_instances: { 26379: { } } }
  vars:
    redis_cluster: redis-sentinel
    redis_password: 'sentinel.password'
    redis_mode: sentinel
    redis_max_memory: 64MB
    redis_sentinel_monitor:
      - { name: redis-ha, host: 10.10.10.10, port: 6379, password: 'ha.password', quorum: 2 }

Large-Scale Native Cluster

For high-volume, high-throughput scenarios using native distributed cluster:

redis-cluster:
  hosts:
    10.10.10.10: { redis_node: 1 , redis_instances: { 6379: { }, 6380: { }, 6381: { } } }
    10.10.10.11: { redis_node: 2 , redis_instances: { 6379: { }, 6380: { }, 6381: { } } }
    10.10.10.12: { redis_node: 3 , redis_instances: { 6379: { }, 6380: { }, 6381: { } } }
    10.10.10.13: { redis_node: 4 , redis_instances: { 6379: { }, 6380: { }, 6381: { } } }
  vars:
    redis_cluster: redis-cluster
    redis_password: 'cluster.password'
    redis_mode: cluster
    redis_cluster_replicas: 1        # 1 replica per primary shard
    redis_max_memory: 16GB           # max memory per instance
    redis_rdb_save: ['900 1']
    redis_aof_enabled: false

# This creates a 6-primary, 6-replica native cluster
# Total capacity ~96GB (6 * 16GB)

Security Hardening Configuration

Recommended security configuration for production environments:

redis-secure:
  hosts:
    10.10.10.10: { redis_node: 1 , redis_instances: { 6379: { } } }
  vars:
    redis_cluster: redis-secure
    redis_password: 'StrongP@ssw0rd!'  # use strong password
    redis_bind_address: ''             # bind to internal IP instead of 0.0.0.0
    redis_max_memory: 4GB
    redis_rename_commands:             # rename dangerous commands
      FLUSHDB: 'DANGEROUS_FLUSHDB'
      FLUSHALL: 'DANGEROUS_FLUSHALL'
      DEBUG: ''                        # disable command
      CONFIG: 'ADMIN_CONFIG'

2 - Parameters

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

Parameter Overview

Use the REDIS parameter group to deploy and configure Redis clusters. It controls identity, instance definitions, operating mode, memory, 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. This identity parameter is required. Set it explicitly at the cluster level. It defines the namespace for cluster resources.

Use the naming pattern [a-z][a-z0-9-]* to meet identity constraints. We recommend the redis- prefix.

redis_node

Parameter: redis_node, Type: int, Level: I

Redis node sequence number. This identity parameter is required. Set it explicitly at the node (Host) level.

Use a positive integer that is unique in the cluster to identify the node. Assign sequence numbers starting at 0 or 1.

redis_instances

Parameter: redis_instances, Type: dict, Level: I

Redis instance definitions for the current node. This parameter is required. Set it explicitly 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

Specifies whether to enable Redis Exporter. It is enabled by default.

Pigsty deploys one exporter per Redis node. It listens on redis_exporter_port, which defaults to 9121. It scrapes metrics from all Redis instances on the node.

If set to false, roles/redis/tasks/exporter.yml still renders configuration files. It skips startup of the redis_exporter systemd service. The redis_exporter_launch task uses when: redis_exporter_enabled|bool. This permits manually configured exporters to remain.

The redis_register task still writes the node’s VictoriaMetrics file-discovery target. If you do not provide an exporter on the same port, adjust this target to prevent 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 Redis Exporter CLI arguments. The default is an empty string. The role writes them to /etc/default/redis_exporter; see roles/redis/tasks/exporter.yml.

The systemd service uses ExecStart=/bin/redis_exporter $REDIS_EXPORTER_OPTS to append REDIS_EXPORTER_OPTS. Use these arguments for 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. Instance systemd units call /bin/redis-server / /bin/redis-cli or /bin/valkey-server / /bin/valkey-cli.

Configuration paths, data directories, instance service names, exporter behavior, and monitoring labels retain the redis namespace. This preserves compatibility with existing inventories and operational entry points.

Set the same value for every member at cluster level. A change to redis_type changes only the selected package and binaries. 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. If redis_mode=cluster, it also runs redis-join. This uses the engine’s redis-cli or valkey-cli to run --cluster create.

Both phases run automatically during a normal ./redis.yml -l <cluster>. You can also select them 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 configuration template, put it in templates/. 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 ''.

If empty, roles/redis/templates/redis.conf uses inventory_hostname to render bind <ip>. This binds Redis to the management address 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.

redis_exporter supports only one redis_password per node. This is usually sufficient because Pigsty does not permit two different Redis clusters on one node.

Pigsty automatically writes this password to /etc/default/redis_exporter as REDIS_PASSWORD=.... The redis-ha and redis-join tasks select redis-cli / valkey-cli and pass the password through REDISCLI_AUTH. This keeps 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

Specifies whether to enable Redis AOF. The default is false, which disables AOF.

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. The port, password, and quorum fields are optional.

quorum sets the number of Sentinels that must agree on master failure. This is typically more than half of the Sentinel instances. The default is 1.

Since Pigsty 4.0, you can add remove: true to an entry. The redis-ha phase then runs only SENTINEL REMOVE <name>. Use this to remove unneeded targets.

REDIS_REMOVE

The redis-rm.yml playbook calls the redis_remove role. These parameters control how that role removes Redis instances.

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

Specifies whether to delete the data directory when removing Redis instances. The 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

Specifies whether node removal also uninstalls the engine selected by redis_type and the redis-exporter package. The default is false. Single-instance removal with redis_port never uninstalls shared packages.

Usually, package removal is unnecessary. Enable this option only for complete node cleanup.

3 - Playbook

The REDIS module provides two playbooks for deploying/removing Redis clusters/nodes/instances:

• redis.yml: Deploy Redis cluster/node/instance
• redis-rm.yml: Remove Redis cluster/node/instance

redis.yml

The redis.yml playbook for deploying Redis contains the following subtasks:

redis_node        : Init redis node
  - redis_install : Install Redis and the `redis-exporter` package
  - redis_user    : Create OS user redis
  - redis_dir     : Configure redis FHS directory structure
redis_exporter    : Configure redis_exporter monitoring
  - redis_exporter_config  : Generate redis_exporter config
  - redis_exporter_launch  : Launch redis_exporter
redis_instance    : Init and restart redis cluster/node/instance
  - redis_config  : Generate redis instance config
  - redis_launch  : Launch redis instance
redis_register    : Register redis to infrastructure
redis_ha          : Configure redis sentinel (sentinel mode only)
redis_join        : Join redis native cluster (cluster mode only)

Operation Levels

redis.yml supports three operation levels. Use -l to limit the target scope. Use -e redis_port=<port> to select one instance:

Cluster-Level Operations

Deploy an entire Redis cluster, including all instances on all nodes:

./redis.yml -l redis-ms           # deploy the entire redis-ms cluster
./redis.yml -l redis-test         # deploy the entire redis-test cluster
./redis.yml -l redis-sentinel     # deploy sentinel cluster

Cluster-level operations will:

• Install Redis or Valkey according to redis_type, plus redis-exporter, on all nodes
• Create redis user and directory structure on all nodes
• Start redis_exporter on all nodes
• Deploy and start all defined Redis instances
• Register all instances to the monitoring system
• If sentinel mode, configure sentinel monitoring targets
• If cluster mode, form the native cluster

Node-Level Operations

Deploy only all Redis instances on the specified node:

./redis.yml -l 10.10.10.10        # deploy all instances on this node
./redis.yml -l 10.10.10.11        # deploy another node

Node-level operations are useful for:

• Scaling up by adding new nodes to an existing cluster
• Redeploying all instances on a specific node
• Reinitializing after node failure recovery

Note: Node-level commands still enter the redis-ha / redis-join mode checks. Sentinel mode refreshes managed targets. In cluster mode, the playbook uses the selected CLI to check the seed instance for cluster_state:ok. It exits for a healthy cluster. Otherwise, it runs --cluster create. This check does not scale out an existing native cluster. For that operation, run redis-cli / valkey-cli --cluster add-node and reshard manually.

Instance-Level Operations

Use the -e redis_port=<port> parameter to operate on a single instance:

# Deploy only the 6379 port instance on 10.10.10.10
./redis.yml -l 10.10.10.10 -e redis_port=6379

# Deploy only the 6380 port instance on 10.10.10.11
./redis.yml -l 10.10.10.11 -e redis_port=6380

Instance-level operations are useful for:

• Adding new instances to an existing node
• Redeploying a single failed instance
• Updating a single instance’s configuration

When redis_port is specified:

• Only renders the config file for that port
• Only starts/restarts the systemd service for that port
• Rewrites the node’s monitoring registration file (content comes from the full redis_instances definition)
• Does not start/stop redis_exporter or reload Vector log config
• Does not affect other Redis instance processes on the same node

Common Tags

Use the -t <tag> parameter to selectively execute certain tasks:

# Install packages only, don't start services
./redis.yml -l redis-ms -t redis_node

# Update config and restart instances only
./redis.yml -l redis-ms -t redis_config,redis_launch

# Update monitoring registration only
./redis.yml -l redis-ms -t redis_register

# Configure sentinel monitoring targets only (sentinel mode)
./redis.yml -l redis-sentinel -t redis-ha

# Form native cluster only (cluster mode, auto-runs after first deployment)
./redis.yml -l redis-cluster -t redis-join

Idempotency

You can repeat most tasks in redis.yml. Before native-cluster initialization, check the topology state:

• Re-running redis_node / redis_exporter / redis_instance / redis_register overwrites config and restarts instances
• Re-running redis-ha reapplies SENTINEL REMOVE/MONITOR based on redis_sentinel_monitor
• redis-join first checks the seed instance for cluster_state:ok. It exits for a healthy cluster. The check does not repair incomplete or damaged topologies or perform scale-out. Do not use it as a general add-node/reshard operation.

Tip: To update configuration without restarting all instances, use -t redis_config. Then manually restart the required instances.

Redis/Valkey units use Type=notify. During startup, systemd waits up to 1800s for readiness. This lets large RDB/AOF loads and recovery finish.

After a timeout, first inspect instance logs, data size, disk I/O, and memory. Do not extend data deletion or force a stop solely because of the timeout.

redis-rm.yml

The redis-rm.yml playbook for removing Redis contains the following subtasks:

redis_safeguard  : Safety check, abort if redis_safeguard=true
redis_deregister : Remove registration from monitoring system
  - rm_metrics   : Delete /infra/targets/redis/*.yml
  - rm_logs      : Revoke /etc/vector/redis.yaml
redis_exporter   : Stop and disable redis_exporter
redis            : Stop and disable redis instances
redis_data       : Delete data directories (when redis_rm_data=true)
redis_pkg        : Uninstall selected engine and redis-exporter (when redis_rm_pkg=true)

Tag-scoped execution follows the data/package switches. The -t redis tag always enters the instance-stop phase. The -t redis_data tag stops instances only if redis_rm_data=true. The -t redis_pkg tag stops them only if redis_rm_pkg=true.

Thus, -t redis_data -e redis_rm_data=false does not stop Redis. Neither does -t redis_pkg -e redis_rm_pkg=false. The selected tag alone is insufficient. Before a real removal, verify the exact same -l, tags, and extra variables.

Operation Levels

redis-rm.yml also supports three operation levels:

Cluster-Level Removal

Remove an entire Redis cluster:

./redis-rm.yml -l redis-ms        # remove the entire redis-ms cluster
./redis-rm.yml -l redis-test      # remove the entire redis-test cluster

Cluster-level removal will:

• Deregister all instances on all nodes from the monitoring system
• Stop redis_exporter on all nodes
• Stop and disable all Redis instances
• Delete all data directories (if redis_rm_data=true)
• Uninstall the engine selected by redis_type and redis-exporter (if redis_rm_pkg=true)

Node-Level Removal

Remove only all Redis instances on the specified node:

./redis-rm.yml -l 10.10.10.10     # remove all instances on this node
./redis-rm.yml -l 10.10.10.11     # remove another node

Node-level removal is useful for:

• Scaling down by removing an entire node
• Cleanup before node decommission
• Preparation before node migration

Node-level removal will:

• Deregister all instances on that node from the monitoring system
• Stop redis_exporter on that node
• Stop all Redis instances on that node
• Delete all data directories on that node
• Delete Vector logging config on that node

Instance-Level Removal

Use the -e redis_port=<port> parameter to remove a single instance:

# Remove only the 6379 port instance on 10.10.10.10
./redis-rm.yml -l 10.10.10.10 -e redis_port=6379

# Remove only the 6380 port instance on 10.10.10.11
./redis-rm.yml -l 10.10.10.11 -e redis_port=6380

Instance-level removal is useful for:

• Removing a single replica from a node
• Removing instances no longer needed
• Removing the original primary after failover

Behavioral differences when redis_port is specified:

Control Parameters

redis-rm.yml provides the following control parameters:

Usage examples:

# Remove cluster but keep data directories
./redis-rm.yml -l redis-ms -e redis_rm_data=false

# Remove cluster and uninstall packages
./redis-rm.yml -l redis-ms -e redis_rm_pkg=true

# Override only after verifying the target and backups when the inventory enables the safeguard
./redis-rm.yml -l redis-ms -e redis_safeguard=false

Safeguard Mechanism

When a cluster has redis_safeguard: true configured, redis-rm.yml will refuse to execute:

redis-production:
  vars:
    redis_safeguard: true    # enable protection for production

$ ./redis-rm.yml -l redis-production
TASK [ABORT due to redis_safeguard enabled] ***
fatal: [10.10.10.10]: FAILED! => {"msg": "Abort due to redis_safeguard..."}

Explicit override is required to execute:

./redis-rm.yml -l redis-production -e redis_safeguard=false

Quick Reference

Deployment Quick Reference

# Deploy entire cluster
./redis.yml -l <cluster>

# Scale up: deploy new node (then manually add-node in cluster mode)
./redis.yml -l <new-node-ip>

# Scale up: add new instance to existing node (add definition to config first)
./redis.yml -l <ip> -e redis_port=<new-port>

# Update config and restart
./redis.yml -l <cluster> -t redis_config,redis_launch

# Update single instance config only
./redis.yml -l <ip> -e redis_port=<port> -t redis_config,redis_launch

Removal Quick Reference

# Remove entire cluster
./redis-rm.yml -l <cluster>

# Scale down: remove entire node
./redis-rm.yml -l <ip>

# Scale down: remove single instance
./redis-rm.yml -l <ip> -e redis_port=<port>

# Remove but keep data
./redis-rm.yml -l <cluster> -e redis_rm_data=false

# Complete cleanup (including packages)
./redis-rm.yml -l <cluster> -e redis_rm_pkg=true

Wrapper Scripts

Pigsty provides convenient wrapper scripts:

# Deploy
bin/redis-add <cluster>           # deploy cluster
bin/redis-add <ip>                # deploy node
bin/redis-add <ip> <port>         # deploy instance

# Remove
bin/redis-rm <cluster>            # remove cluster
bin/redis-rm <ip>                 # remove node
bin/redis-rm <ip> <port>          # remove instance

Demo

Initialize Redis cluster with Redis playbook:

4 - Administration

Use these standard operating procedures (SOPs) to administer Redis.

The REDIS module defaults to redis_type: redis. With redis_type: valkey, the server and client commands become valkey-server and valkey-cli. The examples use the default redis-cli. For Valkey clusters, use valkey-cli instead. Playbooks choose the correct CLI automatically.

Basic Operations

• Initialize Redis
• Remove Redis
• Reconfigure Redis
• Using Redis Client

High Availability

• Configure Redis Replica
• Configure HA with Sentinel
• Initialize Redis Native Cluster

Scaling & Migration

• Scale Up Redis Nodes
• Scale Down Redis Nodes
• Backup and Restore

Troubleshooting

• Common Issue Diagnosis
• Performance Tuning

For more questions, please refer to FAQ: REDIS.

Initialize Redis

You can use the redis.yml playbook to initialize Redis clusters, nodes, or instances:

# Initialize all Redis instances in the cluster
./redis.yml -l <cluster>      # init redis cluster

# Initialize all Redis instances on a specific node
./redis.yml -l 10.10.10.10    # init redis node

# Initialize a specific Redis instance: 10.10.10.11:6379
./redis.yml -l 10.10.10.11 -e redis_port=6379 -t redis

You can also use wrapper scripts to initialize:

bin/redis-add redis-ms          # create redis cluster 'redis-ms'
bin/redis-add 10.10.10.10       # create redis node '10.10.10.10'
bin/redis-add 10.10.10.10 6379  # create redis instance '10.10.10.10:6379'

Remove Redis

You can use the redis-rm.yml playbook to remove Redis clusters, nodes, or instances:

redis_rm_data defaults to true. Verify RDB/AOF backups and the current primary/replica, Sentinel, or cluster topology. Then have the operator confirm the exact target. The commands below perform the corresponding removal directly.

# Remove Redis cluster `redis-test`
./redis-rm.yml -l redis-test

# Remove Redis cluster `redis-test` and uninstall the selected engine and exporter
./redis-rm.yml -l redis-test -e redis_rm_pkg=true

# Remove all instances on Redis node 10.10.10.13
./redis-rm.yml -l 10.10.10.13

# Remove a specific Redis instance 10.10.10.13:6379
./redis-rm.yml -l 10.10.10.13 -e redis_port=6379

You can also use wrapper scripts to remove Redis clusters/nodes/instances:

bin/redis-rm redis-ms          # remove redis cluster 'redis-ms'
bin/redis-rm 10.10.10.10       # remove redis node '10.10.10.10'
bin/redis-rm 10.10.10.10 6379  # remove redis instance '10.10.10.10:6379'

Reconfigure Redis

You can partially run the redis.yml playbook to reconfigure Redis clusters, nodes, or instances:

./redis.yml -l <cluster> -t redis_config,redis_launch

Note that Redis cannot reload configuration online. You must restart Redis using the launch task to make configuration changes take effect.

Using Redis Client

Use redis-cli with the default Redis engine. Valkey uses valkey-cli with the same arguments:

$ redis-cli -h 10.10.10.10 -p 6379 # <--- connect with host and port
10.10.10.10:6379> auth redis.ms    # <--- authenticate with password
OK
10.10.10.10:6379> set a 10         # <--- set a key
OK
10.10.10.10:6379> get a            # <--- get the key value
"10"

Use redis-benchmark to evaluate Redis performance or generate test load.

redis-benchmark -h 10.10.10.13 -p 6379

Configure Redis Replica

https://redis.io/commands/replicaof/

# Promote a Redis instance to primary
> REPLICAOF NO ONE
"OK"

# Make a Redis instance a replica of another instance
> REPLICAOF 127.0.0.1 6379
"OK"

Configure HA with Sentinel

Use Redis Sentinel to provide automatic high availability for standalone master-slave clusters. For details, see the official Sentinel documentation.

In the four-node sandbox environment, the redis-meta Sentinel cluster can manage multiple standalone Redis master-slave clusters.

For example, redis-ms has one master and one slave. On each Sentinel instance, add the target with SENTINEL MONITOR. Set its password with SENTINEL SET. This configures high availability:

# For each sentinel, add the redis master to sentinel management: (26379,26380,26381)
$ redis-cli -h 10.10.10.11 -p 26379 -a redis.meta
10.10.10.11:26379> SENTINEL MONITOR redis-ms 10.10.10.10 6379 1
10.10.10.11:26379> SENTINEL SET redis-ms auth-pass redis.ms      # if auth enabled, password needs to be configured

If you want to remove a Redis master-slave cluster managed by Sentinel, use SENTINEL REMOVE <name>.

You can use the redis_sentinel_monitor parameter defined on the Sentinel cluster to automatically configure the list of masters managed by Sentinel.

redis_sentinel_monitor:  # list of masters to be monitored, port, password, quorum (should be more than 1/2 of sentinels) are optional
  - { 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 }

The redis-ha stage in redis.yml renders /tmp/<cluster>.monitor on each Sentinel instance from this list. It then runs SENTINEL REMOVE followed by SENTINEL MONITOR. This keeps Sentinel management state consistent with the inventory.

To remove a target without adding it again, set remove: true on its monitor object. The playbook then skips registration after SENTINEL REMOVE.

Use the following command to refresh the managed master list on the Redis Sentinel cluster:

./redis.yml -l redis-meta -t redis-ha   # replace redis-meta if your Sentinel cluster has a different name

Initialize Redis Native Cluster

When redis_mode is cluster, redis.yml also runs the redis-join stage. It uses the CLI selected by redis_type. The command is --cluster create --cluster-yes ... --cluster-replicas {{ redis_cluster_replicas }}. This joins all inventory instances into a native cluster.

This step runs automatically during initial deployment. A later ./redis.yml -l <cluster> -t redis-join first checks the seed instance for cluster_state:ok. It exits if the cluster is healthy.

This check does not add nodes, reshard data, or repair a partially initialized topology. Verify the topology state before you run this stage separately.

Scale Up Redis Nodes

Scale Up Standalone Cluster

When adding new nodes/instances to an existing Redis master-slave cluster, first add the new definition in the inventory:

redis-ms:
  hosts:
    10.10.10.10: { redis_node: 1 , redis_instances: { 6379: { }, 6380: { replica_of: '10.10.10.10 6379' } } }
    10.10.10.11: { redis_node: 2 , redis_instances: { 6379: { replica_of: '10.10.10.10 6379' } } }  # new node
  vars: { redis_cluster: redis-ms ,redis_password: 'redis.ms' ,redis_max_memory: 64MB }

Then deploy only the new node:

./redis.yml -l 10.10.10.11   # deploy only the new node

Scale Up Native Cluster

Adding new nodes to a Redis native cluster requires additional steps:

# 1. Add the new node definition in the inventory
# 2. Deploy the new node
./redis.yml -l 10.10.10.14

# 3. Add the new node to the cluster (manual execution)
redis-cli --cluster add-node 10.10.10.14:6379 10.10.10.12:6379

# 4. Reshard slots if needed
redis-cli --cluster reshard 10.10.10.12:6379

Scale Up Sentinel Cluster

After adding new instances to a Sentinel cluster, you should complete both instance deployment and target refresh:

# 1. Add new Sentinel instances to inventory, then deploy instances
./redis.yml -l <sentinel-cluster> -t redis_instance

# 2. Re-apply redis_sentinel_monitor to all sentinels
./redis.yml -l <sentinel-cluster> -t redis-ha

Scale Down Redis Nodes

Scale Down Standalone Cluster

# 1. If removing a replica, just remove it directly
./redis-rm.yml -l 10.10.10.11 -e redis_port=6379

# 2. If removing the primary, first perform a failover
redis-cli -h 10.10.10.10 -p 6380 REPLICAOF NO ONE      # promote replica
redis-cli -h 10.10.10.10 -p 6379 REPLICAOF 10.10.10.10 6380  # demote original primary

# 3. Then remove the original primary
./redis-rm.yml -l 10.10.10.10 -e redis_port=6379

# 4. Update the inventory to remove the definition

Scale Down Native Cluster

# 1. First migrate data slots
redis-cli --cluster reshard 10.10.10.12:6379 \
  --cluster-from <node-id> --cluster-to <target-node-id> --cluster-slots <count>

# 2. Remove node from cluster
redis-cli --cluster del-node 10.10.10.12:6379 <node-id>

# 3. Remove the instance
./redis-rm.yml -l 10.10.10.14

# 4. Update the inventory

Backup and Restore

Manual Backup

# Trigger RDB snapshot
redis-cli -h 10.10.10.10 -p 6379 -a <password> BGSAVE

# Check snapshot status
redis-cli -h 10.10.10.10 -p 6379 -a <password> LASTSAVE

# Copy RDB file (default location)
cp /data/redis/redis-ms-1-6379/dump.rdb /backup/redis-ms-$(date +%Y%m%d).rdb

Data Restore

# 1. Stop Redis instance
sudo systemctl stop redis-ms-1-6379

# 2. Replace RDB file
cp /backup/redis-ms-20241231.rdb /data/redis/redis-ms-1-6379/dump.rdb
chown redis:redis /data/redis/redis-ms-1-6379/dump.rdb

# 3. Start Redis instance
sudo systemctl start redis-ms-1-6379

Using AOF Persistence

If you need higher data safety, enable AOF:

redis-ms:
  vars:
    redis_aof_enabled: true
    redis_rdb_save: ['900 1', '300 10', '60 10000']  # keep RDB as well

Redeploy to apply AOF configuration:

./redis.yml -l redis-ms -t redis_config,redis_launch

Common Issue Diagnosis

Connection Troubleshooting

# Check Redis service status
systemctl status redis-ms-1-6379

# Check port listening
ss -tlnp | grep 6379

# Check firewall
sudo iptables -L -n | grep 6379

# Test connection
redis-cli -h 10.10.10.10 -p 6379 PING

Memory Troubleshooting

# Check memory usage
redis-cli -h 10.10.10.10 -p 6379 INFO memory

# Find big keys
redis-cli -h 10.10.10.10 -p 6379 --bigkeys

# Memory analysis report
redis-cli -h 10.10.10.10 -p 6379 MEMORY DOCTOR

Performance Troubleshooting

# Check slow query log
redis-cli -h 10.10.10.10 -p 6379 SLOWLOG GET 10

# Real-time command monitoring
redis-cli -h 10.10.10.10 -p 6379 MONITOR

# Check client connections
redis-cli -h 10.10.10.10 -p 6379 CLIENT LIST

Replication Troubleshooting

# Check replication status
redis-cli -h 10.10.10.10 -p 6379 INFO replication

# Check replication lag
redis-cli -h 10.10.10.10 -p 6380 INFO replication | grep lag

Performance Tuning

Memory Optimization

redis-cache:
  vars:
    redis_max_memory: 4GB           # set based on available memory
    redis_mem_policy: allkeys-lru   # LRU recommended for cache scenarios
    redis_conf: redis.conf

Persistence Optimization

# Pure cache scenario: disable persistence
redis-cache:
  vars:
    redis_rdb_save: []              # disable RDB
    redis_aof_enabled: false        # disable AOF

# Data safety scenario: enable both RDB and AOF
redis-data:
  vars:
    redis_rdb_save: ['900 1', '300 10', '60 10000']
    redis_aof_enabled: true

Connection Pool Recommendations

When connecting to Redis from client applications:

• Use connection pooling to avoid frequent connection creation
• Set reasonable timeout values (recommended 1-3 seconds)
• Enable TCP keepalive
• For high-concurrency scenarios, consider using Pipeline for batch operations

Key Monitoring Metrics

Monitor these metrics through Grafana dashboards:

• Memory usage: Pay attention when redis:ins:mem_usage > 80%
• CPU usage: Pay attention when redis:ins:cpu_usage > 70%
• QPS: Watch for spikes and abnormal fluctuations
• Response time: Investigate when redis:ins:rt > 1ms
• Connection count: Monitor connection growth trends
• Replication lag: Important for master-slave replication scenarios

5 - Monitoring

Dashboards

The REDIS module provides 3 monitoring dashboards:

• Redis Overview: Overview of all Redis clusters
• Redis Cluster: Details of a single Redis cluster
• Redis Instance: Details of a single Redis instance

Monitoring

Pigsty provides three monitoring dashboards for the REDIS module:

Redis Overview

Redis Overview: Overview of all Redis clusters/instances

Redis Cluster

Redis Cluster: Details of a single Redis cluster

Redis Instance

Redis Instance: Details of a single Redis instance

Alert Rules

Pigsty provides the following six predefined alert rules for Redis, defined in files/victoria/rules/redis.yml:

• RedisDown: Redis instance is down
• RedisRejectConn: Redis instance rejecting connections
• RedisRTHigh: Redis instance response time is too high
• RedisCPUHigh: Redis instance CPU usage is too high
• RedisMemHigh: Redis instance memory usage is too high
• RedisQPSHigh: Redis instance QPS is too high

The rule expr defines the actual alert thresholds:

• Response time: >160µs for 1 minute.
• CPU and memory usage: >70% for 1 minute.
• QPS: >32000 for 5 minutes.

The excerpt below copies the current rule file exactly. Its CPU, memory, and QPS descriptions still show the old 60%, 80%, and 16000 thresholds. The RedisRTHigh comment incorrectly names pg:ins:query_rt. These comments do not change the actual expressions.

#==============================================================#
#                         Error                                #
#==============================================================#
# redis down triggers a P0 alert
- alert: RedisDown
  expr: redis_up < 1
  for: 1m
  labels: { level: 0, severity: CRIT, category: redis }
  annotations:
    summary: "CRIT RedisDown: {{ $labels.ins }} {{ $labels.instance }} {{ $value }}"
    description: |
      redis_up[ins={{ $labels.ins }}, instance={{ $labels.instance }}] = {{ $value }} == 0
      /ui/d/redis-instance?from=now-5m&to=now&var-ins={{$labels.ins}}

# redis reject connection in last 5m
- alert: RedisRejectConn
  expr: redis:ins:conn_reject > 0
  labels: { level: 0, severity: CRIT, category: redis }
  annotations:
    summary: "CRIT RedisRejectConn: {{ $labels.ins }} {{ $labels.instance }} {{ $value }}"
    description: |
      redis:ins:conn_reject[cls={{ $labels.cls }}, ins={{ $labels.ins }}][5m] = {{ $value }} > 0
      /ui/d/redis-instance?from=now-10m&to=now&viewPanel=88&fullscreen&var-ins={{ $labels.ins }}



#==============================================================#
#                         Latency                              #
#==============================================================#
# redis avg query response time > 160 µs
- alert: RedisRTHigh
  expr: redis:ins:rt > 0.00016
  for: 1m
  labels: { level: 1, severity: WARN, category: redis }
  annotations:
    summary: "WARN RedisRTHigh: {{ $labels.cls }} {{ $labels.ins }}"
    description: |
      pg:ins:query_rt[cls={{ $labels.cls }}, ins={{ $labels.ins }}] = {{ $value }} > 160µs
      /ui/d/redis-instance?from=now-10m&to=now&viewPanel=97&fullscreen&var-ins={{ $labels.ins }}



#==============================================================#
#                        Saturation                            #
#==============================================================#
# redis cpu usage more than 70% for 1m
- alert: RedisCPUHigh
  expr: redis:ins:cpu_usage > 0.70
  for: 1m
  labels: { level: 1, severity: WARN, category: redis }
  annotations:
    summary: "WARN RedisCPUHigh: {{ $labels.cls }} {{ $labels.ins }}"
    description: |
      redis:ins:cpu_all[cls={{ $labels.cls }}, ins={{ $labels.ins }}] = {{ $value }} > 60%
      /ui/d/redis-instance?from=now-10m&to=now&viewPanel=43&fullscreen&var-ins={{ $labels.ins }}

# redis mem usage more than 70% for 1m
- alert: RedisMemHigh
  expr: redis:ins:mem_usage > 0.70
  for: 1m
  labels: { level: 1, severity: WARN, category: redis }
  annotations:
    summary: "WARN RedisMemHigh: {{ $labels.cls }} {{ $labels.ins }}"
    description: |
      redis:ins:mem_usage[cls={{ $labels.cls }}, ins={{ $labels.ins }}] = {{ $value }} > 80%
      /ui/d/redis-instance?from=now-10m&to=now&viewPanel=7&fullscreen&var-ins={{ $labels.ins }}

#==============================================================#
#                         Traffic                              #
#==============================================================#
# redis qps more than 32000 for 5m
- alert: RedisQPSHigh
  expr: redis:ins:qps > 32000
  for: 5m
  labels: { level: 2, severity: INFO, category: redis }
  annotations:
    summary: "INFO RedisQPSHigh: {{ $labels.cls }} {{ $labels.ins }}"
    description: |
      redis:ins:qps[cls={{ $labels.cls }}, ins={{ $labels.ins }}] = {{ $value }} > 16000
      /ui/d/redis-instance?from=now-10m&to=now&viewPanel=96&fullscreen&var-ins={{ $labels.ins }}

6 - Metrics

This page is a snapshot of 275 monitoring metric categories for the REDIS module. The actual runtime metric set varies with package version, enabled collectors, and target state.

7 - FAQ

ABORT due to redis_safeguard enabled

This means the Redis instance you are trying to remove has the safeguard enabled. If redis_safeguard is true, redis-rm.yml always refuses to run. The switch does not check whether an instance is running.

First, confirm the exact -l/redis_port target, a recent backup, and the redis_rm_data setting. Then use -e redis_safeguard=false to override the protection and run removal. This switch only disables the guard. It does not verify the target or recovery capability.

How to add a new Redis instance on a node?

Use bin/redis-add <ip> <port> to deploy a new Redis instance on the node.

How to remove a specific instance from a node?

Use bin/redis-rm <ip> <port> to remove a single Redis instance from the node.

How do I choose Redis or Valkey?

Current source defaults to redis_type: redis and also supports explicit redis_type: valkey. The role installs the corresponding redis or valkey package. Instance units use the matching redis-server / valkey-server and CLI binaries. Configuration paths, instance service names, monitoring job, and parameter prefixes retain the redis namespace.

The default Redis package remains on the 7.2 BSD branch. Patch versions vary by operating-system channel. Use the actual repository metadata as the authoritative source.

An engine switch to Valkey does not automatically migrate an existing cluster. First, verify RDB/AOF compatibility with the target version. Also verify replication, Sentinel/Cluster behavior, and a rollback procedure.