In this article, we will explain how to use the kubectl delete deployment command in Kubernetes (K8s). This command is used to remove one or more deployments from a cluster, which stops the managed pods and deletes the associated ReplicaSets.
We’ll walk through the command syntax and practical usage scenarios and provide a step-by-step tutorial with clear examples to ensure you can confidently manage and clean up deployments in any Kubernetes environment.
We will cover:
kubectl delete deployment is a command used to remove a specific Kubernetes Deployment from a cluster. It instructs the Kubernetes API server to delete the deployment resource, which in turn stops all associated ReplicaSets and Pods managed by that deployment.
However, it should be used with caution. Before proceeding, always double-check that the YAML files you are issuing the command against contain what you expect.
One useful option for the kubectl delete deployment command is --grace-period=-1. This is the period of time in seconds given to the resource to terminate gracefully. If negative, it is ignored. Set to 1 for immediate shutdown. It can only be set to 0 when — force is true (force deletion).
How to delete a Deployment from kubectl?
- Open a terminal or command prompt and connect to your K8S cluster.
- View a list of deployments with the
kubectl get deploymentcommand.
Use the-n <namespace>flag to specify the namespace of the deployment. - Delete the deployment with the
kubectl delete deployment <deployment name> -n <namespace name>.
For example, if you had a deployment named blog-deployment in the blog namespace, you would run kubectl delete deployment blog-deployment -n blog.
What happens when you delete a Deployment in Kubernetes?
When you delete a deployment object, Kubernetes first marks the Deployment for deletion in its control plane. The control plane ensures that the desired state of the deployment is removed from the system.
Next, the Deployment controller in Kubernetes, which is responsible for managing the desired number of replicas (pods) specified in the deployment configuration, starts scaling down the number of pods to zero. This involves gracefully terminating the existing pods by sending a SIGTERM signal to the pod’s main process, allowing it to perform any necessary cleanup or shutdown activities. The grace period for termination is defined in the deployment’s pod termination settings.
Once the termination grace period is reached, K8S sends a SIGKILL signal to forcefully terminate the pod if it hasn’t terminated on its own. The pod is then removed from the node.
As pods are terminated and removed, the deployment’s actual state aligns with the desired state of of having zero replicas.
Once all the pods have been terminated and removed, K8S considers the Deployment successfully deleted. The Deployment object is removed from the K8S control plane.
Note that while the deployment object is deleted, the underlying containers and their images are not deleted automatically.
Also, if the deployment managed any associated resources like ConfigMaps, Kubernetes Secrets, or PersistentVolumes, those resources might still exist unless they were specifically deleted.
Kubernetes operates asynchronously, and the actual timing of events might vary based on cluster load, configuration settings, and other factors.
Check out also how to use kubectl delete pod command.
Let’s see how to use the kubectl delete deployment command in action.
Example 1 – How to delete all deployments inside the default namespace
To delete all deployments inside the default namespace, use:
kubectl delete deployment --all --namespace=defaultThe --all option indicates that you want to delete all resources of the specified type.
Be cautious when using commands that delete multiple resources!
Example 2 – How to delete a Kubernetes deployment from a specific namespace
You can delete a Kubernetes deployment from a specific namespace with:
kubectl delete deployment <deployment name> --namespace <namespace name>For example, if you had a deployment named blog-deployment in the blog namespace, you would run kubectl delete deployment blog-deployment -n blog.
Example 3 – How to delete all deployments in all namespaces
To delete all deployments in all namespaces, use:
kubectl delete deployment --all --all-namespaces=trueYou can also use the -A option, which is an alias to --all-namespaces.
Read more about Kubernetes namespaces.
Example 4 – How to delete multiple deployments
To delete multiple deployments in Kubernetes, you can use a loop in your shell to iterate through a list of deployment names and delete each deployment one by one.
The example file below uses Bash as the shell, which will delete three deployments for the blog namespace:
delete_deployments.sh
#!/bin/bash
# List of deployment names to delete
declare -a deployment_names=("blog-deployment-1" "blog-deployment-2" "blog-deployment-3")
# Namespace where the deployments are located
namespace="blog"
# Loop through the deployment names and delete each deployment
for deployment_name in "${deployment_names[@]}"; do
kubectl delete deployment "$deployment_name" --namespace="$namespace"
doneTo execute the script, first make it executable:
chmod +x delete_deployments.shThen run the script:
./delete_deployments.shExample 5 – How to delete Kubernetes deployments using its YAML configuration file
If you had a file with a deployment defined in it named blog-deployment.yaml you could run:
kubectl delete -f blog-deployment.yamlThe -f flag (alias to --filename) is followed by the path containing the resource to delete.
You can also use this approach to delete multiple deployments by specifying multiple file paths:
kubectl delete -f blog-deployment-1.yaml -f blog-deployment-2.yamlExample 6 – Force-delete a hung deployment
To force delete a stuck or hung Kubernetes Deployment, use:
kubectl delete deployment <deployment-name> --grace-period=0 --forceThis command immediately removes the Deployment resource by skipping the graceful termination period. The --grace-period=0 sets the termination grace period to zero seconds, and --force bypasses standard finalization, which is typically used for stuck or orphaned resources.
However, this only deletes the Deployment object, not its child resources. You will likely need to manually delete associated ReplicaSets and Pods:
kubectl delete replicaset --selector=app=<label>
kubectl delete pods --selector=app=<label>Use force deletion cautiously, as it can leave dependent resources unmanaged or in an inconsistent state.
Example 7 – Delete a Deployment using a label selector
Label selectors are useful for managing grouped resources in environments where naming conventions are dynamic or inconsistent.
Run the following to delete a Kubernetes Deployment using a label selector:
kubectl delete deployment -l app=my-appThis command deletes all Deployments that match the specified label selector. In this example, any Deployment with the label app=my-app will be deleted.
Note: Always double-check what will be deleted with a dry-run:
kubectl get deployment -l app=my-appBefore deleting a deployment in production, you should validate the impact, ensure reversibility, and confirm that all dependencies and traffic are accounted for. Failing to do so can result in service outages, data loss, or broken integrations.
Key precautions include:
- Verify traffic and dependencies: Ensure no active traffic is hitting the deployment using monitoring tools or service mesh data. Check if any other services or APIs rely on it.
- Backup configuration and state: Save deployment manifests, environment variables, secrets, and persistent volumes if applicable
- Check for stateful resources: Identify and preserve any stateful data, such as attached volumes, databases, or in-cluster caches
- Implement a rollback plan: Have a tested redeployment or rollback mechanism, such as GitOps, Helm, or infrastructure as code, ready to restore service quickly
- Communicate with stakeholders: Notify relevant teams and schedule deletion during a maintenance window if necessary
If you need help managing your Kubernetes projects, consider Spacelift. It brings with it a GitOps flow, so your Kubernetes Deployments are synced with your Kubernetes Stacks, and pull requests show you a preview of what they’re planning to change.
With Spacelift, you get:
- Policies to control what kind of resources engineers can create, what parameters they can have, how many approvals you need for a run, what kind of task you execute, what happens when a pull request is open, and where to send your notifications
- Stack dependencies to build multi-infrastructure automation workflows with dependencies, having the ability to build a workflow that can combine Terraform with Kubernetes, Ansible, and other infrastructure-as-code (IaC) tools such as OpenTofu, Pulumi, and CloudFormation,
- Self-service infrastructure via Blueprints, enabling your developers to do what matters – developing application code while not sacrificing control
- Creature comforts such as contexts (reusable containers for your environment variables, files, and hooks), and the ability to run arbitrary code
- Drift detection and optional remediation
If you want to learn more about Spacelift, create a free account today or book a demo with one of our engineers.
In this post, we learned how to use the kubectl delete deployment command to delete Kubernetes deployments, with examples for specific namespaces and multiple deployments. We also learned how to delete a Kubernetes deployment using the YAML configuration file.
The most flexible CI/CD automation tool
Spacelift is an alternative to using homegrown solutions on top of a generic CI. It helps overcome common state management issues and adds several must-have capabilities s for infrastructure management.
