Document pod `status.observedGeneration` #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 (b89a59e, 070dda9, 9af480c, 4b8babe)

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

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

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`070dda9`
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-main-staging/deploys/68880f15e23f7b0008b73373
😎 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


+### 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.

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

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

natasha41575 · 2025-07-07T16:09:27Z

/retitle Document pod status.observedGeneration

per this comment:

Feel free to document this in the live docs; no need to wait for v1.34

natasha41575

thanks for the update! I just have a few small wording suggestions.

These comments are mostly because the fact that observedGeneration has a slightly different meaning for different fields is more of a side effect of the way kubelet is implemented rather than something intentional, so I'm trying to get the docs to capture that essence.

after you make these changes I'll LGTM

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

natasha41575 · 2025-07-09T17:43:50Z

No idea why the tests have been consistently failing... can you try rebasing?

# with your current branch checked out
git remote add upstream git@github.com:kubernetes/website.git
git fetch upstream main
git rebase upstream/main

natasha41575 · 2025-07-14T17:28:17Z

/lgtm

/assign @lmktfy
for sig-docs approval

k8s-ci-robot · 2025-07-14T17:28:24Z

LGTM label has been added.

Git tree hash: e0693c6713a9230bc2b50a504518ce219de7d828

SergeyKanzhelev · 2025-07-14T18:58:09Z

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

 - Pod updates may not change fields other than `spec.containers[*].image`,
-  `spec.initContainers[*].image`, `spec.activeDeadlineSeconds` or
-  `spec.tolerations`. For `spec.tolerations`, you can only add new entries.
+  `spec.initContainers[*].image`, `spec.activeDeadlineSeconds`, `spec.terminationGracePeriodSeconds` or


Suggested change

`spec.initContainers[*].image`, `spec.activeDeadlineSeconds`, `spec.terminationGracePeriodSeconds` or

`spec.initContainers[*].image`, `spec.activeDeadlineSeconds`, `spec.terminationGracePeriodSeconds`,

@jonathancecilj , please take a look at @SergeyKanzhelev 's suggestion

SergeyKanzhelev · 2025-07-14T19:04:29Z

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

+Different status fields may either be associated with the `metadata.generation` of the current sync loop, or with the
+`metadata.generation` of the previous sync loop. The key distinction is whether a change in the `spec` is reflected
+directly in the `status` or is an indirect result of a running process.
+


can we add two notices - one for the fact that this does not apply to static pods. And one that node lifecycle controller may set this as well?

The node lifecycle controller does not touch status.observedGeneration. It only touches pod conditions[].observedGeneration which does not apply to this documentation.

If we want to make it a requirement to document more carefully conditions[].observedGeneration, let's leave it out of scope of this PR. I'll take it up as a separate task.

sure. Makes sense

SergeyKanzhelev · 2025-07-14T19:05:13Z

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

+  system such that new pods have a `metadata.generation` of 1, and every update to
+  mutable fields in the pod's spec will increment the `metadata.generation` by 1.
+
+{{< feature-state feature_gate_name="PodObservedGenerationTracking" >}}


should we add a note to say that k8s is not expecting external controllers to modify this field in any ways and changing it may lead to unexpected behavior?

SergeyKanzhelev · 2025-07-14T19:05:28Z

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

+  request.
+- **Container state**: During an in-progress resize, with require restart policy reflects the previous generation's
+  request.
+- **activeDeadlineSeconds** & **terminationGracePeriodSeconds** & **DeletionTimestamp**: The effects of these fields on the


Suggested change

- **activeDeadlineSeconds** & **terminationGracePeriodSeconds** & **DeletionTimestamp**: The effects of these fields on the

- **activeDeadlineSeconds** & **terminationGracePeriodSeconds** & **deletionTimestamp**: The effects of these fields on the

SergeyKanzhelev

/lgtm

k8s-ci-robot · 2025-07-29T06:40:33Z

LGTM label has been added.

Git tree hash: ea8e669a455dd0359007320f2f229f85ad1877c9

natasha41575 · 2025-07-29T14:55:16Z

/lgtm
/assign @reylejano

natasha41575 · 2025-08-04T21:06:48Z

friendly ping @reylejano
would you be able to do a pass for approval?

SergeyKanzhelev

/lgtm

natalisucks · 2025-08-06T13:04:12Z

good for docs, thanks everyone
/approve

k8s-ci-robot · 2025-08-06T13:04:21Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: natalisucks, SergeyKanzhelev

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

The pull request process is described here

Needs approval from an approver in each of these files:

~~content/en/docs/OWNERS~~ [natalisucks]

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

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

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

k8s-ci-robot changed the title ~~Add pod Observed Generation docs for 1.34~~ Document pod status.observedGeneration Jul 7, 2025

natasha41575 reviewed Jul 7, 2025

View reviewed changes

natasha41575 mentioned this pull request Jul 7, 2025

Pod Generation kubernetes/enhancements#5067

Open

12 tasks

tallclair reviewed Jul 7, 2025

View reviewed changes

content/en/docs/concepts/workloads/pods/_index.md Outdated Show resolved Hide resolved

jonathancecilj added 3 commits July 11, 2025 23:51

doc update issue#51195

4b8babe

doc update issue#51195 -v1

b89a59e

Iter2 commit

9af480c

jonathancecilj force-pushed the 51195-k8s_1_34_branch branch from e54e4b2 to 9af480c Compare July 13, 2025 23:02

k8s-ci-robot assigned lmktfy Jul 14, 2025

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jul 14, 2025

SergeyKanzhelev reviewed Jul 14, 2025

View reviewed changes

doc update issue#51195 -v3

070dda9

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jul 29, 2025

k8s-ci-robot requested review from lmktfy and natasha41575 July 29, 2025 00:00

SergeyKanzhelev approved these changes Jul 29, 2025

View reviewed changes

k8s-ci-robot assigned SergeyKanzhelev Jul 29, 2025

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jul 29, 2025

k8s-ci-robot assigned reylejano Jul 29, 2025

This was referenced Jul 29, 2025

add pod generation to docs for v1.33 #49906

Merged

PodObservedGenerationTracking promoted to beta in 1.34 #51532

Merged

SergeyKanzhelev reviewed Aug 5, 2025

View reviewed changes

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Aug 6, 2025

k8s-ci-robot merged commit d0bdbd4 into kubernetes:main Aug 6, 2025
6 checks passed

dkarczmarski mentioned this pull request Aug 9, 2025

[pl] sync with PR 51371 #51859

Merged


		### Pod generation

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

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

	`spec.initContainers[*].image`, `spec.activeDeadlineSeconds`, `spec.terminationGracePeriodSeconds` or
	`spec.initContainers[*].image`, `spec.activeDeadlineSeconds`, `spec.terminationGracePeriodSeconds`,

	- activeDeadlineSeconds & terminationGracePeriodSeconds & DeletionTimestamp: The effects of these fields on the
	- activeDeadlineSeconds & terminationGracePeriodSeconds & deletionTimestamp: The effects of these fields on the

Document pod status.observedGeneration #51371

Document pod status.observedGeneration #51371

Uh oh!

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!

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

Uh oh!

✅ 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

natasha41575 commented Jul 7, 2025

Uh oh!

natasha41575 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

natasha41575 commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

natasha41575 commented Jul 14, 2025

Uh oh!

k8s-ci-robot commented Jul 14, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SergeyKanzhelev left a comment

Choose a reason for hiding this comment

Uh oh!

k8s-ci-robot commented Jul 29, 2025

Uh oh!

natasha41575 commented Jul 29, 2025

Uh oh!

natasha41575 commented Aug 4, 2025

Uh oh!

SergeyKanzhelev left a comment

Document pod `status.observedGeneration` #51371

Document pod `status.observedGeneration` #51371

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

edited

Loading

netlify bot commented Jun 25, 2025 •

edited

Loading

natasha41575 commented Jul 9, 2025 •

edited

Loading