Issue with k8s.io/docs/reference/command-line-tools-reference/kube-controller-manager/

[ethaeris]

This is a Bug Report

Problem:
Two different parts of the documentation imply that the terminated-pod-gc-threshold configuration value is two different units.

https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-lifetime implies that terminated-pod-gc-threshold is in seconds:
"The only exception to this rule is that Pods with a phase of Succeeded or Failed for more than some duration (determined by terminated-pod-gc-threshold in the master) will expire and be automatically destroyed."

https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/ implies that it is a number of pods:
"Number of terminated pods that can exist before the terminated pod garbage collector starts deleting terminated pods. If <= 0, the terminated pod garbage collector is disabled."

Proposed Solution:
Update one page or the other to reflect the unit of terminated-pod-gc-threshold.

Page to Update:
https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/
and/or
https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-lifetime

[sftim]

/kind cleanup
/priority backlog

[sftim]

Also:
/help

[k8s-ci-robot]

@sftim:
This request has been marked as needing help from a contributor.

Please ensure the request meets the requirements listed here.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-help command.

In response to this:

Also:
/help

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]

If anyone wants advice on how to tackle this issue, reply and mention me. I'll try to help.

[hase1128]

@sftim
I checked related source codes.
Explanation of the following URL is correct.
https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/

Related source codes

https://github.com/kubernetes/kubernetes/blob/master/pkg/controller/podgc/gc_controller.go
https://github.com/kubernetes/kubernetes/blob/master/pkg/controller/podgc/doc.go

// Package podgc contains a very simple pod "garbage collector" implementation,
// PodGCController, that runs in the controller manager. If the number of pods
// in terminated phases (right now either Failed or Succeeded) surpasses a
// configurable threshold, the controller will delete pods in terminated state
// until the system reaches the allowed threshold again. The PodGCController
// prioritizes pods to delete by sorting by creation timestamp and deleting the
// oldest objects first. The PodGCController will not delete non-terminated
// pods.

So, I think the description of pod-lifetime should be modified.
https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-lifetime

"The only exception to this rule is that Pods with a phase of Succeeded or Failed for more than some duration (determined by terminated-pod-gc-threshold in the master) will expire and be automatically destroyed."

In the above description, the expression of some duration is not wrong, but misleading expressions.
some duration precisely means is as follows.

It takes a certain amount of time until the number of pods with a phase of Succeeded or Failed exceed the value set for terminated-pod-gc-threshold.

Therefore, So, I think the description of pod-lifetime should be modified.
If you agree with my opinion, I handle this issue.

[hase1128]

/assign

[sftim]

@hase1128 it sounds like you've already got a handle on what to do to fix this issue
If that's right, I'm happy to let you pick the best approach.

In #15374 I've a draft set of changes to document all built-in controllers. I'll be happy to incorporate recommended wording into a revision to that PR.

[hase1128]

@sftim
sorry for my late response, and thank you for the information of a draft set.
I will do PR next week. (currently, I am a little busy....)

[hase1128]

@sftim

I have few questions.

Q1:
I handled this issue and do PR, but this PR handle English document only.
I am Japanese. Should I modify Japanese document ( and other language documents)?

Q2:

In #15374 I've a draft set of changes to document all built-in controllers.

I'm sorry, I would like to know detail procedure to add my modification into #15374.
(This PR is my first one, so I am not yet familiar with this work...)

[inductor]

FYI, the Japanese PR has been merged :)

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