Better docs for garbage collection

[zacharysarah]

This is a...

• Feature Request
• Bug Report

Problem

K8s docs discuss garbage collection in different articles:

• https://kubernetes.io/docs/concepts/cluster-administration/kubelet-garbage-collection/
• https://kubernetes.io/docs/concepts/workloads/controllers/garbage-collection/
• https://kubernetes.io/docs/admin/kube-controller-manager/
• https://kubernetes.io/docs/tasks/administer-cluster/out-of-resource/

Multiple topics show little to no awareness of each other.

Descriptions of garbage collection sometimes conflict.

No single article fully describes garbage collection as a concept or comprehensively demonstrates its implementation.

There is currently no task for garbage collection: only two concept articles and some incidental reference material.

Proposed Solution

1. Consolidate conceptual content at https://kubernetes.io/docs/concepts/workloads/controllers/garbage-collection/.

See Additional information for more details about conceptual content.

Explain garbage collection in Kubernetes as a whole: what it is; why and how different components (kubelet, kube-controller-manager) handle it separately; and interactions and dependencies between components' garbage collection functions.

Provide an end-to-end description of garbage collection in a typical production environment.

2. Create a new task article.

Explain how to set up garbage collection in a typical production environment:
- Which components to configure, and in what order, for default function
- How to assess the health of garbage collection for a pod

Pages to update

• https://kubernetes.io/docs/concepts/cluster-administration/kubelet-garbage-collection/
• https://kubernetes.io/docs/concepts/workloads/controllers/garbage-collection/
• https://kubernetes.io/docs/admin/kube-controller-manager/

Additional information

Different aspects of garbage collection appear to be handled by kubelet and kube-controller-manager. It's unclear from the documentation whether these components' garbage collection functions interact and the extent to which their functions are interdependent.

It's unclear which garbage control functions are available in which versions of Kubernetes:

• https://kubernetes.io/docs/concepts/workloads/controllers/garbage-collection/:
  "Note: Garbage collection is a beta feature and is enabled by default in Kubernetes version 1.4 and later."
• Is garbage collection also a beta feature in kubelet and kube-controller-manager?

Different topics' descriptions of garbage collection don't match:

• https://kubernetes.io/docs/concepts/cluster-administration/kubelet-garbage-collection/ describes garbage collection as a function of kubelet.
• https://kubernetes.io/docs/concepts/workloads/controllers/garbage-collection/ describes a controller as "the Kubernetes garbage collector"
• https://kubernetes.io/docs/admin/kube-controller-manager/ also sets some attributes for garbage collection.

Some of the most helpful material for understanding garbage collection mentions it only incidentally:

• https://kubernetes.io/docs/tasks/administer-cluster/out-of-resource/

Multiple topics break the style guide by making statements about the future:

• https://kubernetes.io/docs/concepts/cluster-administration/kubelet-garbage-collection/: "Some kubelet Garbage Collection features in this doc will be replaced by kubelet eviction in the future."
• https://kubernetes.io/docs/concepts/workloads/controllers/garbage-collection/: "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."

[zacharysarah]

/cc @steveperry-53 for visibility

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

Prevent issues from auto-closing with an /lifecycle frozen comment.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or @fejta.
/lifecycle stale

[nikhita]

/remove-lifecycle stale

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[nikhita]

/remove-lifecycle stale

[nikhita]

Adding the help-wanted label as well, since it has good first issue.

/help

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten

[fejta-bot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

[k8s-ci-robot]

@fejta-bot: Closing this issue.

In response to this:

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[rskrishnar]

/reopen

[k8s-ci-robot]

@rskrishnar: You can't reopen an issue/PR unless you authored it or you are a collaborator.

In response to this:

/reopen

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[rskrishnar]

@zacharysarah Is this still needed ?. I want to work on this.

[zacharysarah]

@rskrishnar Great--feel free to create a PR!

/reopen

[k8s-ci-robot]

@zacharysarah: Reopened this issue.

In response to this:

@rskrishnar Great--feel free to create a PR!

/reopen

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[fejta-bot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

[k8s-ci-robot]

@fejta-bot: Closing this issue.

In response to this:

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[sftim]

/lifecycle frozen

This is an important topic to cover

[nelvadas]

/assign @nelvadas

[sftim]

/kind feature
/priority important-longterm

[Aut0R3V]

Hey guys is anyone working on this?

[sftim]

We should move https://kubernetes.io/docs/concepts/workloads/controllers/garbage-collection/ to a new home. The other pages in this section are about resources you can create to manage a workload (eg CronJob, Deployment).

[sftim]

/triage accepted

[shannonxtreme]

/assign

[shannonxtreme]

Doc plan is here @sftim @zacharysarah please review, leave comments, and LGTM when ready or add other reviewers. Let's get the scope sorted before I dive into content :)

[sftim]

Maybe something to bring up in the SIG Docs Slack channel and / or during a SIG weekly meeting?

[shannonxtreme]

CC: @jimangel

[shannonxtreme]

Draft content for the concept topic is here, with questions: https://docs.google.com/document/d/1fEzX14PQy8jpvgAmx-Qkdd9R-2XMV8YRjRPJ1dLuoSU/edit?usp=sharing

[sftim]

@shannonxtreme that looks like a great starting point - feel free to open a pull request

[Goclipse27]

@shannonxtreme - I have given some review comments. Kindly do the changes if it inches the docs ahead.

[shannonxtreme]

@shannonxtreme - I have given some review comments. Kindly do the changes if it inches the docs ahead.

Noticed! I wish we could call it Waste Management, lol. Thank you for the reviews! Feel free to review the PR as well and give feedback.

[Goclipse27]

What inspired me was dependent cleanup for resources, in PV/PVCs came across retain, reclaim and recycle (Deprecated). :)