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.returningPrimaryWaitMsoverrides 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 yoursentinel.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 doneCheck with
SENTINEL CKQUORUM mymaster, which must answerOK. 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 upgradethen fails, and a platform that reads the token must treat the outcome as unknown.
- A cluster held by
REPAIR_BLOCKEDbecause 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 (itsCLUSTER INFOshowscluster_known_nodesbelow 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:-
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> -
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 MYIDon 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 -
Check that
cluster_known_nodeson every Pod equals the number of Pods and that no node is flaggedfail, then runhelm upgradeagain: 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(withoutFORCEorTAKEOVER) on that Pod, so that it becomes the primary of those slots, check that every shard has one primary that owns slots, and runhelm upgradeagain: the Job re-pairs the rest. - Helm’s timeout: Helm applies
--timeoutto 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 10mor 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(fromCLUSTER 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.keyto eachvalkey-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, runsvalkey-cli --cluster add-nodefor each, and--cluster rebalanceto 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.aclkey, 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 needshelm installorhelm upgraderun against the cluster, because the chart reads the existing Secret at that moment. Underhelm template, Argo CD or a dry run the Secret cannot be read: the Pods then mount the existing Secret’susers.acl, and stay inContainerCreatingif it has none. With such tools, put ausers.aclkey 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>-acland 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:
- Generates a self-signed CA + server certificate inline via Helm’s
genCA/genSignedCerthelpers (preserved across upgrades by lookup). - Renders a
kubernetes.io/tlsSecret holdingca.crt,tls.crt,tls.key. - Publishes the CA as a ConfigMap (
<release>-tls-ca) so client Pods can mount it and verify the server. - 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:
- Runs
BGSAVEon the chosen Pod. - Polls
LASTSAVEuntil the snapshot completes. - Streams the RDB to local disk via
valkey-cli --rdb. - 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
PodDisruptionBudgetis 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: requiredforbids 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 inaffinityreplaces both. terminationGracePeriodSeconds: 120gives Valkey time toSHUTDOWN SAVEon SIGTERM and, in cluster mode, a primary time to hand over to its replica before it stops.- StatefulSet
persistentVolumeClaimRetentionPolicy: Retainprotects 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 playbooksdocs/backups-restore.md— S3 lifecycle, restore recipes, disaster recoverydocs/tls-and-auth.md— TLS handshake details, ACL bootstrap recipes, mTLSdocs/network-and-exposure.md— how a namespace baseline policy interacts with the chart’s, cross-namespace allowlist, Kong external exposure