From 2626c980f9af51232cf10faa01b54878b6a09601 Mon Sep 17 00:00:00 2001 From: Chao Xu Date: Thu, 16 Mar 2017 17:37:26 -0700 Subject: [PATCH 1/4] update gc doc for foreground garbage collection; add known issues for non-core resources --- .../controllers/garbage-collection.md | 85 +++++++++++++------ 1 file changed, 60 insertions(+), 25 deletions(-) diff --git a/docs/concepts/workloads/controllers/garbage-collection.md b/docs/concepts/workloads/controllers/garbage-collection.md index f273599921..8bfd546fd3 100644 --- a/docs/concepts/workloads/controllers/garbage-collection.md +++ b/docs/concepts/workloads/controllers/garbage-collection.md @@ -27,9 +27,12 @@ points to the owning object. Sometimes, Kubernetes sets the value of `ownerReference` automatically. For example, when you create a ReplicaSet, Kubernetes automatically sets the -`ownerReference` field of each Pod in the ReplicaSet. You can also specify -relationships between owners and dependents by manually setting the -`ownerReference` field. +`ownerReference` field of each Pod in the ReplicaSet. In 1.6, Kubernetes +automatically sets the value of `ownerReference` for objects created by +ReplicationController, Replicaset, StatefulSet, DaemonSet, and Deployment. + +You can also specify relationships between owners and dependents by manually +setting the `ownerReference` field. Here's a configuration file for a ReplicaSet that has three Pods: @@ -53,38 +56,67 @@ metadata: ownerReferences: - apiVersion: extensions/v1beta1 controller: true + blockOwnerDeletion: true kind: ReplicaSet name: my-repset uid: d9607e19-f88f-11e6-a518-42010a800195 ... ``` -## Controlling whether the garbage collector deletes dependents +## Controlling whether and how the garbage collector deletes dependents -When you delete object, you can specify whether the object's dependents -are deleted automatically. Deleting dependents automatically is called -*cascading deletion*. If you delete an object without deleting its -dependents automatically, the dependents are said to be *orphaned*. +When you delete object, you can specify whether the object's dependents are +deleted automatically. If you delete an object without deleting its dependents +automatically, the dependents are said to be *orphaned*. Deleting dependents +automatically is called *cascading deletion*. Further, there are two modes of +*cascading deletion*: if the object is deleted immediately and the garbage +collector then deletes the dependents in the background, it is called +*background cascading deletion*. In contrast, in *foreground cascading +deletion*, the object first enters a "deletion in progress" state, where the +object is still visible via the REST API, its `deletionTimestamp` is set, and +its metadata.finalizers contains "foregroundDeletion". Then the garbage +collector deletes the dependents. Once the garbage collector has deleted all +dependents whose ownerReferences.blockOwnerDeletion=true, it will finally delete +the object. -To delete dependent objects automatically, set the `orphanDependents` query -parameter to false in your request to delete the owner object. +To control whether delete dependent objects or delete them in +foreground/background, set the deleteOptions.propagationPolicy to "Orphan", +"Foregound", or "Background" respectively. -To orphan the dependents of an owner object, set the `orphanDependents` query -parameter to true in your request to delete the owner object. - -The default value for `orphanDependents` is true. So unless you specify +The default garbage collection policy for controller resources is `orphan`. So unless you specify otherwise, dependent objects are orphaned. -Here's an example that deletes dependents automatically: +Here's an example that deletes dependents in background: ```shell kubectl proxy --port=8080 -curl -X DELETE localhost:8080/apis/extensions/v1beta1/namespaces/default/replicasets/my-repset?orphanDependents=false +curl -X DELETE localhost:8080/apis/extensions/v1beta1/namespaces/default/replicasets/my-repset \ +-d '{"kind":"DeleteOptions","apiVersion":"v1","propagationPolicy":"Background"}' \ +-H "Content-Type: application/json" ``` -To delete dependents automatically using kubectl, set `--cascade` to true. -To orphan dependents, set `--cascade` to false. The default value for -`--cascade` is true. +Here's an example that deletes dependents in foreground: + +```shell +kubectl proxy --port=8080 +curl -X DELETE localhost:8080/apis/extensions/v1beta1/namespaces/default/replicasets/my-repset \ +-d '{"kind":"DeleteOptions","apiVersion":"v1","propagationPolicy":"Foreground"}' \ +-H "Content-Type: application/json" +``` + +Here's an example that orphans dependents: + +```shell +kubectl proxy --port=8080 +curl -X DELETE localhost:8080/apis/extensions/v1beta1/namespaces/default/replicasets/my-repset \ +-d '{"kind":"DeleteOptions","apiVersion":"v1","propagationPolicy":"Orphan"}' \ +-H "Content-Type: application/json" +``` + +kubectl also supports cascading deletion, though implemented in a different way. +To delete dependents automatically using kubectl, set `--cascade` to true. To +orphan dependents, set `--cascade` to false. The default value for `--cascade` +is true. Here's an example that orphans the dependents of a ReplicaSet: @@ -92,20 +124,23 @@ Here's an example that orphans the dependents of a ReplicaSet: kubectl delete replicaset my-repset --cascade=false ``` -## Ongoing development +## Known issues +* In 1.6, garbage collection does not support non-core resources, e.g., + resources added via ThirdPartyResource or via aggregated API servers. It will + support non-core resources in the future. When it does, garbage collector will + delete objects with ownerRefereneces referring to non-existent object of a + valid non-core resource. -In Kubernetes version 1.5, synchronous garbage collection is under active -development. See the tracking -[issue](https://github.com/kubernetes/kubernetes/issues/29891) for more details. +[Other known issues](https://github.com/kubernetes/kubernetes/issues/26120) {% endcapture %} {% capture whatsnext %} -[Design Doc](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/garbage-collection.md) +[Design Doc 1](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/garbage-collection.md) -[Known issues](https://github.com/kubernetes/kubernetes/issues/26120) +[Design Doc 2](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/synchronous-garbage-collection.md) {% endcapture %} From 20fb544429f1d0ee69d001b3894fae6a71d2a385 Mon Sep 17 00:00:00 2001 From: Chao Xu Date: Fri, 17 Mar 2017 17:42:04 -0700 Subject: [PATCH 2/4] address comments --- .../controllers/garbage-collection.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/concepts/workloads/controllers/garbage-collection.md b/docs/concepts/workloads/controllers/garbage-collection.md index 8bfd546fd3..493df20d32 100644 --- a/docs/concepts/workloads/controllers/garbage-collection.md +++ b/docs/concepts/workloads/controllers/garbage-collection.md @@ -28,8 +28,8 @@ points to the owning object. Sometimes, Kubernetes sets the value of `ownerReference` automatically. For example, when you create a ReplicaSet, Kubernetes automatically sets the `ownerReference` field of each Pod in the ReplicaSet. In 1.6, Kubernetes -automatically sets the value of `ownerReference` for objects created by -ReplicationController, Replicaset, StatefulSet, DaemonSet, and Deployment. +automatically sets the value of `ownerReference` for objects created or adopted +by ReplicationController, ReplicaSet, StatefulSet, DaemonSet, and Deployment. You can also specify relationships between owners and dependents by manually setting the `ownerReference` field. @@ -76,15 +76,24 @@ deletion*, the object first enters a "deletion in progress" state, where the object is still visible via the REST API, its `deletionTimestamp` is set, and its metadata.finalizers contains "foregroundDeletion". Then the garbage collector deletes the dependents. Once the garbage collector has deleted all -dependents whose ownerReferences.blockOwnerDeletion=true, it will finally delete +dependents whose ownerReference.blockOwnerDeletion=true, it will finally delete the object. +Note that in the "foregroundDeletion", only dependents with +ownerReference.blockOwnerDeletion block the deletion of the owner object. In +1.7, we will add an admission controller that disallows a user without the delete +permission of the owner object to set blockOwnerDeletion to true, so that such a +user cannot delay the deletion of the owner. For ownerReferences set up +by a controller, blockOwnerDeletion is set to true. So in most use cases, users +do not need to manually modify this field. + To control whether delete dependent objects or delete them in foreground/background, set the deleteOptions.propagationPolicy to "Orphan", "Foregound", or "Background" respectively. -The default garbage collection policy for controller resources is `orphan`. So unless you specify -otherwise, dependent objects are orphaned. +The default garbage collection policy for many controller resources is `orphan`, +including ReplicationController, ReplicaSet, StatefulSet, DaemonSet, and +Deployment. So unless you specify otherwise, dependent objects are orphaned. Here's an example that deletes dependents in background: From 14945047416de65efba5753ab07fc62445a73196 Mon Sep 17 00:00:00 2001 From: devin-donnelly Date: Wed, 22 Mar 2017 13:28:37 -0700 Subject: [PATCH 3/4] Update garbage-collection.md --- .../controllers/garbage-collection.md | 65 ++++++++++++------- 1 file changed, 41 insertions(+), 24 deletions(-) diff --git a/docs/concepts/workloads/controllers/garbage-collection.md b/docs/concepts/workloads/controllers/garbage-collection.md index 493df20d32..7e13b15a20 100644 --- a/docs/concepts/workloads/controllers/garbage-collection.md +++ b/docs/concepts/workloads/controllers/garbage-collection.md @@ -63,33 +63,50 @@ metadata: ... ``` -## Controlling whether and how the garbage collector deletes dependents +## Controlling how the garbage collector deletes dependents -When you delete object, you can specify whether the object's dependents are -deleted automatically. If you delete an object without deleting its dependents -automatically, the dependents are said to be *orphaned*. Deleting dependents -automatically is called *cascading deletion*. Further, there are two modes of -*cascading deletion*: if the object is deleted immediately and the garbage -collector then deletes the dependents in the background, it is called -*background cascading deletion*. In contrast, in *foreground cascading -deletion*, the object first enters a "deletion in progress" state, where the -object is still visible via the REST API, its `deletionTimestamp` is set, and -its metadata.finalizers contains "foregroundDeletion". Then the garbage -collector deletes the dependents. Once the garbage collector has deleted all -dependents whose ownerReference.blockOwnerDeletion=true, it will finally delete -the object. +When you delete an object, you can specify whether the object's dependents are +also deleted automatically. Deleting dependents automatically is called *cascading +deletion*. There are two modes of *cascading deletion*: *background* and *foreground*. + +If you delete an object without deleting its dependents +automatically, the dependents are said to be *orphaned*. + +### Background cascading deletion + +In *background cascading deletion*, Kubernetes deletes the owner object +immediately and the garbage collector then deletes the dependents in +the background. + +### Foreground cascading deletion + +In *foreground cascading deletion*, the root object first +enters a "deletion in progress" state. In the "deletion in progress" state, +the following things are true: + + * The object is still visible via the REST API + * The object's `deletionTimestamp` is set + * The object's `metadata.finalizers` contains the value "foregroundDeletion". + +Once the "deletion in progress" state is set, the the garbage +collector deletes the object's dependents. Once the garbage collector has deleted all +dependents (objects with `ownerReference.blockOwnerDeletion=true`), it delete +the owner object. Note that in the "foregroundDeletion", only dependents with -ownerReference.blockOwnerDeletion block the deletion of the owner object. In -1.7, we will add an admission controller that disallows a user without the delete -permission of the owner object to set blockOwnerDeletion to true, so that such a -user cannot delay the deletion of the owner. For ownerReferences set up -by a controller, blockOwnerDeletion is set to true. So in most use cases, users -do not need to manually modify this field. +`ownerReference.blockOwnerDeletion` block the deletion of the owner object. +Kubernetes version 1.7, will add an admission controller that controls user access to set +`blockOwnerDeletion` to true based on delete permissions on the owner object, so that +unauthorized dependents cannot delay deletion of an owner object. -To control whether delete dependent objects or delete them in -foreground/background, set the deleteOptions.propagationPolicy to "Orphan", -"Foregound", or "Background" respectively. +If an object's `ownerReferences` field is set by a controller (such as Deployment or ReplicaSet), +blockOwnerDeletion is set automatically and you do not need to manually modify this field. + +### Setting the cascading deletion policy + +To control the cascading deletion policy, set the `deleteOptions.propagationPolicy` +field on your owner object. Possible values include "Orphan", +"Foregound", or "Background". The default garbage collection policy for many controller resources is `orphan`, including ReplicationController, ReplicaSet, StatefulSet, DaemonSet, and @@ -122,7 +139,7 @@ curl -X DELETE localhost:8080/apis/extensions/v1beta1/namespaces/default/replica -H "Content-Type: application/json" ``` -kubectl also supports cascading deletion, though implemented in a different way. +kubectl also supports cascading deletion. To delete dependents automatically using kubectl, set `--cascade` to true. To orphan dependents, set `--cascade` to false. The default value for `--cascade` is true. From 9939c7c9536752f10ecd19681cc019a5e07509a6 Mon Sep 17 00:00:00 2001 From: devin-donnelly Date: Sun, 26 Mar 2017 18:25:03 -0700 Subject: [PATCH 4/4] Update garbage-collection.md --- docs/concepts/workloads/controllers/garbage-collection.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/concepts/workloads/controllers/garbage-collection.md b/docs/concepts/workloads/controllers/garbage-collection.md index 7e13b15a20..085fd1e168 100644 --- a/docs/concepts/workloads/controllers/garbage-collection.md +++ b/docs/concepts/workloads/controllers/garbage-collection.md @@ -88,14 +88,14 @@ the following things are true: * The object's `deletionTimestamp` is set * The object's `metadata.finalizers` contains the value "foregroundDeletion". -Once the "deletion in progress" state is set, the the garbage +Once the "deletion in progress" state is set, the garbage collector deletes the object's dependents. Once the garbage collector has deleted all -dependents (objects with `ownerReference.blockOwnerDeletion=true`), it delete +"blocking" dependents (objects with `ownerReference.blockOwnerDeletion=true`), it delete the owner object. Note that in the "foregroundDeletion", only dependents with `ownerReference.blockOwnerDeletion` block the deletion of the owner object. -Kubernetes version 1.7, will add an admission controller that controls user access to set +Kubernetes version 1.7 will add an admission controller that controls user access to set `blockOwnerDeletion` to true based on delete permissions on the owner object, so that unauthorized dependents cannot delay deletion of an owner object.