Use Cascading Deletion in a Cluster

    You need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. It is recommended to run this tutorial on a cluster with at least two nodes that are not acting as control plane hosts. If you do not already have a cluster, you can create one by using or you can use one of these Kubernetes playgrounds:

    You also need to create a sample Deployment to experiment with the different types of cascading deletion. You will need to recreate the Deployment for each type.

    Check owner references on your pods

    Check that the field is present on your pods:

    The output has an ownerReferences field similar to this:

    1. apiVersion: v1
    2.     ...
    3.     ownerReferences:
    4.     - apiVersion: apps/v1
    5.       blockOwnerDeletion: true
    6.       controller: true
    7.       kind: ReplicaSet
    8.       name: nginx-deployment-6b474476c4
    9.       uid: 4fdcd81c-bd5d-41f7-97af-3a3b759af9a7
    10.     ...

    By default, Kubernetes uses to delete dependents of an object. You can switch to foreground cascading deletion using either kubectl or the Kubernetes API, depending on the Kubernetes version your cluster runs. To check the version, enter kubectl version.

    You can delete objects using foreground cascading deletion using kubectl or the Kubernetes API.

    Using kubectl

    Run the following command:

    1. kubectl delete deployment nginx-deployment --cascade=foreground

    1. Start a local proxy session:

      1. kubectl proxy --port=8080

    Use background cascading deletion

    1. .
    2. Use either kubectl or the Kubernetes API to delete the Deployment, depending on the Kubernetes version your cluster runs. To check the version, enter kubectl version.

    You can delete objects using background cascading deletion using kubectl or the Kubernetes API.

    Kubernetes uses background cascading deletion by default, and does so even if you run the following commands without the --cascade flag or the propagationPolicy argument.

    Using kubectl

    Run the following command:

    1. kubectl delete deployment nginx-deployment --cascade=background

    Using the Kubernetes API

      1. kubectl proxy --port=8080

    2. Use curl to trigger deletion:

      1. curl -X DELETE localhost:8080/apis/apps/v1/namespaces/default/deployments/nginx-deployment \
      2.     -d '{"kind":"DeleteOptions","apiVersion":"v1","propagationPolicy":"Background"}' \
      3.     -H "Content-Type: application/json"

      The output is similar to this:

      1. "kind": "Status",
      2. "apiVersion": "v1",
      3. ...
      4. "status": "Success",
      5. "details": {
      6.     "name": "nginx-deployment",
      7.     "group": "apps",
      8.     "kind": "deployments",
      9.     "uid": "cc9eefb9-2d49-4445-b1c1-d261c9396456"

    By default, when you tell Kubernetes to delete an object, the also deletes dependent objects. You can make Kubernetes orphan these dependents using kubectl or the Kubernetes API, depending on the Kubernetes version your cluster runs. To check the version, enter kubectl version.

    Using kubectl

    Run the following command:

    Using the Kubernetes API

    1. Start a local proxy session:

      1. kubectl proxy --port=8080

    2. Use curl to trigger deletion:

      1. curl -X DELETE localhost:8080/apis/apps/v1/namespaces/default/deployments/nginx-deployment \
      2.     -d '{"kind":"DeleteOptions","apiVersion":"v1","propagationPolicy":"Orphan"}' \
      3.     -H "Content-Type: application/json"
      1. "kind": "Deployment",
      2. "apiVersion": "apps/v1",
      3. "namespace": "default",
      4. "uid": "6f577034-42a0-479d-be21-78018c466f1f",
      5. "creationTimestamp": "2021-07-09T16:46:37Z",
      6. "deletionTimestamp": "2021-07-09T16:47:08Z",
      7. "deletionGracePeriodSeconds": 0,
      8. "finalizers": [
      9.   "orphan"
      10. ],
      11. ...

    You can check that the Pods managed by the Deployment are still running:

    What’s next

    • Learn about in Kubernetes.
    • Learn about Kubernetes finalizers.
    • Learn about .