How to Decommission a Kafka Connect Cluster

This guide shows you how to remove a Kafka Connect cluster completely: stopping its connectors, uninstalling the chart, and clearing the state that Helm does not manage on the broker, in Vault and in Self-Service.

Type

How-to guide

Goal

Remove a Kafka Connect cluster and everything it left behind, without disturbing the other clusters on the instance.

Audience

Platform Operator with Helm access to the namespace, superuser access to the broker, and write access to the Connector Vault.

When to use

Use this guide when a tenant no longer needs a Connect cluster, or when a cluster is being rebuilt from scratch.

Work in progress. This guide is being written; the content below is a placeholder and may be incomplete.

The sections below cover each task in this guide:

Prerequisites
Stop the connectors
Uninstall the chart
Clear the state Helm does not manage
Verify the cluster is gone

Prerequisites

Confirm the following before you begin.

Replace every <…> placeholder with your actual value before running a command. <tenant>, <instance> and <cluster-name> are the cluster’s short names, <connector-vault-path> is the Vault path holding the cluster’s connector credentials (shown as Vault path on its page in Self-Service), and the rest (<RELEASE_NAME>, <NAMESPACE>, <bootstrap>, <worker-principal>, <accessor>) are your own infrastructure values.

Access and permissions required

You need the following access and permissions:

Helm access to the namespace the cluster runs in.
A Kafka superuser identity, to remove the worker’s Access Control List (ACL) entries and the internal topics.
Write access to the Connector Vault, to delete the cluster’s AppRole, policy and connector credentials.
Tenant Admin, or membership of the cluster’s Owner Group, to change the cluster in Self-Service.

Tools and versions required

You need the following tools:

helm >= 3.12, or access to the pipeline that applies the values.
kubectl >= 1.28, with access to the target namespace.
kafka-topics.sh and kafka-acls.sh from the Kafka CLI.
vault, or another way to reach the Connector Vault.

Resources that must exist before starting

The following must be true before you start:

Every connector on the cluster is either stopped or moved to another cluster. A connector that is still running when the chart is uninstalled stops moving data without warning.
You know the cluster name, because every resource below is named after it.

Stop the connectors

A connector belongs to an application in Self-Service, not to the cluster, so removing the cluster does not remove its connectors. Stop each one first, or move it to another cluster if the data flow has to continue. See Managing Connector Applications.

Stopping is not enough on its own: Stage 3 blocks cluster deletion until every Connector deployment is removed from the cluster, whatever its state.

Uninstall the chart

Uninstalling the release removes the worker pods, the KafkaConnect resource Strimzi manages, and the Kubernetes objects the chart created.

helm uninstall <RELEASE_NAME> --namespace <NAMESPACE>

The Secrets you created by hand are not part of the release, so they survive. Remove the ones that served only this cluster, including the Secret named in restApi.basicAuth.existingSecret if you created one:

kubectl -n <NAMESPACE> delete secret <cluster-name>-vault-creds

Clear the state Helm does not manage

Three kinds of state outlive the release: the broker’s internal topics, ACLs and bootstrap Job, the cluster’s objects in the Connector Vault, and the cluster’s registration in Self-Service. Work through the three stages below once the connectors are stopped and the chart is uninstalled. None of this state belongs to the Helm release, so none of it goes away with helm uninstall.

Stage 1: Undo the broker preparation

Neither of the broker preparation paths is undone by uninstalling the chart. The topics and the ACLs are broker-side state that Helm never manages, and the aclBootstrap Job is a Helm hook resource the release does not track, so all of it survives helm uninstall. Run the commands below as the Kafka superuser, with the superuser’s broker authentication configuration in client.properties, and remove the state in this order.

Delete the leftover hook resources, which the automated preparation path leaves behind whether the chart is uninstalled or aclBootstrap.enabled is set to false:
```
kubectl -n <NAMESPACE> delete job <cluster-name>-acl-bootstrap
kubectl -n <NAMESPACE> delete configmap <cluster-name>-acl-bootstrap
```

Remove the worker’s ACLs, using the same resource flags the grant used:

kafka-acls.sh --bootstrap-server <bootstrap> \
  --command-config client.properties \
  --remove --allow-principal "User:<worker-principal>" \
  --resource-pattern-type literal \
  --topic <CONFIG_STORAGE_TOPIC> --topic <OFFSET_STORAGE_TOPIC> --topic <STATUS_STORAGE_TOPIC> \
  --operation Read --operation Write --operation Describe --operation DescribeConfigs

kafka-acls.sh --bootstrap-server <bootstrap> \
  --command-config client.properties \
  --remove --allow-principal "User:<worker-principal>" \
  --resource-pattern-type literal \
  --group <GROUP_ID> --operation Read --operation Describe

If aclBootstrap.distributionPrincipal was set, the Job granted it the same ACLs, so repeat both commands for that principal.

Delete the three internal topics:

kafka-topics.sh --bootstrap-server <bootstrap> \
  --command-config client.properties \
  --delete --topic <CONFIG_STORAGE_TOPIC>

Deleting a topic drops its data. The config storage topic holds every connector configuration on the cluster, so delete it only when the cluster is not coming back.

Unless the values file sets groupId, configStorageTopic, offsetStorageTopic or statusStorageTopic, the chart derives the names from the cluster identity: <GROUP_ID> is _<tenant>-<instance>-<clusterName>-connect, and the three topics add -configs, -offsets and -status to it. Repeat the topic deletion for <OFFSET_STORAGE_TOPIC> and <STATUS_STORAGE_TOPIC>.

Stage 2: Remove the cluster’s Vault objects

The worker AppRole, its policy and the connector credentials stay in the Connector Vault after the release is gone. Delete the objects this cluster owns, and leave the ones it shares with the other clusters on the same Vault.

AppRole and policy deletion is permanent. Recreating them means repeating the Connector Vault setup from Step 5: Create the worker reader policy.

# Revoke and delete the worker AppRole
vault write auth/approle/role/<tenant>-<instance>-<cluster-name>-connect/secret-id/destroy \
  secret_id_accessor=<accessor>
vault delete auth/approle/role/<tenant>-<instance>-<cluster-name>-connect

# Delete the worker policy
vault policy delete <tenant>-<instance>-<cluster-name>-connect

# Delete the cluster's connector credentials: each is a separate secret. `vault kv list` shows one
# level at a time, so run it again on every path it returns (tls/sasl/sr, then <env>, then <app>),
# until a level returns real secret names instead of more sub-paths, then delete each one.
vault kv list -mount=connector-auth \
  <connector-vault-path>/<tenant>/<instance>/<cluster-name>
vault kv metadata delete -mount=connector-auth <secret-path>

Do not delete Platform Manager’s AppRole; it is shared across all clusters. If Platform Manager’s policy was extended with this cluster’s paths in Step 4: Confirm or extend the Platform Manager writer policy, remove the added paths from it.

Strict on-premises with a dedicated writer AppRole. Also delete the writer AppRole and its policy, which that deployment shape creates per cluster:

vault delete auth/approle/role/<tenant>-<instance>-<cluster-name>-connector-writer
vault policy delete <tenant>-<instance>-<cluster-name>-connector-writer

Stage 3: Deregister the cluster in Self-Service

Self-Service still lists the cluster and its endpoint after the pods are gone, so the registration is the last state to remove. Only a Tenant Admin can remove it, and only once no Connector application deployment still targets it.

Open the Instance overview page for the Instance that owns the cluster.
From the Connect section of the page select the Instance Cluster, then click View clusters.
Click the name of the cluster to open its detail page, then click Delete.

Only a Tenant Admin sees the Delete button. Unlike editing, membership of the cluster’s Owner Group does not grant delete rights.
Review the confirmation dialog:
1. If no Connector deployment targets the cluster, click Delete to confirm.
2. If one or more Connector deployments still target the cluster, in any deployment state, the dialog lists each one under Connector deployments by application name and environment, and the Delete button stays disabled until every listed deployment is removed. Self-Service does not stop or remove deployments on your behalf.

Deleting a Kafka Connect cluster cannot be undone. It also removes the cluster’s AppRole credentials from the Governance Vault, in addition to the Connector Vault objects removed manually in Stage 2.

Cluster deletion is recorded in the Audit History.

Verify the cluster is gone

Confirm each layer separately, because a leftover in one is invisible from the others.

helm list --namespace <NAMESPACE>
kubectl -n <NAMESPACE> get kafkaconnect,pods,job,configmap | grep <cluster-name>

Neither command should return anything for the cluster. Then confirm the internal topics no longer exist on the broker, and that <connector-vault-path>/<tenant>/<instance>/<cluster-name> under the Connector Vault’s connector-auth mount is empty.