Clarify API version and alpha field guidance by dims · Pull Request #9222 · kubernetes/community

dims · 2026-10-15T14:47:45Z

Had a chat with @kflynn who shared a doc with their experiences, trying to capture what we can from there for forward guidance to folks

AI assistance was used to review existing guidance and draft these documentation clarifications. Signed-off-by: Davanum Srinivas <davanum@gmail.com>

kubernetes-prow · 2026-10-15T14:47:56Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: dims

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

The pull request process is described here

Details

Needs approval from an approver in each of these files:

~~contributors/devel/sig-architecture/OWNERS~~ [dims]

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

dims · 2026-10-16T14:03:53Z

@kflynn please review and let me know what else we can word smith for now.

dims · 2026-10-21T11:06:39Z

cc @kubernetes/api-reviewers

pohly · 2026-10-21T12:09:36Z


+Checking whether a field is in use does not by itself handle incompatible changes
+to its type or meaning. See [New field in existing API version](api_changes.md#new-field-in-existing-api-version)
+for guidance on changing or removing alpha fields.


This looks like an odd place to put this comment. Was it added here because of "removing alpha fields"?

That's not what field wiping does: it's about removing fields which are currently disabled.

@pohly suggest changes please?

To be honest, I would simply leave out this comment. I'm not sure what it's trying to tell me besides pointing to some other doc.

(I replied in #9222 (comment).)

lmktfy · 2026-10-21T13:42:29Z

+Checking whether a field is in use does not by itself handle incompatible changes
+to its type or meaning. See [New field in existing API version](api_changes.md#new-field-in-existing-api-version)
+for guidance on changing or removing alpha fields.


Leaving the file as-is seems better:

Suggested change

Checking whether a field is in use does not by itself handle incompatible changes

to its type or meaning. See [New field in existing API version](api_changes.md#new-field-in-existing-api-version)

for guidance on changing or removing alpha fields.

I think I disagree. The point of all of these changes is to provide better guidance around how apiVersion works and how alpha fields work, and it seems relevant to call out that knowing that an alpha field is in use is not a guarantee that it hasn't changed.

It's true that the details are in another doc, but someone reading this has not automatically read the other. Nor will they necessarily have the other doc in mind.

@kflynn: I simply don't understand what you are trying to say here.

What does "checking is in use" refer to? What does "handle incompatible changes" imply for alpha field?

Here's my interpretation:

"checking in use" is part of the drop-disabled-field logic during updates. It's unrelated to changing the field type.

"handle incompatible changes" is typically not something we do for alpha-quality fields. They can be changed from one release to another, even if that breaks version-skew scenarios, existing clusters, or out-dated consumers. That's what "alpha" means. We try to avoid it, but it's better to make such breaking changes early when a feature is still new instead of increasing technical debt or making the API more complex.

lmktfy · 2026-10-21T13:44:37Z

+An object may be accessed through multiple API versions. The `apiVersion` returned
+by the server identifies the representation being returned, not the API version
+used to create the object. For custom resources, it also does not identify the
+release of the CRD that defined the schema.


At an architectural level, Kubernetes doesn't record the API version used at creation time. This new test isn't wrong; it could perhaps be even more emphatic.

"The apiVersion returned by the server identifies the representation being returned, not the API version used to create the object – Kubernetes does not record the apiVersion used to create the object."

??

pohly · 2026-10-21T14:28:49Z


+An object may be accessed through multiple API versions. The `apiVersion` returned
+by the server identifies the representation being returned, not the API version
+used to create the object. For custom resources, it also does not identify the


Suggested change

used to create the object. For custom resources, it also does not identify the

used to create or store the object. For custom resources, it also does not identify the

I would just move to store. I don't think create is correct here, create doesn't matter as soon as the create API request is complete right?

Having both is more clear to me.

I'm fine with just "store". Otherwise we have to add "update" and "patch"...

Clarify API version and alpha field guidance

accb9eb

AI assistance was used to review existing guidance and draft these documentation clarifications. Signed-off-by: Davanum Srinivas <davanum@gmail.com>

kubernetes-prow Bot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Oct 15, 2026

kubernetes-prow Bot requested review from derekwaynecarr and johnbelamaric October 15, 2026 14:47

dims changed the title ~~[WIP] Clarify API version and alpha field guidance~~ Clarify API version and alpha field guidance Oct 16, 2026

kubernetes-prow Bot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Oct 16, 2026

pohly reviewed Oct 21, 2026

View reviewed changes

lmktfy reviewed Oct 21, 2026

View reviewed changes

pohly reviewed Oct 21, 2026

View reviewed changes

	Checking whether a field is in use does not by itself handle incompatible changes
	to its type or meaning. See [New field in existing API version](api_changes.md#new-field-in-existing-api-version)
	for guidance on changing or removing alpha fields.

	used to create the object. For custom resources, it also does not identify the
	used to create or store the object. For custom resources, it also does not identify the

Conversation

dims commented Oct 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kubernetes-prow Bot commented Oct 15, 2026

Uh oh!

dims commented Oct 16, 2026

Uh oh!

dims commented Oct 21, 2026

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!

pohly Oct 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

dims commented Oct 15, 2026 •

edited

Loading

pohly Oct 30, 2026 •

edited

Loading