Document API server /livez and /readyz

[johscheuer]

This is a Feature Request

During creating this PR: kubernetes/kubernetes#90970 I found out that the /livez and /readyz endpoints of the kube-apiserver are not really document. Also the documentation should highlight that /livez and /readyz are the new endpoints which should be used (otherwise some flags like --livez-grace-period and --shutdown-delay-duration will be ignored.

What would you like to be added

It would be nice to describe the differences of the endpoints and when the specific endpoints should be used (or not). Probably a sub page in https://kubernetes.io/docs/tasks/administer-cluster would be nice (or maybe it fits somewhere else)

Why is this needed
It would be nice to know what endpoints should be used to create a readinessProbe and a livenessProbe and what are the difference between these 3 endpoints.

Comments

[neolit123]

/sig network node

[neolit123]

actually livez/readyz is kube-apiserver only, so:

/remove-sig node network
/sig api-machinery

though, one way to get the attention of sig-api-machinery would have been to log this issue in k/kubernetes.

[sftim]

/sig docs

[sftim]

@johscheuer this sounds like reference documentation to me, rather than a task.

[johscheuer]

That's right, @sftim do you have any preferred place where we could put this documentation? If so I would start writing down some documentation that can be reviewed by api-machinery.

[sftim]

There's already https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/ (generated documentation).

Maybe add https://kubernetes.io/docs/reference/using-api/health-checks/ (currently a 404)?

[sftim]

If there's a place in the code for kube-apiserver to add text that ends up on https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/ and explains the health checks, that's also a valid approach.

[johscheuer]

I think https://kubernetes.io/docs/reference/using-api/health-checks/ is the best place, I don't think that the command line reference is the best place. I try to write something down this week.

[tengqm]

/language en