#Architecture

Users declare one Valkey resource in rds.valkey.buf.red/v1alpha1. The Valkey Operator translates it into lower-level resources and owns their lifecycle.

Do not edit Operator-managed Cluster, Failover, or Sentinel resources. Apply changes to the owning Valkey resource and let the controller propagate them.

#Reconciliation flow

The controller continuously compares the declared state with these resources. Manual changes to generated objects can be overwritten and can also hide the actual source of a failed operation.

#Cluster architecture

A Cluster has 16,384 hash slots. spec.replicas.shards controls the number of shards and must be between 3 and 128. spec.replicas.replicasOfShard controls the number of members in every shard and must be between 1 and 5.

The Operator creates one StatefulSet for each shard, assigns slots, joins new members, rebalances slots during shard scaling, and heals membership after Pod replacement. A value of replicasOfShard: 1 creates a primary without a replica; use at least 2 for primary-replica redundancy.

Cluster replication is asynchronous. During topology changes or failures, clients must follow MOVED and ASK redirections, and acknowledged writes can still be lost in the failure windows described by the Valkey Cluster protocol.

#Failover architecture

A Failover instance has exactly one data shard. Its data member count is spec.replicas.replicasOfShard. The Operator also creates or references a Valkey Sentinel deployment. When the Operator creates Sentinel, the count must be odd and at least 3. Sentinel monitors the primary and coordinates failover.

The Operator exposes separate read-write and read-only Services. Clients that must write should use the read-write Service and reconnect after failover.

#Replica architecture

Replica architecture uses the same primary-replica data workload as Failover but does not deploy Sentinel. With one member it behaves as a single-node instance. With multiple members the Operator maintains replication and manages recovery, but applications do not have Sentinel discovery or Sentinel-coordinated failover. Recovery depends on successful Operator reconciliation; applications continue to use the role-selecting read-write Service and must reconnect when the selected primary changes.

#Select an architecture

Cluster multi-key commands require the involved keys to map to the same hash slot. Failover and Replica keep the complete dataset on each data member and are therefore bounded by one member's usable memory.

#Storage and failure domains

Persistent storage protects data files across Pod recreation, subject to the StorageClass, volume health, and PVC retention behavior. It does not protect against logical deletion, corrupted data, namespace or cluster loss, or an Operator error. Use an independently tested external data-protection process.

Anti-affinity improves placement only when enough eligible Kubernetes nodes and failure domains exist. A redundant Valkey topology placed on one node or one storage failure domain does not provide infrastructure-level high availability.

#Reconciliation and status

The high-level resource reports these phases:

Inspect the full observed state with:

kubectl -n <namespace> get valkey <name> -o yaml
kubectl -n <namespace> describe valkey <name>
kubectl -n <namespace> get events --sort-by=.lastTimestamp

Upstream behavior referenced by this architecture is defined in the Valkey Cluster specification, replication documentation, and Sentinel documentation.