Skip to main content

Topic Administration

Rafka implements the standard Kafka topic admin APIs (CreateTopics, DeleteTopics, DescribeConfigs, AlterConfigs). Any standard Kafka client works. This guide uses confluent-kafka-python and kcat.

Prerequisites​

pip install confluent-kafka

Rafka gateway running on localhost:9092 (see Quickstart: Produce).

Full lifecycle — confluent-kafka AdminClient​

from confluent_kafka.admin import AdminClient, NewTopic, ConfigResource, ResourceType

admin = AdminClient({"bootstrap.servers": "localhost:9092"})
topic = "orders-v1"

# 1. Create
fs = admin.create_topics([
    NewTopic(topic, num_partitions=3, replication_factor=1,
             config={"retention.ms": "3600000"})
])
for t, f in fs.items():
    f.result()  # raises on error
print(f"Created {topic}")

# 2. List — shows partition count from the registry
meta = admin.list_topics(timeout=10)
t_info = meta.topics[topic]
print(f"Partitions: {len(t_info.partitions)}")  # → 3

# 3. Describe configs
desc = admin.describe_configs([ConfigResource(ResourceType.TOPIC, topic)])
for resource, future in desc.items():
    for key, entry in future.result().items():
        print(f"  {key} = {entry.value}")
# → retention.ms = 3600000

# 4. Alter configs (full-replace)
admin.alter_configs([
    ConfigResource(ResourceType.TOPIC, topic,
                   set_config={"retention.ms": "60000"})
])

# 5. Delete
admin.delete_topics([topic])

kcat snippets​

List topics:

kcat -b localhost:9092 -L

Check topic metadata:

kcat -b localhost:9092 -L -t orders-v1

(kcat's -L sends a wildcard Metadata request with allow_auto_topic_creation=false.)

Auto-create vs. explicit create​

Rafka distinguishes two creation paths controlled by the allow_auto_topic_creation flag in Metadata requests:

  • Producer (Producer.produce(...)) sends Metadata with flag=true → topic is auto-registered with 1 partition if absent. Produce continues without error.
  • AdminClient (list_topics(), describe_configs(...)) sends Metadata with flag=false → absent topic returns UNKNOWN_TOPIC_OR_PARTITION (3).

If you need a specific partition count, use AdminClient.create_topics(...) before the first produce. An auto-created topic (1 partition) cannot be re-partitioned in P2.

Error handling​

ErrorCodeCause
TOPIC_ALREADY_EXISTS36create_topics called twice with the same name
INVALID_PARTITIONS37num_partitions <= 0
INVALID_REPLICATION_FACTOR38replication_factor <= 0
INVALID_TOPIC_EXCEPTION17Name is empty, ., .., contains /, or >249 chars
UNKNOWN_TOPIC_OR_PARTITION3Delete/describe/alter on a topic that was never created
INVALID_CONFIG40Config conflict: cleanup.policy=compact with rafka.failover.enabled=true; or attempting to change rafka.failover.enabled via AlterConfigs (set it at creation time instead)

Partition count and the v4-cap​

Rafka advertises CreateTopics at api_version 0–4. At v4, the num_partitions echo in the create response is absent (it appears at v5+). Real AdminClients resolve the partition count by calling Metadata after create — which is exactly what list_topics() does. The conformance test confirms this works correctly: list_topics() after a 3-partition create returns 3 partitions.