Skip to main content

​
Overview

Redis Cluster is a distributed Redis deployment with automatic data sharding across multiple primary nodes and built-in replication. This template deploys a native Redis Cluster with 3 primary shards and 3 replicas, providing both horizontal scalability and high availability without an external Sentinel process.
This template does not create a GVC. You must deploy it into an existing GVC.

​
What Gets Created

  • Stateful Redis Cluster Workload — (RELEASE_NAME-redis-cluster): all replicas managed together. 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

This template has no external prerequisites unless backup is enabled. To install, follow the instructions for your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations
Pulumi Icon Streamline Icon: https://streamlinehq.com

Pulumi

Declare templates in your Pulumi programs

​
Configuration

The default values.yaml for this template: 
replicas: 6 # minimum value is 6

port: 6379
memory: 250Mi
cpu: 200m

internalAccess:
  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

volumeset:
  capacity: 10 # initial capacity in GiB (minimum is 10)
  autoscaling:
    enabled: false
    maxCapacity: 100 # Maximum capacity in GiB
    minFreePercentage: 10 # Trigger scaling when free space drops below this percentage
    scalingFactor: 1.2 # Multiply current capacity by this factor when scaling up

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

backup:
  enabled: false
  image: controlplanecorporation/redis-backup:1.0 # compatible with all Redis versions
  schedule: "0 2 * * *"  # daily at 2am UTC

  resources:
    cpu: 100m
    memory: 128Mi

  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: my-backup-bucket
    cloudAccountName: my-backup-cloudaccount
    prefix: redis-cluster/backups

​
Authentication

Authentication is disabled by default. To enable it, set a password: 
redis:
  password: your-secure-password
When set, the password is stored in a dictionary secret and injected into both requirepass and masterauth in redis.conf, ensuring all nodes authenticate with each other.

​
Cluster Size

  • replicas — Total number of Redis nodes. Minimum is 6 (3 primaries + 3 replicas). The cluster is always created with --cluster-replicas 1, meaning each primary has exactly one replica.
Do not scale the replica count below 6. The cluster requires at least 3 primary nodes and 3 replica nodes to initialize. 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

A Volume Set is always created to persist cluster data. The file system is ext4 and the performance class is general-purpose-ssd.
  • 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

Redis Cluster nodes must be able to communicate with each other on both the data port and the cluster bus port. Setting internalAccess.type to none will prevent inter-node communication and break the cluster.
  • internalAccess.type — Controls which workloads can connect to the cluster:
ValueDescription
same-gvcAllow access from all workloads in the same GVC (recommended)
same-orgAllow access from all workloads in the same organization
workload-listAllow access only from specific workloads listed in workloads
  • internalAccess.workloads — List of specific workload links, used when type is workload-list.

​
Connecting to Redis Cluster

Redis Cluster requires a cluster-aware client. Connect to any node as a seed address — the client will discover the rest of the cluster automatically: 
RELEASE_NAME-redis-cluster.GVC_NAME.cpln.local:6379
Each individual node is also accessible directly: 
RELEASE_NAME-redis-cluster-N.RELEASE_NAME-redis-cluster.GVC_NAME.cpln.local:6379

​
Ports

PortProtocolDescription
6379TCPRedis data port
16379TCPRedis cluster bus (internal node-to-node communication)

​
Backup

Backup is disabled by default. When enabled, a cron workload runs on the configured schedule and produces one compressed .rdb.gz file per primary shard, uploaded to AWS S3 or GCS. The backup image is compatible with all Redis versions.
  • 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

Before enabling backup with provider: aws, complete the following in your AWS account:
  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"
            ],
            "Resource": [
                "arn:aws:s3:::YOUR_BUCKET_NAME",
                "arn:aws:s3:::YOUR_BUCKET_NAME/*"
            ]
        }
    ]
}
  1. Set backup.aws.policyName to the name of the policy created in step 3.
  2. Set backup.aws.prefix to the folder path where backups will be stored.

​
GCS

Before enabling backup with provider: gcp, complete the following in your GCP account:
  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

Each primary shard produces its own backup file (e.g. redis-<timestamp>-node-0.rdb.gz). Download and decompress the file for the shard you want to restore, then copy it to /data/dump.rdb on the corresponding replica and restart that replica. For GCS, replace aws s3 cp s3://... with gsutil cp gs://.... 
aws s3 cp s3://BUCKET_NAME/PREFIX/BACKUP_FILE.rdb.gz - \
  | gunzip > /tmp/dump.rdb

​
External References

Redis Cluster Documentation

Official Redis Cluster setup and client configuration guide

Backup Image Source

Source code for the Redis backup container image

Redis Cluster Template

View the source files, default values, and chart definition