Bahriya Tersane

Documentation / valkey

Valkey

An enterprise-grade Helm chart for deploying Valkey on Kubernetes. Valkey is the open-source, BSD-licensed key-value store that succeeded Redis OSS — wire-compatible with the Redis protocol and clients.

The chart supports three deployment topologies behind a single mode: switch, and ships TLS, ACL bootstrap, persistence, S3 backups, an exporter sidecar, and a NetworkPolicy. It mirrors the conventions of the mysql chart.

Mode Topology Use it for
standalone 1 Pod dev, ephemeral caches, single-node fits-in-memory
sentinel 1 primary + N replicas, Sentinel sidecar on every Pod HA caches, session stores; data fits one node
cluster M shards × (1 primary + N replicas), gossip-based failover horizontal scale, > one node of data

Prerequisites

  • Kubernetes 1.27+
  • Helm 3.x
  • A StorageClass that supports ReadWriteOnce (Longhorn by default)

Installation

# Standalone
helm install vk charts/valkey

# Sentinel (HA), recommended 3-Pod topology
helm install vk charts/valkey \
  --set mode=sentinel \
  --set sentinel.preset=standard

# Cluster (sharded), recommended 3-shard topology
helm install vk charts/valkey \
  --set mode=cluster \
  --set cluster.preset=standard

See docs/topologies.md for the topology decision matrix.

Topology presets

Sentinel and Cluster modes both expose pre-built preset: shortcuts so you can pick a topology without sizing it yourself.

Sentinel presets

Preset Pods Quorum Notes
minimal 2 2 1 primary + 1 replica. Sentinel quorum is fragile — survives Pod loss but a network partition can prevent failover.
standard 3 2 Recommended. 1 primary + 2 replicas.
hardened 5 3 1 primary + 4 replicas. Higher read fan-out, stricter quorum.
custom sentinel.replicas sentinel.quorum Set both values yourself.

Cluster presets

Preset Pods Shards × Replicas Notes
minimal 3 3 × 0 Cache-only — losing any shard takes its slots offline.
standard 6 3 × 1 Recommended. Survives any single Pod loss.
hardened 9 3 × 2 Higher durability + more read replicas.
custom computed cluster.shards × (1 + cluster.replicasPerShard) Set both values yourself.

Connecting to Valkey

After helm install, the NOTES.txt printout includes connection examples for your chosen mode. Quick reference:

# Standalone / Sentinel best-effort / Cluster any-Pod
HOST=vk-valkey.<namespace>.svc.cluster.local   # svc.<clusterDomain> — set clusterDomain if your cluster does not use cluster.local

# Sentinel discovery — sentinel-aware clients use this to find the primary
SENTINEL_HOST=vk-valkey-sentinel.<namespace>.svc.cluster.local
SENTINEL_PORT=26379
MASTER_NAME=mymaster

# Read-only Service (sentinel + cluster modes)
READ_HOST=vk-valkey-readonly.<namespace>.svc.cluster.local

# Port-forward for local testing
kubectl port-forward -n <namespace> svc/vk-valkey 6379:6379

The chart also creates a headless service (vk-valkey-headless) so every Pod has a stable DNS name like vk-valkey-0.vk-valkey-headless.<namespace>.svc.cluster.local. Cluster-mode Pods follow the pattern vk-valkey-shard-<shard>-<ordinal>.

Failover + role tracking

In sentinel and cluster modes, every Valkey Pod labels itself: the image’s post-start monitor (/opt/bahriya/post-start.sh) checks INFO replication every 5 seconds and patches valkey.bahriya.io/role={primary,replica} on its own Pod through the Kubernetes API (RBAC: pods: get,patch — nothing more). The primary <release> Service selects role=primary and the <release>-readonly Service selects role=replica — so the load-balanced Services always track reality, even after a Sentinel-driven or cluster-gossip-driven failover.

Self-labelling is on by default for sentinel and cluster modes and a no-op in standalone. Disable it explicitly:

roleLabels:
  enabled: false

What this gives you in practice:

  • Non-Sentinel clients can use the primary Service safely. Writes routed through vk-valkey.<ns> always reach the live primary, including after a failover. Sentinel SDKs are still the gold standard, but the Service is no longer a foot-gun.
  • Reads spread across replicas. vk-valkey-readonly.<ns> excludes the current primary, so read traffic doesn’t pile up there.
  • Convergence within ~10s of a failover. Each Pod re-checks its role every 5 seconds; allow up to ~10 seconds for both sides of a promotion to settle.

In addition, sentinel-mode Pods consult the Sentinel Service on startup to determine their role — so a previous primary returning to a topology where a replica was promoted boots correctly as a replica instead of fighting for primary.

Sentinel mode: restarts and failover

  • A returning primary waits. When the Sentinels still name a starting Pod as the primary but already know replicas, the Pod is a primary returning before the Sentinels noticed it had gone. It waits with its server stopped for twice sentinel.downAfterMilliseconds (sentinel.returningPrimaryWaitMs overrides this), so that the Sentinels promote a replica, and then starts as that replica’s replica. Without this, an empty primary could return and its replicas would copy the empty data set. As a result, a planned restart of the primary always causes a failover, and takes about 10 seconds longer.
  • No second primary on a fault. If the Sentinels cannot be asked, the Pod asks its peers directly. A peer counts as absent only when its name does not resolve or its port refuses the connection. Any other failure (a timeout, a DNS fault, an authentication error), or a Pod whose own name does not resolve (a wrong clusterDomain), stops the container, which restarts and asks again. Only when every peer is definitely absent does ordinal 0 start as the primary of a new release.
  • Each Sentinel keeps one identity across restarts and announces its stable name, so a recreated Sentinel leaves no departed peer behind to block a failover.
  • After upgrading from a version published before 16 November 2026, each Sentinel may still list its old identity as a departed peer. Run SENTINEL RESET mymaster (or your sentinel.masterName) on each Sentinel in turn, about 30 seconds apart:

    for i in 0 1 2; do
      kubectl exec <release>-$i -c sentinel -- sh -c 'VALKEYCLI_AUTH="$VALKEY_PASSWORD" valkey-cli -p 26379 SENTINEL RESET mymaster'
      sleep 30
    done
    

    Check with SENTINEL CKQUORUM mymaster, which must answer OK. With TLS, add --tls --cacert /tls/ca.crt --cert /tls/tls.crt --key /tls/tls.key.

  • Known limit: when every Pod of a Sentinel release with persistence restarts at once, ordinal 0 becomes the primary even if another Pod held newer data.

Cluster mode: restarts, rolling updates and recovery

Without persistence, every start of a node is a new node. The data does not survive a restart, so the cluster configuration (nodes.conf) is removed too. A restarted primary therefore never keeps its slots empty: the cluster promotes its replica, and the restarted node joins its own shard (from its name, …-shard-N-M) as that replica’s replica. Every node then forgets the node’s earlier identity, so no failed entry stays listed; clients that refuse a cluster listing a failed node, such as Envoy’s rate-limit service, keep working. With persistence, a node keeps its identity and data, as before.

Before a primary stops, it hands over. A rolling update (any helm upgrade or value change) rolls every shard’s StatefulSet at the same time. To keep the shards from losing all their primaries together, a primary with an in-step replica asks that replica to take over (CLUSTER FAILOVER) before it stops, preferring the replica of its own shard. The shards hand over one at a time. A primary with no in-step replica stops without a handover, and says so in its log. A Pod’s stop can therefore take up to 90 seconds in cluster mode. terminationGracePeriodSeconds defaults to 120; cluster mode refuses less than 70, and 120 or more is recommended.

A roll the handover cannot protect (for example the upgrade from a version published before 16 November 2026, whose Pods have no handover) can stop every primary at once. No majority is then left to authorise a failover. A restarting node that finds its own earlier identity listed as a failed primary still owning slots tells that primary’s live replica to take over (CLUSTER FAILOVER TAKEOVER). That primary is certainly gone, because the restarting Pod replaces it, so the shard keeps its data. This relies on there being one Pod per name: do not force-delete a Pod (kubectl delete pod --force) on a node that has not failed. The old process could then still be running beside the new Pod, and a takeover could split the shard.

Both Pods of a shard lost, or every Pod deleted. If a shard’s primary and replica are lost together, that shard’s data is lost. With cluster.requireFullCoverage: true (the default) the whole cluster then refuses every key, not only that shard’s. The readiness check makes every Pod not ready, and with podDisruptionBudget.maxUnavailable: 1 node drains are blocked. A normal delete of every Pod of the release can end the same way: the Pods stop one after another during their grace period, so some shards keep their data through their replicas while another loses both nodes. Without persistence, the lost shard’s new nodes log no live primary in shard N … both of its nodes were lost and wait, checking every 10 seconds; no node joins another shard. One of them may instead replicate the lost primary in the second before that primary stops, and then logs nothing about the lost shard; the shard is lost either way. The cluster does not recover by itself while any shard still holds data, because the chart never empties a shard that holds data. To recover a cache, delete every Pod of the release with no grace period, so that they all stop together:

kubectl delete pod -l app.kubernetes.io/instance=<release> --grace-period=0

Do not add --force: without it each Pod still stops under its node’s control, and only one Pod per name runs. This empties every shard. The Pods start together, the first shard’s first Pod (…-shard-0-0) forms the cluster, empty, with each shard’s replicas replicating their own shard’s primary, and the cluster serves again within about a minute. This is the supported recovery. With persistence, a node keeps its data on its volume; if both volumes of a shard are lost, restore from a backup. Known limit, with persistence: when every Pod is deleted at once, the cluster can stay down (every key refused with CLUSTERDOWN) with the data intact on the volumes, because the Pods return with new addresses and the nodes still know each other only by the old ones. This does not happen every time. No recovery step has been tested yet; do not delete the volumes. To avoid a lost shard, set podAntiAffinity: required, so that one node never holds two Pods of a shard.

Without persistence, once no node holds data, the chart may also form an empty cluster again by itself. Rely on the recovery step above, not on this. The first shard’s first Pod (…-shard-0-0) does this only when every Pod of the release answers and none of them sees a primary that owns slots and could still be running, or a running replica of one. That must hold on every check, every 10 seconds, for terminationGracePeriodSeconds plus 30 seconds (150 seconds by default), so that no Pod still in its grace period is missed. It then checks once more, resets every node (CLUSTER RESET HARD), confirms each is reset, and forms the cluster, with each shard’s replicas replicating their own shard’s primary. A Pod that does not answer, or any node that still sees a possible owner of data, starts the wait again; the log names the reason. One log line names the reset. If the formation itself stops part-way (shard-0-0 logs the reason and restarts), run the recovery step again. With persistence this step does not exist: the chart does not render it.

Replicas are re-paired by shard on every upgrade. Clusters created with a version published before 16 November 2026 may have replicas paired across shards. Before an upgrade changes anything, a Job from the new chart (<release>-cluster-repair-pre) tells each such replica to replicate the primary of its own shard (CLUSTER REPLICATE), one replica at a time, and waits for each to be in step and for the cluster to be healthy before the next. It never moves slots, never fails over, and never changes a primary. It acts only on a settled cluster: every Pod answers, cluster_state is ok with all slots served, no node is flagged failed, and every node reports the same cluster. After the roll, <release>-cluster-repair-post checks again and normally logs pairing already by shard.

  • When the cluster is not settled within 2 minutes, the Job changes nothing and, in almost every case, logs why and lets the upgrade proceed. It stops the upgrade (UPGRADE FAILED) in one case only: a hardened layout (3 or more Pods per shard) in which a node lists a replica paired across shards, because the roll of such a cluster does not complete from that pairing. The next upgrade, once the cluster is settled, runs the step again. The post-upgrade Job never fails the release.
  • The outcome is in the Job’s log and in its Pod’s termination message (kubectl get pod -l job-name=<release>-cluster-repair-pre -o jsonpath='{.items[0].status.containerStatuses[0].state.terminated.message}'). The termination message is one line that starts with one of four tokens, then : and a description. The tokens are a stable interface; the description is not:
    • REPAIR_OK: the replicas were already paired by shard (exit 0);
    • REPAIR_RESTORED: replicas were re-paired by shard (exit 0);
    • REPAIR_SKIPPED: nothing more was done, because the cluster was not settled, the time budget was spent or a step did not complete; the upgrade proceeds (exit 0);
    • REPAIR_BLOCKED: the upgrade is stopped, in the hardened case described above (exit 1, pre-upgrade only).
    • No message at all: the Job did not end by itself, for example because its Pod could not be scheduled or was stopped from outside. helm upgrade then fails, and a platform that reads the token must treat the outcome as unknown.
  • A cluster held by REPAIR_BLOCKED because a Pod restarted on a version published before 16 November 2026 is outside the cluster. On those versions a recreated Pod can stay outside the cluster (its CLUSTER INFO shows cluster_known_nodes below the number of Pods, and the other nodes do not list its ID), while its earlier identity stays listed as failed. The cluster stays held until an operator brings the Pod back into the cluster, in this order:
    1. On the outside Pod, meet a member of the cluster (here shard-0-0, by its address):

      kubectl exec <outside-pod> -c valkey -- sh -c 'ip="$(getent ahosts "$1" | awk "{print \$1; exit}")"; VALKEYCLI_AUTH="$VALKEY_PASSWORD" valkey-cli CLUSTER MEET "$ip" 6379' \
        sh <release>-shard-0-0.<release>-headless.<namespace>.svc.<cluster domain>
      
    2. Wait a few seconds; then, on every node, forget each node ID that is flagged fail, owns no slots, and is not the ID of any Pod of the release (CLUSTER MYID on each Pod):

      ids="$(for p in $(kubectl get pods -l app.kubernetes.io/instance=<release> -o name | grep shard); do
        kubectl exec $p -c valkey -- sh -c 'VALKEYCLI_AUTH="$VALKEY_PASSWORD" valkey-cli CLUSTER MYID'; done)"
      for p in $(kubectl get pods -l app.kubernetes.io/instance=<release> -o name | grep shard); do
        for id in $(kubectl exec $p -c valkey -- sh -c 'VALKEYCLI_AUTH="$VALKEY_PASSWORD" valkey-cli CLUSTER NODES' \
            | awk '$3 ~ /(^|,)fail(,|$)/ && $9 == "" {print $1}'); do
          echo "$ids" | grep -qx "$id" || kubectl exec $p -c valkey -- sh -c 'VALKEYCLI_AUTH="$VALKEY_PASSWORD" valkey-cli CLUSTER FORGET "$1"' sh "$id"
        done
      done
      
    3. Check that cluster_known_nodes on every Pod equals the number of Pods and that no node is flagged fail, then run helm upgrade again: the re-pairing Job and the roll place the Pod in its own shard.

  • A shard with two primaries that own slots, or none (possible after a failover in a cluster paired across shards), cannot be re-paired without a failover. The Job names it and leaves its replicas as they are. To pair it: the shard with no slot owner has a Pod that replicates the primary, in another shard, that now holds its slots. Run CLUSTER FAILOVER (without FORCE or TAKEOVER) on that Pod, so that it becomes the primary of those slots, check that every shard has one primary that owns slots, and run helm upgrade again: the Job re-pairs the rest.
  • Helm’s timeout: Helm applies --timeout to each hook Job and to the roll separately. The pre-upgrade Job ends within 210 seconds and the post-upgrade Job within 120 seconds, inside Helm’s default of 5 minutes. A roll of every shard can take longer than 5 minutes, because each primary hands over before it stops: pass --timeout 10m or more. A platform that limits the whole upgrade (both Jobs, the roll and the cluster-bootstrap Job) to a fixed time must allow 330 seconds for the two Jobs beside its roll timeout: for example, a 15-minute limit with one minute of margin holds only for a roll timeout of 8 minutes (480 seconds) or less.

Checking a cluster.

  • A node left outside the cluster still reports Ready. On each Pod, cluster_known_nodes (from CLUSTER INFO) must equal the number of Pods:

    for p in $(kubectl get pods -l app.kubernetes.io/instance=<release> -o name | grep shard); do
      kubectl exec $p -c valkey -- sh -c 'VALKEYCLI_AUTH="$VALKEY_PASSWORD" valkey-cli CLUSTER INFO' | grep -E 'cluster_state|known_nodes'
    done
    
  • Each replica must belong to its own shard. Every line printed by this command must show the same shard number on both sides:

    kubectl exec <release>-shard-0-0 -c valkey -- sh -c 'VALKEYCLI_AUTH="$VALKEY_PASSWORD" valkey-cli CLUSTER NODES' \
      | awk '{split($2, a, ","); h[$1] = a[2]; m[$1] = $4; f[$1] = $3} END {for (i in f) if (f[i] ~ /slave/ && f[i] !~ /fail/) print h[i], "->", h[m[i]]}'
    

    The upgrade re-pairs replicas by shard (see above), so every line should match after an upgrade.

  • With TLS, add --tls --cacert /tls/ca.crt --cert /tls/tls.crt --key /tls/tls.key to each valkey-cli.

Slot rebalancing + scale-up (cluster mode)

The cluster-bootstrap Job is fully reconcile-aware:

  • Fresh install → valkey-cli --cluster create.
  • Restored data on primaries → manual CLUSTER ADDSLOTSRANGE + MEET + REPLICATE.
  • helm upgrade --set cluster.shards=N+1 → the bootstrap Job detects the new Pods, runs valkey-cli --cluster add-node for each, and --cluster rebalance to migrate slots onto the new shards. No manual intervention.

For ongoing maintenance, enable a periodic rebalance CronJob:

cluster:
  rebalanceCronJob:
    enabled: true
    schedule: "0 4 * * 0"   # Sunday 04:00
    threshold: 2            # skip if imbalance < 2%

The CronJob runs valkey-cli --cluster rebalance --cluster-yes --cluster-threshold N — idempotent, a no-op when slots are already evenly spread.

Authentication

Auth is disabled by default; the chart relies on NetworkPolicy for isolation. Enable it when Valkey is exposed beyond the trusted namespace.

auth:
  enabled: true
  ## Default-user password. Auto-generated if empty.
  password: ""
  ## Additional ACL users. Each is rendered into the ACL file.
  users:
    - name: app
      password: ""            # auto-generated and preserved across upgrades
      rules: "on ~* &* +@all"
    - name: readonly
      password: ""
      rules: "on ~* +@read"

Passwords are preserved across helm upgrade via a Secret lookup, so re-running the chart never rotates them.

To use an externally managed Secret instead, set auth.existingSecret. The Secret must contain the key password, and one key user-<name>-password for each user in auth.users. A users.acl key is optional:

  • If the Secret has a users.acl key, the chart uses it as the access list.
  • If it has none, the chart builds the access list from the password keys into a Secret of its own, <fullname>-acl. This needs helm install or helm upgrade run against the cluster, because the chart reads the existing Secret at that moment. Under helm template, Argo CD or a dry run the Secret cannot be read: the Pods then mount the existing Secret’s users.acl, and stay in ContainerCreating if it has none. With such tools, put a users.acl key in the existing Secret.
  • After you change a password in the existing Secret, run helm upgrade. Until then the access list holds the old password, while clients that read the Secret already use the new one. The upgrade rebuilds <fullname>-acl and restarts the Pods.

A password must not contain a space, tab or line break: Valkey reads each password as a single word, and would not start. The chart refuses such a password at install, naming it. A file given with --set-file keeps its final newline, so write it without one (printf '%s' "$PASSWORD" > file). A password in auth.existingSecret is checked when the Secret can be read, as it can by helm install and helm upgrade, but not by helm template.

Retrieve a password:

kubectl get secret vk-valkey -n <namespace> \
  -o jsonpath='{.data.password}' | base64 -d

TLS

tls:
  enabled: true
  requireSecureTransport: true   # reject plaintext on port 6379; tls-port only
  authClients: false             # set true to require client certificates (mTLS)

When TLS is enabled, the chart:

  1. Generates a self-signed CA + server certificate inline via Helm’s genCA / genSignedCert helpers (preserved across upgrades by lookup).
  2. Renders a kubernetes.io/tls Secret holding ca.crt, tls.crt, tls.key.
  3. Publishes the CA as a ConfigMap (<release>-tls-ca) so client Pods can mount it and verify the server.
  4. Wires TLS into replication and (in cluster mode) the cluster bus.

Mount the CA on a client Pod:

volumes:
  - name: valkey-ca
    configMap:
      name: vk-valkey-tls-ca
volumeMounts:
  - name: valkey-ca
    mountPath: /etc/valkey-tls
    readOnly: true

To use an external CA (cert-manager, your own PKI), set tls.existingSecret — the Secret must contain ca.crt, tls.crt, tls.key.

Persistence

RDB snapshots and AOF are both enabled by default. Each Pod gets its own PVC via volumeClaimTemplates; PVCs are retained on uninstall.

persistence:
  enabled: true
  rdb:
    enabled: true
    save:
      - "900 1"     # snapshot every 15min if >=1 key changed
      - "300 10"    # every 5min if >=10 changed
      - "60 1000"   # every 60s if >=1000 changed
    stopWritesOnBgsaveError: true
  aof:
    enabled: true
    fsync: "everysec"   # always | everysec | no
    autoRewritePercentage: 100
    autoRewriteMinSize: "64mb"

storage:
  storageClass: "longhorn"
  size: 10Gi

Memory limits and eviction

valkey:
  maxmemory: "1gb"                  # empty = no limit (uses all available)
  maxmemoryPolicy: "allkeys-lru"    # or noeviction, allkeys-lfu, volatile-lru, ...

maxmemory-policy is fully configurable — set it to noeviction when Valkey is used as a durable store rather than a cache.

Backups

S3-compatible backups via a daily CronJob. In sentinel/cluster mode the backup runs against a replica (configurable ordinal) to avoid taking BGSAVE load on the primary.

backup:
  enabled: true
  schedule: "0 2 * * *"
  fromReplicaOrdinal: 1        # which Pod ordinal to back up from
  allShards: true              # cluster mode: back up every shard
  s3:
    accessKey: ""
    secretKey: ""
    host: "s3.eu-central-1.amazonaws.com"
    bucket: "my-backups"
    region: "eu-central-1"
    prefix: "valkey"
    # existingSecret: my-backup-creds   # alternative

The CronJob:

  1. Runs BGSAVE on the chosen Pod.
  2. Polls LASTSAVE until the snapshot completes.
  3. Streams the RDB to local disk via valkey-cli --rdb.
  4. Uploads to s3://<bucket>/<prefix>/<release>/<shard>/<UTC-timestamp>.rdb.

See docs/backups-restore.md for restore recipes, S3 lifecycle, and disaster-recovery patterns.

Restoring from backup

# Standalone / Sentinel — literal key
restore:
  enabled: true
  s3Key: "valkey/vk-valkey/vk-valkey/20260521T020000Z.rdb"

# Cluster — use a `{shard}` placeholder, substituted at runtime per shard
restore:
  enabled: true
  s3Key: "valkey/vk-valkey/{shard}/20260521T020000Z.rdb"

When restore.enabled: true, each primary Pod gets an init container that downloads the RDB into its PVC on first boot, then drops a .restore-complete marker so subsequent restarts skip the download.

Mode What restores
standalone The single Pod.
sentinel Ordinal 0 only; replicas resync from the primary via replication.
cluster Ordinal 0 of every shard, each with its own per-shard RDB. The bootstrap Job detects the loaded data and switches from --cluster create to a manual join (CLUSTER ADDSLOTSRANGE + MEET + REPLICATE) so non-empty nodes are tolerated. Replicas resync via cluster replication.

To force a re-restore: delete /data/.restore-complete from the relevant PVC and restart the Pod.

Observability

A redis_exporter sidecar runs on every Pod when enabled:

metrics:
  enabled: true
  port: 9121

Prometheus scrape annotations are added to every Pod automatically. Valkey is wire-compatible with Redis, so the redis_exporter image works without modification. The chart does not ship a ServiceMonitor — wire scraping however you scrape elsewhere.

NetworkPolicy and external exposure

While networkPolicy.enabled is true, which is the default, the chart renders a Calico projectcalico.org/v3 NetworkPolicy. It then requires Calico with its API server, which serves that API; Calico is the network fabric the Bahriya Kubernetes Engine installs. The chart has no standard networking.k8s.io NetworkPolicy in its place, so on a cluster without the Calico API server set networkPolicy.enabled: false and restrict access by other means. The policy adds Allow rules on top of any baseline policy the namespace already has; it never subtracts. The chart handles only the receiving side.

networkPolicy:
  enabled: true
  openByDefault: true                       # ingress from any Pod in the SAME namespace

  # Cross-namespace clients — pass any matchLabels block (recommended:
  # the auto-managed kubernetes.io/metadata.name label).
  allowFromNamespaces:
    - kubernetes.io/metadata.name: app-prod
    - kubernetes.io/metadata.name: app-staging

  # Pre-allowlist Kong even without external exposure (e.g. for a
  # manually-managed TCPIngress).
  allowFromIngressController:
    enabled: false
    namespace: kong
    podSelector:
      matchLabels:
        app.kubernetes.io/name: kong

  # Raw NetworkPolicyPeer escape hatch — full Kubernetes API surface.
  allowFrom:
    - ipBlock:
        cidr: 10.42.0.0/16

For external clients via Kong:

tls:
  enabled: true                              # REQUIRED — Kong does SSL passthrough

exposure:
  external:
    enabled: true
    host: "valkey.example.com"
    ingressClassName: kong
    ipAllowlist:                             # REQUIRED — empty list refused at render time
      - "203.0.113.0/24"
      - "198.51.100.42/32"

The chart renders a Kong TCPIngress + KongPlugin (ip-restriction), adds the Kong proxy to the chart’s NP, and bakes the external hostname into the TLS cert’s SAN list. Kong must be configured with a stream listener in ssl_preread mode — see docs/network-and-exposure.md for the full prerequisites and debugging walkthrough.

High availability

  • PodDisruptionBudget is enabled by default (maxUnavailable: 1) for sentinel and cluster modes. Disable for standalone (it’s a single Pod).
  • Pods are kept apart by a preference by default (podAntiAffinity: preferred): the scheduler avoids placing two Pods of one shard (cluster mode), or two of the Pods (Sentinel mode), on one node, but places them together when it has no other node. podAntiAffinity: required forbids that; a Pod that cannot be placed on its own node then stays Pending, so it needs at least as many schedulable nodes as Pods per shard (cluster mode) or Pods (Sentinel mode). A value in affinity replaces both.
  • terminationGracePeriodSeconds: 120 gives Valkey time to SHUTDOWN SAVE on SIGTERM and, in cluster mode, a primary time to hand over to its replica before it stops.
  • StatefulSet persistentVolumeClaimRetentionPolicy: Retain protects against accidental data loss on uninstall.

Pod Security

The chart meets the Kubernetes restricted Pod Security Standard by default, in every mode: the Valkey Pods with the restore init container and the metrics exporter, the backup CronJob, the cluster bootstrap and rebalance Jobs, and the test Pod. Each runs as a user other than root, cannot escalate its privileges, drops all Linux capabilities and runs under the container runtime’s default seccomp profile. The backup Job writes its dump to an emptyDir volume at /tmp, on the node’s ephemeral storage, before uploading it.

An upgrade from a release without the seccomp profile restarts the Pods one at a time; data on the persistent volumes is unaffected. To remove the profile, which is not recommended, set podSecurityContext.seccompProfile to null; the Pods then meet baseline only.

Parameters

Image and naming

Parameter Description Default
image.repository Container image repository 1x.ax/tersane/core/valkey/valkey
image.tag Image tag (defaults to Chart appVersion) Set in each release
image.pullPolicy Pull policy IfNotPresent
imagePullSecrets Image pull secrets; the Secret must exist in the release’s namespace [{name: 1x-ax}]
nameOverride Override the chart name ""
fullnameOverride Override the full release name ""

Mode

Parameter Description Default
mode standalone | sentinel | cluster standalone
clusterDomain Kubernetes cluster DNS domain used in composed FQDNs cluster.local
clusterRegion Region identifier of the target cluster (set per install; only used for external announce names) ""

Valkey core

Parameter Description Default
valkey.port Client port 6379
valkey.maxmemoryPolicy Eviction policy when maxmemory is reached allkeys-lru
valkey.maxmemory Memory limit (empty = no limit) ""
valkey.config Map of valkey.conf settings see values.yaml
valkey.configOverride Raw extra lines appended to valkey.conf ""

Persistence

Parameter Description Default
persistence.enabled Mount a PVC for /data true
persistence.rdb.enabled Write RDB snapshots true
persistence.rdb.save List of save <sec> <changes> lines ["900 1", "300 10", "60 1000"]
persistence.rdb.stopWritesOnBgsaveError Stop writes on snapshot failure true
persistence.aof.enabled Enable AOF true
persistence.aof.fsync always | everysec | no everysec
persistence.aof.autoRewritePercentage Auto-rewrite threshold (%) 100
persistence.aof.autoRewriteMinSize Auto-rewrite minimum size 64mb

Auth

Parameter Description Default
auth.enabled Enable AUTH + ACLs false
auth.password Default-user password (auto-generated if empty) ""
auth.users[] Additional ACL users (name, password, rules) []
auth.existingSecret Use an existing Secret instead ""

Sentinel mode

Parameter Description Default
sentinel.preset minimal | standard | hardened | custom standard
sentinel.replicas Custom topology Pod count 3
sentinel.quorum Custom topology quorum 2
sentinel.masterName Sentinel master name mymaster
sentinel.port Sentinel port 26379
sentinel.downAfterMilliseconds down-after timer 5000
sentinel.returningPrimaryWaitMs How long a returning primary waits for a failover before starting; empty means twice downAfterMilliseconds ""
sentinel.failoverTimeoutMs failover timeout 180000
sentinel.parallelSyncs parallel-syncs 1

Cluster mode

Parameter Description Default
cluster.preset minimal | standard | hardened | custom standard
cluster.shards Custom topology shard count 3
cluster.replicasPerShard Custom topology replicas per shard 1
cluster.busPort Cluster gossip port 16379
cluster.bootstrap Run the bootstrap Job on install/upgrade true
cluster.requireFullCoverage Refuse writes when any slot is unassigned true
cluster.rebalanceCronJob.enabled Render a periodic slot-rebalance CronJob false
cluster.rebalanceCronJob.schedule Cron schedule 0 4 * * 0
cluster.rebalanceCronJob.threshold Min imbalance % before migration 2

Storage

Parameter Description Default
storage.storageClass StorageClass for PVCs longhorn
storage.size PVC size 10Gi
storage.accessModes PVC access modes [ReadWriteOnce]
persistentVolumeClaimRetentionPolicy.whenDeleted PVC retention on uninstall Retain
persistentVolumeClaimRetentionPolicy.whenScaled PVC retention on scale-down Retain

TLS

Parameter Description Default
tls.enabled Enable TLS for client + intra-cluster traffic false
tls.requireSecureTransport Reject plaintext connections true
tls.authClients Require client certificates (mTLS) false
tls.existingSecret Use an existing TLS Secret ""
tls.existingSecretKeys Key names inside the existing Secret, projected onto /tls/{ca.crt,tls.crt,tls.key} {ca: ca.crt, cert: tls.crt, key: tls.key}
tls.selfSigned.validity Self-signed cert validity in days 3650
tls.selfSigned.caSubject Self-signed CA subject; a common name only, as /CN=<name> /CN=Valkey CA

Backup + restore

Parameter Description Default
backup.enabled Render the backup CronJob false
backup.schedule Cron schedule 0 2 * * *
backup.image Container image (must have valkey-cli + s3cmd) Set in each release
backup.fromReplicaOrdinal Pod ordinal to back up from (sentinel/cluster) 1
backup.allShards Back up every shard (cluster mode) true
backup.s3.* S3 credentials + bucket + region + prefix ""
backup.s3.existingSecret Use an existing S3 credentials Secret ""
restore.enabled Render the restore init container false
restore.s3Key S3 key of the RDB to restore ""
restore.s3.* Override the restore S3 credentials (defaults to backup) ""

Role labels

Parameter Description Default
roleLabels.enabled true / false / null (auto-on for sentinel+cluster) null

Observability

Parameter Description Default
metrics.enabled Run a redis_exporter sidecar false
metrics.image.repository Exporter image 1x.ax/tersane/core/redis-exporter/redis_exporter
metrics.image.tag Exporter tag Set in each release
metrics.port Exporter port 9121

NetworkPolicy

Parameter Description Default
networkPolicy.enabled Render the NetworkPolicy true
networkPolicy.openByDefault Allow ingress from any Pod in the same namespace true
networkPolicy.allowFromNamespaces List of matchLabels blocks — each becomes a namespaceSelector ingress rule []
networkPolicy.allowFromIngressController.enabled Allow Kong proxy Pods to reach Valkey false (auto-on when exposure.external.enabled)
networkPolicy.allowFromIngressController.namespace Kong’s namespace kong
networkPolicy.allowFromIngressController.podSelector Kong Pod selector {app.kubernetes.io/name: kong}
networkPolicy.allowFrom Raw NetworkPolicyPeer entries (ipBlock, custom selectors) []
networkPolicy.platformEgress.enabled Pod-scoped egress allows (intra-namespace, DNS, 443/6443) so replication, role labels and backups survive a default-deny egress policy true
networkPolicy.platformEgress.extraPorts Extra TCP ports to allow egress to anywhere []

External exposure (Kong TCPIngress)

Parameter Description Default
exposure.external.enabled Render TCPIngress + KongPlugin (requires tls.enabled: true) false
exposure.external.host SNI hostname for the TCPIngress (required when enabled and hosts is empty) ""
exposure.external.hosts Full SNI host list — per-pod node-<N>.… names route to their per-pod Service, everything else to the primary []
exposure.external.defaultHostname Instance’s default hostname label — with domain and clusterRegion, enables per-pod announce names + per-pod Services ""
exposure.external.domain Base domain of the announce names ""
exposure.external.ingressClassName IngressClass routed by the Kong proxy kong
exposure.external.ipAllowlist CIDRs / IPs allowed (REQUIRED non-empty when enabled) []
exposure.external.annotations Additional annotations on the TCPIngress {}

Services

Parameter Description Default
service.type Primary Service type ClusterIP
service.port Primary Service port 6379
readonlyService.enabled Render a <release>-readonly Service true
readonlyService.type Read-only Service type ClusterIP
sentinelService.type Sentinel Service type (sentinel mode only) ClusterIP

Pods + scheduling

Parameter Description Default
resources.limits.cpu CPU limit 1
resources.limits.memory Memory limit 1Gi
resources.requests.cpu CPU request 100m
resources.requests.memory Memory request 256Mi
terminationGracePeriodSeconds Grace period for clean shutdown, including the cluster-mode handover (cluster mode needs at least 70) 120
podDisruptionBudget.enabled Render a PDB (sentinel + cluster) true
podDisruptionBudget.maxUnavailable PDB target 1
podAnnotations Additional pod annotations {}
podLabels Additional pod labels {}
podSecurityContext Pod-level security context {fsGroup: 1000, seccompProfile: {type: RuntimeDefault}}
securityContext Container-level security context non-root, read-only rootfs
topologySpreadConstraints Override the default soft spread []
podAntiAffinity preferred or required: how strictly Pods of one shard (cluster) or of the release (Sentinel) are kept on separate nodes preferred
affinity Override the default anti-affinity entirely {}
nodeSelector Node selector {}
tolerations Tolerations []
priorityClassName PriorityClass name ""

Extras

Parameter Description Default
extraEnv Extra env vars on the Valkey container []
extraInitContainers Extra init containers []
extraVolumes Extra volumes []
extraVolumeMounts Extra volume mounts []

See also

  • docs/topologies.md — when to pick standalone vs sentinel vs cluster, scale-up/shrink playbooks
  • docs/backups-restore.md — S3 lifecycle, restore recipes, disaster recovery
  • docs/tls-and-auth.md — TLS handshake details, ACL bootstrap recipes, mTLS
  • docs/network-and-exposure.md — how a namespace baseline policy interacts with the chart’s, cross-namespace allowlist, Kong external exposure