Kvindo™ Cloud Docs
A ClickHouse Cluster is a managed analytical deployment with sharding and replication. Each shard group runs 1 + spec.replicasPerShardGroup dedicated virtual machines. In addition, an independent Keeper quorum of 1, 3, or 5 dedicated virtual machines manages consensus and replication metadata. Shard groups are add-only while holding data, and Keepers grow append-only (1 -> 3 -> 5).
• Independent sizing for Data nodes and Keepers — data nodes use spec.vmOfferId and spec.volumeOfferId; Keepers use spec.keeperVmOfferId and spec.keeperVolumeOfferId with a dedicated spec.keeperVolumeSizeGiB disk
• Shard groups and placement — each shard group specifies its own name and subnet via spec.shardGroups[].vpcSubnetId. Every replica in the shard group runs in that subnet
• Keepers quorum — spec.keepers must contain 1, 3, or 5 nodes; each specifies its subnet in spec.keepers[].vpcSubnetId
• Backups — automatic full and incremental backups to S3 configured via spec.backupRetentionDays and spec.fullBackupIntervalDays
• Mutual TLS and endpoints — client access via native (9000/9440) and HTTP (8123/8443) ports. The cluster CA certificate is exposed in status for clients to pin
| UI Name | API / kc name | Terraform name | Optional | Format | Default | Is read only | Description |
|---|---|---|---|---|---|---|---|
| Shard groups | spec.shardGroups |
spec.shard_groups |
No | list of objects | — | No | 1..N shard groups. Add-only while holding data |
| Shard group name | shardGroups[].name |
shard_groups[].name |
No | string | — | No | Identity of the shard group |
| VPC subnet | shardGroups[].vpcSubnetId |
shard_groups[].vpc_subnet_id |
No | ULID — references a VPC Subnet | — | No | Subnet for this shard group's instances |
| Replicas per shard group | spec.replicasPerShardGroup |
spec.replicas_per_shard_group |
No | integer | 1 | No | Additional VMs per shard group replicating data |
| Keepers | spec.keepers |
spec.keepers |
No | list of objects | — | No | 1, 3, or 5 Keeper nodes for distributed consensus |
| Keeper name | keepers[].name |
keepers[].name |
No | string | — | No | Identity of the keeper node |
| Keeper VPC subnet | keepers[].vpcSubnetId |
keepers[].vpc_subnet_id |
No | ULID — references a VPC Subnet | — | No | Subnet for this keeper node |
| Parameters set | spec.parametersSetId |
spec.parameters_set_id |
Yes | ULID — references a ClickHouseParametersSet | — | No | Reusable server configuration profile |
| ClickHouse version | spec.clickHouseVersion |
spec.clickhouse_version |
No | string — LTS version | — | No | Pinned LTS line (e.g. 26.8.11.7) |
| VM offer | spec.vmOfferId |
spec.vm_offer_id |
No | string (≤32) — compute offer | — | No | Compute offer for data nodes |
| Volume offer | spec.volumeOfferId |
spec.volume_offer_id |
No | string (≤32) — disk offer | — | No | Disk tier offer for data nodes |
| Volume size | spec.volumeSizeGiB |
spec.volume_size_gib |
No | integer — GiB | — | No | Disk size per data node instance |
| Keeper VM offer | spec.keeperVmOfferId |
spec.keeper_vm_offer_id |
No | string (≤32) — compute offer | — | No | Compute offer for Keeper nodes |
| Keeper Volume offer | spec.keeperVolumeOfferId |
spec.keeper_volume_offer_id |
No | string (≤32) — disk offer | — | No | Disk tier offer for Keeper nodes |
| Keeper Volume size | spec.keeperVolumeSizeGiB |
spec.keeper_volume_size_gib |
No | integer — GiB | 10 | No | Disk size per Keeper node instance |
| Backup retention days | spec.backupRetentionDays |
spec.backup_retention_days |
Yes | integer | 7 | No | How many days backups are preserved in S3 |
| Full backup interval days | spec.fullBackupIntervalDays |
spec.full_backup_interval_days |
Yes | integer | 7 | No | Interval between full S3 backup snapshots |
| Use FQDN | spec.useFqdn |
spec.use_fqdn |
Yes | boolean | false |
No | Announce nodes by DNS name instead of IP |
| Public IPv4 | spec.createPublicIpv4 |
spec.create_public_ipv4 |
Yes | boolean | false |
No | Attach public IP to data nodes (accessible on TLS port 9440) |
| Cluster name | status.clusterName |
status.cluster_name |
— | string | default | Yes | ClickHouse cluster configuration name |
| Cluster state | status.clusterState |
status.cluster_state |
— | string | — | Yes | ok | degraded | no-quorum | unknown |
| Running version | status.runningVersion |
status.running_version |
— | string | — | Yes | Observed ClickHouse version running on nodes |
| Native endpoints | status.nativeEndpoints |
status.native_endpoints |
— | list of strings | — | Yes | Internal plaintext endpoints (port 9000) |
| Native TLS endpoints | status.nativeTlsEndpoints |
status.native_tls_endpoints |
— | list of strings | — | Yes | Internal TLS endpoints (port 9440) |
| HTTP endpoints | status.httpEndpoints |
status.http_endpoints |
— | list of strings | — | Yes | Internal HTTP endpoints (port 8123) |
| HTTPS endpoints | status.httpsEndpoints |
status.https_endpoints |
— | list of strings | — | Yes | Internal HTTPS endpoints (port 8443) |
| Public endpoints | status.publicEndpoints |
status.public_endpoints |
— | list of strings | — | Yes | External TLS endpoints on public IPs (port 9440) |
| Keeper quorum size | status.keeperQuorumSize |
status.keeper_quorum_size |
— | integer | — | Yes | Number of responsive Keeper nodes |
| CA certificate | status.caCertificate |
status.ca_certificate |
— | string | — | Yes | Cluster root CA certificate to pin on client connections |
Resource docs
Examples