Redis

Overview

Redis is a high-performance in-memory data store used as a cache, session store, message broker and queue backend. This template deploys a master-replica Redis cluster fronted by Redis Sentinel, which elects a new master automatically when the current one fails and gives clients a stable address to discover it. One engine knob runs both tiers on Valkey, the BSD-licensed fork of Redis, instead; leaving it alone changes nothing. For development and testing, mode: dev runs a single Redis node with no Sentinel and no failover instead.

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`	Redis or Valkey data nodes (stateful, port `6379`). Production: 3 replicas, replica 0 boots as the first master and the others replicate from it. Dev: one node that runs as a plain master	—
Workload	`RELEASE_NAME-sentinel`	Sentinel quorum (stateful, 3 replicas, port `26379`); monitors the master and promotes a replica when it fails	`mode: production` (default)
Workload	`RELEASE_NAME-redis-backup`	Cron job that uploads an RDB snapshot to S3 or GCS; runs as the Redis identity	`backup.enabled: true`
Secret	`RELEASE_NAME-redis-config`	`redis.conf`, file-mounted into each Redis container	—
Secret	`RELEASE_NAME-sentinel-config`	`sentinel.conf`, file-mounted into each Sentinel container	`mode: production` (default)
Secret	`RELEASE_NAME-redis-auth-password`	Redis password, created only for a password set in values	`redis.auth.password.enabled: true`
Secret	`RELEASE_NAME-sentinel-auth-password`	Sentinel password, created only for a password set in values	`sentinel.auth.password.enabled: true` (production mode)
Secret	`RELEASE_NAME-redis-backup-config`	Bucket and region for the backup job	`backup.enabled: true`
Identity	`RELEASE_NAME-redis-identity`	Identity of the Redis workload and the backup job; carries the cloud account binding when backup is enabled	—
Identity	`RELEASE_NAME-sentinel-identity`	Sentinel workload identity	`mode: production` (default)
Policy	`RELEASE_NAME-redis-policy`	`reveal` on the Redis config and password secrets	—
Policy	`RELEASE_NAME-sentinel-policy`	`reveal` on the Sentinel config and password secrets	`mode: production` (default)
Policy	`RELEASE_NAME-redis-backup-policy`	`reveal` for the Redis identity on the backup config secret and the Redis password	`backup.enabled: true`
Volume set	`RELEASE_NAME-redis-vs`	Redis data directory (`/data`)	`redis.persistence.enabled: true`
Volume set	`RELEASE_NAME-sentinel-vs`	Sentinel state (`/etc/sentinel`), so the elected master survives a restart	`sentinel.persistence.enabled: true` (production mode)
Domain	the `redis.publicAccess.address` value	Public TCP entry point for Redis, one port per replica	`redis.publicAccess.enabled: true`
Domain	the `sentinel.publicAccess.address` value	Public TCP entry point for Sentinel, one port per replica	`sentinel.publicAccess.enabled: true` (production mode)

Prerequisites

None for a default install. Three optional features need something to exist first:

Optional: a password secret for authentication (recommended)

Authentication is off by default. To turn it on, the recommended way is a password secret you create before install, so the password never enters the release values. Create a dictionary secret with the password under the key password (the default passwordKey); one secret can serve both Redis and Sentinel:

cpln secret create-dictionary --name my-redis-password --entry password="$(openssl rand -hex 32)"

Set redis.auth.fromSecret.name (and, in production mode, sentinel.auth.fromSecret.name) to this name and fromSecret.enabled to true. See Authentication.

If the secret does not exist when the workload starts, the deployment wedges silently: cpln logs returns nothing and the workload never becomes ready. The missing secret is named only in status.versions[].message:

cpln workload get-deployments RELEASE_NAME-redis --gvc GVC_NAME -o yaml

Create the secret and the deployment recovers on its own after several minutes, or run cpln workload force-redeployment RELEASE_NAME-redis --gvc GVC_NAME to skip the wait.

Optional: public TCP access

Public access needs a domain you control, the Dedicated Load Balancer enabled on your GVC, and DNS records created before the first deploy. See Public Access and Firewall.

Optional: scheduled backups

Backups need an S3 or GCS bucket, a Control Plane cloud account and (on AWS) a bucket-scoped IAM policy. See Backing Up.

Installation

A default install needs no values:

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

To turn on authentication from the password secret in Prerequisites, set redis.auth.fromSecret.enabled=true and redis.auth.fromSecret.name=my-redis-password, and the same two keys under sentinel.auth in production mode.

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

Mode

mode: production                  # production | dev

production (default) runs redis.replicas Redis nodes and a Sentinel quorum that fails over automatically. Everything else on this page describes this mode unless it says otherwise.
dev runs one Redis node that boots as a plain master, with no Sentinel tier at all. It has no failover and is not for production: a restart or reschedule means the database is down until the node returns. Use it for development and testing.

To install in dev mode:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/redis \
  --version 3.9.0 --gvc GVC_NAME \
  --set mode=dev

In dev mode:

redis.replicas and every other sentinel setting are ignored; the Redis workload always runs one node.
Sentinel public access, persistence and authentication are refused at render. Keep sentinel.publicAccess.enabled, sentinel.persistence.enabled, sentinel.auth.password.enabled and sentinel.auth.fromSecret.enabled set to false; the Redis password is redis.auth.
Turn on redis.persistence.enabled if your data must survive restarts and upgrades. Without it the data lives in memory only. Set it at install when you can; to add it to a running release, see Persistence.
Everything else works the same as in production mode: authentication, persistence, the metrics exporter, backups, the Valkey engine, the firewall settings and Redis public access (one public port, 6380). With workload-list and backups on, add RELEASE_NAME-redis-backup to inboundAllowWorkload, or the backup job cannot reach Redis.
Clients connect directly to RELEASE_NAME-redis.GVC_NAME.cpln.local:6379. There is no Sentinel to query, so a client configured for Sentinel discovery cannot connect. See Connecting.

To move a dev release to production later, see Moving from Dev to Production.

Engine

engine: redis                     # redis | valkey
# Used for BOTH tiers when engine is valkey; redis.image / sentinel.image are
# then ignored. Only the Debian-based tags are supported (the -alpine tags have
# no bash and this chart's probes require it).
valkeyImage: valkey/valkey:8.1.9

engine is chosen at install. engine: valkey moves the Redis and Sentinel workloads onto valkeyImage together; running different engines on the two tiers is not supported. Nothing else changes: the Valkey image ships redis-server, redis-cli and redis-sentinel compatibility symlinks, so every command and config directive on this page applies to both engines. Valkey reports redis_version:7.2.4 in INFO for client compatibility and carries its real version in server_name and valkey_version; check that before switching if your client library gates features on redis_version.

The engine cannot be switched on a running deployment. Valkey cannot read the data files Redis 8 writes, so switching engine on a running release crash-loops the nodes (persistence on) or starts them empty (persistence off). Move data between engines with dump/restore or replication, never by changing engine. Setting engine back recovers the release.

Suspend

# true stops every workload in the release: Redis, Sentinel and the backup job.
# Volume sets and secrets are kept; set back to false to start it again.
suspend: false

suspend: true stops every workload the release runs: the Redis nodes, the Sentinel tier (production mode) and the backup job. Nothing is deleted: volume sets and secrets are kept, and Redis is unreachable until you set suspend back to false. With persistence on, each node reloads its data from its volume set when it starts again; without persistence, the data held in memory is lost. To suspend a release, set suspend: true in the values file you installed with and upgrade; set it back to false and upgrade again to resume:

cpln helm upgrade RELEASE_NAME oci://ghcr.io/controlplane-com/templates/redis \
  --version 3.9.0 --gvc GVC_NAME -f values.yaml

Suspending is also how persistence is added to a running release; see Persistence.

Image and Resources

redis:
  image: redis:8                  # redis:7.4 remains a supported value; the upgrade from 7.4 to 8 is one-way
  resources:
    maxCpu: 200m
    maxMemory: 256Mi
    minCpu: 80m
    minMemory: 128Mi
  replicas: 3                     # ignored in dev mode (always 1)
  timeoutSeconds: 15
  multiZone: false
  replicaDirect: false # https://docs.controlplane.com/reference/workload/general#internal-endpoint-formatting
  serverCommand: redis-server  # correct for both engines — the Valkey image ships a redis-server symlink
  # extraArgs: "--maxclients 20000 --maxmemory 200mb --maxmemory-policy allkeys-lru"
  env: []
  tags: {}
  requestRetryPolicy: {}
  dataDir: /data

Authentication

Authentication is off by default. Enable exactly one method per tier; the chart refuses to render with both enabled. In production mode apply the same config under both redis.auth and sentinel.auth; dev mode uses redis.auth only and refuses sentinel.auth. Recommended: read the password from the secret created in Prerequisites:

redis:
  auth:
    fromSecret:
      enabled: true
      name: my-redis-password   # dictionary secret; must exist before install
      passwordKey: password     # key holding the password

sentinel:
  auth:
    fromSecret:
      enabled: true
      name: my-redis-password   # the same secret can serve both tiers
      passwordKey: password

Still supported, but less secure: a password in values is stored in the Helm release, and the chart creates the password secret from it:

redis:
  auth:
    password:
      enabled: true
      value: change-me-redis-password

Set the password at install. Nodes read the secret only when they start, so a new value reaches them only after cpln workload force-redeployment, and that is a password change on a running release (see the warning below). With Sentinel persistence on, Sentinel also keeps the password it wrote at its first start.

Do not change the password on a running release, in values or in the password secret. Changing redis.auth.password.value (or the contents of the referenced secret) stops the rolling update: a restarted replica can no longer authenticate to the master, so it never becomes ready and the rollout stops advancing. Setting the previous password back recovers it. To change the password, uninstall and reinstall.

A password may contain spaces, quotes, backslashes and any other printable character. Line breaks, tabs and other control characters are not supported, because each password is written on a single configuration line.

Public Access and Firewall

redis:
  publicAccess:
    enabled: false                # true creates a domain resource routing one public TCP port per replica
    address: redis-test.example-cpln.com
  firewall:
    internal_inboundAllowType: "same-gvc" # Options: same-org / same-gvc(Recommended) / workload-list
    # external_inboundAllowCIDR: 0.0.0.0/0 # Provide a comma-separated list — REQUIRED when publicAccess is enabled
    # # You can specify additional workloads with either same-gvc or workload-list:
    # inboundAllowWorkload:
    #   - //gvc/GVC_NAME/workload/WORKLOAD_NAME
    # external_outboundAllowCIDR: "0.0.0.0/0" # Provide a comma-separated list

Public access exposes Redis and Sentinel over the internet through a Control Plane domain with per-replica TCP port routing. Sentinel public access is production mode only; dev mode refuses it. Before enabling it:

Enable the Dedicated Load Balancer on your GVC — required for arbitrary TCP port routing. It is under the GVC’s settings in the console.
Create the DNS records before deploying — ownership is verified when the domain resource is first created, and the deploy fails with Unable to apply domain if they are missing. Disable any proxying: TCP must pass straight through.

Type	Name	Value
TXT	`_cpln-SUBDOMAIN`	your Control Plane org name or org ID
CNAME	`SUBDOMAIN`	`GVC_ALIAS.cpln.app` (the alias is shown in the GVC’s settings)

Set external_inboundAllowCIDR on each tier you expose. Without it the workload’s external firewall stays closed and the domain routes nowhere.

redis:
  publicAccess:
    enabled: true
    address: redis.example.com
  firewall:
    internal_inboundAllowType: "same-gvc"
    external_inboundAllowCIDR: "0.0.0.0/0"   # or a comma-separated list of the CIDRs allowed in

sentinel:
  publicAccess:
    enabled: true
    address: redis-sentinel.example.com
  firewall:
    internal_inboundAllowType: "same-gvc"
    external_inboundAllowCIDR: "0.0.0.0/0"

Ports are assigned one per replica: Redis replica N on 6380 + N, Sentinel replica N on 26380 + N. In dev mode the single Redis node is on 6380. Firewall changes take a few minutes to take effect; re-check before concluding a rule is not working.

Replication and Probes

redis:
  # Replication tuning. See secret-redis-config.yaml for how these are rendered.
  # backlogSize: sized for (peak write throughput × tolerable disconnect window).
  #   1mb (Redis default) escalates any brief disconnect to a full RDB resync. 1gb
  #   covers ~5 minutes of disconnect at ~3MB/s of writes.
  # timeout (seconds): bound on full-resync transfer + RDB load + heartbeat.
  #   60s (Redis default) is too low for multi-GB datasets — master/slave drop the
  #   link mid-sync. 300s covers ~30GB at typical 1Gbps + load throughput.
  # slaveOutputBufferLimit: "<hard> <soft> <seconds>". Default
  #   "256mb 64mb 60" can't sustain a full resync of a multi-GB dataset at high
  #   write rate — master kills the replica mid-stream. Bump for production loads.
  replication:
    backlogSize: 1gb
    timeout: 300
    slaveOutputBufferLimit: "2gb 512mb 300"
  probes:
    readiness:
      failureThreshold: 10
      initialDelaySeconds: 10  # extend if AOF load takes longer than this
      periodSeconds: 5         # also controls startup window: budget = initialDelay + 30×period
      timeoutSeconds: 4
    liveness:
      failureThreshold: 5
      initialDelaySeconds: 30
      periodSeconds: 10
      timeoutSeconds: 5

The readiness probe holds a replica out of rotation until it has finished syncing from the master, and a node or Sentinel that answers with an authentication error is not reported ready. The liveness probe only checks that the process is up, so a replica mid-resync is never killed. The startup window is initialDelaySeconds + 30 × periodSeconds (160 seconds by default). With persistence enabled and a large dataset, a replica must load its AOF before it can sync, so raise periodSeconds to widen the window — for example initialDelaySeconds: 35 and periodSeconds: 20 gives 635 seconds.

Metrics Exporter

redis:
  exporter:
    enabled: false    # adds a redis_exporter sidecar that exposes metrics at :9121/metrics
    image: oliver006/redis_exporter:v1.67.0-alpine
    resources:
      maxCpu: 50m
      maxMemory: 64Mi
      minCpu: 25m
      minMemory: 32Mi
    dropMetrics: []  # e.g., ["redis_command_.*", "redis_keyspace_.*"]

When enabled, Control Plane scrapes :9121/metrics on each Redis replica and the metrics appear in the console. dropMetrics takes regular expressions matched against metric names, for filtering high-cardinality series such as redis_commands_latencies_usec_bucket before they are stored. The exporter authenticates with the Redis password automatically when auth is enabled.

Persistence

redis:
  persistence:
    # Best set at install. To add it to a running release, set suspend: true in
    # the same upgrade, then false; data held only in memory is lost.
    enabled: false
    volumes:
      data:
        initialCapacity: 10 # In GB
        performanceClass: general-purpose-ssd # general-purpose-ssd / high-throughput-ssd (min 200 GB)
        fileSystemType: ext4 # ext4 / xfs
        snapshots:
          retentionDuration: 7d
          schedule: 0 0 * * * # UTC
        autoscaling:
          maxCapacity: 100 # In GB
          minFreePercentage: 20
          scalingFactor: 1.2
        # customEncryption:
        #   enabled: true
        #   region: aws-us-east-1 # Replace with the appropriate region
        #   keyId: arn:aws:kms:us-east-1:1234567890:key/d411f35a-1d31-4515-9934-4f193e042d80 # Replace with your AWS KMS key ARN

With persistence enabled each Redis replica keeps its data in redis.dataDir on a volume set with both AOF and RDB persistence on, so data survives restarts and redeployments. Each node removes leftover temporary RDB and AOF-rewrite files from the volume before Redis starts, so files from an interrupted sync never accumulate. Without persistence the data lives in memory and on the container’s ephemeral filesystem only.

Turn persistence on at install when you can. Adding redis.persistence or sentinel.persistence to a running release takes effect only once every node stops, so an upgrade that turns it on by itself stalls the rollout. Add it in two upgrades instead, using the values file you installed with:

Set redis.persistence.enabled: true (or sentinel.persistence.enabled: true) and suspend: true, then upgrade.
Set suspend: false, then upgrade again.

Every node stops in between, so Redis data that is held only in memory is lost. Take a backup first if it matters.

Sentinel

The Sentinel tier exists in production mode only. In dev mode the whole sentinel block is ignored, except that Sentinel public access, persistence and authentication must stay off.

sentinel:                         # production mode only; ignored in dev mode
  image: redis:8
  resources:
    maxCpu: 200m
    maxMemory: 256Mi
    minCpu: 80m
    minMemory: 128Mi
  replicas: 3                     # keep it odd; quorum is a majority
  timeoutSeconds: 10
  multiZone: false
  replicaDirect: false # https://docs.controlplane.com/reference/workload/general#internal-endpoint-formatting
  quorumAutoCalculation: true  # Set to false if you want to override quorum. Quorum is (replicas/2)+1
  quorumOverride: null  # Only used if quorumAutoCalculation is false
  auth:
    fromSecret:
      enabled: false
      name: example-redis-auth-password
      passwordKey: password
    password:
      enabled: false
      value: change-me-sentinel-password
  publicAccess:
    enabled: false
    address: redis-sentinel-test.example-cpln.com
  firewall:
    internal_inboundAllowType: "same-gvc" # Options: same-org / same-gvc(Recommended)
  env: []
  tags: {}
  requestRetryPolicy: {}
  # Sentinel persistence preserves the post-failover master across restarts via
  # CONFIG REWRITE. Replicas query sentinel at startup, so persisted state lets
  # them rejoin the real master rather than redis-0. Recommended ON in prod.
  persistence:
    # Best set at install. To add it to a running release, set suspend: true in
    # the same upgrade, then false; data held only in memory is lost.
    enabled: false
    volumes:
      data:
        initialCapacity: 10 # In GB
        performanceClass: general-purpose-ssd # general-purpose-ssd / high-throughput-ssd (min 200 GB)
        fileSystemType: ext4 # ext4 / xfs
        snapshots:
          retentionDuration: 7d
          schedule: 0 0 * * * # UTC
        autoscaling:
          maxCapacity: 50 # In GB
          minFreePercentage: 20
          scalingFactor: 1.2

Sentinel monitors the master under the name mymaster, marks it down after 5 seconds without a response, and promotes a replica once a quorum of Sentinels agrees. Enable sentinel.persistence in production: without it, a Sentinel that restarts forgets which replica was promoted and answers from its static config (replica 0) until it re-learns the cluster.

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: 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/backups # folder name where your backups will be stored

  gcp:
    bucket: my-backup-bucket
    cloudAccountName: my-backup-cloudaccount
    prefix: redis/backups # folder name where your backups will be stored

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

Grafana Dashboard

grafana:
  dashboard:
    enabled: false          # K8s clusters only - set to true to provision the dashboard via the Grafana Operator
  folder: Redis             # Grafana folder the dashboard is placed in
  datasource: metrics       # name of the Prometheus datasource in your Grafana instance
  instanceSelector:
    matchLabels:
      dashboards: grafana   # must match the label on your Grafana CR

Kubernetes only: this emits a GrafanaDashboard custom resource for clusters running the Grafana Operator. On Control Plane’s managed platform there is no operator to reconcile it, so leave it disabled there. The Redis-specific panels need redis.exporter.enabled: true.

Connecting

What	Address	Notes
Redis, inside the GVC (production mode)	`RELEASE_NAME-redis.GVC_NAME.cpln.local:6379`	Resolves to any data node, so a plain connection may land on a read replica
Sentinel, inside the GVC (production mode)	`RELEASE_NAME-sentinel.GVC_NAME.cpln.local:26379`	Master name `mymaster`; Sentinel-aware clients use this and always reach the current master
Redis, inside the GVC (dev mode)	`RELEASE_NAME-redis.GVC_NAME.cpln.local:6379`	The single node is the master; connect to it directly, with no Sentinel discovery
Redis, public	the `redis.publicAccess.address` value, port `6380 + N` for replica N	Only with `redis.publicAccess.enabled: true`
Sentinel, public	the `sentinel.publicAccess.address` value, port `26380 + N` for replica N	Only with `sentinel.publicAccess.enabled: true` (production mode)
Password, chart-created	`cpln secret reveal RELEASE_NAME-redis-auth-password -o yaml`	With `redis.auth.password.enabled: true`; the Sentinel password is in `RELEASE_NAME-sentinel-auth-password`
Password, your own secret	`cpln secret reveal SECRET_NAME -o yaml`	With `redis.auth.fromSecret.enabled: true`

In production mode, point your client library at the Sentinel address with master name mymaster rather than at a specific Redis replica: the master moves during failovers and rolling upgrades, and writes sent to a replica are refused with READONLY You can't write against a read only replica. In dev mode, point it directly at RELEASE_NAME-redis.GVC_NAME.cpln.local:6379. To verify the deployment, ask a data node to respond and, in production mode, ask Sentinel which node is the master (add -a PASSWORD when auth is enabled):

cpln workload exec RELEASE_NAME-redis --gvc GVC_NAME --container redis -- redis-cli ping

cpln workload exec RELEASE_NAME-sentinel --gvc GVC_NAME --container sentinel -- \
  redis-cli -p 26379 SENTINEL get-master-addr-by-name mymaster

The second command prints the current master’s announced hostname and port; it does not apply in dev mode, which has no Sentinel workload. To confirm which engine a deployment is running, run redis-cli INFO server the same way: Valkey answers with server_name:valkey and a valkey_version line, Redis has neither. With public access enabled, connect from outside with the standard client, one port per replica:

redis-cli -h redis.example.com -p 6380 ping            # Redis replica 0
redis-cli -h redis-sentinel.example.com -p 26380 ping  # Sentinel replica 0

Operations

Backing Up

Backups are off by default. When backup.enabled is true, a cron workload runs on backup.schedule, takes an RDB snapshot of the cluster and uploads it to your bucket as PREFIX/redis-YYYY-MM-DDTHH-MM-SSZ.rdb.gz. The job authenticates to the bucket through the Redis identity’s cloud account binding — no static keys. Step schedules such as */30 * * * * are supported.

Switching backup.provider between aws and gcp on an existing release leaves the previous provider’s cloud binding on RELEASE_NAME-redis-identity: the rendered manifest is correct, but identity updates are merged rather than replaced. If least privilege matters to you, inspect the identity in the console 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

Each backup is a standard gzipped RDB file (redis-TIMESTAMP.rdb.gz). This template does not provide an in-place restore into a running release. To use a backup, decompress it and start a standalone Redis or Valkey server with AOF disabled and the file in place as its dump.rdb (or, on Redis 8.10 and later, with the startup-only preload-file rdb:/path/to/file.rdb setting described under Restoring a backup in the Redis persistence documentation), for example on a local machine with Docker. From there, inspect the data or replay it into your cluster with your own tooling.

Two shortcuts do not restore anything:

Placing a dump.rdb in the cluster’s data directory has no effect: the cluster runs with AOF enabled, and Redis loads the AOF at startup.
redis-cli --rdb FILE downloads a dump from a server; it does not load one, and pointing it at your backup file overwrites it.

If you enabled redis.persistence, the volume set also takes its own scheduled snapshots on redis.persistence.volumes.data.snapshots.schedule; those are managed through the volume set, independently of the bucket backups.

Upgrading from an Earlier Version

From 3.8.0 — no values changes needed. suspend defaults to false, so the release keeps running. The Redis and Sentinel start scripts and readiness probes change, so every node restarts once during the rolling upgrade. If you changed a password at runtime with CONFIG SET requirepass, set the configured password (redis.auth or the referenced secret) to match the running one before upgrading; a node whose running password differs from the configured one is not ready and stops serving. Passwords may now contain spaces, quotes and backslashes.
From 3.7.x — no values changes needed. mode defaults to production, which deploys the same topology as 3.7.x. Every Redis and Sentinel replica restarts once during the rolling upgrade, which moves the master through one Sentinel failover. With redis.persistence.enabled, data is kept.
From 3.5.1 or earlier — resource keys were renamed. Blocks that expose both a reservation and a limit now name the limit maxCpu / maxMemory instead of cpu / memory: redis.resources, sentinel.resources and redis.exporter.resources. Rename them in your values before upgrading; an upgrade that still carries the old names is refused at render with redis.resources.cpu was RENAMED to redis.resources.maxCpu. backup.resources, which exposes only a limit, keeps bare cpu / memory.
From 3.5.0 or earlier with AWS backups — permissions narrowed. Version 3.5.1 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.
From 3.4.x — Redis 7.4 to Redis 8 is one-way. Version 3.5.0 moved the default image to redis:8. Redis 8 reads 7.4 data directly, so an upgrade with persistence enabled keeps your data, but once a node has written under Redis 8 a 7.4 image can no longer load it. Snapshot the volume set first if you want a rollback path, or pin redis.image and sentinel.image to redis:7.4.

A rolling upgrade replaces replicas one at a time. The master is replaced along the way, which triggers a Sentinel failover; clients that discover the master through Sentinel follow it, clients pinned to replica 0 start receiving READONLY errors.

Moving from Dev to Production

Run a helm upgrade on the same release with mode set to production and every other value exactly as you installed it (in particular redis.persistence.enabled and redis.auth). If you installed with a values file, change mode in it:

cpln helm upgrade RELEASE_NAME oci://ghcr.io/controlplane-com/templates/redis \
  --version 3.9.0 --gvc GVC_NAME -f values.yaml

If you installed with --set flags, repeat every one of them and replace mode=dev:

cpln helm upgrade RELEASE_NAME oci://ghcr.io/controlplane-com/templates/redis \
  --version 3.9.0 --gvc GVC_NAME --set mode=production

Do not rebuild a values file from cpln helm get values: it returns --set values as flat dotted keys, which -f ignores, so persistence and authentication would fall back to their defaults. What happens:

The new replicas start and copy node 0, with or without persistence, while the dev node keeps serving.
Node 0 then restarts and Sentinel fails over to one of the new nodes, so the master ends up on node 1 or 2. This failover is expected and your data is kept.
Sentinel-aware clients see a write gap of a few seconds during the failover.

Afterwards, point your clients at Sentinel (RELEASE_NAME-sentinel.GVC_NAME.cpln.local:26379, master name mymaster) as described under Connecting. A client left on the Redis address can land on a read replica and get READONLY errors.

Scaling and Availability

The default shape is already highly available: three data nodes (one master, two replicas) and three Sentinels with a quorum of two. Change redis.replicas and sentinel.replicas to resize either tier; keep the Sentinel count odd. For a single node with no Sentinel and no failover, use mode: dev instead (see Mode).
When the master stops responding, Sentinel marks it down after 5 seconds, elects a replica and repoints the remaining replicas at it. The old master rejoins as a replica when it comes back. Writes pause for the duration of the failover; reads from replicas continue.
Write capacity is that of a single node: replicas take reads only. For more memory or throughput, raise redis.resources and redis.persistence.volumes.data rather than adding replicas.
Enable sentinel.persistence so the elected master survives Sentinel restarts, and redis.persistence so data survives Redis restarts. Set both at install when you can; to add one later, see Persistence.

Troubleshooting

Rollout stalls on Replica N will be restarted shortly after enabling persistence

Symptom: after a cpln helm upgrade that turned redis.persistence.enabled or sentinel.persistence.enabled on, every replica reports Replica N will be restarted shortly indefinitely and the volume set’s volumes stay unbound.Cause: persistence added to a running release takes effect only once every node stops.Fix: run the upgrade again with suspend: true added, then a second upgrade with suspend: false, as described under Persistence. Data held only in memory is lost, so take a backup first if it matters.

Unable to AUTH to MASTER: -WRONGPASS invalid username-password pair or user is disabled.

Symptom: after changing the Redis password, the rollout stops at the first restarted node, which logs this line and never becomes ready.Cause: the restarted node uses the new password; the master it must replicate from still runs with the old one.Fix: run cpln helm upgrade again with the previous password to recover. To change the password, uninstall and reinstall.

READONLY You can't write against a read only replica.

Symptom: writes that used to succeed are refused after a failover or a rolling upgrade.Cause: the client is connected to a fixed Redis replica that is no longer the master.Fix: configure the client for Sentinel at RELEASE_NAME-sentinel.GVC_NAME.cpln.local:26379 with master name mymaster, so it follows the master.

Can't handle RDB format version 15 after changing engine

Symptom: the first replaced replica exits with # Can't handle RDB format version 15 / # Error reading the RDB base file appendonly.aof.1.base.rdb, AOF loading aborted and crash-loops.Cause: engine was changed to valkey on a release whose data directory was written by Redis 8, which Valkey cannot read.Fix: set engine back to redis and upgrade; the rollout halts on the unhealthy replica, so the remaining nodes keep serving throughout. Migrate between engines with dump/restore or replication.

Deployment never becomes ready after enabling auth.fromSecret

Symptom: the workload never reaches ready and cpln logs returns nothing at all.Cause: the secret named in redis.auth.fromSecret.name or sentinel.auth.fromSecret.name does not exist, so the container never starts.Fix: read the missing secret’s name from status.versions[].message:

cpln workload get-deployments RELEASE_NAME-redis --gvc GVC_NAME -o yaml

Create it as shown under Prerequisites. The deployment recovers on its own after several minutes, or run cpln workload force-redeployment RELEASE_NAME-redis --gvc GVC_NAME to skip the wait.

Unable to apply domain when installing with public access

Symptom: the install fails while creating the domain resource for redis.publicAccess.address or sentinel.publicAccess.address.Cause: domain ownership is verified when the resource is first created, and the TXT or CNAME record is missing.Fix: create the records listed under Public Access and Firewall with proxying disabled, wait for DNS to propagate, then install again.

Render fails with redis.resources.cpu was RENAMED to redis.resources.maxCpu

Symptom: cpln helm install or cpln helm upgrade refuses to render and prints this message (or the memory, sentinel or exporter variant).Cause: your values file still uses the pre-3.6.0 key names.Fix: rename cpu to maxCpu and memory to maxMemory under redis.resources, sentinel.resources and redis.exporter.resources.

Render fails with cannot be true in dev mode or sentinel.auth cannot be enabled in dev mode

Symptom: cpln helm install or cpln helm upgrade with mode: dev refuses to render and prints one of:

redis: sentinel.publicAccess.enabled cannot be true in dev mode. Dev mode runs no Sentinel, so there is nothing to expose. Set it to false, or use mode: production.
redis: sentinel.persistence.enabled cannot be true in dev mode. Dev mode runs no Sentinel, and switching a release to dev would delete the Sentinel volume set. Set it to false, or use mode: production.
redis: sentinel.auth cannot be enabled in dev mode. Dev mode runs no Sentinel. Set sentinel.auth.password.enabled and sentinel.auth.fromSecret.enabled to false (the Redis password is redis.auth), or use mode: production.

Cause: dev mode runs no Sentinel tier, so a Sentinel setting that would create or remove a domain, volume set or credential is refused rather than silently dropped. Nothing is changed when the render is refused.Fix: set the named Sentinel setting to false, or keep mode: production.

Clients can still connect after tightening the firewall

Symptom: after changing internal_inboundAllowType or inboundAllowWorkload, clients the new rule excludes 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

mode: dev has no failover and is not for production. Turn on redis.persistence.enabled if dev data must survive restarts and upgrades.
Choose engine at install time. Switching it on a running release does not migrate anything; Valkey cannot read data written by Redis 8.
Choose persistence at install time when you can. To add it to a running release, set suspend: true in the same upgrade, then suspend: false; data held only in memory is lost.
suspend: true stops every node. Without persistence, the data in memory is lost.
Prefer auth.fromSecret over a password in values, which is stored in the Helm release. Create the secret before install; a missing one is named only in status.versions[].message from cpln workload get-deployments.
Never change the password in place, in values or in the password secret. The rolling update stops advancing; set the previous password back to recover, and reinstall to change it.
In production mode, always discover the master through Sentinel (mymaster at RELEASE_NAME-sentinel.GVC_NAME.cpln.local:26379). A client pinned to replica 0 gets READONLY errors after any failover or upgrade. In dev mode, connect to RELEASE_NAME-redis.GVC_NAME.cpln.local:6379 directly.
Enable sentinel.persistence in production so the elected master survives Sentinel restarts.
The Redis 7.4 to 8 upgrade is one-way. Snapshot the volume set before upgrading if you need a rollback path.
Public access needs the DNS records in place before the first deploy and external_inboundAllowCIDR uncommented, or the domain is rejected or routes nowhere.
Bucket backups are not restored in place. Load them into a standalone server; see Restoring a Backup.

External References

Redis Documentation

Official Redis documentation

Redis Sentinel

Sentinel setup and client configuration

Redis Persistence

RDB, AOF, backups and how RDB files load

Valkey Documentation

Official Valkey documentation, including Redis to Valkey migration

Backup Image Source

Source code for the Redis backup container image

Redis Template

View the source files, default values, and chart definition

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Mode

​Engine

​Suspend

​Redis

​Image and Resources

​Authentication

​Public Access and Firewall

​Replication and Probes

​Metrics Exporter

​Persistence

​Sentinel

​Backup

​Grafana Dashboard

​Connecting

​Operations

​Backing Up

​AWS S3

​GCS

​Restoring a Backup

​Upgrading from an Earlier Version

​Moving from Dev to Production

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

Redis Documentation

Redis Sentinel

Redis Persistence

Valkey Documentation

Backup Image Source

Redis Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

Mode

Engine

Suspend

Redis

Image and Resources

Authentication

Public Access and Firewall

Replication and Probes

Metrics Exporter

Persistence

Sentinel

Backup

Grafana Dashboard

Connecting

Operations

Backing Up

AWS S3

GCS

Restoring a Backup

Upgrading from an Earlier Version

Moving from Dev to Production

Scaling and Availability

Troubleshooting

Important Notes

External References