Add pod Observed Generation docs for 1.34 #51371

jonathancecilj · 2025-06-25T02:00:34Z

Description

Add pod ObservedGeneration info to pod docs as part of beta promotion.

Observed Pod Generation KEP: kubernetes/enhancements#2377

Issue

Closes: #51195

linux-foundation-easycla · 2025-06-25T02:00:39Z

The committers listed above are authorized under a signed CLA.

✅ login: jonathancecilj / name: Jonathan Cecil (bd7093f, 5b13e12)

k8s-ci-robot · 2025-06-25T02:00:43Z

Welcome @jonathancecilj!

It looks like this is your first PR to kubernetes/website 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes/website has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

k8s-ci-robot · 2025-06-25T02:00:46Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign salaxander for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

content/en/docs/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

netlify · 2025-06-25T02:10:13Z

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`5b13e12`
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-main-staging/deploys/685b5845e43e860008c8596b
😎 Deploy Preview	https://deploy-preview-51371--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

natasha41575 · 2025-06-25T15:01:21Z

/assign

natasha41575

Looks pretty good! I have a few small suggestions. Thanks for taking this on

natasha41575 · 2025-06-25T15:03:01Z

content/en/docs/concepts/workloads/pods/_index.md

@@ -260,6 +255,19 @@ The above update rules apply to regular pod updates, but other pod fields can be
 - **Binding:** The `binding` subresource allows setting the pod's `spec.nodeName` via a `Binding` request.
  This is typically only used by the {{< glossary_tooltip text="scheduler" term_id="kube-scheduler" >}}.

+### Pod generation
+
+- The `generation` field is unique. It will be automatically set by the


Suggested change

- The `generation` field is unique. It will be automatically set by the

- The `metadata.generation` field is unique. It will be automatically set by the

Previously this was in a section that was talking about metadata, but since we are moving it to its own section, we should make it expicit

natasha41575 · 2025-06-25T15:03:47Z

content/en/docs/concepts/workloads/pods/_index.md

+
+  {{< feature-state for_k8s_version="v1.34" state="beta" >}}
+
+- `observedGeneration` is an optional field that is captured in the `status` section of the Pod


nit: remove the word "optional". Optional usually implies that it is optional for the user, but in this case the field is set by the system (and is always set when the feature gate is on)

Suggested change

- `observedGeneration` is an optional field that is captured in the `status` section of the Pod

- `observedGeneration` is a field that is captured in the `status` section of the Pod

natasha41575 · 2025-06-25T15:04:26Z

content/en/docs/concepts/workloads/pods/_index.md

+  {{< feature-state for_k8s_version="v1.34" state="beta" >}}
+
+- `observedGeneration` is an optional field that is captured in the `status` section of the Pod
+  object. Kubelet will set `status.observedGeneration` to track the pod state to the current pod status.


Suggested change

object. Kubelet will set `status.observedGeneration` to track the pod state to the current pod status.

object. If the feature gate `PodObservedGenerationTracking` is set, the Kubelet will set `status.observedGeneration` to track the pod state to the current pod status.

natasha41575 · 2025-06-25T15:08:28Z

content/en/docs/concepts/workloads/pods/_index.md

+  object. Kubelet will set `status.observedGeneration` to track the pod state to the current pod status.
+  The pod's `status.observedGeneration` will reflect the `metadata.generation` of the pod at the point
+  that the pod status is being reported.
+


I think this is a great high-level description of what generation / observedGeneration is, thank you!

Just one thing I want us to add here. #51195 states that we have to carefully document the nuanced meaning of observedGeneration. That "nuance" I think is captured well in summary section of the mutable fields analysis doc:

If allocated spec is reflected directly in the pod status, it makes sense for the observed generation to be the generation observed in the current sync loop. This is the case for: allocated resources, resize status, ephemeral containers.
If the status is an indirect result of running the spec, then the generation associated is the generation from the previous sync loop. This is the case for: actual resources, container image, activeDeadlineSeconds/terminationGracePeriodSeconds

Can we add something to this effect here?

natasha41575 · 2025-06-25T15:10:22Z

/cc @SergeyKanzhelev
(as the sig node reviewer of this feature)

jonathancecilj · 2025-06-28T19:28:42Z

/retest

k8s-ci-robot · 2025-06-28T19:28:57Z

@jonathancecilj: Cannot trigger testing until a trusted user reviews the PR and leaves an /ok-to-test message.

In response to this:

/retest

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.

tallclair · 2025-06-30T16:18:03Z

/ok-to-test

tallclair · 2025-06-30T16:18:20Z

/retest

doc update issue#51195

5b13e12

k8s-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Jun 25, 2025

k8s-ci-robot added the cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. label Jun 25, 2025

k8s-ci-robot added the language/en Issues or PRs related to English language label Jun 25, 2025

k8s-ci-robot requested review from natalisucks and tengqm June 25, 2025 02:00

k8s-ci-robot added size/S Denotes a PR that changes 10-29 lines, ignoring generated files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. and removed cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. labels Jun 25, 2025

k8s-ci-robot assigned natasha41575 Jun 25, 2025

natasha41575 reviewed Jun 25, 2025

View reviewed changes

k8s-ci-robot requested a review from SergeyKanzhelev June 25, 2025 15:10

doc update issue#51195 -v1

bd7093f

k8s-ci-robot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Jun 27, 2025

jonathancecilj marked this pull request as ready for review June 28, 2025 19:27

k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Jun 28, 2025

k8s-ci-robot requested a review from nate-double-u June 28, 2025 19:27

k8s-ci-robot added the ok-to-test Indicates a non-member PR verified by an org member that is safe to test. label Jun 30, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add pod Observed Generation docs for 1.34 #51371

Add pod Observed Generation docs for 1.34 #51371

jonathancecilj commented Jun 25, 2025

Uh oh!

linux-foundation-easycla bot commented Jun 25, 2025 •

edited

Loading

Uh oh!

k8s-ci-robot commented Jun 25, 2025

Uh oh!

k8s-ci-robot commented Jun 25, 2025

Uh oh!

netlify bot commented Jun 25, 2025

Uh oh!

natasha41575 commented Jun 25, 2025

Uh oh!

natasha41575 left a comment

Uh oh!

natasha41575 Jun 25, 2025

Uh oh!

natasha41575 Jun 25, 2025

Uh oh!

natasha41575 Jun 25, 2025

Uh oh!

natasha41575 Jun 25, 2025

Uh oh!

natasha41575 commented Jun 25, 2025

Uh oh!

jonathancecilj commented Jun 28, 2025

Uh oh!

k8s-ci-robot commented Jun 28, 2025

Uh oh!

tallclair commented Jun 30, 2025

Uh oh!

tallclair commented Jun 30, 2025

Uh oh!

Uh oh!

	- The `generation` field is unique. It will be automatically set by the
	- The `metadata.generation` field is unique. It will be automatically set by the


		{{< feature-state for_k8s_version="v1.34" state="beta" >}}

		- `observedGeneration` is an optional field that is captured in the `status` section of the Pod

	- `observedGeneration` is an optional field that is captured in the `status` section of the Pod
	- `observedGeneration` is a field that is captured in the `status` section of the Pod

	object. Kubelet will set `status.observedGeneration` to track the pod state to the current pod status.
	object. If the feature gate `PodObservedGenerationTracking` is set, the Kubelet will set `status.observedGeneration` to track the pod state to the current pod status.

Add pod Observed Generation docs for 1.34 #51371

Are you sure you want to change the base?

Add pod Observed Generation docs for 1.34 #51371

Conversation

jonathancecilj commented Jun 25, 2025

Description

Issue

Uh oh!

linux-foundation-easycla bot commented Jun 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

k8s-ci-robot commented Jun 25, 2025

Uh oh!

k8s-ci-robot commented Jun 25, 2025

Uh oh!

netlify bot commented Jun 25, 2025

✅ Pull request preview available for checking

Uh oh!

natasha41575 commented Jun 25, 2025

Uh oh!

natasha41575 left a comment

Choose a reason for hiding this comment

Uh oh!

natasha41575 Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

natasha41575 Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

natasha41575 Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

natasha41575 Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

natasha41575 commented Jun 25, 2025

Uh oh!

jonathancecilj commented Jun 28, 2025

Uh oh!

k8s-ci-robot commented Jun 28, 2025

Uh oh!

tallclair commented Jun 30, 2025

Uh oh!

tallclair commented Jun 30, 2025

Uh oh!

Uh oh!

linux-foundation-easycla bot commented Jun 25, 2025 •

edited

Loading