#Connect to Failover and Replica instances

Failover and Replica architectures expose role-selecting Services. The read-write Service selects the current primary and the read-only Service selects replicas.

Failover additionally deploys or references Valkey Sentinel. Replica architecture does not deploy Sentinel; applications use the same read-write Service but must not assume Sentinel-based automatic failover.

#Discover endpoints

kubectl -n default get valkey valkey-failover -o wide
kubectl -n default get service -l buf.red/name=valkey-failover -o wide
kubectl -n default get endpointslice \
  -l kubernetes.io/service-name=rfr-valkey-failover-readwrite
kubectl -n default get endpointslice \
  -l kubernetes.io/service-name=rfr-valkey-failover-readonly

For in-cluster clients, the stable DNS names are:

rfr-valkey-failover-readwrite.default.svc:6379
rfr-valkey-failover-readonly.default.svc:6379

Replace the instance name and namespace for your environment. Discover the actual Service names rather than constructing them in production automation.

#Test the write endpoint

Without access control list (ACL) authentication:

valkey-cli -h rfr-valkey-failover-readwrite.default.svc -p 6379 PING

With a custom ACL user, request the password interactively:

valkey-cli -h rfr-valkey-failover-readwrite.default.svc -p 6379 \
  --user app --askpass PING

Test a write only with a disposable key approved for the environment:

valkey-cli -h rfr-valkey-failover-readwrite.default.svc -p 6379 \
  --user app --askpass SET connectivity:test ok EX 60
valkey-cli -h rfr-valkey-failover-readwrite.default.svc -p 6379 \
  --user app --askpass GET connectivity:test

#Test the read-only endpoint

valkey-cli -h rfr-valkey-failover-readonly.default.svc -p 6379 \
  --user app --askpass GET connectivity:test

The read-only Service can have no endpoints when no replica is ready. Replication is asynchronous, so a replica can return an older value. During primary failure and promotion, an acknowledged write can also be absent from the promoted replica. Do not use this endpoint for read-after-write consistency.

#Use TLS

When spec.access.enableTLS is true, obtain a trusted client identity through the approved certificate-distribution process. The generated server requires a trusted client certificate by default, so the certificate authority (CA) alone is insufficient:

valkey-cli --tls --cacert <ca-file> \
  --cert <client-certificate-file> --key <client-key-file> \
  -h rfr-valkey-failover-readwrite.default -p 6379 \
  --user app --askpass PING

rfr-valkey-failover-readwrite.default is included in the generated certificate for this example; the .svc form is not. Inspect Certificate.spec.dnsNames and use an exact listed name. The instance TLS Secret contains a server private key used internally by the Operator; do not distribute that key as a general application client identity. Do not use --insecure as a normal connection method.

#External access

For LoadBalancer, inspect the role-selecting Service and wait for an ingress address:

kubectl -n default get service rfr-valkey-failover-readwrite -w
kubectl -n default get service rfr-valkey-failover-readwrite -o yaml

For NodePort, obtain the allocated port and a reachable Kubernetes node address. Firewall rules and routing must permit the connection:

kubectl -n default get service rfr-valkey-failover-readwrite \
  -o jsonpath='{.spec.ports[0].nodePort}{"\n"}'
kubectl get nodes -o wide

The generated certificate does not include the LoadBalancer ingress or Kubernetes node addresses. External TLS therefore needs a product-approved certificate path whose subject alternative names cover the client hostname; the high-level 2.0.0 API does not expose an arbitrary subject-alternative-name field.

Do not publish a fixed spec.access.ports example for 2.0.0: the inspected custom resource definition (CRD) schema and runtime parser use incompatible formats. Leave the field unset unless the delivered build documents a validated format.

#Client behavior

• Use the read-write endpoint for writes and consistency-sensitive reads.
• Configure bounded connection, command, and retry timeouts.
• Re-resolve DNS and reconnect after a primary transition.
• Retry only operations that are safe for the application's idempotency model.
• Monitor replica health before sending production reads to the read-only endpoint.

The consistency and failover boundaries above follow the official Valkey replication and Sentinel documentation. Select a client from the Valkey client catalog and verify its retry and TLS behavior in that client's own documentation.