Introduction

In Kubernetes, deleting a Deployment and deleting a container image are two separate operations. A Deployment is a Kubernetes API object, while an image lives in a registry and may also exist in node-level caches, so cleanup has to be handled at the correct layer.

Delete the Deployment Object

If the goal is to stop the running workload, start with the Deployment itself.

kubectl get deployments -n prod
kubectl describe deployment web-api -n prod
kubectl delete deployment web-api -n prod

After deletion, verify that the workload is really gone.

kubectl get deployment web-api -n prod
kubectl get pods -n prod -l app=web-api

Deleting the Deployment removes the controller that manages the pods. It does not remove the image from the registry.

Check Whether Another Tool Owns It

If Helm, Argo CD, Flux, or another controller manages the workload, deleting the live Deployment may only be temporary.

For Helm-managed releases:

helm list -n prod
helm uninstall web-stack -n prod

For GitOps-managed workloads, the real source of truth is usually the manifest in Git. If you delete the object only from the cluster, the reconciler may recreate it.

Understand What Kubernetes Does Not Delete

Kubernetes does not have a generic command that removes an image from a remote registry. Deleting a Deployment does not automatically delete:

• the image in your registry
• node-level image caches
• tags referenced by other workloads
• other deployments, jobs, or cron jobs that use the same image

This is where many people get confused. Kubernetes references images; it does not own registry lifecycle for you.

Verify Whether the Image Is Still Used

Before deleting an image from the registry, check whether another workload still depends on it.

kubectl get pods -A -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,IMAGES:.spec.containers[*].image'

If another Deployment or Job still references the same tag or digest, deleting that image can break future pulls, restarts, or scale-out events.

Delete the Image in the Registry

Image deletion is registry-specific. Kubernetes itself is not the place to delete the remote artifact.

Example with Amazon ECR:

aws ecr batch-delete-image \
  --repository-name my-service \
  --image-ids imageTag=old-release

Example with Google Artifact Registry:

gcloud artifacts docker images delete \
  us-central1-docker.pkg.dev/myproj/repo/my-service:old-release \
  --delete-tags --quiet

For Docker Distribution-style registries, deletion often targets the manifest digest instead of the human-friendly tag name.

Node Caches Are a Separate Cleanup Step

Even after the registry copy is deleted, nodes may still have the image cached locally. On self-managed nodes using CRI tools, cache cleanup might look like this:

sudo crictl images
sudo crictl rmi --prune

In managed clusters, manual node cache cleanup is often unnecessary or the wrong first action. Only do it if you control the nodes and understand the operational impact.

Common Pitfalls

The biggest mistake is expecting kubectl delete deployment to remove the image from the registry automatically. It does not.

Another issue is deleting an image tag without checking whether another workload still uses it.

A third problem is deleting a live Deployment in a GitOps or Helm-managed environment and then being surprised when it comes back.

Summary

• Deleting a Deployment removes the workload object, not the underlying image artifact.
• Use kubectl delete deployment only for the cluster-side resource.
• Respect Helm or GitOps ownership so the object does not get recreated unexpectedly.
• Delete images through the registry API or CLI, not through Kubernetes.
• Check whether the image is still referenced before removing it from the registry.