Alauda Cache Service E2
  • English

    • 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.

    Valkey.spec.archOperator-managed resourceMain workloads and access Services
    clusterClusterOne StatefulSet per shard; an instance Service plus per-Pod Services when external access is enabled.
    failoverFailover and SentinelA data StatefulSet, Sentinel StatefulSet, read-write Service, read-only Service, and per-Pod Services as required.
    replicaFailover without Sentinel settingsA data StatefulSet, read-write Service, read-only Service, and per-Pod Services as required.

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

    TOC

    Reconciliation flowCluster architectureFailover architectureReplica architectureSelect an architectureStorage and failure domainsReconciliation and status

    Reconciliation flow

    LayerResourceResponsibility
    Product APIValkey, UserUser-declared topology, version, resources, access, configuration, scheduling, and access control list (ACL) intent.
    Topology APICluster, Failover, SentinelOperator-generated topology state and operation progress.
    Kubernetes workloadStatefulSet, Pod, Service, ConfigMap, Secret, persistent volume claim (PVC), CertificateRuntime resources generated from the topology.
    Data planeValkey server, Sentinel, exporterCommands, replication, slots, failure detection, and metrics.

    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

    RequirementClusterFailoverReplica
    Dataset larger than one primary can holdYesNoNo
    Horizontal write distributionYesNoNo
    Automatic slot rebalancingYesNot applicableNot applicable
    Sentinel-coordinated primary failoverNoYesNo
    Simple primary-replica topologyNoYesYes
    Single-node development shapeNoNoYes, with one member
    Cluster-aware client requiredYesNoNo

    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:

    PhaseMeaning
    InitializingChild resources are being created or reconciled.
    RebalancingCluster hash slots are moving after a topology change.
    ReadyReconciled resources are available according to the Operator.
    FailedThe current reconciliation reported an error. Read .status.message, Events, and Operator logs; a later reconciliation can update the phase.
    PausedWorkload replicas have been reduced to zero by the pause annotation.

    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.