Reference: KafkaTopic CRD¶
The KafkaTopic custom resource defines a single Kafka topic in your managed
Kafka cluster. When you create, change, or delete a KafkaTopic, the Strimzi
Topic Operator makes the same change to the topic in Kafka. Changes only flow
in one direction. If someone changes a managed topic directly in Kafka, the
Topic Operator reverts the change to match the KafkaTopic resource.
| Property | Value |
|---|---|
apiVersion |
kafka.strimzi.io/v1 |
kind |
KafkaTopic |
| Scope | Namespaced |
| Short name | kt |
This page documents Strimzi 1.3.1.
Example¶
apiVersion: kafka.strimzi.io/v1
kind: KafkaTopic
metadata:
name: my-app-orders
namespace: your-application-namespace
labels:
# Required. The name of the Kafka cluster we provisioned for you.
strimzi.io/cluster: my-kafka-cluster
spec:
partitions: 3
replicas: 3
config:
retention.ms: 604800000 # 7 days
min.insync.replicas: 2
cleanup.policy: delete
Required Metadata¶
| Field | Description |
|---|---|
metadata.labels."strimzi.io/cluster" |
Required. The name of the Kafka cluster resource the topic belongs to. If the label is missing or does not match the cluster, the Topic Operator ignores the resource and does not create the topic. |
metadata.annotations."strimzi.io/managed" |
Optional. Set to "false" to stop the Topic Operator from managing the topic. You can then delete the KafkaTopic resource without deleting the topic in Kafka. Set it to "true", or remove it, to resume management. |
Specification (spec)¶
The spec block is required.
| Field | Type | Description |
|---|---|---|
topicName |
string |
Optional. The name of the topic in Kafka. Defaults to metadata.name. Set it only when the Kafka topic name is not a valid Kubernetes resource name, for example My.Topic.1. You cannot change the topic name after the topic is created. |
partitions |
integer |
Optional. The number of partitions. Minimum 1. Defaults to the broker setting num.partitions. You can increase the value after creation but you cannot decrease it. Increasing it changes which partition a record key maps to, which affects topics that rely on key-based partitioning. |
replicas |
integer |
Optional. The replication factor, that is, the number of copies of each partition. Minimum 1, maximum 32767. Defaults to the broker setting default.replication.factor. Upstream recommends 3. Changing the value after creation requires Cruise Control in the Kafka cluster. |
config |
map[string]any |
Optional. Kafka topic configuration properties as key-value pairs. See spec.config. |
spec.config¶
config accepts any Kafka topic configuration property.
Strimzi passes the keys and values to Kafka unchanged, so the property names are
the Kafka names, such as retention.ms. Commonly used properties:
| Property | Type | Description |
|---|---|---|
retention.ms |
long |
How long Kafka keeps records, in milliseconds. -1 means no time limit. |
retention.bytes |
long |
Maximum size of a partition before Kafka deletes old segments. -1 means no size limit. |
cleanup.policy |
string |
delete removes old segments by time or size. compact keeps the latest record per key. You can combine them as compact,delete. |
min.insync.replicas |
integer |
Minimum number of replicas that must acknowledge a write when the producer uses acks=all. Upstream recommends 2 with replicas: 3. |
max.message.bytes |
integer |
Largest record batch size that the topic accepts. |
compression.type |
string |
Final compression of the topic data, for example producer, zstd, lz4, snappy, gzip, or uncompressed. |
segment.bytes |
integer |
Size of a single log segment file. |
Status (status)¶
Run kubectl get kafkatopic <name> -o yaml to see the status.
| Field | Description |
|---|---|
conditions |
List of conditions. A Ready condition with status True means the topic exists in Kafka and matches the spec. Otherwise reason and message explain the problem, for example PartitionDecreaseException when you lower partitions. |
observedGeneration |
The resource generation the Topic Operator last reconciled. If it is lower than metadata.generation, the operator has not yet processed your latest change. |
topicName |
The name of the topic in Kafka. |
topicId |
The Kafka topic ID. It changes only if the topic is deleted and created again with the same name. |
replicasChange |
Progress of a replication factor change. targetReplicas is the requested value, state is pending or ongoing, and message holds any error. |
kubectl get kafkatopics also shows the cluster, partitions, replication
factor, and readiness in its default output.
Platform Notes¶
- We provision and manage the
Kafkacluster resource for you, including high availability, upgrades, and the underlying infrastructure. You do not create or edit it. Reference it by name in thestrimzi.io/clusterlabel. We give you the cluster name when we provision the cluster. Contact us to have one provisioned. - Manage your
KafkaTopicresources in your GitOps repository, next to your application.