valkey-operator

Valkey Operator

A Kubernetes operator for deploying and managing production-grade Valkey instances — standalone or highly available with Sentinel.

Features

• Standalone & HA modes — single-node or multi-node with automatic Sentinel deployment
• TLS encryption — full TLS for Valkey, replication, and Sentinel via cert-manager or user-provided Secrets
• Persistence — RDB, AOF, or both with configurable PVCs
• Authentication — password from Kubernetes Secret
• Observability — CRD status visible in kubectl and Lens, Kubernetes Events
• Controlled rolling updates — replica-first rollout with replication sync verification and automatic failover
• Network policies — optional firewall rules for Valkey and Sentinel traffic
• Helm deployment — install the operator with a single helm install

Quick Start

Prerequisites

• Kubernetes cluster (v1.29+)
• Helm 3
• cert-manager (only if using TLS with automatic certificate management)

Install the Operator

helm install valkey-operator deploy/helm/valkey-operator \
  --namespace valkey-operator-system \
  --create-namespace

Deploy a Standalone Valkey Instance

apiVersion: vko.gtrfc.com/v1
kind: Valkey
metadata:
  name: my-valkey
spec:
  replicas: 1
  image: valkey/valkey:8.0

kubectl apply -f my-valkey.yaml
kubectl get valkey

NAME        REPLICAS   READY   PHASE   MASTER          AGE
my-valkey   1          1       OK      my-valkey-0     2m

Examples

Standalone — Minimal

The simplest deployment: a single Valkey pod with no persistence, no TLS, no auth.

apiVersion: vko.gtrfc.com/v1
kind: Valkey
metadata:
  name: minimal
spec:
  replicas: 1
  image: valkey/valkey:8.0

Standalone — With Persistence

Data survives pod restarts via a PersistentVolumeClaim.

apiVersion: vko.gtrfc.com/v1
kind: Valkey
metadata:
  name: persistent
spec:
  replicas: 1
  image: valkey/valkey:8.0
  persistence:
    enabled: true
    mode: rdb          # rdb | aof | both
    size: 5Gi
    storageClass: ""   # empty = default StorageClass
  resources:
    requests:
      cpu: 250m
      memory: 256Mi
    limits:
      cpu: 500m
      memory: 512Mi

Standalone — With TLS (cert-manager)

All traffic is encrypted. The operator creates a cert-manager Certificate resource automatically.

Prerequisite: cert-manager must be installed and a ClusterIssuer (or Issuer) must exist.

apiVersion: vko.gtrfc.com/v1
kind: Valkey
metadata:
  name: tls-standalone
spec:
  replicas: 1
  image: valkey/valkey:8.0
  tls:
    enabled: true
    certManager:
      issuer:
        kind: ClusterIssuer
        name: my-ca-issuer

Note: When TLS is enabled, the plaintext port (6379) is disabled. Valkey listens on TLS port 16379.

Standalone — With TLS (User-Provided Secret)

If you manage certificates yourself, provide a Secret with tls.crt, tls.key, and ca.crt:

apiVersion: vko.gtrfc.com/v1
kind: Valkey
metadata:
  name: tls-manual
spec:
  replicas: 1
  image: valkey/valkey:8.0
  tls:
    enabled: true
    secretName: my-valkey-tls-secret

HA — 3 Replicas with Sentinel

A production-ready HA setup: 3 Valkey nodes (1 master + 2 replicas) with 3 Sentinel instances for automatic failover.

apiVersion: vko.gtrfc.com/v1
kind: Valkey
metadata:
  name: ha-cluster
spec:
  replicas: 3
  image: valkey/valkey:8.0
  sentinel:
    enabled: true
    replicas: 3
  persistence:
    enabled: true
    mode: rdb
    size: 10Gi
  resources:
    requests:
      cpu: 250m
      memory: 256Mi
    limits:
      cpu: "1"
      memory: 1Gi

The operator creates:

HA — Full Production Setup (TLS + Persistence + Labels)

The most comprehensive configuration with TLS, persistence, custom labels, and resource limits.

apiVersion: vko.gtrfc.com/v1
kind: Valkey
metadata:
  name: production
spec:
  replicas: 3
  image: valkey/valkey:8.0
  sentinel:
    enabled: true
    replicas: 3
    podLabels:
      app: sentinel
      team: platform
    podAnnotations:
      prometheus.io/scrape: "true"
  tls:
    enabled: true
    certManager:
      issuer:
        kind: ClusterIssuer
        name: production-ca
      extraDnsNames:
        - valkey.example.com
  persistence:
    enabled: true
    mode: both          # RDB + AOF for maximum durability
    size: 20Gi
    storageClass: fast-ssd
  podLabels:
    app: valkey
    team: platform
    environment: production
  podAnnotations:
    prometheus.io/scrape: "true"
    prometheus.io/port: "9121"
  resources:
    requests:
      cpu: 500m
      memory: 512Mi
    limits:
      cpu: "2"
      memory: 2Gi

HA — With Authentication

Protect your cluster with a password stored in a Kubernetes Secret.

kubectl create secret generic valkey-auth --from-literal=password=my-strong-password

apiVersion: vko.gtrfc.com/v1
kind: Valkey
metadata:
  name: auth-cluster
spec:
  replicas: 3
  image: valkey/valkey:8.0
  sentinel:
    enabled: true
    replicas: 3
  auth:
    secretName: valkey-auth
    secretPasswordKey: password

CRD Reference

spec

spec.sentinel

spec.tls

spec.tls.certManager

spec.persistence

spec.auth

status

Phase Values

Common Labels

All managed resources carry a consistent set of labels:

app.kubernetes.io/component: valkey | sentinel
app.kubernetes.io/instance: <cr-name>
app.kubernetes.io/managed-by: vko.gtrfc.com
app.kubernetes.io/name: valkey
app.kubernetes.io/version: <image-tag>
vko.gtrfc.com/cluster: <cr-name>

Pod-level labels additionally include:

vko.gtrfc.com/instanceName: <pod-name>
vko.gtrfc.com/instanceRole: master | replica

TLS Details

When TLS is enabled (spec.tls.enabled: true):

• The plaintext port 6379 is disabled (port 0)
• Valkey listens on TLS port 16379
• Sentinel listens on TLS port 26379
• All replication traffic is encrypted (tls-replication yes)
• Probes use valkey-cli --tls with the mounted certificates

Connecting to a TLS-enabled instance from within the cluster:

valkey-cli --tls \
  --cert /tls/tls.crt \
  --key /tls/tls.key \
  --cacert /tls/ca.crt \
  -h my-valkey -p 16379 PING

Persistence Modes

Development

Prerequisites

• Go 1.26+
• Docker
• Kind (for local E2E testing)
• cert-manager (for TLS E2E tests)

Build

make build        # Build operator binary
make docker-build # Build container image

Test

make test-unit               # Unit tests
make test-unit-coverage      # Unit tests with coverage
make test-integration        # Integration tests (envtest)
make test-e2e                # E2E tests (requires running cluster)
make e2e-local               # Full E2E: create Kind cluster → deploy → test → cleanup
make lint                    # Linting (golangci-lint + go vet)
make gosec                   # Security scan
make vuln                    # Vulnerability check
make cyclo                   # Cyclomatic complexity check

Run Locally

make run  # Run the operator against the current kubeconfig

Helm Chart Values

The operator itself is configured via Helm values:

replicaCount: 1

image:
  repository: guidedtraffic/valkey-operator
  pullPolicy: IfNotPresent
  tag: ""            # defaults to Chart appVersion

resources:
  limits:
    cpu: 500m
    memory: 128Mi
  requests:
    cpu: 10m
    memory: 64Mi

leaderElection:
  enabled: true      # required for HA operator deployment

Architecture

┌─────────────────────────────────────────────────────────────────┐
│ Kubernetes Cluster                                              │
│                                                                 │
│  ┌──────────────────┐     watches      ┌────────────────────┐  │
│  │ Valkey Operator   │ ◄──────────────► │ Valkey CRD         │  │
│  │ (Deployment)      │                  │ (vko.gtrfc.com/v1) │  │
│  └────────┬─────────┘                  └────────────────────┘  │
│           │ creates/manages                                     │
│           ▼                                                     │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Managed Resources                                        │   │
│  │                                                          │   │
│  │  ┌─────────────┐  ┌────────────┐  ┌────────────────┐   │   │
│  │  │ StatefulSet  │  │ ConfigMaps │  │ Services       │   │   │
│  │  │ (Valkey)     │  │ (master,   │  │ (headless,     │   │   │
│  │  │              │  │  replica)  │  │  client)       │   │   │
│  │  └─────────────┘  └────────────┘  └────────────────┘   │   │
│  │                                                          │   │
│  │  ┌─────────────┐  ┌────────────┐  ┌────────────────┐   │   │
│  │  │ StatefulSet  │  │ ConfigMap  │  │ Service        │   │   │
│  │  │ (Sentinel)   │  │ (sentinel) │  │ (sentinel-     │   │   │
│  │  │              │  │            │  │  headless)     │   │   │
│  │  └─────────────┘  └────────────┘  └────────────────┘   │   │
│  │                                                          │   │
│  │  ┌─────────────┐  ┌────────────────────────────────┐   │   │
│  │  │ Certificate  │  │ Certificate (Sentinel)         │   │   │
│  │  │ (Valkey TLS) │  │ (if sentinel + TLS enabled)    │   │   │
│  │  └─────────────┘  └────────────────────────────────┘   │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

License

Apache License 2.0