Update the description of PodTopologySpread matchLabelKeys implementation change since v1.34 #51119

mochizuki875 · 2025-05-30T18:03:26Z

Description

This PR is a follow-up to #49607 and #50122, resubmitted for the v1.34 release because the code change missed v1.33.

KEP-3243: Update milestone v1.33 to v1.34 and add the new feature gate to control the design change of TopologySpreadConstraint's matchLabelKeys enhancements#5205
Change the implementation design of matchLabelKeys in PodTopologySpread to be aligned with PodAffinity kubernetes#129874

netlify · 2025-05-30T18:03:32Z

👷 Deploy Preview for kubernetes-io-vnext-staging processing.

Name	Link
🔨 Latest commit	`8ad8c10`
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-vnext-staging/deploys/686cca6142132b00080d41d2

lmktfy

/lgtm

content/en/docs/concepts/scheduling-eviction/topology-spread-constraints.md

k8s-ci-robot · 2025-05-30T18:09:11Z

LGTM label has been added.

Details

Git tree hash: 3198ef123f30040fafb95be0d9458712dcd744c0

netlify · 2025-05-30T18:12:26Z

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`8ad8c10`
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-main-staging/deploys/686cca61dbfb9b000825a87f
😎 Deploy Preview	https://deploy-preview-51119--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.

lmktfy

LGTM for docs

lmktfy · 2025-06-01T14:00:09Z

/lgtm

k8s-ci-robot · 2025-06-01T14:00:17Z

LGTM label has been added.

Details

Git tree hash: e0ce9afeec7c3ac1f968ddee7ba4662e2a0e9c81

divya-mohan0209 · 2025-06-15T12:54:09Z

/sig scheduling

divya-mohan0209 · 2025-06-15T12:54:32Z

@kubernetes/sig-scheduling-leads PTAL and advise on tech accuracy.

sanposhiho

two nits

sanposhiho · 2025-06-15T13:03:18Z

...command-line-tools-reference/feature-gates/MatchLabelKeysInPodTopologySpreadSelectorMerge.md

+    fromVersion: "1.34"
+---
+Enable merging of selectors built from `matchLabelKeys` into `labelSelector` of 
+[Pod topology spread constraints](/docs/concepts/scheduling-eviction/topology-spread-constraints/).


This feature gate can be enabled when matchLabelKeys feature is enabled with the MatchLabelKeysInPodTopologySpread feature flag.

sanposhiho · 2025-06-15T13:04:10Z

content/en/docs/concepts/scheduling-eviction/topology-spread-constraints.md

  The `matchLabelKeys` field is a beta-level field and enabled by default in 1.27. You can disable it by disabling the
  `MatchLabelKeysInPodTopologySpread` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/).
+
+  Before v1.34, kube-scheduler just internally handled `matchLabelKeys` before the calculation of scheduling results.


nit: kube-scheduler didn't handle it before the calculation, it did handle it during the calculation.

Suggested change

Before v1.34, kube-scheduler just internally handled `matchLabelKeys` before the calculation of scheduling results.

Before v1.34, kube-scheduler just internally handled `matchLabelKeys` and calculating scheduling results.

@sanposhiho
That's absolutely true.
BTW, is "calculated" more appropriate than "calculating" in terms of grammar?

tengqm · 2025-06-21T01:00:32Z

content/en/docs/concepts/scheduling-eviction/topology-spread-constraints.md

  `MatchLabelKeysInPodTopologySpread` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/).

-  Before v1.34, kube-scheduler just internally handled `matchLabelKeys` before the calculation of scheduling results.
+  Before v1.34, kube-scheduler just internally handled `matchLabelKeys` and calculated scheduling results.


Why this change?

@tengqm
It's to align with PodAffinity's matchLabelKeys and described in KEP-3243.
However should we describe it here too?

So .... there used to be a strict order but starting from 1.34, the ordering has been relaxed?

In terms of the function of matchLabelKeys, which is a list of pod label keys that pod spreading is calculated based on, the strength of constraints hasn't changed between v1.33 and v1.34.

In the case of PodAffinity's matchLabelKeys, key-value labels corresponding to matchLabelKeys are explicitly merged into LabelSelector by apiserver, and scheduler handles them.
On the other hand, in the case of TopologySpreadConstraints prior to v1.34, matchLabelKeys are directly handled by scheduler and key-value labels corresponding to matchLabelKeys are not merged into LabelSelector.

From v1.34, key-value labels are merged into LabelSelector as PodAffinity(as described here), but the function of matchLabelKeys does not change or become stricter.

@mochizuki875 Do you mean that the user perceivable behavior has not changed? In other words, users don't need to care about this level of implementation details?

@tengqm
Hmm, the behavior itself(scheduling calculation logic of matchLabelKeys) has not change.
So I think users don't need to care about it so much.
It only changes how it appears to the user; whether labelSelectors built from matchLabelKeys are visible in podSpec(e.g. The result of kubectl get pod xxx -o yaml).

Thanks for the clarification, @mochizuki875. Can we then focus on the user-perceivable changes rather than forcing the users to understand the implementation details?
If users don't need to care about it, maybe we can remove all the relevant texts to avoid confusion?

What's "users" you are saying? I mean, if it's end users who just uses K8s cluster that whoever provisioned, then they shouldn't have to know about this detail. But, if you mean "users" equals cluster admins, then they might want to know it. Because they might observe some unintended behavior from this change (of course, hopefully not though). Note that we introduced this feature flag for those cases.

Okay. Then I'd suggest that we focus on the user-perceivable (behavior) changes.
Changing from

Before v1.34, kube-scheduler just internally handled matchLabelKeys before the calculation of scheduling results.

to

Before v1.34, kube-scheduler just internally handled matchLabelKeys and calculated scheduling results.

doesn't help clarify what the users need/want to know.

@tengqm
If we focus on behavior as perceived by end users, I think we should only refer to whether labelSelectors built from matchLabelKeys are visible in podSpec or not.
So how about this:

Before v1.34, matchLabelKeys was handled implicitly.
Since v1.34, key-value labels corresponding to matchLabelKeys are explicitly merged into labelSelector.

t-inu · 2025-07-13T05:48:56Z

/remove-language bn fr id ja pt zh
/remove-area blog localization web-development

michellengnx · 2025-08-01T15:30:21Z

Hello @mochizuki875 👋! I'm reaching out from the Docs team.

Just checking in as we approach Docs Freeze on Wednesday August 6, 2025 18:00 PDT. This documentation appears to still be under review. To meet the Docs Freeze, this PR must have a technical review as well as lgtm and approve labels applied, without any unaddressed comments or concerns from SIG Docs. Thank you!

macsko · 2025-08-06T07:10:09Z

/approve
SIG Scheduling

/assign @lmktfy
For docs approval

natalisucks · 2025-08-06T12:53:24Z

@macsko for future tech reviews on docs, please add the LGTM label instead, since only SIG Docs approvers have the ability to add the approve label in this repo.
given we have both tech and now my docs review, i'm adding both labels so we can make sure this makes the Docs Freeze deadline – thanks so all reviewers!
/lgtm
/approve

k8s-ci-robot · 2025-08-06T12:53:32Z

LGTM label has been added.

Details

Git tree hash: 01870e94af849257c00729fc8ebdc468d6a510c3

k8s-ci-robot · 2025-08-06T12:53:32Z

[APPROVALNOTIFIER] This PR is APPROVED

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

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:

~~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 this to the 1.34 milestone May 30, 2025

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label May 30, 2025

k8s-ci-robot requested a review from drewhagen May 30, 2025 18:03

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

k8s-ci-robot requested a review from reylejano May 30, 2025 18:03

k8s-ci-robot added the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label May 30, 2025

lmktfy reviewed May 30, 2025

View reviewed changes

content/en/docs/concepts/scheduling-eviction/topology-spread-constraints.md Outdated Show resolved Hide resolved

k8s-ci-robot assigned lmktfy May 30, 2025

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

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

k8s-ci-robot requested a review from lmktfy May 31, 2025 16:43

lmktfy reviewed Jun 1, 2025

View reviewed changes

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

k8s-ci-robot added the sig/scheduling Categorizes an issue or PR as relevant to SIG Scheduling. label Jun 15, 2025

github-project-automation bot added this to SIG Scheduling Jun 15, 2025

github-project-automation bot moved this to Needs Triage in SIG Scheduling Jun 15, 2025

sanposhiho reviewed Jun 15, 2025

View reviewed changes

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

k8s-ci-robot requested a review from lmktfy June 20, 2025 16:14

tengqm reviewed Jun 21, 2025

View reviewed changes

mochizuki875 mentioned this pull request Jun 26, 2025

Respect PodTopologySpread after rolling upgrades kubernetes/enhancements#3243

Open

12 tasks

mochizuki875 force-pushed the design_change_of_podtopologyspread_matchlablkeys branch from da6f099 to 525fb22 Compare July 8, 2025 07:03

k8s-ci-robot added the area/blog Issues or PRs related to the Kubernetes Blog subproject label Jul 8, 2025

k8s-ci-robot added sig/docs Categorizes an issue or PR as relevant to SIG Docs. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Jul 8, 2025

mochizuki875 force-pushed the design_change_of_podtopologyspread_matchlablkeys branch from 525fb22 to 4a09bb7 Compare July 8, 2025 07:04

fix1

8ad8c10

mochizuki875 force-pushed the design_change_of_podtopologyspread_matchlablkeys branch from 2167fb7 to 8ad8c10 Compare July 8, 2025 07:35

k8s-ci-robot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Jul 8, 2025

helayoty moved this from Needs Triage to Backlog in SIG Scheduling Jul 24, 2025

helayoty moved this from Backlog to Needs Review in SIG Scheduling Jul 24, 2025

k8s-ci-robot assigned natalisucks Aug 6, 2025

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

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 66f381e into kubernetes:dev-1.34 Aug 6, 2025
6 checks passed

github-project-automation bot moved this from Needs Review to Done in SIG Scheduling Aug 6, 2025

	Before v1.34, kube-scheduler just internally handled `matchLabelKeys` before the calculation of scheduling results.
	Before v1.34, kube-scheduler just internally handled `matchLabelKeys` and calculating scheduling results.

Update the description of PodTopologySpread matchLabelKeys implementation change since v1.34 #51119

Update the description of PodTopologySpread matchLabelKeys implementation change since v1.34 #51119

Uh oh!

Conversation

mochizuki875 commented May 30, 2025

Description

Uh oh!

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

Uh oh!

👷 Deploy Preview for kubernetes-io-vnext-staging processing.

Uh oh!

lmktfy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

k8s-ci-robot commented May 30, 2025

Uh oh!

netlify bot commented May 30, 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!

lmktfy left a comment

Choose a reason for hiding this comment

Uh oh!

lmktfy commented Jun 1, 2025

Uh oh!

k8s-ci-robot commented Jun 1, 2025

Uh oh!

divya-mohan0209 commented Jun 15, 2025

Uh oh!

divya-mohan0209 commented Jun 15, 2025

Uh oh!

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

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!

mochizuki875 Jun 23, 2025 • 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!

sanposhiho Jun 23, 2025 • 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!

t-inu commented Jul 13, 2025

Uh oh!

michellengnx commented Aug 1, 2025

Uh oh!

macsko commented Aug 6, 2025

Uh oh!

natalisucks commented Aug 6, 2025

Uh oh!

k8s-ci-robot commented Aug 6, 2025

Uh oh!

k8s-ci-robot commented Aug 6, 2025

Uh oh!

Uh oh!

netlify bot commented May 30, 2025 •

edited

Loading

netlify bot commented May 30, 2025 •

edited

Loading

mochizuki875 Jun 23, 2025 •

edited

Loading

sanposhiho Jun 23, 2025 •

edited

Loading