KEP-3453 to GA

[danwinship]

(The fact that it looks like we missed adding a Beta feature-gates line for 1.27 is an artifact of the current state of the dev-1.28 branch. The line exists in main.)

[tengqm]

/approve

Not sure if we want to merge this because the 'dev-1.28' is not well sync'ed with 'main'.
/hold

Feel free to lift the hold if the potential conflict is not a big issue.

[sftim]

This might well need a rewrite: I'm assuming that the feature gate is going to be GA and locked to true, so “defaults to” isn't correct any more.

[sftim]

The sense could change here; for example:

##### Legacy `minSyncPeriod` configuration in `iptables` mode {#minimize-iptables-restore}

Also, consider moving this into or after the minSyncPeriod section.

[sftim]

Perhaps this heading isn't needed at all?

[danwinship]

updated... I still don't have a good sense of how we refer to different versions in the docs. (I feel like we should say "kube-proxy 1.28 and later do X" but it seems like the preferred style is to always talk about currentVersion instead?)

Current subsection order is

#### Optimizing iptables mode performance
##### `minSyncPeriod`
##### Updating legacy `minSyncPeriod` configuration {#minimize-iptables-restore}
##### `syncPeriod`

And I feel like maybe the "Updating" section breaks the flow? But it doesn't seem like it fits after syncPeriod either. And putting syncPeriod first also feels wrong since the minSyncPeriod section is more important.

Maybe it could be "minSyncPeriod, syncPeriod, Updating legacy config", ane the part in the syncPeriod section about "in the past, it was sometimes useful to set [syncPeriod] to a very large value (eg, 1h). This is no longer recommended" could be moved to the "legacy config" section?

[sftim]

I still don't have a good sense of how we refer to different versions in the docs. (I feel like we should say "kube-proxy 1.28 and later do X" but it seems like the preferred style is to always talk about currentVersion instead?)

If we can, we write wording that will still feel relevant even 5 minor releases later. So we avoid phrases like “new implementation” or “has graduated to GA”. The best way to achieve that timelessness depends on what we want to say.

Watch out for one thing though. Any time we say “foo 1.28 and later”, consider if any future minor release might make this previously true statement false. Maybe, in that scenario, you can reword to make that problem case less likely?

[sftim]

Do we even need an “Optimizing iptables mode performance” section in the v1.28 docs? We can instead suggest that if people are running an older version, to read the docs for that version as there are some important hints.

[tengqm]

updated... I still don't have a good sense of how we refer to different versions in the docs. (I feel like we should say "kube-proxy 1.28 and later do X" but it seems like the preferred style is to always talk about currentVersion instead?)

I'm more inclined to explicitly call out the specific version when we mention something added/removed/changed. Users can get a good sense of when the change was introduced. Switching this to the skew shortcode may cause some confusion. A change introduced in 1.24 may smell something new. As a project that has 3 releases each year, Kubernetes users really need to know whether a feature has been there for "a long time".

Later on, say two years from now, our attitude towards this change will be different. The "something" has become so stable and well understood that no one cares when it was introduced. We will remove the mention "kube-proxy 1.24 and later on". On the contrary, if we use the skew shortcode, we won't be confident whether that shortcode can be removed. It will read as "kube-proxy 1.33 blah blah", "kubernetes 1.34 blah blah...". It will become very difficult to know how old that change is.

The skew shortcode does have an important use case, which is for referencing the source code, the release, the generated API reference etc. But attempting to use it everywhere doesn't sound to me like the right thing to do.

[sftim]

How about this? It's not ideal but maybe it's better.

[danwinship]

updated

[danwinship]

/hold cancel
sorry, this has been ready to go for a while but I didn't notice it was marked /hold

[sftim]

/hold
pending merge of #41720 (or its replacement)

[danwinship]

/hold cancel
rebased (no changes)

[Rishit-dagli]

nit: changing the status of this KEP to "Docs PR Ready for review" in the board

[kbhawkey]

@danwinship
Is this PR ready to merge?

[danwinship]

yes

[kbhawkey]

/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: kbhawkey, tengqm

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/OWNERS [kbhawkey,tengqm]

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

[kbhawkey]

/lgtm

[k8s-ci-robot]

LGTM label has been added.

Git tree hash: 0b797469d61e2ec2ba1e3cc4d6c02a5066173fa3