"Forced deletions ..." is a copy of the advice from https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination-forced.

It's debatable whether it should get repeated here.

Even the comment above your change is not exactly true:

The value zero indicates stop immediately via the kill signal (no opportunity to shut down).

The doc reads:

Setting the grace period to 0 forcibly and immediately deletes the Pod from the API server. If the pod was still running on a node, that forcible deletion triggers the kubelet to begin immediate cleanup.
[...]
When a force deletion is performed, the API server does not wait for confirmation from the kubelet that the Pod has been terminated on the node it was running on. It removes the Pod in the API immediately so a new Pod can be created with the same name. On the node, Pods that are set to terminate immediately will still be given a small grace period before being force killed.

So here's my suggestion:

The value zero indicates that the pod should be forced-deleted immediately without waiting for confirmation
that it has been terminated. On the node, pods that are set to terminate immediately will still be given a
small grace period before being force killed. Forced deletions can be potentially disruptive for some workloads
and their Pods.

I think that explains both what happens on the apiserver and the node, and also gives the warning you're looking for, wdyt?

So "The value zero indicates stop immediately via the kill signal (no opportunity to shut down)." (from the original documentation) is really just plain wrong?

On the node, pods that are set to terminate immediately will still be given a small grace period before being force killed.

Where does this small grace period come from? Can it be configured?

I don't know anything but what I've seen in the doc you linked :-) I doubt it can be configured. But I think that's almost irrelevant, what matters most is that it's removed from the apiserver without confirmation.

What problem are you trying to solve? It sounds like you need some policy to prevent terminationGracePeriod from being set to 0.

I don't know anything but what I've seen in the doc you linked :-)

Those docs also might be wrong... If we want the API documentation to be correct, we probably need to determine what the implementation in kubelet actually does.

What problem are you trying to solve?

I wanted test pods to be killed immediately by kubelet but without also enabling a force delete because I wanted to go through the normal pod deletion process. From the documentation it sounded like TerminationGracePeriodSeconds: 0 would do that ("The value zero indicates stop immediately via the kill signal"), but than I discovered that a Delete(..., metav1.DeleteOptions{}) (i.e. a normal delete) acted like a force-delete (Delete(..., metav1.DeleteOptions{GracePeriodSeconds: &zero})).

This was surprising. I want to avoid that surprise for others, either:

• by fixing the documentation to describe accurately what TerminationGracePeriodSeconds does or
• by making the implementation behave as implied by the documentation (control kill period in kubelet, without the force-delete side effect).

If someone wants it to be one, why wouldn't they set it to one?

They might want it to be zero, without realizing the full implications. Fixing the documentation would help here because in practice, a delay of one second is close enough - users just need to know it.

@klueska do you know how quickly kubelet kills pods when TerminationGracePeriodSeconds: 0? Is it immediately (because the Pod object is gone) or after a certain grace period?

It would be counter-intuitive if pods got killed more slowly for TerminationGracePeriodSeconds: 0 than for TerminationGracePeriodSeconds: 1.