Merge pull request #2886 from caesarxuchao/gc-update-1.6

Update garbage collection doc for foreground garbage collection

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
+`ownerReference` field of each Pod in the ReplicaSet. In 1.6, Kubernetes
-relationships between owners and dependents by manually setting the
+automatically sets the value of `ownerReference` for objects created or adopted
-`ownerReference` field.
+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,93 @@ 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 how the garbage collector deletes dependents
 
-When you delete object, you can specify whether the object's dependents
+When you delete an object, you can specify whether the object's dependents are
-are deleted automatically. Deleting dependents automatically is called
+also deleted automatically. Deleting dependents automatically is called *cascading
-*cascading deletion*. If you delete an object without deleting its
+deletion*.  There are two modes of *cascading deletion*: *background* and *foreground*. 
-dependents automatically, the dependents are said to be *orphaned*.
 
-To delete dependent objects automatically, set the `orphanDependents` query
+If you delete an object without deleting its dependents
-parameter to false in your request to delete the owner object.
+automatically, the dependents are said to be *orphaned*. 
 
-To orphan the dependents of an owner object, set the `orphanDependents` query
+### Background cascading deletion
-parameter to true in your request to delete the owner object.
 
-The default value for `orphanDependents` is true. So unless you specify
+In *background cascading deletion*, Kubernetes deletes the owner object 
-otherwise, dependent objects are orphaned.
+immediately and the garbage collector then deletes the dependents in 
+the background.
 
-Here's an example that deletes dependents automatically:
+### 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 garbage
+collector deletes the object's dependents. Once the garbage collector has deleted all
+"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
+`blockOwnerDeletion` to true based on delete permissions on the owner object, so that
+unauthorized dependents cannot delay deletion of an owner object. 
+
+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
+Deployment. So unless you specify otherwise, dependent objects are orphaned.
+
+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.
+Here's an example that deletes dependents in foreground:
-To orphan dependents, set `--cascade` to false. The default value for
+
-`--cascade` is true.
+```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.
+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 +150,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
+[Other known issues](https://github.com/kubernetes/kubernetes/issues/26120)
-development. See the tracking
-[issue](https://github.com/kubernetes/kubernetes/issues/29891) for more details.
 
 {% 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 %}