update gc doc

_data/guides.yml

@@ -58,8 +58,8 @@ toc:
     path: /docs/user-guide/config-best-practices/
   - title: Using kubectl to Manage Resources
     path: /docs/user-guide/working-with-resources/
-  - title: Garbage collection
-    path: /docs/user-guide/garbage-collector/
+  - title: Garbage Collection (Beta)
+    path: /docs/user-guide/garbage-collection/
   - title: Using NetworkPolicy
     section:
     - title: Example Walkthrough

docs/user-guide/garbage-collection.md

@@ -0,0 +1,36 @@
+---
+assignees:
+- caesarxuchao
+
+---
+
+* TOC
+{:toc}
+
+## Garbage Collection
+
+Note: the Garbage Collection is a beta feature and is enabled by default in Kubernetes version 1.4.
+
+### What does Garbage Collector do
+
+When you delete, for example, a ReplicaSet, it is often desirable for the server to automatically garbage collect all the Pods that the ReplicaSet creates. The Garbage Collector (GC) implements this. In general, when you delete an owner object, GC deletes that owner's dependent objects.
+
+### How to establish an owner-dependent relationship between objects
+
+Kubernetes 1.3 added a metadata.ownerReferences field to every Kubernetes API object. If an API object is a dependent of another object, ownerReference should point to the owning API object.
+
+When you create a ReplicationController or a ReplicaSet in Kubernetes 1.4, the Kubernetes control plane automatically sets the ownerReference field in each created pod to point to the owning ReplicationController or ReplicaSet.
+
+You can set up owner-dependent relationships among other objects by manually setting the ownerReference field on dependent objects.
+
+### Controlling whether Garbage Collector deletes dependents
+
+When deleting an object, you can request the GC to ***asynchronously*** delete its dependents by ***explicitly*** specifying `deleteOptions.orphanDependents=false` in the deletion request that you send to the API server. A 200 OK response from the API server indicates the owner is deleted.
+
+Synchronous garbage collection will be supported in 1.5 (tracking [issue](https://github.com/kubernetes/kubernetes/issues/29891)).
+
+If you specify `deleteOptions.orphanDependents=true`, or leave it blank, then the GC will first reset the `ownerReferences` in the dependents, then delete the owner. Note that the deletion of the owner object is asynchronous, that is, a 200 OK response will be sent by the API server before the owner object gets deleted.
+
+### Other references
+[Design Doc](https://github.com/kubernetes/kubernetes/blob/master/docs/proposals/garbage-collection.md)
+[Known issues](https://github.com/kubernetes/kubernetes/issues/26120)

docs/user-guide/garbage-collector.md

@@ -1,30 +0,0 @@
----
-assignees:
-- caesarxuchao
-- mikedanese
-
----
-
-* TOC
-{:toc}
-
-## WARNING: Garbage Collector is an alpha feature and is disabled by default. Use it at your own risk!
-
-### What is garbage collector for
-
-The garbage collector (GC) cascadingly deletes dependent API objects when the owner is deleted. One use case is if two objects have functional dependency, you can specify the dependency in their configuration file when creating them, and if one of them is deleted, the GC will delete the other one automatically. The other use case is if there is logical dependency among API objects, e.g., the pods created by a replicaset depending on the replicaset, Kubernetes will automatically set the dependency (this will be implemented in release 1.4) and the GC will delete the pods when the replicaset is deleted.
-
-### How does the garbage collector work
-
-In release 1.3, there is a new `ownerReferences` field in the `metadata` of every Kubernetes API objects. The GC monitors the cluster and checks the `metadata.ownerReferences` field of each object. If none of the owners present in `metadata.ownerReferences` exists in the cluster, the GC will request the API server to delete the object.
-
-Currently a user needs to manually set the `metadata.ownerReferences`. In release 1.4, controllers will automatically set the field for the objects it controls. For example, when the replicaset controller creates or adopts pods, it will automatically add the replicaset to the `metadata.ownerReferences` fields of the pods.
-
-### How to request the garbage collector to not delete dependents
-
-When deleting an object, you can prevent the GC from deleting that object's dependents by specifying `deleteOptions.orphanDependents=true` in the deletion request. It prevents garbage collection by removing the object from its dependents' metadata.ownerReferences field.
-
-### How to enable the garbage collector
-
-The garbage collector is an alpha feature so it is disabled by default. To enable it, you need to start the kube-apiserver and kube-controller-manager with flag `--enable-garbage-collector`.
-