Create and configure a topic

Declare a Kafka topic with partitions and configuration in a KafkaTopic manifest and apply it from the CLI or the operator.

How-to guides 3 of 18

2 min read

Updated 9 October 2026

Markdown

Declare a topic in a KafkaTopic manifest, with its partition count and the configuration keys you want to manage, and monedula-gitops creates the topic and keeps that configuration in line. The same manifest works with the CLI and the operator.

Before you start

A principal that may create topics and change their configuration. A super-user works; Least-privilege connecting principal lists the exact ACLs.

Steps

1. Write the manifest

Save this manifest as manifests/topic.yaml:

apiVersion: gitops.monedula.dev/v1alpha1
kind: KafkaTopic
metadata:
  name: payments-orders
spec:
  clusterRef:
    name: shared
  topicName: payments.orders
  partitions: 3
  config:
    cleanup.policy: compact

topicName is the Kafka topic name. It defaults to metadata.name and cannot change once set, because a rename would create a second topic and orphan the first.
partitions must be at least 1.
config maps topic configuration keys to string values; quote numbers, as in retention.ms: "604800000". monedula-gitops manages only the keys you list: it never changes other live keys and never reports them as drift.
replicationFactor is optional. Without it, the cluster’s spec.defaults.replicationFactor applies, or else the broker default. Setting it together with confluent.placement.constraints in config is a validation error, and a topic with a placement constraint does not get the cluster default either: the constraint decides replication.

2. Preview the change

With the CLI, preview the plan before you apply it:

monedula-gitops apply -f ./manifests --cluster-config-file ./cluster.yaml --dry-run

--dry-run lists the planned operations, here the topic create, and changes nothing.

3. Apply the manifest

CLIOperator

monedula-gitops apply -f ./manifests --cluster-config-file ./cluster.yaml

kubectl apply -f manifests/

The CLI exits 0 and lists payments.orders in its output. The operator creates the topic when it reconciles the resource.

4. Change the topic later

Edit the manifest and apply it again. A configuration change applies directly. Removing a key from config stops managing it, and its live value stays as it is. A partition increase is gated: apply reports it as Blocked and exits 3 until you approve it with --allow-destructive, or with the annotation gitops.monedula.dev/allow-destructive: "true" on the resource when you use the operator. A partition decrease is always rejected. A replication factor change is gated the same way, and even with approval apply reports it as Unsupported.

Check it worked