kubeblocks-delete-cluster

name	kubeblocks-delete-cluster
version	0.2.0
description	Destructive lifecycle capability entry for removing an existing KubeBlocks cluster. Use when the user wants to decommission a database cluster and has explicitly confirmed the data-protection boundary. Do not confuse this with stop/start lifecycle actions or operator uninstall.

Delete a KubeBlocks Database Cluster

This skill belongs to the destructive lifecycle / data-protection boundary for already-created clusters.

Entry Contract

• Use this only after confirming the target cluster already exists and the user explicitly intends to decommission it.
• Treat deletion as a lifecycle action gated by backup, restore, PVC, and terminationPolicy checks.
• Use kubeblocks-op-backup or kubeblocks-op-restore before destructive deletion when recovery posture is unclear.
• Route non-destructive stop/start needs to kubeblocks-op-lifecycle.

Overview

Safely remove a KubeBlocks-managed database cluster. This skill covers pre-deletion checks, handling the terminationPolicy, and cleaning up residual resources.

Official docs: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-mysql/cluster-management/delete-mysql-cluster Full doc index: https://kubeblocks.io/llms-full.txt

Workflow

- [ ] Step 1: Pre-deletion checklist
- [ ] Step 2: Handle terminationPolicy
- [ ] Step 3: Delete the cluster
- [ ] Step 4: Verify deletion
- [ ] Step 5: Clean up residual resources (optional)

Step 1: Pre-Deletion Checklist

Before deleting, confirm the following with the user:

1a: Identify the Cluster

kubectl get cluster -n <namespace>

1b: Check terminationPolicy

kubectl get cluster <cluster-name> -n <namespace> -o jsonpath='{.spec.terminationPolicy}'

Policy	What Happens on Delete
DoNotTerminate	Deletion is blocked. Must patch before deleting.
Delete	Deletes pods and PVCs. Retains backups.
WipeOut	Deletes everything including backups.

1c: Check for Existing Backups

kubectl get backup -n <namespace> -l app.kubernetes.io/instance=<cluster-name>

If backups exist and the policy is WipeOut, warn the user that all backups will also be deleted.

1d: Check for Dependent Resources

kubectl get opsrequest -n <namespace> -l app.kubernetes.io/instance=<cluster-name>

Cancel any running OpsRequests before deleting:

kubectl delete opsrequest <ops-name> -n <namespace>

Step 2: Handle terminationPolicy

If the current policy is DoNotTerminate, the cluster cannot be deleted until it is changed. Patch it:

kubectl patch cluster <cluster-name> -n <namespace> \
  --type merge -p '{"spec":{"terminationPolicy":"Delete"}}'

Warning: Confirm with the user before changing from DoNotTerminate. This policy exists to protect production clusters from accidental deletion.

To also delete backups, use WipeOut instead of Delete.

Step 3: Delete the Cluster

kubectl delete cluster <cluster-name> -n <namespace>

This may take a minute as KubeBlocks gracefully shuts down database instances and cleans up resources.

Step 4: Verify Deletion

Confirm the cluster is gone:

kubectl get cluster <cluster-name> -n <namespace>

Expected output:

Error from server (NotFound): clusters.apps.kubeblocks.io "<cluster-name>" not found

Confirm pods are terminated:

kubectl get pods -n <namespace> -l app.kubernetes.io/instance=<cluster-name>

Expected: no resources found.

Step 5: Clean Up Residual Resources (Optional)

PVCs

If the terminationPolicy was DoNotTerminate (before patching) or if PVCs remain for any reason:

kubectl get pvc -n <namespace> -l app.kubernetes.io/instance=<cluster-name>

To delete them:

kubectl delete pvc -n <namespace> -l app.kubernetes.io/instance=<cluster-name>

Caution: Deleting PVCs permanently destroys data. Make sure backups exist if the data might be needed.

Secrets

Connection credential secrets may remain:

kubectl get secret -n <namespace> | grep <cluster-name>

To delete them:

kubectl delete secret -n <namespace> -l app.kubernetes.io/instance=<cluster-name>

ConfigMaps

kubectl get configmap -n <namespace> -l app.kubernetes.io/instance=<cluster-name>

To delete them:

kubectl delete configmap -n <namespace> -l app.kubernetes.io/instance=<cluster-name>

Troubleshooting

Cluster deletion hangs (stuck in Deleting):

• Check for finalizers: kubectl get cluster <cluster-name> -n <namespace> -o jsonpath='{.metadata.finalizers}'
• Check KubeBlocks controller logs: kubectl logs -n kb-system -l app.kubernetes.io/name=kubeblocks --tail=50

terminationPolicy is DoNotTerminate and user forgot the policy:

• The kubectl delete command will return an error. Patch the policy first (Step 2).

PVCs remain after deletion:

• This is expected if terminationPolicy was DoNotTerminate. Clean them up in Step 5.

For general agent safety conventions (dry-run, status confirmation, production protection), see safety-patterns.md.