Valkey

Valkey is an open-source in-memory key-value datastore. The HelmForge chart supports standalone, replication, Sentinel, and cluster topologies in one chart.

Key Features

Official docker.io/valkey/valkey image pinned to 9.1.0
Topology selection with architecture
Generated, inline, existing Secret, or ExternalSecret password modes
Optional TLS file wiring
Topology-specific Services, StatefulSets, and Valkey Cluster bootstrap Job
Valkey exporter sidecar, ServiceMonitor, PDB, dual-stack Services, and extension hooks
Restricted-compatible pod and container security contexts for Valkey, metrics, tests, and cluster bootstrap workloads

Installation

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install valkey helmforge/valkey --namespace valkey --create-namespace

helm install valkey oci://ghcr.io/helmforgedev/helm/valkey --namespace valkey --create-namespace

Topologies

Architecture	Use case
`standalone`	Development and simple workloads.
`replication`	Fixed primary with read replicas.
`sentinel`	Automatic primary discovery and failover for Sentinel-aware clients.
`cluster`	Sharded datasets for Valkey Cluster-aware clients.

Examples

Sentinel production baseline:

architecture: sentinel
auth:
  existingSecret: valkey-auth
replication:
  replicaCount: 3
sentinel:
  replicaCount: 3
  quorum: 2
pdb:
  enabled: true
metrics:
  enabled: true

Operations

Choose topology before production use. Sentinel requires Sentinel-aware clients. Cluster mode requires Valkey Cluster-aware clients and a fresh cluster bootstrap.

Architecture

One HelmForge Valkey chart supports four topologies through architecture:

Architecture	Contract	Best Fit
`standalone`	One Valkey pod with optional persistence	Development, small caches, simple app state
`replication`	Fixed primary with read replicas	Read-heavy workloads that can tolerate manual failover
`sentinel`	Replication plus Sentinel primary discovery	HA clients that support Sentinel
`cluster`	Native Valkey Cluster sharding and replicas	Cluster-aware clients and horizontally growing datasets

Each topology renders the appropriate StatefulSets, Services, persistence settings, and tests. Select topology as an application contract, not only as a replica count.

Standalone

Minimal standalone with an existing password Secret:

architecture: standalone

auth:
  enabled: true
  existingSecret: valkey-auth
  existingSecretPasswordKey: valkey-password

standalone:
  persistence:
    enabled: true
    size: 10Gi

Standalone does not provide failover. Use it when the workload can tolerate downtime or when Valkey is a disposable cache.

Replication

Replication gives one fixed primary endpoint and separate read replicas:

architecture: replication

auth:
  enabled: true
  existingSecret: valkey-auth
  existingSecretPasswordKey: valkey-password

replication:
  replicaCount: 2
  primary:
    persistence:
      enabled: true
      size: 50Gi
  replica:
    persistence:
      enabled: true
      size: 50Gi

metrics:
  enabled: true
  serviceMonitor:
    enabled: true

pdb:
  enabled: true

Replication alone does not promote a replica automatically. Applications should write only to the primary Service.

Sentinel

Sentinel adds primary discovery and failover for Sentinel-aware clients:

architecture: sentinel

replication:
  replicaCount: 2

sentinel:
  replicaCount: 3
  quorum: 2

pdb:
  enabled: true

Keep at least three Sentinels and choose a quorum that matches the failure domains. Validate application reconnect behavior before production rollout.

The chart enables Sentinel failover hardening by default. sentinel.gracefulFailover.enabled triggers a bounded preStop failover when the active master is voluntarily terminated, and sentinel.startupFailoverGuard.enabled prevents a fresh data directory from resuming as an empty master while peers still hold data. Keep sentinel.podManagementPolicy empty for upgrade compatibility on existing StatefulSets; use Parallel only for new installs where immutable StatefulSet fields are acceptable.

Cluster

Cluster mode is for native sharding and requires Valkey Cluster-compatible clients:

architecture: cluster

auth:
  enabled: true
  existingSecret: valkey-auth
  existingSecretPasswordKey: valkey-password

cluster:
  nodes: 6
  replicasPerMaster: 1
  persistence:
    enabled: true
    size: 20Gi

Cluster clients must handle MOVED and ASK redirects. Plan operational windows for future resharding, expansion, or maintenance.

TLS And Secrets

Password authentication is enabled by default. Production should use existing Secrets or External Secrets:

auth:
  enabled: true
  existingSecret: valkey-auth
  existingSecretPasswordKey: valkey-password

externalSecrets:
  enabled: true
  secretStoreRef:
    name: cluster-secrets
    kind: ClusterSecretStore
  data:
    - secretKey: valkey-password
      remoteRef:
        key: valkey/auth
        property: password

TLS is file-based and expects the referenced Secrets to be created by the platform:

tls:
  enabled: true
  existingSecret: valkey-tls
  certFilename: tls.crt
  keyFilename: tls.key
  caFilename: ca.crt

Keep tls.insecureSkipVerify=false in production. Enable it only for CI or controlled self-signed test certificates when chart-rendered valkey-cli clients cannot validate release-specific hostnames.

Security Contexts

The chart sets pod-level RuntimeDefault seccomp and non-root container security contexts by default. The Valkey containers use UID/GID 999, the metrics exporter sidecar uses UID/GID 65534, and the cluster initialization Job uses the Valkey UID/GID 999.

These defaults cover the container-level fields required by Kubernetes Pod Security Admission restricted, including runAsNonRoot, allowPrivilegeEscalation=false, and capabilities.drop=["ALL"].

Networking

The chart renders topology-specific Services and supports Kubernetes dual-stack fields:

service:
  type: ClusterIP
  ipFamilyPolicy: PreferDualStack

Leave service.ipFamilies empty for portable installs. Set explicit families only in environment-specific values for clusters that advertise every requested family.

Observability

Enable the exporter sidecar and ServiceMonitor for production topologies:

metrics:
  enabled: true
  serviceMonitor:
    enabled: true
    labels:
      release: prometheus

Monitor memory pressure, evictions, replication lag, Sentinel quorum, cluster slot health, and restart counts.

Validation

After deployment:

helm test valkey -n valkey
kubectl get pods -n valkey -l app.kubernetes.io/name=valkey
kubectl logs -n valkey statefulset/valkey --since=10m
kubectl get events -n valkey --sort-by=.lastTimestamp

For Sentinel and cluster mode, test the exact client library used by the application. A healthy pod does not prove the client understands Sentinel discovery or Cluster redirects.

Common Issues

Symptom	Likely Cause	Fix
Writes fail in replication mode	Application writes to replica Service	Use the primary Service for writes.
Sentinel failover is not observed by app	Client is not Sentinel-aware	Configure Sentinel client support or use another topology.
Cluster client receives redirect errors	Client lacks Cluster support	Use a Cluster-compatible client library.
Auth changes break clients	Password Secret rotated without app rollout	Coordinate Secret rotation and application restarts.

Values

Parameter	Default	Description
`architecture`	`standalone`	Topology: `standalone`, `replication`, `sentinel`, or `cluster`.
`image.repository`	`docker.io/valkey/valkey`	Official Valkey image.
`auth.enabled`	`true`	Enable password authentication.
`auth.existingSecret`	`""`	Existing password Secret.
`tls.enabled`	`false`	Enable TLS file wiring.
`tls.existingSecret`	`""`	Existing Secret with TLS files.
`tls.certFilename`	`tls.crt`	Certificate filename mounted from `tls.existingSecret`.
`tls.keyFilename`	`tls.key`	Private key filename mounted from `tls.existingSecret`.
`tls.caFilename`	`ca.crt`	CA filename mounted from `tls.existingSecret`.
`tls.insecureSkipVerify`	`false`	Skip TLS hostname verification for chart-rendered CLI clients.
`standalone.persistence.enabled`	`true`	Persist standalone data.
`replication.replicaCount`	`2`	Replica count for replication modes.
`sentinel.replicaCount`	`3`	Number of Sentinel pods.
`sentinel.podManagementPolicy`	`""`	Optional Sentinel StatefulSet pod management policy.
`sentinel.gracefulFailover.enabled`	`true`	Trigger preStop failover when the active master shuts down.
`sentinel.gracefulFailover.maxAttempts`	`12`	Failover confirmation attempts during graceful shutdown.
`sentinel.startupFailoverGuard.enabled`	`true`	Prevent fresh pods from resuming as empty masters.
`sentinel.startupFailoverGuard.maxAttempts`	`20`	Failover confirmation attempts during startup guard handling.
`cluster.nodes`	`6`	Total cluster pods.
`cluster.initJob.securityContext.runAsUser`	`999`	Cluster bootstrap Job container user ID.
`service.type`	`ClusterIP`	Client Service type where applicable.
`service.ipFamilyPolicy`	`null`	Service IP family policy for dual-stack clusters.
`service.ipFamilies`	`[]`	Optional explicit Service IP families.
`metrics.enabled`	`false`	Enable Valkey exporter sidecar.
`metrics.securityContext.runAsUser`	`65534`	Metrics exporter container user ID.
`metrics.securityContext.capabilities.drop`	`["ALL"]`	Linux capabilities dropped from the metrics exporter.
`podSecurityContext.seccompProfile.type`	`RuntimeDefault`	Pod-level seccomp profile for chart-managed pods.
`securityContext.capabilities.drop`	`["ALL"]`	Linux capabilities dropped from Valkey containers.