Kvindo™ Cloud Docs
A Valkey Cluster is a managed, sharded Valkey (Redis-compatible) deployment. Each shard owns a slice of the 16384-slot hash space and runs on its own dedicated VM, with spec.replicasPerShard additional VMs replicating that shard for failover. The cluster is described as a single resource with one entry per shard in spec.shards — per-VM instance ids (one primary + N replicas per shard) are derived automatically and never appear in the spec.
• Shard count: 1 or 3+, never 2 — a single shard is a valid non-HA tier; exactly 2 shards is rejected outright, since two primaries can never reach a majority vote to promote one another on failover
• Cluster-wide sizing, per-shard placement — spec.vmOfferId/spec.volumeOfferId/spec.volumeSizeGiB apply identically to every instance across every shard; only each shard's id and subnet (spec.shards[].id/vpcSubnetId) vary
• Shard id is caller-supplied — reuse a shard's existing id across modifies to keep it, or supply a new id to add a shard
• Scaling is one shard, or one replica-per-shard step, per modify — a single request may change the shard count by at most one, or replicasPerShard by at most one, but never both at once
• Parameter sets — attach a reusable ValkeyParametersSet via spec.parametersSetId to apply a tuning profile (eviction policy, persistence, cluster timeouts); swapping which set is referenced is the one field this resource allows to change freely on a modify
• Public access — private by default; set spec.createPublicIpv4 to give every instance a public IPv4
| UI Name | API / kc name | Terraform name | Optional | Format | Default | Is read only | Description |
|---|---|---|---|---|---|---|---|
| Shards | spec.shards |
spec.shards |
No | list of objects | — | No | One entry per shard — the smallest real HA tier is 3 shards (1 = non-HA, 2 = rejected) |
| Shard ID | shards[].id |
shards[].id |
No | ULID | — | No | Caller-supplied — reuse across modifies to keep an existing shard |
| VPC subnet | shards[].vpcSubnetId |
shards[].vpc_subnet_id |
No | ULID — references a VPC Subnet | — | No | Subnet for this shard's instances |
| Replicas per shard | spec.replicasPerShard |
spec.replicas_per_shard |
No | integer | — | No | Extra VMs per shard replicating the primary for failover — required, no implicit default |
| Root password | spec.rootPassword |
spec.root_password |
No | string (sensitive, write-only) | — | No | Cluster-wide credential; never returned in status |
| Parameters set | spec.parametersSetId |
spec.parameters_set_id |
Yes | ULID — references a ValkeyParametersSet | — | No | The one field this resource allows to change freely on a modify |
| Valkey version | spec.valkeyVersion |
spec.valkey_version |
No | string — Valkey version | — | No | No default and not validated synchronously by this API — cloud-valkey-svc's image currently only prefetches 8.1.9; any other value fails once the request reaches the microservice, not at submit time |
| VM offer | spec.vmOfferId |
spec.vm_offer_id |
No | string (≤32) — compute offer | — | No | Applies to every instance — no platform default; see the Console catalog for real offer ids (e.g. g3-1c1-100) |
| Volume offer | spec.volumeOfferId |
spec.volume_offer_id |
No | string (≤32) — disk offer | — | No | Applies to every instance — no platform default (e.g. gp3-750) |
| Volume size | spec.volumeSizeGiB |
spec.volume_size_gib |
No | integer — GiB | — | No | Applies to every instance |
| Use FQDN | spec.useFqdn |
spec.use_fqdn |
Yes | boolean | false |
No | Announce nodes by DNS name instead of raw IP |
| Public IPv4 | spec.createPublicIpv4 |
spec.create_public_ipv4 |
Yes | boolean | false |
No | Give every instance a public IPv4 |
| Password | status.password |
status.password |
— | string | — | Yes | Effective root password — echoes back what was set |
| Port | status.port |
status.port |
— | integer | — | Yes | Client port — always 6379 today |
| DNS seed FQDN | status.dnsSeedFqdn |
status.dns_seed_fqdn |
— | string | — | Yes | Set only when spec.useFqdn is enabled |
| Cluster endpoints | status.clusterEndpoints |
status.cluster_endpoints |
— | list of strings | — | Yes | host:port for every node in the cluster |
| Primary endpoints | status.primaryEndpoints |
status.primary_endpoints |
— | list of strings | — | Yes | host:port for each shard's current primary |
| Connection URI | status.connectionUri |
status.connection_uri |
— | string | — | Yes | valkey://:password@host:port — a starting point; a real client needs full cluster-mode support |
| Cluster state | status.clusterState |
status.cluster_state |
— | string | — | Yes | Raw CLUSTER INFO cluster_state — "ok" once every slot is assigned |
| Anti-affinity OK | status.antiAffinityOk |
status.anti_affinity_ok |
— | boolean | — | Yes | False when a primary and one of its own replicas share a VM (degraded placement) |
| Anti-affinity message | status.antiAffinityMessage |
status.anti_affinity_message |
— | string | — | Yes | Human-readable detail behind antiAffinityOk |
| Shards | status.shards |
status.shards |
— | list of objects | — | Yes | Observed slot ownership per shard |
| Slot start | shards[].slotStart |
shards[].slot_start |
— | integer | — | Yes | First hash slot (inclusive) this shard owns (0–16383 total across all shards) |
| Slot end | shards[].slotEnd |
shards[].slot_end |
— | integer | — | Yes | Last hash slot (inclusive) this shard owns (0–16383 total across all shards) |
| Primary endpoint | shards[].primaryEndpoint |
shards[].primary_endpoint |
— | string | — | Yes | host:port of this shard's current primary |
| Replica endpoints | shards[].replicaEndpoints |
shards[].replica_endpoints |
— | list of strings | — | Yes | host:port for each of this shard's replicas |
| Nodes | status.nodes |
status.nodes |
— | list of objects | — | Yes | One entry per provisioned instance across all shards |
| Private IPv4 | nodes[].privateIpV4 |
nodes[].private_ipv4 |
— | string | — | Yes | Address on the shard's VPC subnet |
| Is primary | nodes[].isPrimary |
nodes[].is_primary |
— | boolean | — | Yes | Whether this instance is currently its shard's primary |
| Observed role | nodes[].observedRole |
nodes[].observed_role |
— | string | — | Yes | Raw CLUSTER NODES role — "master" or "slave" |
A private 3-shard cluster (the smallest real HA tier) with one replica per shard, on an existing subnet.
Terraform
Python SDK
kc CLI
Resource docs