Monedula
monedula-gitops docs menu

Delete topics from Kubernetes

Choose between the Orphan and Delete deletion policies when a KafkaTopic resource is removed, and allow deletion with an annotation.

How-to guides 13 of 18

3 min read

Updated 5 October 2026

Markdown

On this page

When you delete a KafkaTopic resource, the operator’s finalizer decides what happens to the Kafka topic, based on spec.deletionPolicy. Orphan, the default, stops managing the topic and leaves it on the broker. Delete removes the topic, but only once you approve it with an annotation.

Before you start

  • The operator. The CLI never deletes a topic: removing a KafkaTopic from the manifests you apply with the CLI leaves the topic in Kafka.
  • For Delete, a connecting principal that may delete the topic and its ACLs, which takes Delete on the topic and Alter on the Cluster resource, or a super-user.

Steps

1. Keep the topic with Orphan

This topic sets deletionPolicy: Orphan explicitly. Save it as manifests/orphan-demo.yaml:

apiVersion: gitops.monedula.dev/v1alpha1
kind: KafkaTopic
metadata:
  name: orphan-demo
spec:
  clusterRef:
    name: shared
  topicName: orphan.demo
  partitions: 1
  deletionPolicy: Orphan
  config:
    cleanup.policy: compact

When a topic omits deletionPolicy, the operator uses the KafkaCluster’s spec.defaults.topicDeletionPolicy, and Orphan when that is not set either.

Apply the topic, wait until it is ready, then delete the resource:

kubectl apply -f manifests/orphan-demo.yaml
kubectl wait kafkatopic/orphan-demo --for=condition=Ready --timeout=120s
kubectl delete kafkatopic orphan-demo

The finalizer is removed at once, without contacting the broker. The topic orphan.demo and its ACLs stay in Kafka, unmanaged.

2. Delete the topic with Delete and approval

This topic sets deletionPolicy: Delete and carries the approval annotation. Save it as manifests/delete-demo.yaml:

apiVersion: gitops.monedula.dev/v1alpha1
kind: KafkaTopic
metadata:
  name: delete-demo
  annotations:
    gitops.monedula.dev/allow-delete: "true"
spec:
  clusterRef:
    name: shared
  topicName: delete.demo
  partitions: 1
  deletionPolicy: Delete
  config:
    cleanup.policy: compact

Apply it, wait until it is ready, then delete the resource:

kubectl apply -f manifests/delete-demo.yaml
kubectl wait kafkatopic/delete-demo --for=condition=Ready --timeout=120s
kubectl delete kafkatopic delete-demo

kubectl delete returns once the finalizer has cleaned up, in this order:

  1. It deletes the topic’s ACLs, except those another live KafkaTopic or KafkaAccessPolicy still declares.
  2. It deletes the topic delete.demo.
  3. If the topic declares schema content in spec.schema, it deletes the topic’s subjects. Subjects in governance mode, where the topic manages only the compatibility level, are never deleted. If a subject cannot be deleted, the operator emits a SubjectDeletionFailed Warning event and still finishes the deletion.

On a cluster whose topic access also compiles to Confluent role bindings, the finalizer does not remove the topic’s derived role bindings.

3. Approve a topic for deletion

Both the policy and the annotation are required. Without the annotation, deleting a Delete topic removes nothing: the resource stays in Terminating with a DeleteNotApproved Warning event, and adding the annotation to the waiting resource lets the deletion continue. Tenancy rules never block the deletion.

To delete a topic that currently uses Orphan, switch its policy to Delete and approve it before you delete the resource. For the topic orders in the namespace monedula-demo:

kubectl -n monedula-demo patch kafkatopic orders --type merge \
  -p '{"spec":{"deletionPolicy":"Delete"}}'
kubectl -n monedula-demo annotate kafkatopic orders \
  gitops.monedula.dev/allow-delete=true --overwrite

kubectl -n monedula-demo delete kafkatopic orders

For a KafkaTopic managed in Git, make the same two changes there.

4. Release a topic whose cleanup cannot run

A deletion can also wait because the cleanup cannot run:

  • When the referenced KafkaCluster no longer exists, or its credentials cannot be read, the operator emits a DeletionBlocked Warning event. The annotation gitops.monedula.dev/force-finalizer-removal: "true" then removes the finalizer without any cleanup in Kafka; the topic and its ACLs stay.
  • When Kafka rejects the cleanup, for example because the broker is down or the principal lacks a permission, the operator emits a DeleteFailed Warning event with the error and retries. To keep the topic and release the resource instead, switch its deletionPolicy to Orphan.

Safety gates lists the deletion policy of every other kind.

Check it worked

kubectl get kafkatopic

Neither orphan-demo nor delete-demo is listed any more. On the broker, the topic orphan.demo still exists and delete.demo is gone. A Delete topic that stays in Terminating shows the reason in kubectl describe kafkatopic <name>.