Kvindo™ Cloud Docs
A Kafka Topic is a topic inside one specific Kafka Cluster. It carries the partition count, the replication factor, and any per-topic configuration overrides — everything else about the topic's storage is inherited from the cluster's parameter set.
• Belongs to one cluster forever — spec.kafkaId is required and immutable; a topic cannot move between clusters
• Replication factor: leaving it out is meaningful, and is not 1 — omitting spec.replicationFactor keeps the topic's existing factor on a modify, and takes the cluster's effective default.replication.factor (i.e. min(3, broker count) unless that parameter was overridden) on create. Sending 1 is a completely different, explicit request that pins the topic to a single replica — on a 3-broker cluster that silently removes all fault tolerance
• An explicit factor must fit the cluster — and that check is asynchronous — the API accepts the request (a topic resource deliberately does not know its cluster's broker count), then the service rejects replication_factor > broker count when it applies the change. So the failure surfaces on the request's status, not as a submit-time error: poll the request rather than trusting an accepted submit. Only replicationFactor < 1 and a change to an already-set factor are rejected synchronously
• Partitions grow, never shrink — Kafka has no partition-decrease operation, so a reduction is rejected rather than silently ignored
• Per-topic config is dynamic — the keys in spec.config are checked against Kafka's own topic-level catalog, and none of them requires a broker restart
• A topic costs nothing extra — it is a metadata entry inside an already-billed cluster, with no VM or disk of its own
• Kafka's own name rules, not DNS ones — a topic name is 1–249 characters of [a-zA-Z0-9._-], it may start with _ (Schema Registry's _schemas is the usual case), and it may not mix . with _ or use the reserved __ prefix
| UI Name | API / kc name | Terraform name | Optional | Format | Default | Is read only | Description |
|---|---|---|---|---|---|---|---|
| Kafka cluster | spec.kafkaId |
spec.kafka_id |
No | ULID — references a Kafka cluster | — | No | Immutable after creation |
| Partitions | spec.partitions |
spec.partitions |
No | integer ≥ 1 | 1 |
No | Increase-only — Kafka cannot decrease a topic's partition count |
| Replication factor | spec.replicationFactor |
spec.replication_factor |
Yes | integer 1..broker count, or omitted | omitted | No | Omitted keeps the topic's current factor (or takes the cluster's effective default on create). An explicit value must not exceed the broker count. Immutable after creation |
| Config | spec.config |
spec.config |
Yes | map of string → string — raw Kafka topic properties | {} |
No | Allow-listed against Kafka's topic-level catalog (e.g. retention.ms, cleanup.policy, max.message.bytes). All dynamic — none needs a restart |
A six-partition topic on an existing cluster, with an explicit retention override and the replication factor deliberately left unset.
Terraform
Python SDK
kc CLI
Resource docs
Examples
More in this section