---
title: "Create and configure a topic"
description: "Declare a Kafka topic with partitions and configuration in a KafkaTopic manifest and apply it from the CLI or the operator."
url: https://monedula.dev/flock/docs/gitops/how-to/create-and-configure-a-topic/
---
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](/flock/docs/gitops/reference/connecting-principal-acls/) lists the exact ACLs.

## Steps

### 1. Write the manifest

Save this manifest as `manifests/topic.yaml`:

```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:

```bash
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

<Tabs group="create-and-configure-a-topic-mode" labels={['CLI', 'Operator']} label="Where you run it">

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

```bash
kubectl apply -f manifests/
```

</Tabs>

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](/flock/docs/gitops/concepts/safety-gates/): `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

<Tabs group="create-and-configure-a-topic-check" labels={['CLI', 'Operator']} label="Where you run it">

```bash
monedula-gitops verify -f ./manifests --cluster-config-file ./cluster.yaml
```

```bash
kubectl get kafkatopic payments-orders -o jsonpath='{.status.conditions}'
```

</Tabs>

`verify` exits 0 when the live topic matches the manifest and 1 when it finds drift. With the operator, the `Ready` condition has the status `True`. The topic `payments.orders` now exists with 3 partitions and `cleanup.policy=compact`.

## Related

- The [KafkaTopic reference](/flock/docs/gitops/reference/resources/kafka-topic/) lists every field.
- [Grant producers and consumers access](/flock/docs/gitops/how-to/grant-topic-access/) adds access to the same manifest.
- Runnable version: [scenarios/01-create-topic](https://github.com/monedula-dev/monedula-gitops/tree/main/scenarios/01-create-topic)