Running an Undermoon Redis Cluster with Docker Compose

Undermoon is an open‑source system for managing Redis clusters. Repository: https://github.com/doyoubi/undermoon

Prerequisites

docker‑compose

redis-cli

jq

Start an example cluster

Run the provided Docker composition directly: $ make docker-mem-broker-example Or build the test image and start it:

$ make docker-build-test-image
$ make docker-mem-broker

Register storage resources

After the containers are up, execute the initialization script which registers six proxies via the HTTP API: $ ./examples/mem-broker/init.sh List the registered proxy addresses:

$ curl http://localhost:7799/api/v3/proxies/addresses

Create a cluster

Each proxy hosts two Redis nodes, giving a total of twelve nodes. The cluster size must be a multiple of four. Create a four‑node cluster (two masters, two replicas):

$ curl -XPOST -H 'Content-Type: application/json' \
    http://localhost:7799/api/v3/clusters/meta/mycluster -d '{"node_number": 4}'

Add the proxy hostnames to /etc/hosts so the client can resolve them:

# /etc/hosts
127.0.0.1 server_proxy1
127.0.0.1 server_proxy2
127.0.0.1 server_proxy3
127.0.0.1 server_proxy4
127.0.0.1 server_proxy5
127.0.0.1 server_proxy6

Identify the proxies assigned to the cluster using jq:

# List the proxies of "mycluster"
$ curl -s http://localhost:7799/api/v3/clusters/meta/mycluster | jq '.cluster.nodes[].proxy_address' | uniq
"server_proxy5:6005"
"server_proxy6:6006"

Connect to a chosen proxy with cluster mode enabled:

$ redis-cli -h server_proxy5 -p 6005 -c
server_proxy5:6005> get a
-> Redirected to slot [15495] located at server_proxy6:6006
(nil)
server_proxy6:6006> get b
-> Redirected to slot [3300] located at server_proxy5:6005
(nil)

Scale the cluster

Expand the four‑node cluster to eight nodes by adding four more nodes and starting data migration:

# Add 4 nodes
$ curl -XPATCH -H 'Content-Type: application/json' \
    http://localhost:7799/api/v3/clusters/nodes/mycluster -d '{"node_number": 4}'
# Start migration
$ curl -XPOST http://localhost:7799/api/v3/clusters/migrations/expand/mycluster

List all Redis node addresses after expansion:

$ curl -s http://localhost:7799/api/v3/clusters/meta/mycluster | jq '.cluster.nodes[].address'
"redis9:6379"
"redis10:6379"
"redis11:6379"
"redis12:6379"
"redis3:6379"
"redis4:6379"
"redis7:6379"
"redis8:6379"

Failover demonstration

Terminate a proxy container (e.g., server_proxy5:6005) to trigger failover:

$ docker ps | grep server_proxy5 | awk '{print $1}' | xargs docker kill

Undermoon detects the failure, replaces the dead proxy with a spare, promotes a replica to master, and attaches a new replica. Verify the updated proxy list:

# server_proxy5 is replaced by server_proxy3
$ curl -s http://localhost:7799/api/v3/clusters/meta/mycluster | jq '.cluster.nodes[].proxy_address' | uniq
"server_proxy3:6003"
"server_proxy6:6006"
"server_proxy2:6002"
"server_proxy4:6004"

Remove the replaced proxy from the cluster:

$ curl -XDELETE http://localhost:7799/api/v3/proxies/meta/server_proxy3:6003