#Access and TLS

Configure access under spec.access on the high-level Valkey resource.

#Service types

For Cluster architecture, the same-name bootstrap Service remains ClusterIP; the requested external type is used by generated per-Pod Services. For Failover and Replica, the read-write and read-only role Services use the requested type, and external access can also create per-Pod Services. Always inspect the generated Services instead of assuming one uniform Service shape.

For NodePort in 2.0.0, leave spec.access.ports unset unless the delivered build documents a validated format. Kubernetes then allocates ports. The source baseline contains conflicting schema and runtime formats for fixed assignment.

Switch access type with a merge patch:

kubectl -n default patch valkey valkey-cluster --type=merge \
  -p '{"spec":{"access":{"serviceType":"LoadBalancer"}}}'
kubectl -n default get service -l buf.red/name=valkey-cluster -w

Wait for all external addresses and the Valkey phase to become ready before updating clients.

#In-cluster Service names

For Cluster architecture, use the Service with the same name as the Valkey resource and a Cluster-aware client:

valkey-cli -c -h valkey-cluster.default.svc -p 6379 PING

For Failover and Replica architectures, use the read-write or read-only Service:

valkey-cli -h rfr-valkey-failover-readwrite.default.svc -p 6379 PING
valkey-cli -h rfr-valkey-failover-readonly.default.svc -p 6379 GET app:key

The read-write Service selects the current primary. Applications must reconnect after failover. The read-only Service selects replicas and can return stale data.

Discover the actual Services instead of constructing names in automation:

kubectl -n default get service -l buf.red/name=valkey-failover -o wide

#Internet Protocol family

Set spec.access.ipFamilyPrefer to Internet Protocol (IP) version 4 (IPv4) or version 6 (IPv6). The generated Services use a single-stack IP family policy. Ensure the cluster, nodes, load balancer, DNS, and clients support the selected family before changing an existing instance.

#Enable TLS

TLS requires cert-manager and an existing Issuer or ClusterIssuer. The Operator creates a cert-manager Certificate and stores the issued material in <instance-name>-tls.

kubectl -n default patch valkey valkey-cluster --type=merge -p '
{
  "spec": {
    "access": {
      "enableTLS": true,
      "certIssuer": "valkey-ca",
      "certIssuerType": "ClusterIssuer"
    }
  }
}'

Verify certificate issuance and the rolling update:

kubectl -n default get certificate valkey-cluster-cert
kubectl -n default describe certificate valkey-cluster-cert
kubectl -n default get secret valkey-cluster-tls
kubectl -n default get valkey valkey-cluster -w

The generated Valkey arguments retain upstream client-certificate authentication. A TLS client therefore needs the trusted certificate authority (CA), a trusted client certificate, and its private key. The instance Secret must contain ca.crt, tls.crt, and tls.key; confirm that the selected cert-manager issuer populates all three keys.

Use a client identity issued by the same trusted CA. The following form avoids putting an access control list (ACL) password on the command line, but it checks only the Cluster bootstrap connection:

valkey-cli -c --tls \
  --cacert <ca-file> --cert <client-certificate-file> --key <client-key-file> \
  -h valkey-cluster.default -p 6379 --user <username> --askpass PING

valkey-cluster.default is present in the Operator-generated Cluster certificate for this example; valkey-cluster.default.svc is not. Inspect Certificate.spec.dnsNames and use an exact listed name. The generated Secret contains the server identity used internally by the Operator; do not distribute its private key to applications as a general client credential. Issue and distribute dedicated client certificates through an approved certificate process.

The generated certificate does not include arbitrary NodePort or LoadBalancer addresses. For Cluster, it also omits the per-Pod Service names or addresses announced for redirection. A successful bootstrap PING therefore does not prove that a Cluster-aware client can validate redirected connections. Require a delivered build that aligns every announced endpoint with a certificate subject alternative name before production Cluster TLS use. Do not use --insecure as the workaround.

For end-to-end endpoint discovery, authentication, TLS, and client behavior, see:

• Connect to Failover and Replica instances
• Connect to a Cluster instance

See the official Valkey TLS documentation for server and client certificate behavior.