-
Notifications
You must be signed in to change notification settings - Fork 107
Utilities ‐ Cluster Manager
The cluster_manager.py script is a utility for creating and managing Redis/Valkey clusters and standalone instances. It supports both standalone Redis configurations with replication and cluster mode configurations with multiple shards and replicas. The script is used primarily for development, testing, and performance evaluation purposes.
- Python 3.x
- Redis/Valkey server binaries (
redis-server/valkey-serverandredis-cli/valkey-cli) - OpenSSL (for TLS certificate generation)
python utils/cluster_manager.py [global_options] <action> [action_options]| Option | Description | Default | Required |
|---|---|---|---|
-H, --host |
Host address for the Redis/Valkey instances | 127.0.0.1 |
No |
--tls |
Enable TLS encryption | False |
No |
--auth |
Authentication password | None |
No |
-log, --loglevel |
Logging level (critical, error, warn, warning, info, debug) | info |
No |
--logfile |
Path to log file | Defaults to cluster folder | No |
Creates a new Redis/Valkey cluster or standalone instance.
| Option | Description | Default | Required |
|---|---|---|---|
--cluster-mode |
Create a Redis Cluster with cluster mode enabled | False |
No |
--folder-path |
Path to create the cluster main folder | Auto-detected | No |
-p, --ports |
List of specific ports to use | Auto-assigned | No |
-n, --shard-count |
Number of cluster shards (cluster mode only) | 3 |
No |
-r, --replica-count |
Number of replicas in each shard | 1 |
No |
--prefix |
Prefix for the cluster folder name |
cluster (or tls-cluster with TLS) |
No |
--load-module |
Paths to server modules to load | None |
No |
Shuts down running Redis/Valkey clusters or instances.
| Option | Description | Default | Required |
|---|---|---|---|
--folder-path |
Folder path to stop all clusters with a prefix | Auto-detected | No |
--prefix |
Stop all clusters starting with this prefix | None |
No |
--cluster-folder |
Stop cluster in specified folder path | None |
No |
--keep-folder |
Keep the cluster folder after stopping | False |
No |
--pids |
Comma-separated list of process IDs to terminate | "" |
No |
python utils/cluster_manager.py startCreates a standalone Redis instance with 1 replica on default host (127.0.0.1).
python utils/cluster_manager.py -H 192.168.1.100 --loglevel debug start \
--replica-count 2 \
--prefix my-redis \
--folder-path /opt/redis-clustersCreates a standalone Redis with 2 replicas, custom host, debug logging, and custom folder.
python utils/cluster_manager.py start \
--replica-count 1 \
--ports 6379 6380Creates a standalone Redis with 1 replica using specific ports 6379 (primary) and 6380 (replica).
python utils/cluster_manager.py start --cluster-modeCreates a Redis cluster with 3 shards, 1 replica per shard (6 total nodes).
python utils/cluster_manager.py start \
--cluster-mode \
--shard-count 5 \
--replica-count 2 \
--prefix production-cluster \
--folder-path /var/redis-clustersCreates a Redis cluster with 5 shards, 2 replicas per shard (15 total nodes).
python utils/cluster_manager.py start \
--cluster-mode \
--shard-count 2 \
--replica-count 1 \
--ports 7000 7001 7002 7003Creates a Redis cluster with 2 shards, 1 replica each, using ports 7000-7003.
python utils/cluster_manager.py --tls start \
--cluster-mode \
--shard-count 3 \
--replica-count 1Creates a TLS-enabled Redis cluster with automatic certificate generation.
python utils/cluster_manager.py start \
--load-module /path/to/module1.so \
--load-module /path/to/module2.so \
--replica-count 0Creates a standalone Redis instance (no replicas) with custom modules loaded.
python utils/cluster_manager.py --auth mypassword start \
--cluster-mode \
--shard-count 2 \
--replica-count 1Creates an authenticated Redis cluster.
python utils/cluster_manager.py stop --cluster-folder /path/to/cluster-2024-01-15T10-30-45Z-abc123Stops a specific cluster by its folder path.
python utils/cluster_manager.py stop \
--prefix production-cluster \
--folder-path /var/redis-clustersStops all clusters starting with "production-cluster" in the specified folder.
python utils/cluster_manager.py stop \
--cluster-folder /path/to/my-cluster \
--keep-folderStops the cluster but preserves the cluster folder and log files.
python utils/cluster_manager.py --auth mypassword stop \
--cluster-folder /path/to/authenticated-clusterStops an authenticated cluster.
python utils/cluster_manager.py --tls stop \
--cluster-folder /path/to/tls-clusterStops a TLS-enabled cluster.
python utils/cluster_manager.py stop --pids 12345,12346,12347Stops Redis processes by their process IDs.
python utils/cluster_manager.py stop \
--prefix test \
--folder-path /tmp/test-clustersStops all clusters with "test" prefix in the test folder.
When starting a cluster, the script outputs:
-
CLUSTER_FOLDER=<path>- Path to the created cluster folder -
CLUSTER_NODES=<host:port,host:port,...>- List of all node addresses -
SERVERS_JSON=<json>- JSON array with detailed server information
The script uses the following environment variables:
| Variable | Description | Default |
|---|---|---|
GLIDE_HOME_DIR |
Base directory for GLIDE | Script directory |
CLUSTERS_FOLDER |
Directory for cluster folders | ${GLIDE_HOME_DIR}/clusters |
When using the --tls flag:
- Certificates are automatically generated if they don't exist
- Certificate files are stored in
${GLIDE_HOME_DIR}/tls_crts/ - Generated certificates are valid for 10 years
- Certificate files include:
-
ca.crt- Certificate Authority certificate -
server.crt- Server certificate -
server.key- Server private key
-
cluster-folder/
├── cluster_manager.log # Main log file
├── 6379/ # Node folder (port number)
│ ├── server.log # Node-specific log
│ └── [other Redis files]
├── 6380/
│ ├── server.log
│ └── [other Redis files]
└── ...
For development and testing purposes, you can use shorter-lived clusters:
# Start a test cluster
python utils/cluster_manager.py start \
--prefix test \
--cluster-mode \
--shard-count 2 \
--replica-count 0
# Stop all test clusters
python utils/cluster_manager.py stop --prefix test# Start cluster for tests
CLUSTER_OUTPUT=$(python utils/cluster_manager.py start --cluster-mode)
CLUSTER_FOLDER=$(echo "$CLUSTER_OUTPUT" | grep "CLUSTER_FOLDER=" | cut -d'=' -f2)
# Run your tests here
# ...
# Clean up
python utils/cluster_manager.py stop --cluster-folder "$CLUSTER_FOLDER"# Large cluster for performance testing
python utils/cluster_manager.py start \
--cluster-mode \
--shard-count 10 \
--replica-count 1 \
--prefix perf-test- Port conflicts: If specific ports are unavailable, the script will automatically find free ports
- Permission issues: Ensure the user has write permissions to the cluster folder path
- TLS certificate issues: Certificates are regenerated automatically if invalid or expired
- Server startup failures: Check the individual node log files in the cluster folder
- Main log:
{cluster_folder}/cluster_manager.log - Node logs:
{cluster_folder}/{port}/server.log
Use debug logging for detailed information:
python utils/cluster_manager.py --loglevel debug start --cluster-mode- Port assignment: If no specific ports are provided, the script automatically finds available ports
-
TLS certificates: When using
--tls, certificates are automatically generated if they don't exist - Cluster validation: The script waits for all nodes to be ready and properly connected before completing
- Process management: The script tracks process IDs for proper shutdown management
- Compatibility: Works with both Redis and Valkey server binaries
- Platform support: Tested on macOS and Linux systems
When making changes to the cluster manager:
- Test with both standalone and cluster configurations
- Verify TLS functionality works correctly
- Ensure proper cleanup in stop operations
- Add appropriate logging for debugging
- Use
git commit --signoffwhen committing changes (required for DCO compliance)