[WIP] Add reference docs for pod PreStop hooks #48342
Conversation
k8s-ci-robot
added
the
cncf-cla: no
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
k8s-ci-robot
added
language/en
✅ Pull request preview available for checkingBuilt without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site configuration. |
|
|
||
| The following are essential concepts related to Pod lifecycle management: | ||
|
|
||
| - [Lifecycle Hooks](./lifecycle_hooks/index.md) |
There was a problem hiding this comment.
This link needs update its not correct.
| - [Lifecycle Hooks](./lifecycle_hooks/index.md) | |
| - [Lifecycle Hooks](/docs/reference/pod-lifecycle/lifecycle_hooks/) |
| - [Lifecycle Hooks](./lifecycle_hooks/index.md) | ||
| - Lifecycle hooks like PreStop and PostStart allow you to execute commands or run HTTP requests at critical moments in a container’s lifecycle. These hooks provide flexibility during container startup or shutdown, ensuring proper initialization or graceful termination. | ||
|
|
||
| - [Probes](./probes/readiness-probes.md) |
There was a problem hiding this comment.
There is no file named "readiness-probes.md". Where is this link leading to?
| - [PreStop Hook](./PreStop.md) | ||
| - This hook runs a command or sends an HTTP request right before the container is terminated, allowing you to execute graceful shutdown steps. | ||
|
|
||
| - [PostStart Hook](./PostStart.md) |
There was a problem hiding this comment.
There is no file named "PostStart.md". Where is this link leading to?
|
|
||
| Kubernetes provides two main types of lifecycle hooks: | ||
|
|
||
| - [PreStop Hook](./PreStop.md) |
There was a problem hiding this comment.
This link needs update its not correct.
| - [PreStop Hook](./PreStop.md) | |
| - [PreStop Hook](/docs/reference/pod-lifecycle/PreStop) |
|
@impact-maker I can see we already have few pages that has the related info, is the objective of pull request to add more data or increase the scope. Could you add a some description of the PR and also, looks like there is some content that is still waiting to be added, maybe make this WIP or draft PR. List of pages of similar info |
|
@steve-hardman We are restructuring the pod lifecycle events and I am performing a demo to generate documentation from the lifecycle event test cases along with @SergeyKanzhelev @tallclair. Will add some description and make this |
k8s-ci-robot
added
the
do-not-merge/work-in-progress
|
/sig node |
k8s-ci-robot
added
the
sig/node
|
BTW if this is documenting something for v1.32, please set the base branch to dev-1.32 |
|
You'll find https://kubernetes.io/docs/contribute/style/style-guide/ helpful @impact-maker - please check against that before marking this ready for review. |
k8s-ci-robot
added
cncf-cla: no
|
@impact-maker you need to sign a copyright agreement before we can formally review this - see https://api.easycla.lfx.linuxfoundation.org/v2/repository-provider/github/sign/18706487/51478266/48342/#/?version=2 An approver may close this PR if we don't see that covered. |
k8s-ci-robot
added
cncf-cla: yes
k8s-ci-robot
added
cncf-cla: no
k8s-ci-robot
added
cncf-cla: no
|
|
||
| <!-- overview --> | ||
|
|
||
| **lifecycle hooks** provide a way to trigger specific actions at crucial stages of a container's lifecycle. These hooks are useful for handling tasks such as performing tasks before the container shuts down or initiating tasks immediately after it starts. |
There was a problem hiding this comment.
| **lifecycle hooks** provide a way to trigger specific actions at crucial stages of a container's lifecycle. These hooks are useful for handling tasks such as performing tasks before the container shuts down or initiating tasks immediately after it starts. | |
| Pod _lifecycle hooks_ provide a way to trigger specific actions at crucial stages of a container's lifecycle. | |
| These hooks are useful for handling tasks such as performing tasks before the container shuts down or initiating tasks immediately after it starts. |
|
|
||
| The following behaviors describes the functionality of the `PreStop` hook. Each behavior ensures that the `PreStop` hook behaves as expected under different scenarios. | ||
|
|
||
| --- |
| - A specified command is executed during the graceful termination of a container. | ||
| - The command completes its execution within the defined termination grace period before the container shuts down. | ||
|
|
||
| <!-- prestop_basic_execution_test_starts --> |
There was a problem hiding this comment.
I don't understand how this is a test.
We could put a Pod manifest in the examples directory (for the English localization)
- including a special annotation?
- with a separate hard coded list of examples that are used in testing
and then we could refer to those examples using code_example
If we do that, the manifests are easier to access (just a plain YAML file) and they can still appear on the site.
We can also put comments in the manifests where helpful.
There was a problem hiding this comment.
If we have examples available, another tool can download them and try them in an e2e cluster. Or maybe just the GA APIs out of our set of all examples?
| The following log output confirms the successful execution of the PreStop hook: | ||
|
|
||
| ``` | ||
| PreStop Hook Executed | ||
| ``` |
There was a problem hiding this comment.
I don't get what readers learn from this (if we're not helping readers learn: why are we including it in the docs?)
There was a problem hiding this comment.
End users often seek clarity on edge cases of lifecycle events, such as how the PreStop behavior operates in scenarios with multiple containers. However, the available documentation on these cases is quite limited. To address this, we are creating documentation directly backed by tests. The approach involves writing test cases for Pod lifecycle behaviors using a specially annotated framework.
These annotations enable a script to automatically generate documentation for the corresponding behavior. This ensures that as developers add tests for lifecycle behaviors, the associated documentation is consistently and accurately updated. To illustrate this process, I’ve shared two markdown files: one showing placeholders before the script runs and another demonstrating how the script populates those placeholders with test-derived content.
| - The command completes its execution within the defined termination grace period before the container shuts down. | ||
|
|
||
| <!-- prestop_basic_execution_test_starts --> | ||
| <!-- Auto-generated test details, pod specifications, steps, and logs for the PreStop Basic Behavior will be inserted here. --> |
There was a problem hiding this comment.
In the preview, I don't see anything.
There was a problem hiding this comment.
There was a problem hiding this comment.
Netlify automatically generates a preview for how the site will look with these commits included.
I'm looking at https://deploy-preview-48342--kubernetes-io-main-staging.netlify.app/docs/reference/lifecycle-events/hooks/prestop-postinsertion/ (“the preview”)
| - shows failure affects the overall container shutdown process. | ||
|
|
||
| <!-- prestop_basic_failure_test_starts --> | ||
| <!-- Auto-generated test details, pod specifications, steps, and logs for PreStop Failure Handling will be inserted here. --> |
There was a problem hiding this comment.
In the preview, I don't see anything.
There was a problem hiding this comment.
Yes @sftim Yes currently it might not look merge ready, but I working on the PR aggressively and getting it merge ready after a few feedbacks and corrections.
|
I looked at https://deploy-preview-48342--kubernetes-io-main-staging.netlify.app/docs/reference/lifecycle-events/hooks/prestop/ - the preview for these changes I think if a reader saw that page, as it appears right now, they might well file a bug report. Here's a screenshot of what they'd see: |
|
So, is this a work-in-progress? It doesn't look like a change we could merge as is. |
There was a problem hiding this comment.
This documentation, if we add it, would belong inside https://k8s.io/docs/reference/node/ or a new section https://k8s.io/docs/reference/pod/
There was a problem hiding this comment.
@sftim This documentation would ideally belong to a new section https://k8s.io/docs/reference/lifecycle-events which have all possible areas and behaviors documentation for pod lifecycle events. Correct if I am wrong or there is a better way to do so.
There was a problem hiding this comment.
This documentation, if we add it, would belong inside https://k8s.io/docs/reference/node/ or a new section https://k8s.io/docs/reference/pod/
This. https://k8s.io/docs/reference/pod/lifecycle/ or https://k8s.io/docs/reference/pod/lifecycle-events/ would work.
|
/retitle [WIP] Add reference docs for pod PreStop hooks per #48342 (comment) |
k8s-ci-robot
changed the title
k8s-ci-robot
added
the
do-not-merge/work-in-progress
|
@sftim I am looking to get the work approved and ideally merge ready, I have created a slack thread for all the follow up questions. Aslo I have already got an approval from sig-docs on this work in the community biweekly meeting and looking to get a wholesome review on this so that I can iterate over this and close it. |
|
When this is ready for review, please update the PR title to show that it's no longer a work-in-progress. |
|
The Kubernetes project currently lacks enough contributors to adequately respond to all PRs. This bot triages PRs according to the following rules:
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /lifecycle stale |
k8s-ci-robot
added
the
lifecycle/stale
|
The Kubernetes project currently lacks enough active contributors to adequately respond to all PRs. This bot triages PRs according to the following rules:
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /lifecycle rotten |
k8s-ci-robot
added
lifecycle/rotten
|
The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs. This bot triages PRs according to the following rules:
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /close |
|
@k8s-triage-robot: Closed this PR. DetailsIn response to this:
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-sigs/prow repository. |
github-project-automation
bot
moved this from Work in progress
to Done
in SIG Node: code and documentation PRs
7 participants
Description
This PR introduces automated, testable documentation for Kubernetes Pod Lifecycle Behaviors, with a focus on PreStop hook behaviors. It leverages a Python script to dynamically populate placeholders in Markdown files with test-backed autogenerated documentation, covering the following:
Behavior Steps: Provides a clear understanding of the flow of lifecycle behaviors.
Behavior Logs: Displays expected logs to help end users validate complex behaviors.
Behavior Pod Specifications: Includes YAML configurations relevant to the behaviors being documented.
The script ensures consistent formatting and accuracy by using placeholders. Two Markdown files—
area.mdandarea-postinsertion.mdare included to validate the content before and after running the script.Issue
Closes: kubernetes/kubernetes#126369