[GarbageCollector] update user guide #1152

caesarxuchao · 2016-09-02T22:33:53Z

cc @kubernetes/docs

This change is

caesarxuchao · 2016-09-07T17:37:28Z

@mbohlool friendly ping :)

caesarxuchao · 2016-09-07T19:29:40Z

Thanks @mbohlool. @devin-donnelly do I need more label to get it merged?

mbohlool · 2016-09-07T19:30:55Z

I guess This PR may need a DOC LGTM (by a tech writer). If that is the case, I would suggest we send these type of changes initiated by developers directly to tech writers as they make sense to an engineer (the PR owner) and validating the truth of the statement is not part of another developer's review. There is not much value in having another developer review these changes, having a tech writer as reviewer should be enough.

caesarxuchao · 2016-09-07T21:56:30Z

#1159 will fix the travis failure

devin-donnelly · 2016-09-08T19:14:36Z

Review status: 0 of 2 files reviewed at latest revision, 10 unresolved discussions.

_data/guides.yml, line 61 [r1] (raw file):

  - title: Using kubectl to Manage Resources
    path: /docs/user-guide/working-with-resources/
  - title: Garbage collection (Beta)

Capitalize the "C" in "collection

docs/user-guide/garbage-collector.md, line 11 [r1] (raw file):

{:toc}

## Garbage Collector is a beta feature and is enabled by default

Is this the main header? If so, change to just "Garbage Collection".

Afterward add a paragraph: "Note: the Garbage Collector is a beta feature and enabled by default in Kubernetes version 1.4."

docs/user-guide/garbage-collector.md, line 13 [r1] (raw file):

## Garbage Collector is a beta feature and is enabled by default

### What is garbage collector for

Change heading to "What Does Garbage Collection Do?"

docs/user-guide/garbage-collector.md, line 15 [r1] (raw file):

### What is garbage collector for

When a replica set is deleted, in many cases it is desirable that server will automatically garbage collects all the pods created by the replica set. The garbage collector (GC) implements this. Generally, when an owner is deleted, GC deletes its dependents.

Passive voice.

"When you delete a replica set, it is often desirable for the server [editorial note: should this be "Master"?] to automatically garbage collect all the pods that the replica set has created. When you delete an owner object, the Garbage Collector (GC) deletes that owner's dependent objects.

docs/user-guide/garbage-collector.md, line 17 [r1] (raw file):

When a replica set is deleted, in many cases it is desirable that server will automatically garbage collects all the pods created by the replica set. The garbage collector (GC) implements this. Generally, when an owner is deleted, GC deletes its dependents.

### How to establish owner-dependent relation

"How to establish an owner-dependent relationship between objects"

docs/user-guide/garbage-collector.md, line 19 [r1] (raw file):

### How to establish owner-dependent relation

In release 1.3, a `metadata.ownerReferences` field is introduced to every Kubernetes API objects. When an object has an `ownerReference` pointing to another object, the dependent-owner relation is established.

More passive voice.

"Kubernetes added 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.

docs/user-guide/garbage-collector.md, line 21 [r1] (raw file):

In release 1.3, a `metadata.ownerReferences` field is introduced to every Kubernetes API objects. When an object has an `ownerReference` pointing to another object, the dependent-owner relation is established.

In release 1.4, Kubernetes control plane will automatically set a pod to have an ownerReference pointing to the replication controller or the replica set that creates it.

"When you create a Replication Controller or ReplicaSet in Kubernetes 1.4, the Kubernetes control plane automatically sets the ownerReference field for each pod that set creates.

docs/user-guide/garbage-collector.md, line 23 [r1] (raw file):

In release 1.4, Kubernetes control plane will automatically set a pod to have an ownerReference pointing to the replication controller or the replica set that creates it.

To set up owner-dependent relation among other objects, you can manually update the `ownerReferences` field of the dependent objects.

You can set up owner-dependent relationships among other objects in the Kubernetes API by manually setting the ownerReference field on dependent objects.

docs/user-guide/garbage-collector.md, line 25 [r1] (raw file):

To set up owner-dependent relation among other objects, you can manually update the `ownerReferences` field of the dependent objects.

### How to request the garbage collector to delete or not delete dependents

Change to "Controlling how Garbage Collector deletes dependents"

docs/user-guide/garbage-collector.md, line 27 [r1] (raw file):

### How to request the garbage collector to delete or not delete 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 sent to the API server. A 200 OK response from the API server indicates the owner is deleted.

"in the deletion request that you send to the API server."

Comments from Reviewable

devin-donnelly · 2016-09-08T19:15:55Z

Some writerly comments. Once those are cleared up, we can merge.

caesarxuchao · 2016-09-08T23:45:21Z

Review status: 0 of 2 files reviewed at latest revision, 10 unresolved discussions.

docs/user-guide/garbage-collector.md, line 15 [r1] (raw file):

Previously, devin-donnelly wrote…

Passive voice.

"When you delete a replica set, it is often desirable for the server [editorial note: should this be "Master"?] to automatically garbage collect all the pods that the replica set has created. When you delete an owner object, the Garbage Collector (GC) deletes that owner's dependent objects.

The first sentence is one specific use case. Then I say the garbage collector fulfills this use case. And the last sentence abstracts the function of the garbage collector. I don't think the edits express this, so I changed the paragraph differently from your suggestion. PTAL.

docs/user-guide/garbage-collector.md, line 21 [r1] (raw file):

Previously, devin-donnelly wrote…

"When you create a Replication Controller or ReplicaSet in Kubernetes 1.4, the Kubernetes control plane automatically sets the ownerReference field for each pod that set creates.

I modified it different. PTAL.

Comments from Reviewable

caesarxuchao · 2016-09-08T23:45:51Z

@devin-donnelly thank you! I modified some sentences differently. PTAL.

devin-donnelly · 2016-09-09T21:43:14Z

Review status: 0 of 2 files reviewed at latest revision, 10 unresolved discussions.

docs/user-guide/garbage-collector.md, line 15 [r1] (raw file):

Previously, caesarxuchao (Chao Xu) wrote…

The first sentence is one specific use case. Then I say the garbage collector fulfills this use case. And the last sentence abstracts the function of the garbage collector. I don't think the edits express this, so I changed the paragraph differently from your suggestion. PTAL.

Only change I'd make is to say "When you delete, for example, a ReplicaSet"

(I'd use the actual API name "ReplicaSet" as well)

docs/user-guide/garbage-collector.md, line 17 [r1] (raw file):

Previously, devin-donnelly wrote…

"How to establish an owner-dependent relationship between objects"

object -> objects

docs/user-guide/garbage-collector.md, line 21 [r1] (raw file):

Previously, caesarxuchao (Chao Xu) wrote…

I modified it different. PTAL.

Still has incorrect grammar. Maybe change to "automatically sets the `ownerReference` field for each pod that the ReplicationController or ReplicaSet creates."

Comments from Reviewable

devin-donnelly · 2016-09-09T21:43:37Z

Almost there. :) Thanks.

devin-donnelly · 2016-09-09T22:08:25Z

docs/user-guide/garbage-collector.md, line 22 [r2] (raw file):

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 replication controller or a replica set in Kubernetes 1.4, the Kubernetes control plane automatically sets the ownerReference field for each created pod to the replication controller or the replica set.

"the Kubernetes control plane automatically sets the ownerReference field in each created pod to point to the owning ReplicationController or ReplicaSet."

Comments from Reviewable

caesarxuchao · 2016-09-09T22:11:58Z

Review status: 0 of 2 files reviewed at latest revision, 11 unresolved discussions.

docs/user-guide/garbage-collector.md, line 15 [r1] (raw file):

Previously, devin-donnelly wrote…

Only change I'd make is to say "When you delete, for example, a ReplicaSet"

(I'd use the actual API name "ReplicaSet" as well)

Thanks. I changed to use "ReplicaSet", "ReplicationController", "Pod" throughout the doc.

Comments from Reviewable

caesarxuchao · 2016-09-09T22:14:37Z

Comments addressed. Thank you @devin-donnelly!

I also changed the file name from garbage-collector.md to garbage-collection.md

devin-donnelly · 2016-09-14T23:21:35Z

LGTM. Would you mind fixing the merge conflict? It's preventing me from merging.

caesarxuchao · 2016-09-15T05:25:32Z

@devin-donnelly sorry for the delay I was solving a P0 bug in the day. Rebased. PTAL. Thanks.

devin-donnelly · 2016-09-15T22:36:27Z

Awesome, no problem. Merging in now.

lavalamp · 2016-09-15T22:51:10Z

docs/user-guide/garbage-collection.md

+
+## Garbage Collection
+
+Note: the Garbage Collection is a beta feature and is enabled by default in Kubernetes version 1.4.


@caesarxuchao this doc may be a good place to list behavior differences with/without the garbage collector, too.

(in an followup)

* Localize term site_reliabilty_engineering Signed-off-by: Tania Duggal <[email protected]> * Localize site-reliability-engineering.md into Hindi Signed-off-by: Tania Duggal <[email protected]> Signed-off-by: Tania Duggal <[email protected]>

caesarxuchao assigned lavalamp Sep 2, 2016

googlebot added the cla: yes label Sep 2, 2016

caesarxuchao added this to the 1.4 milestone Sep 2, 2016

lavalamp assigned mbohlool and unassigned lavalamp Sep 2, 2016

mbohlool added the lgtm label Sep 7, 2016

caesarxuchao assigned devin-donnelly Sep 7, 2016

caesarxuchao closed this Sep 7, 2016

caesarxuchao reopened this Sep 7, 2016

caesarxuchao force-pushed the update-gc branch from 6ce4d7a to 80941d3 Compare September 7, 2016 21:17

caesarxuchao force-pushed the update-gc branch from 80941d3 to 527cea8 Compare September 8, 2016 23:44

devin-donnelly added the Docs Review: Open Issues label Sep 9, 2016

caesarxuchao force-pushed the update-gc branch from 527cea8 to 7a4ef95 Compare September 9, 2016 22:13

devin-donnelly added Docs LGTM and removed Docs Review: Open Issues labels Sep 14, 2016

update gc doc

2be2ac9

caesarxuchao force-pushed the update-gc branch from 7a4ef95 to 2be2ac9 Compare September 15, 2016 05:24

devin-donnelly removed the needs-rebase label Sep 15, 2016

devin-donnelly merged commit 6dd2eae into kubernetes:release-1.4 Sep 15, 2016

lavalamp reviewed Sep 15, 2016

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[GarbageCollector] update user guide #1152

[GarbageCollector] update user guide #1152

caesarxuchao commented Sep 2, 2016 •

edited by pwittrock

Loading

caesarxuchao commented Sep 7, 2016

caesarxuchao commented Sep 7, 2016

mbohlool commented Sep 7, 2016

caesarxuchao commented Sep 7, 2016

devin-donnelly commented Sep 8, 2016

devin-donnelly commented Sep 8, 2016

caesarxuchao commented Sep 8, 2016

caesarxuchao commented Sep 8, 2016

devin-donnelly commented Sep 9, 2016

devin-donnelly commented Sep 9, 2016

devin-donnelly commented Sep 9, 2016

caesarxuchao commented Sep 9, 2016

caesarxuchao commented Sep 9, 2016

devin-donnelly commented Sep 14, 2016

caesarxuchao commented Sep 15, 2016

devin-donnelly commented Sep 15, 2016

lavalamp Sep 15, 2016

lavalamp Sep 15, 2016


		## Garbage Collection

		Note: the Garbage Collection is a beta feature and is enabled by default in Kubernetes version 1.4.

[GarbageCollector] update user guide #1152

[GarbageCollector] update user guide #1152

Conversation

caesarxuchao commented Sep 2, 2016 • edited by pwittrock Loading

caesarxuchao commented Sep 7, 2016

caesarxuchao commented Sep 7, 2016

mbohlool commented Sep 7, 2016

caesarxuchao commented Sep 7, 2016

devin-donnelly commented Sep 8, 2016

devin-donnelly commented Sep 8, 2016

caesarxuchao commented Sep 8, 2016

caesarxuchao commented Sep 8, 2016

devin-donnelly commented Sep 9, 2016

devin-donnelly commented Sep 9, 2016

devin-donnelly commented Sep 9, 2016

caesarxuchao commented Sep 9, 2016

caesarxuchao commented Sep 9, 2016

devin-donnelly commented Sep 14, 2016

caesarxuchao commented Sep 15, 2016

devin-donnelly commented Sep 15, 2016

lavalamp Sep 15, 2016

Choose a reason for hiding this comment

lavalamp Sep 15, 2016

Choose a reason for hiding this comment

caesarxuchao commented Sep 2, 2016 •

edited by pwittrock

Loading