How to Use Kubectl Delete Deployment in Kubernetes: Examples & Tricks

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:

1. What is the kubectl delete deployment command?
2. Kubectl delete deployment examples
3. Precautions before deleting a Deployment in production

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. 

If you need fast termination, you can either use --now (which sets --grace-period=1) or set --grace-period=0 --force for an aggressive, non-graceful delete. Only 0 requires --force – anything else is a standard graceful termination.

How to delete a Deployment from kubectl?

1. Open a terminal or command prompt and connect to your K8S cluster.
2. View a list of deployments with the kubectl get deployment command.
   Use the -n <namespace> flag to specify the namespace of the deployment.
3. 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 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=default

The --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=true

You 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"
done

To execute the script, first make it executable:

chmod +x delete_deployments.sh

Then run the script:

./delete_deployments.sh

Example 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.yaml

The -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.yaml

Example 6 – Force-delete a hung deployment

To force delete a stuck or hung Kubernetes Deployment, use:

kubectl delete deployment <deployment-name> --grace-period=0 --force

This command tells Kubernetes to skip the normal graceful termination period and request immediate deletion. The --grace-period=0 flag sets the termination grace period to zero seconds, and --force bypasses standard finalization, which is typically used only when a normal delete is blocked by issues such as stuck finalizers or an unreachable node. 

By default, Kubernetes also performs a cascading delete, so the Deployment’s ReplicaSets and Pods are removed as part of the operation. If you previously used --cascade=orphan or have misconfigured owner references, some child resources may remain and need manual cleanup. In that case, you can remove them by label, for example:

kubectl delete replicaset -l app=<label>
kubectl delete pods -l app=<label>

Use force deletion cautiously, as it can leave dependent resources in an inconsistent state or interrupt in-flight traffic.

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-app

This 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-app

Before 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:

1. 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.
2. Backup configuration and state: Save deployment manifests, environment variables, secrets, and persistent volumes if applicable
3. Check for stateful resources: Identify and preserve any stateful data, such as attached volumes, databases, or in-cluster caches
4. Implement a rollback plan: Have a tested redeployment or rollback mechanism, such as GitOps, Helm, or infrastructure as code, ready to restore service quickly
5. 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.