Redis Cluster

Overview

Redis Cluster is the native distributed mode of Redis: the keyspace is split into 16384 hash slots and spread across several primary nodes, each with its own replica, so a dataset can outgrow a single node and a failed primary is replaced by its replica without an external coordinator. This template deploys a six-node cluster — three primaries and three replicas — on persistent volumes, with optional password authentication and scheduled backups. One engine knob runs every node on Valkey, the BSD-licensed fork of Redis, instead; leaving it alone changes nothing.

This template deploys into an existing GVC that you already have. It does not create, provision or manage a GVC.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-redis-cluster`	Redis or Valkey cluster nodes (stateful, 6 replicas, data port `6379` and cluster bus `16379`); replica 0 creates the cluster once every node answers	—
Workload	`RELEASE_NAME-redis-cluster-backup`	Cron job that uploads one RDB snapshot per primary shard to S3 or GCS	`backup.enabled: true`
Secret	`RELEASE_NAME-redis-cluster-config`	`redis.conf` (cluster mode, AOF persistence, port and, when set, the password), file-mounted into each node	—
Secret	`RELEASE_NAME-redis-cluster-startup`	Start script that boots each node and bootstraps the cluster from replica 0	—
Secret	`RELEASE_NAME-redis-cluster-auth`	Dictionary secret holding `REDIS_PASSWORD`	`redis.password` set
Identity	`RELEASE_NAME-redis-cluster-identity`	Workload identity; carries the cloud account binding when backup is enabled	—
Policy	`RELEASE_NAME-redis-cluster-policy`	`reveal` on the config and start-script secrets, and on the auth secret when it exists	—
Volume set	`RELEASE_NAME-redis-cluster-vs`	Per-node data directory (`/data`), `ext4` on `general-purpose-ssd`	—

Prerequisites

None for a default install. Scheduled backups need an S3 or GCS bucket, a Control Plane cloud account and, on AWS, a bucket-scoped IAM policy before they can be enabled — see Backing Up.

Installation

A default install needs no values:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/redis-cluster \
  --version 1.6.0 --gvc GVC_NAME

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Engine

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

engine: valkey runs every cluster node on valkeyImage. Nothing else changes: the Valkey image ships redis-server, redis-cli, redis-sentinel, redis-check-rdb and redis-check-aof compatibility symlinks, so the cluster bootstrap, the config directives, the readiness probe and the backup job all run unmodified, and every command on this page applies to both engines. Valkey reports redis_version:7.2.4 in INFO server for client compatibility and carries its real identity in server_name:valkey and valkey_version; check that before switching if your client library gates features on redis_version.

	`engine: redis` (default)	`engine: valkey`
Image knob read	`image`	`valkeyImage`
Default image	`docker.io/redis:7.2`	`valkey/valkey:8.1.9`
License	Redis RSALv2 / SSPLv1	BSD-3-Clause
`INFO server` reports	`redis_version:7.2.x`	`server_name:valkey`, `valkey_version:8.1.9`, and `redis_version:7.2.4` for client compatibility

Choose the engine at install time — switching an existing release is not supported. Newer Redis releases write an on-disk format Valkey cannot read: a node whose data directory was written by redis:8 fails with Can't handle RDB format version 15 and exits instead of starting. The failure is nearly invisible, because the start script discards server output — cpln logs returns nothing for the failing node and the deployment message is empty; the only symptom is a node that never becomes ready. Migrate between engines with dump/restore or replication, never by changing engine.

Do not enable dual-channel-replication-enabled on Valkey; a known upstream defect confuses replica accounting. The marketplace card shows the Redis version even for a Valkey install, because a chart’s appVersion is a constant.

Image

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

Read only when engine is redis. A Redis tag left here has no effect under engine: valkey.

Cluster Size and Resources

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

replicas — 6 is the only supported value. The cluster is always created with one replica per primary, so six nodes form three primaries and three replicas. Fewer cannot form a cluster, which needs three primaries for quorum; more is rejected at install, because a built-in platform quota caps replica-direct workloads at 6 replicas (exceed the autoscaling.maxScale of 6 (quota: replicas-per-replica-direct-workload)).
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.
cpu / memory — per node. The default 250Mi is a floor, not a recommendation: a cache left at the default begins evicting almost immediately under real load.

Internal Access

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

Value	Description
`same-gvc`	Allow access from all workloads in the same GVC (recommended)
`same-org`	Allow access from all workloads in the same org
`workload-list`	Allow access only from the workloads listed in `workloads`
`none`	Breaks the cluster — the nodes can no longer reach each other on the data port or the cluster bus

When no password is set, internalAccess is the only access control on the cluster. Firewall changes take a few minutes to take effect; re-check before concluding a rule is not working.

Storage

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

Each node keeps its data directory (/data) on its own volume in the volume set, so data and cluster state survive restarts and upgrades. The nodes run with AOF persistence on (appendonly yes).

Authentication

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

Authentication is off by default. Setting redis.password creates the RELEASE_NAME-redis-cluster-auth secret and injects the value into both requirepass and masterauth in redis.conf, so clients and the nodes themselves authenticate with it. The password is a Helm value and is stored in the release. Add --no-auth-warning -a PASSWORD to every redis-cli call on this page when it is set.

Backup

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"

The bucket, cloud account and (on AWS) IAM policy must exist before you enable backups — see Backing Up for the per-provider setup steps.

Connecting

The template exposes no public endpoint. Reach the cluster from workloads in the same GVC, or from your machine through cpln port-forward.

What	Address	Notes
Cluster seed address, inside the GVC	`RELEASE_NAME-redis-cluster.GVC_NAME.cpln.local:6379`	Resolves to any node; a cluster-aware client discovers the rest from it
Redirect hostnames	`RELEASE_NAME-redis-cluster-N.RELEASE_NAME-redis-cluster:6379`	What `MOVED` and `ASK` redirects name node N as; resolvable only from inside the GVC, which is why clients must run there
Password	`cpln secret reveal RELEASE_NAME-redis-cluster-auth -o yaml`	Only when `redis.password` is set

Use a cluster-aware client (or redis-cli -c): a plain client pointed at one node receives MOVED redirects it does not follow, which is the most common cause of “it does not work” with this template. To verify the cluster, ask any node for its cluster state. ready on the workload only means the node answers; the cluster itself is created by replica 0 once every node is up, so during first boot a node can report ready for up to about a minute before the cluster exists.

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

cluster_state:ok with cluster_slots_assigned:16384 and cluster_known_nodes:6 means the cluster is formed. A write and read through the cluster protocol confirms redirects are followed (-c follows them):

cpln workload exec RELEASE_NAME-redis-cluster --gvc GVC_NAME \
  --replica RELEASE_NAME-redis-cluster-0 --container redis-cluster \
  -- redis-cli -c -p 6379 set mykey test

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

To confirm which engine a deployment is running, run redis-cli -p 6379 INFO server the same way: Valkey answers with server_name:valkey and a valkey_version line, Redis has neither. From your own machine, cpln port-forward RELEASE_NAME-redis-cluster 6379:6379 --gvc GVC_NAME gives a local redis-cli -p 6379 a connection to one node — good for cluster info and inspecting that node’s keys, but not for cluster-mode use, because the redirect hostnames do not resolve outside the GVC.

Operations

Backing Up

Backups are off by default. When backup.enabled is true, a cron workload runs on backup.schedule, finds the current primary of each shard, takes an RDB snapshot of each one and uploads them to your bucket as PREFIX/redis-YYYY-MM-DDTHH-MM-SSZ-node-N.rdb.gz, where N is the index of the node that was the primary at the time. A full run therefore produces three files. The job authenticates to the bucket through the workload identity’s cloud account binding — no static keys — and uses the cluster password automatically when redis.password is set.

Switching backup.provider between aws and gcp on an existing release leaves the previous provider’s cloud binding on RELEASE_NAME-redis-cluster-identity: the rendered manifest is correct, but identity updates are merged rather than replaced. If least privilege matters to you, inspect the identity after a provider switch and remove the stale binding, or reinstall the release.

AWS S3

Create an S3 bucket. Set backup.aws.bucket to its name and backup.aws.region to its region.
Create a cloud account for your AWS account if you do not have one. Set backup.aws.cloudAccountName to its name.
Create an IAM policy with the following JSON, replacing YOUR_BUCKET_NAME, and set backup.aws.policyName to its 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/*"
            ]
        }
    ]
}

Set backup.aws.prefix to the folder path where backups will be stored, then set backup.enabled: true and backup.provider: aws.

GCS

Create a GCS bucket. Set backup.gcp.bucket to its name.
Create a cloud account for your GCP project if you do not have one. Set backup.gcp.cloudAccountName to its name.
Grant the Storage Admin role to the GCP service account associated with the cloud account.
Set backup.gcp.prefix to the folder path where backups will be stored, then set backup.enabled: true and backup.provider: gcp.

Restoring a Backup

There is no verified procedure for restoring these snapshots into a running release of this template. Two things that look like they should work do not:

Copying a file into a node’s data directory as dump.rdb and restarting does nothing. The chart runs with appendonly yes, and when both AOF and RDB persistence are enabled Redis rebuilds the dataset from the AOF at startup and ignores dump.rdb.
redis-cli --rdb FILE downloads an RDB from a server; it does not load one. Running it against the cluster overwrites your downloaded backup with the live dataset.

A third problem is specific to clusters: each file holds only the keys of the hash slots its primary owned at backup time, and a node reloaded from it would serve only the keys that fall in the slots it owns now. Slot ownership is reassigned whenever the cluster is created, so after a reinstall there is no guarantee that node N owns the same slots it did when node-N was written.

What the backup is: three standard, gzipped RDB files, one per shard, and RDB files are portable. The upstream-documented way to read one is to start a standalone Redis or Valkey server with AOF disabled and the decompressed file in place as its dump.rdb — for example on a local machine with Docker — and inspect or replay the data from there. Redis documents redis-cli --cluster import for moving keys from a standalone instance into a cluster; that path has not been tested against this template. If you need to load a backup into a running cluster, test the procedure against a throwaway release before relying on it.

Upgrading from an Earlier Version

From 1.4.3 or earlier with AWS backups — permissions narrowed. Version 1.4.4 removed the AWS managed policy ReadOnlyAccess from the backup identity. It granted read access to every bucket in your account and had been silently supplying any read action your own policy omitted. Update your IAM policy to the full action list under Backing Up before upgrading; if it already matches, nothing changes. The identity now carries cpln-connector and your bucket-scoped policy only.
From 1.5.0 or earlier — a non-default port now works. In earlier versions any value other than 6379 crash-looped every node permanently, because the readiness probe and the start script always targeted the default port and the cluster bus was fixed at 16379. Version 1.6.0 passes the configured port everywhere and derives the bus from it. At the default port nothing about the deployment changes.
From 1.5.0 or earlier — the readiness probe requires a real PONG. Earlier versions ran a bare redis-cli ping, which exits 0 even when the server answers NOAUTH Authentication required, so a password-protected cluster could report ready without being usable. From 1.6.0 a node that cannot authenticate is not ready, and because the nodes roll in order, a bad credential stalls the rollout at the first replica instead of rolling all six into a broken state.
From 1.5.0 or earlier — cluster creation retries transient DNS failures. During first boot the cluster create step re-resolves every peer hostname, and a name that briefly stops resolving used to restart the container. From 1.6.0 creation retries in place and still fails loudly (FATAL: cluster create did not succeed after 12 attempts) if it genuinely cannot succeed.
1.6.0 adds engine. The default redis deploys exactly as before; see Engine before setting valkey.

Upgrades roll the nodes in order; each node’s data and cluster state are on its volume, so the cluster re-forms from nodes.conf as the nodes come back.

Scaling and Availability

The shape is fixed at six nodes: three primaries, each with exactly one replica. replicas must stay at 6 — see Cluster Size and Resources. Scale vertically with cpu, memory and volumeset.capacity (or volumeset.autoscaling) instead.
Primary failure is handled by the cluster itself. The nodes run with cluster-node-timeout 5000: when a primary stops responding for 5 seconds the other primaries agree it is down and its replica is promoted. Writes to that shard pause for the election; the other two shards keep serving. When the old primary returns it rejoins as a replica.
A cluster-aware client follows failovers automatically by refreshing its slot map from the MOVED redirects it receives. A client pinned to a single node does not.
Data survives restarts and upgrades, not an uninstall: cpln helm uninstall removes the volume set with the release. Take a backup first if the data matters.

Troubleshooting

MOVED errors, or keys that appear and disappear depending on the node

Symptom: commands fail with (error) MOVED 12182 RELEASE_NAME-redis-cluster-1.RELEASE_NAME-redis-cluster:6379, or a key written through one node cannot be read through another.Cause: the client is not cluster-aware. Redis Cluster places each key on one of three primaries and answers requests for a key held elsewhere with a redirect that a plain client does not follow.Fix: use a cluster-aware client, or redis-cli -c. The client must run inside the same GVC, because the hostnames in the redirects (RELEASE_NAME-redis-cluster-N.RELEASE_NAME-redis-cluster) resolve only there.

Workload is ready but cluster info reports cluster_state:fail or cluster_known_nodes:1

Symptom: every replica reports ready, yet redis-cli -p 6379 cluster info on a node shows cluster_state:fail, cluster_slots_assigned:0 or cluster_known_nodes:1.Cause: ready means the node answers a PING, not that the cluster exists. Replica 0 creates the cluster only after all six nodes are up, and retries if a peer hostname briefly fails to resolve; during first boot this can take about a minute after the last node is ready. If it never settles, the nodes cannot reach each other — most often internalAccess.type: none.Fix: wait a minute and run cluster info again. If it still fails, check replica 0’s log for the create attempts and their outcome:

cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-redis-cluster"}' --limit 50 --since 10m

FATAL: cluster create did not succeed after 12 attempts means creation was genuinely impossible: confirm internalAccess.type is not none, and that replicas is 6.

Install rejected with exceed the autoscaling.maxScale of 6 (quota: replicas-per-replica-direct-workload)

Symptom: cpln helm install or cpln helm upgrade fails while applying the workload with this message.Cause: replicas was set above 6. The cluster nodes are a replica-direct workload, and a built-in platform quota caps those at 6 replicas.Fix: set replicas: 6, the only supported value, and install again.

NOAUTH Authentication required

Symptom: a client or redis-cli call answers (error) NOAUTH Authentication required.Cause: redis.password is set and the client did not authenticate.Fix: pass the password — redis-cli --no-auth-warning -a PASSWORD, or your client library’s password option. Read it back with cpln secret reveal RELEASE_NAME-redis-cluster-auth -o yaml.

A node never becomes ready after changing engine, and cpln logs shows nothing

Symptom: after a cpln helm upgrade that changed engine, the first replaced node never reports ready, cpln logs returns no lines for it and the deployment message is empty.Cause: the node’s data directory was written by a Redis release whose on-disk format Valkey cannot read (Can't handle RDB format version 15); the server exits immediately, and the start script discards its output, so nothing reaches the logs.Fix: set engine and image back to the values the data was written with and upgrade again. Migrate between engines with dump/restore or replication, never by switching engine on a release that holds data.

Backup job restarts with reason OOMKilled

Symptom: backup runs end without an upload, and cpln workload get-deployments RELEASE_NAME-redis-cluster-backup --gvc GVC_NAME -o yaml shows restarts with reason OOMKilled.Cause: the job dumps every primary in turn and the upload step needs more memory than backup.resources.memory allows; lowering it to 128Mi is known to fail during GCS uploads.Fix: keep backup.resources.memory at the default 512Mi or raise it.

Clients can still connect after tightening internalAccess

Symptom: after changing internalAccess.type or internalAccess.workloads, previously allowed clients keep connecting.Cause: firewall changes take a few minutes to propagate.Fix: wait and re-test before concluding the rule is not applied.

Important Notes

Your client must speak the Redis Cluster protocol and run inside the same GVC. A plain client gets MOVED redirects it will not follow, and the redirect hostnames resolve only inside the GVC.
Authentication is off by default. Anything internalAccess admits has full access until you set redis.password.
Keep replicas at 6. Fewer cannot form a cluster; more is rejected by a platform quota.
Never set internalAccess.type: none. The nodes stop reaching each other and the cluster breaks.
Choose engine at install time. Switching it on a release that holds data is unsupported, and the failure leaves no log output.
Changing port moves the cluster bus too (port + 10000); clients and firewall rules that expect 16379 must move with it.
The default 250Mi per node is a floor. Size memory for your dataset before putting real load on the cluster.
This is not interchangeable with the Redis template. That one is primary/replica with Sentinel and a single write endpoint; this one shards the keyspace. Moving between them is a data migration, not a values change.
Bucket backups have no verified in-place restore. Treat them as portable RDB files; see Restoring a Backup.
cpln helm uninstall deletes the volume set and with it the data. Back up first.

External References

Redis Cluster Documentation

Official Redis Cluster tutorial, including client requirements and redis-cli cluster commands

Redis Persistence

RDB, AOF, backups and how RDB files load

Valkey Cluster Tutorial

The same cluster mode as documented for Valkey

Backup Image Source

Source code for the Redis backup container image

Redis Cluster Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Engine

Image

Cluster Size and Resources

Internal Access

Storage

Authentication

Backup

Connecting

Operations

Backing Up

AWS S3

GCS

Restoring a Backup

Upgrading from an Earlier Version

Scaling and Availability

Troubleshooting

Important Notes

External References

Redis Cluster Documentation

Redis Persistence

Valkey Cluster Tutorial

Backup Image Source

Redis Cluster Template

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Engine

​Image

​Cluster Size and Resources

​Internal Access

​Storage

​Authentication

​Backup

​Connecting

​Operations

​Backing Up

​AWS S3

​GCS

​Restoring a Backup

​Upgrading from an Earlier Version

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

Redis Cluster Documentation

Redis Persistence

Valkey Cluster Tutorial

Backup Image Source

Redis Cluster Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

Engine

Image

Cluster Size and Resources

Internal Access

Storage

Authentication

Backup

Connecting

Operations

Backing Up

AWS S3

GCS

Restoring a Backup

Upgrading from an Earlier Version

Scaling and Availability

Troubleshooting

Important Notes

External References