Redis Multi-Location

​

Overview

​

How Many Locations You Need

​

What Gets Created

​

Prerequisites

cpln gvc get GVC_NAME -o yaml

# Redis password (redis.passwordSecretName)
printf '%s' "$(openssl rand -hex 32)" | cpln secret create-opaque --name REDIS_PASSWORD_SECRET_NAME --encoding plain -f -

# Sentinel password (sentinel.passwordSecretName), independent of the one above
printf '%s' "$(openssl rand -hex 32)" | cpln secret create-opaque --name SENTINEL_PASSWORD_SECRET_NAME --encoding plain -f -

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

​

Installation

# values.yaml
global:
  locations:
    - name: aws-us-east-1
    - name: aws-eu-central-1
    - name: aws-us-west-2

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/redis-multi-location \
  --version 3.0.0 --gvc GVC_NAME -f values.yaml

​

Configuration

​

Locations

global:
  locations:
    - name: aws-us-east-1
    - name: aws-eu-central-1
    - name: aws-us-west-2

• Every entry must already be a location of the GVC you install into. At least two are required; an odd count is what buys automatic failover — see How Many Locations You Need.
• The first entry is where the initial master is seeded and where the backup job runs.
• global.locations[].replicas is deliberately not read — set redis.replicasPerLocation instead, which applies to every location. A standalone install that sets replicas is refused at render with global.locations[].replicas is not read by redis-multi-location.
• To add or remove a location, edit this list and run cpln helm upgrade. Every instance restarts (see Scaling and Availability).

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

​

Redis or Valkey

engine: redis # redis | valkey
valkeyImage: valkey/valkey:8.1.9

• INFO reports redis_version:7.2.4 for client compatibility. Read server_name and valkey_version to see what is really running; a client library that version-gates on redis_version believes it is talking to Redis 7.2.
• Use a Debian-based valkeyImage tag. Both tiers assemble their configuration in a way the -alpine images do not support, and an -alpine tag fails at start with Bad directive or wrong number of arguments. The redis -alpine tags fail the same way through redis.image and sentinel.image. Valkey 9.x tags are reachable through valkeyImage but have not been tested with this template.

​

Redis

redis:
  image: redis:7.4 # ignored when engine is valkey
  replicasPerLocation: 2 # Redis instances in EVERY location; total = this × locations
  resources:
    cpu: 200m
    memory: 256Mi
  serverCommand: redis-server # correct for both engines — the Valkey image ships a redis-server symlink
  extraArgs: "" # e.g. "--maxmemory 200mb --maxmemory-policy allkeys-lru"
  passwordSecretName: "" # e.g. my-redis-password — OPTIONAL prerequisite secret, see Authentication
  publicAccess:
    enabled: false
    address: redis.my-domain.com # a domain you own; prove ownership before enabling
  volumeset:
    initialCapacity: 20 # GiB
    autoscaling:
      enabled: false
      maxCapacity: 100 # GiB
      minFreePercentage: 10
      scalingFactor: 1.2

​

Sentinel

sentinel:
  image: redis:7.4 # ignored when engine is valkey
  resources:
    cpu: 200m
    memory: 256Mi
  extraArgs: "" # e.g. "--sentinel down-after-milliseconds mymaster 5000"
  passwordSecretName: "" # e.g. my-redis-sentinel-password — OPTIONAL prerequisite secret, independent of the Redis one
  publicAccess:
    enabled: false
    address: redis-sentinel.my-domain.com # a domain you own

​

Authentication

redis:
  passwordSecretName: "" # e.g. my-redis-password
sentinel:
  passwordSecretName: "" # e.g. my-redis-sentinel-password

• redis.passwordSecretName — applied as both requirepass and masterauth on every Redis instance, and used by Sentinel to authenticate to the master. Empty means no Redis password at all.
• sentinel.passwordSecretName — applied as requirepass on every Sentinel. Independent of the Redis password; empty means Sentinel itself is unauthenticated.

# redis-password.yaml — the whole secret, with the new payload
kind: secret
name: REDIS_PASSWORD_SECRET_NAME
type: opaque
data:
  encoding: plain
  payload: YOUR-NEW-STRONG-PASSWORD

cpln apply -f redis-password.yaml
cpln workload force-redeployment RELEASE_NAME-sentinel --gvc GVC_NAME
cpln workload force-redeployment RELEASE_NAME-redis --gvc GVC_NAME

​

Public Access

redis:
  publicAccess:
    enabled: false
    address: redis.my-domain.com # a domain you own; prove ownership before enabling
sentinel:
  publicAccess:
    enabled: false
    address: redis-sentinel.my-domain.com # a domain you own
firewall:
  externalInboundAllowCIDR: "" # comma-separated; defaults to 0.0.0.0/0 when publicAccess is on

1. Enable the dedicated load balancer on your GVC. Arbitrary TCP ports need one, and it is a paid feature. This template deploys into a GVC you already own, so it cannot turn that on for you; a domain pointed at a GVC without one is created but never serves traffic.
2. Add the DNS records before the deploy that turns public access on. Domain ownership is verified when the domain resource is first created; if the records are missing the deploy fails and the error lists the exact TXT and CNAME records required (see Required DNS Records). Add them, then upgrade the release. Disable any DNS proxying — TCP traffic must pass straight through.
3. Decide who may connect. firewall.externalInboundAllowCIDR defaults to 0.0.0.0/0 when public access is on; set it to the CIDRs your clients actually come from. Do not pin it to a single /32 unless that address is genuinely static — when your office, VPN or NAT egress rotates its IP you lose access to your own cluster from outside.

redis-cli -h redis.my-domain.com -p 6380 ping            # Redis replica 0
redis-cli -h redis-sentinel.my-domain.com -p 26380 ping  # Sentinel in the first location

​

Firewall

firewall:
  internalAllowType: same-gvc # options: same-gvc, same-org, workload-list
  # Only used when internalAllowType is workload-list. This release's OWN
  # workloads (Redis, Sentinel, the backup cron) are added automatically.
  # List your clients here; do not list this release's workloads.
  workloads: []
  #- //gvc/GVC_NAME/workload/WORKLOAD_NAME
  externalInboundAllowCIDR: "" # comma-separated; defaults to 0.0.0.0/0 when publicAccess is on
  externalOutboundAllowCIDR: "" # comma-separated

​

Backup

backup:
  enabled: false
  image: ghcr.io/controlplane-com/backup-images/redis-backup:1.0.0
  schedule: "0 2 * * *" # cron schedule, default is daily at 02:00 UTC

  resources:
    cpu: 100m
    memory: 128Mi

  provider: aws # options: aws or gcp

  aws:
    bucket: my-redis-bucket
    region: us-east-1
    cloudAccountName: my-s3-cloud-account
    policyName: my-redis-backup-policy # bucket-scoped IAM policy, see Backing Up
    prefix: redis/backups # folder within the bucket

  gcp:
    bucket: my-redis-bucket
    cloudAccountName: my-gcs-cloud-account
    prefix: redis/backups # folder within the bucket

​

Connecting

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

cpln workload exec RELEASE_NAME-redis --gvc GVC_NAME --location LOCATION_NAME \
  --replica RELEASE_NAME-redis-0 --container redis -- redis-cli ping

MASTER_INFO=$(redis-cli -h RELEASE_NAME-sentinel.GVC_NAME.cpln.local -p 26379 SENTINEL get-master-addr-by-name mymaster)
MASTER_HOST=$(echo $MASTER_INFO | cut -d' ' -f1)
MASTER_PORT=$(echo $MASTER_INFO | cut -d' ' -f2)
redis-cli -h $MASTER_HOST -p $MASTER_PORT SET my-key "Hello world"

​

Operations

​

Backing Up

​

AWS S3

1. Create an S3 bucket. Set backup.aws.bucket to its name and backup.aws.region to its region.
2. Create a cloud account for your AWS account if you do not have one. Set backup.aws.cloudAccountName to its name.
3. Create an IAM policy with the following JSON, replacing YOUR_BUCKET_NAME, and set backup.aws.policyName to its name. The workload identity is granted this policy and cpln-connector only — no broad managed policy:

{
    "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/*"
            ]
        }
    ]
}

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

​

GCS

1. Create a GCS bucket. Set backup.gcp.bucket to its name.
2. Create a cloud account for your GCP project if you do not have one. Set backup.gcp.cloudAccountName to its name.
3. Grant the Storage Admin (roles/storage.admin) role to the GCP service account associated with the cloud account. The template additionally binds the identity to roles/storage.objectAdmin on exactly the bucket named in backup.gcp.bucket.
4. 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

​

Upgrading from Version 2

​

Scaling and Availability

• Shape. The cluster has redis.replicasPerLocation Redis instances in each of your global.locations and one Sentinel per location — six Redis instances and three Sentinels by default. One Redis instance is the master; every other instance, in every location, is a replica of it. Write capacity is that of a single instance; replicas serve reads only.
• What a failover looks like. When the master stops responding, the Sentinels mark it down after 5 seconds and, if a majority of them agree, promote a replica — in any location — and repoint the rest at it. Writes pause for the duration; reads from replicas continue; the old master rejoins as a replica when it returns. Clients that discover the master through Sentinel follow it; clients pinned to one instance get READONLY errors.
• What it survives. With three or more locations, losing the master instance or an entire location leaves a quorum of Sentinels standing and a replica in a surviving location is promoted. With two locations the surviving replicas keep the data but no automatic failover happens — the vote cannot reach a majority. See How Many Locations You Need.
• Replication is asynchronous, so a failover can lose the writes the promoted replica had not yet received, bounded by the replication lag at the moment of failure.
• Every cpln helm upgrade, and every forced redeployment of the Redis tier, restarts all Redis instances in every location at once rather than one at a time. Treat it as a planned write outage and expect the master to move afterwards.
• Resizing. Change redis.replicasPerLocation to add or remove instances in every location, or edit global.locations to add or remove a location; both are a cpln helm upgrade and both restart the tier. Grow a volume with redis.volumeset.autoscaling or a larger initialCapacity. Data survives upgrades, but cpln helm uninstall deletes both volume sets.

​

Troubleshooting

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

​

Important Notes

• Never helm upgrade a 2.x release onto 3.0.0 — it deletes the GVC the old release created and everything in it. Install a new release and migrate; see Upgrading from Version 2.
• Every entry in global.locations must already be a location of the GVC, and there must be at least two. A fresh install that names a missing location refuses to start and says which one; an already-running cluster warns and keeps serving.
• Choose engine before the first install. Switching it on a running release crash-loops every instance until it is set back; migrate with a dump and restore instead.
• Create the password secrets before installing. A passwordSecretName that points at a secret that does not exist wedges the deployment silently; the name appears only in status.versions[].message.
• Rotating a password needs a forced redeployment, Sentinel first and Redis second. Updating the secret alone leaves the old password in force.
• Always discover the master through Sentinel (mymaster at RELEASE_NAME-sentinel.GVC_NAME.cpln.local:26379). A client pinned to one instance gets READONLY errors after any failover or upgrade.
• Two locations give no automatic failover. Use three or more to survive losing a location, and remember replication is asynchronous.
• Every helm upgrade restarts all Redis instances in every location at once — plan it as a short write outage and expect a new master.
• Pass global.locations from a values file, never with --set, which replaces the list with a single entry.
• With firewall.internalAllowType: workload-list, list only your clients — this release’s own workloads are added for you.
• Public access needs the dedicated load balancer enabled on your GVC and the DNS records in place first; otherwise the domain is rejected or never serves.
• Bucket backups have no verified in-place restore. Treat them as portable RDB files; see Restoring a Backup.
• Data survives an upgrade but not an uninstall — cpln helm uninstall deletes both volume sets.

​

External References