Undermoon

Undermoon is a self-managed Redis clustering system based on Redis Cluster Protocol supporting:

• Horizontal scalability and high availability
• Cluster management through HTTP API
• Automatic failover for both master and replica
• Fast scaling

Any storage system implementing redis protocol could also somehow work with undermoon, such as KeyDB.

For more in-depth explanation of Redis Cluster Protocol and how Undermoon implement it, please refer to Redis Cluster Protocol.

Architecture

Metadata Storage

Metadata storage stores all the metadata of the whole undermoon cluster, including existing Redis instances, proxies, and exposed Redis clusters. Now it's an in-memory storage server called Memory Broker. When using undermoon-operator, this Memory Broker will change to use ConfigMap to store the data.

Coordinator

Coordinator will synchronize the metadata between broker and server proxy. It also actively checks the liveness of server proxy and initiates failover.

Storage Cluster

The storage cluster consists of server proxies and Redis instances. It serves just like the official Redis Cluster to the applications. A Redis Cluster Proxy could be added between it and applications so that applications don't need to upgrade their Redis clients to smart clients.

Chunk

Chunk is the smallest building block of every single exposed Redis Cluster. Each chunk consists of 4 Redis instances and 2 server proxies evenly distributed in two different physical machines. So the node number of each Redis cluster will be the multiples of 4 with half masters and half replicas.

The design of chunk makes it very easy to build a cluster with a good topology for workload balancing.

Getting Started

Run Undermoon in Kubernetes

Using undermoon-operator is the easiest way to create Redis clusters if you have Kubernetes.

helm install my-undermoon-operator undermoon-operator-<x.x.x>.tgz

helm install \
    --set 'cluster.clusterName=my-cluster-name' \
    --set 'cluster.chunkNumber=2' \
    --set 'cluster.maxMemory=2048' \
    --set 'cluster.port=5299' \
    my-cluster \
    -n my-namespace \
    undermoon-cluster-<x.x.x>.tgz

See the README.md of undermoon-operator for how to use it.

Run Undermoon Using Docker Compose

See docker compose example.

Setup Undermoon Manually

Or you can set them up without docker following this docs: setting up undermoon manually.

Development

undermoon tries to avoid unsafe and some calls that could crash like unwrap.

Run the following commands before committing your codes:

$ make lint
$ make test

See more in the development guide.

Documentation

• Redis Cluster Protocol and Server Proxy
• Chunk
• Slot Migration
• Memory Broker Replica
• Configure to support non-cluster-mode clients
• Command Table
• Performance
• Best Practice
• Broker External Storage

API

• Proxy UMCTL command
• HTTP Broker API
• Memory Broker API