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 minikube or you can use one of these Kubernetes playgrounds:

    You also need to 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

    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":"Foreground"}' \
      3. -H "Content-Type: application/json"

      The output contains a foregroundDeletion finalizer like this:

      1. "kind": "Deployment",
      2. "apiVersion": "apps/v1",
      3. "metadata": {
      4. "name": "nginx-deployment",
      5. "namespace": "default",
      6. "uid": "d1ce1b02-cae8-4288-8a53-30e84d8fa505",
      7. "resourceVersion": "1363097",
      8. "deletionTimestamp": "2021-07-08T20:27:39Z",
      9. "finalizers": [
      10. "foregroundDeletion"
      11. ...

    You can delete objects using foreground cascading deletion by calling the Kubernetes API.

    For details, read the .

    1. Start a local proxy session:

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

      The output contains a foregroundDeletion finalizer like this:

    Use background cascading deletion

    1. Create a sample Deployment.
    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. 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":"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"
      10. }

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

    For details, read the .

    Using kubectl

    Run the following command:

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

    Using the Kubernetes API

    1. Start a local proxy session:

        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:

      By default, when you tell Kubernetes to delete an object, the controller 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:

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

      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"

        The output contains orphan in the finalizers field, similar to this:

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

      For details, read the .

      Using kubectl

      Run the following command:

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

      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"

        The output contains orphan in the finalizers field, similar to this:

      What’s next

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