Skip to content

[GarbageCollector] Add a doc for the garbage collector #686

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
johndmulhausen merged 1 commit into from
Jun 23, 2016
Merged

[GarbageCollector] Add a doc for the garbage collector #686

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion _data/guides.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +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
Copy link
Copy Markdown
Member

@pwittrock pwittrock Jun 21, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We also have Garbage collection for container images. Is a way to disambiguate?

Copy link
Copy Markdown
Contributor Author

@caesarxuchao caesarxuchao Jun 23, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks Phil. I'll get back to your comments tomorrow.

Copy link
Copy Markdown
Contributor Author

@caesarxuchao caesarxuchao Jun 23, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed the title of that one to kubelet garbage collection.

path: /docs/user-guide/garbage-collector/

- title: Service Discovery and Load Balancing
section:
Expand Down Expand Up @@ -261,7 +263,7 @@ toc:
path: /docs/admin/network-plugins/
- title: Static Pods
path: /docs/admin/static-pods/
- title: Configuring Garbage Collection
- title: Configuring kubelet Garbage Collection
path: /docs/admin/garbage-collection/
- title: Configuring Kubernetes with Salt
path: /docs/admin/salt/
26 changes: 26 additions & 0 deletions docs/user-guide/garbage-collector.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
---
---

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

Copy link
Copy Markdown
Member

@pwittrock pwittrock Jun 21, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How long does GC take? Is there any way to be notified when GC is complete?

Copy link
Copy Markdown
Contributor Author

@caesarxuchao caesarxuchao Jun 23, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How long does GC take?

We don't have numbers yet.

Is there any way to be notified when GC is complete?

No, there is no special notification mechanism yet. We have thought about this and have found solutions, but I don't want to mention it in the doc as we don't have a timeline yet.

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