Redis Cluster

​

Overview

​

What Gets Created

• Stateful Redis Cluster Workload — (RELEASE_NAME-redis-cluster): all six nodes managed together, each running Redis or Valkey according to engine. Replica 0 initializes the cluster once all nodes are healthy.
• Volume Set — Persistent storage for each Redis node’s data directory.
• Secret — An opaque secret containing the Redis cluster configuration (redis.conf), mounted into each container.
• Secret — An opaque secret containing the cluster initialization script, mounted and executed at startup.
• Secret (optional) — A dictionary secret holding the Redis password, created when redis.password is set.
• Identity & Policy — An identity bound to the workload with reveal access to the config, startup script, and auth secrets, and cloud storage access when backup is enabled.
• Backup Cron Workload (optional) — A scheduled backup job that writes one snapshot per primary shard to AWS S3 or GCS.

​

Installation

​

Configuration

# ─── Engine ───────────────────────────────────────────────────────────────────
# Which server the cluster nodes run. `redis` is the default and changes nothing.
# `valkey` runs every node on the image below — Valkey is the BSD-licensed fork
# of Redis 7.2 and ships redis-server / redis-cli compatibility symlinks, so the
# cluster bootstrap, config directives and probes are identical.
# Chosen at INSTALL time: switching an existing release between engines is not
# supported — see Engine Selection below.
engine: redis                     # redis | valkey
# Used for every node when engine is valkey; `image` below is then ignored.
# Only the Debian-based tags are supported (the -alpine tags have no bash and the
# start script requires it).
valkeyImage: valkey/valkey:8.1.9

# Redis image for the cluster nodes. Pinned so installs are reproducible.
image: docker.io/redis:7.2

replicas: 6 # minimum value is 6
port: 6379
memory: 250Mi
cpu: 200m

internalAccess: # Sets the internal firewall scope - if set to none, replicas will not be able to reach each other
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads:  # Note: can only be used if type is same-gvc or workload-list
    #- //gvc/GVC_NAME/workload/WORKLOAD_NAME
    #- //gvc/GVC_NAME/workload/WORKLOAD_NAME

volumeset:
  capacity: 10 # initial capacity in GiB (minimum is 10)
  autoscaling:
    enabled: false # Set to true to enable autoscaling
    maxCapacity: 100 # Maximum capacity in GiB when autoscaling is enabled
    minFreePercentage: 10 # Minimum free percentage to trigger scaling when autoscaling is enabled
    scalingFactor: 1.2 # Scaling factor to determine how much to scale up when autoscaling is triggered

# Configure Redis authentication by uncommenting and setting the password field
redis: {}
  # password: "your-secure-password-here"

backup:
  enabled: false
  image: ghcr.io/controlplane-com/backup-images/redis-backup:1.0.0
  schedule: "0 2 * * *"  # daily at 2am UTC

  resources:
    cpu: 100m
    memory: 512Mi # cluster mode dumps every primary sequentially; 128Mi OOMs during GCS uploads

  provider: aws # Options: aws or gcp

  aws:
    bucket: my-backup-bucket
    region: us-east-1
    cloudAccountName: my-backup-cloudaccount
    policyName: my-backup-policy
    prefix: "redis-cluster/backups"

  gcp:
    bucket: ""
    cloudAccountName: ""
    prefix: "redis-cluster/backups"

​

Engine Selection

engine: valkey
valkeyImage: valkey/valkey:8.1.9

• valkeyImage is used for every node whenever engine is valkey, and image is then ignored entirely — a Redis tag left in image has no effect.
• Use the Debian-based Valkey tags. The -alpine tags ship no bash, which both the cluster start script and the readiness probe require.
• Valkey reports redis_version:7.2.4 in INFO for client compatibility. Read server_name and valkey_version to tell what is actually running — anything that version-gates on redis_version will believe it is talking to Redis 7.2.
• The marketplace card still shows the Redis version. A chart’s appVersion is a constant and cannot follow a values knob.
• Do not enable dual-channel-replication-enabled on Valkey; a known upstream defect confuses replica accounting.

​

Authentication

redis:
  password: "your-secure-password-here"

​

Cluster Size

• replicas — Total number of Redis nodes. 6 is the only supported value (3 primaries + 3 replicas). The cluster is always created with --cluster-replicas 1, meaning each primary has exactly one replica. Replica 0 waits for all nodes to be healthy before running redis-cli --cluster create.

​

Resources

• cpu — CPU allocated to each Redis node.
• memory — Memory allocated to each Redis node.

​

Storage

• volumeset.capacity — Initial volume size in GiB per node (minimum 10).
• volumeset.autoscaling.enabled — Automatically expand volumes as they fill. When enabled:
  • maxCapacity — Maximum volume size in GiB.
  • minFreePercentage — Trigger a scale-up when free space drops below this percentage.
  • scalingFactor — Multiply current capacity by this factor when scaling up.

​

Internal Access

• internalAccess.type — Controls which workloads can connect to the cluster:

• internalAccess.workloads — List of specific workload links, used when type is workload-list.

​

Connecting to Redis Cluster

RELEASE_NAME-redis-cluster.GVC_NAME.cpln.local:6379

RELEASE_NAME-redis-cluster-N.RELEASE_NAME-redis-cluster.GVC_NAME.cpln.local:6379

​

Ports

• port — The port every node listens on. Redis derives the cluster bus as port + 10000, and the template declares both ports, so a custom port needs no further configuration — but any client or firewall rule expecting 16379 must move with it.

​

Cluster Formation and Readiness

cpln workload exec RELEASE_NAME-redis-cluster \
  --gvc GVC_NAME \
  --replica RELEASE_NAME-redis-cluster-0 \
  --container redis-cluster \
  -- redis-cli -p 6379 cluster info

​

Backup

• backup.enabled — Enable scheduled backups.
• backup.schedule — Cron expression for backup frequency (default: daily at 2am UTC).
• backup.provider — aws or gcp.
• backup.resources.cpu / backup.resources.memory — Resources for the backup cron container.

​

AWS S3

1. Create an S3 bucket. Set backup.aws.bucket to its name and backup.aws.region to its region.
2. If you do not have a Cloud Account set up, refer to the docs to Create a Cloud Account. Set backup.aws.cloudAccountName to its name.
3. Create an IAM policy with the following JSON, replacing YOUR_BUCKET_NAME:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject",
                "s3:ListBucket",
                "s3:GetObjectVersion",
                "s3:DeleteObjectVersion",
                "s3:GetBucketLocation",
                "s3:AbortMultipartUpload",
                "s3:ListBucketMultipartUploads",
                "s3:ListMultipartUploadParts"
            ],
            "Resource": [
                "arn:aws:s3:::YOUR_BUCKET_NAME",
                "arn:aws:s3:::YOUR_BUCKET_NAME/*"
            ]
        }
    ]
}

4. Set backup.aws.policyName to the name of the policy created in step 3.
5. Set backup.aws.prefix to the folder path where backups will be stored.

​

GCS

1. Create a GCS bucket. Set backup.gcp.bucket to its name.
2. If you do not have a Cloud Account set up, refer to the docs to Create a Cloud Account. Set backup.gcp.cloudAccountName to its name.
3. Add the Storage Admin role to the GCP service account associated with the Cloud Account.
4. Set backup.gcp.prefix to the folder path where backups will be stored.

​

Restoring a Backup

aws s3 cp s3://BUCKET_NAME/PREFIX/BACKUP_FILE.rdb.gz - \
  | gunzip > /tmp/dump.rdb

​

External References