kep-1965: update doc references for APIServerIdentity #37921

andrewsykim · 2022-11-16T02:20:08Z

Signed-off-by: Andrew Sy Kim [email protected]

Update feature gate reference for APIServerIdentity. Currently on the fence about whether we want more comprehensive documentation for this feature. In it's current state it is mainly going to be used for internal optimizations (i.e. StorageVersion API) and likely won't see too much use from users.

netlify · 2022-11-16T02:20:13Z

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

Name	Link
🔨 Latest commit	`991a4a3`
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-vnext-staging/deploys/6386bca035048f0009ad537e

sftim · 2022-11-16T04:05:48Z

I recommend adding a short, simple page inside https://kubernetes.io/docs/concepts/overview/working-with-objects/: https://kubernetes.io/docs/concepts/architecture/leases/

In that page, outline what a Lease is and where Kubernetes uses them.

andrewsykim · 2022-11-16T04:36:52Z

I recommend adding a short, simple page inside https://kubernetes.io/docs/concepts/overview/working-with-objects/: https://kubernetes.io/docs/concepts/architecture/leases/

In that page, outline what a Lease is and where Kubernetes uses them.

I agree this would be useful, but admittedly also going outside the scope of this KEP to write general documentation about Leases. I will try to find the time to work on this but no promises :)

sftim · 2022-11-16T08:39:37Z

Second-mover disadvantage: the SIG that makes the general API gets to write up specific, whereas making good use of the existing API means the new documentation only makes sense following a tidying and reorganization.

For GA, we'll want the docs about API server identity leases to have a home somewhere (and not just in the list of former feature gates). Optional but also recommened: revise pages within https://kubernetes.io/docs/tasks/debug/debug-cluster/

andrewsykim · 2022-11-17T01:15:25Z

I think general documentation about Leases and their uses (kube-apiserver identtiy being one of many) would be good to have, and I am happy to try to work on it during regular development cycle. I just don't have time to work on this right now.

content/en/docs/reference/command-line-tools-reference/feature-gates.md

krol3 · 2022-11-28T01:17:42Z

Hi @andrewsykim! This PR needs a doc review by Mon Nov 28th to get this into the release. Please reach out to required SIGs to get their review. Thank you!

sftim

As well as documenting the feature gate, please document how Kubernetes behaves when this is enabled. A few lines may be enough; zero documentation is not sufficient.

See #37921 (comment)

sftim · 2022-11-28T10:37:26Z

content/en/docs/reference/command-line-tools-reference/feature-gates.md

@@ -62,7 +62,8 @@ For a reference to old feature gates that are removed, please refer to
 | `APIPriorityAndFairness` | `true` | Beta | 1.20 | |
 | `APIResponseCompression` | `false` | Alpha | 1.7 | 1.15 |
 | `APIResponseCompression` | `true` | Beta | 1.16 | |
-| `APIServerIdentity` | `false` | Alpha | 1.20 | |
+| `APIServerIdentity` | `false` | Alpha | 1.20 | 1.26 |


leonardpahlke · 2022-11-28T11:33:11Z

x posting my slack comment

I agree, the PR does not add sufficient documentation just yet.

About the PR comment:

(@andrewsykim) I agree this would be useful, but admittedly also going outside the scope of this KEP to write general documentation about Leases.

Seems to me like a bit like an ownership issue, who “bootstraps general docs”. Perhaps we have missed to introduce the documentation page a while back?
I am +1 adding the documentation & suggestions @sftim mentioned now.

sftim · 2022-11-28T11:51:28Z

@andrewsykim if you write the text for the APIServerIdentity part, SIG Docs can write up any generic text that the new bit needs in order to have context.

enj · 2022-11-28T17:12:22Z

/assign @enj

enj · 2022-11-28T17:13:27Z

/assign @ritazh @aramase

andrewsykim · 2022-11-29T17:17:02Z

@andrewsykim if you write the text for the APIServerIdentity part, SIG Docs can write up any generic text that the new bit needs in order to have context.

ack, will add this later today

Signed-off-by: Andrew Sy Kim <[email protected]>

andrewsykim · 2022-11-30T02:17:05Z

I added some general docs for Leases, PTAL.

Docs definitely can use more details, but trying to be mindful of the docs deadline today. Definitely needs to be a follow-up to add more content in this area.

sftim

LGTM for docs

I don't think this needs tech review; I can see that these pages look right enough.

/lgtm
/approve

sftim · 2022-11-30T09:39:28Z

content/en/docs/concepts/architecture/leases.md

+HA configurations, where only one instance of the component should be actively running while the other
+instances are on stand-by.
+
+## kube-apiserver identity


Suggested change

## kube-apiserver identity

## API Server identity

k8s-ci-robot · 2022-11-30T09:39:40Z

LGTM label has been added.

Git tree hash: 73b37c1dbd940030dd9a766297af49747b756ba4

k8s-ci-robot · 2022-11-30T09:39:50Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: sftim

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~~ [sftim]

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

sftim · 2022-11-30T09:40:42Z

After the release, we can track an issue to mention that workloads / out-of-tree things are also welcome to use Leases (especially controllers and operators).

enj · 2022-11-30T14:33:40Z

content/en/docs/concepts/architecture/leases.md

+
+{{< feature-state for_k8s_version="v1.26" state="beta" >}}
+
+Starting in Kubernetes v1.26, each `kube-apiserver` uses the Lease API to publish its identity to the


Should we provide more details on the specifics here? Like if I want to build an external integration that uses this information, how would I know what to look for?

More detail is good. IMO we don't need that for beta.

Added more details in #38196

k8s-ci-robot added this to the 1.26 milestone Nov 16, 2022

k8s-ci-robot 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. labels Nov 16, 2022

k8s-ci-robot requested review from jimangel and sftim November 16, 2022 02:20

k8s-ci-robot added language/en Issues or PRs related to English language sig/docs Categorizes an issue or PR as relevant to SIG Docs. size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. labels Nov 16, 2022

andrewsykim mentioned this pull request Nov 16, 2022

kube-apiserver identity kubernetes/enhancements#1965

Open

andrewsykim commented Nov 17, 2022

View reviewed changes

content/en/docs/reference/command-line-tools-reference/feature-gates.md Show resolved Hide resolved

andrewsykim changed the title ~~[WIP] kep-1965: update doc references for APIServerIdentity~~ kep-1965: update doc references for APIServerIdentity Nov 17, 2022

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 Nov 17, 2022

sftim reviewed Nov 28, 2022

View reviewed changes

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 28, 2022

k8s-ci-robot assigned enj Nov 28, 2022

k8s-ci-robot assigned aramase and ritazh Nov 28, 2022

andrewsykim force-pushed the kep-1965 branch from 21b0c0a to b2cb7ee Compare November 30, 2022 01:21

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 30, 2022

kep-1965: update doc references for APIServerIdentity

26d8ad4

Signed-off-by: Andrew Sy Kim <[email protected]>

andrewsykim force-pushed the kep-1965 branch from b2cb7ee to 26d8ad4 Compare November 30, 2022 01:21

k8s-ci-robot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. labels Nov 30, 2022

add general docs for leases

991a4a3

Signed-off-by: Andrew Sy Kim <[email protected]>

andrewsykim force-pushed the kep-1965 branch from 68f5b10 to 991a4a3 Compare November 30, 2022 02:14

sftim reviewed Nov 30, 2022

View reviewed changes

k8s-ci-robot assigned sftim Nov 30, 2022

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

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Nov 30, 2022

k8s-ci-robot merged commit 0ac0f16 into kubernetes:dev-1.26 Nov 30, 2022

enj reviewed Nov 30, 2022

View reviewed changes

andrewsykim mentioned this pull request Nov 30, 2022

leases: add more details on API Server Identity #38196

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

kep-1965: update doc references for APIServerIdentity #37921

kep-1965: update doc references for APIServerIdentity #37921

andrewsykim commented Nov 16, 2022

netlify bot commented Nov 16, 2022 •

edited

Loading

sftim commented Nov 16, 2022

andrewsykim commented Nov 16, 2022

sftim commented Nov 16, 2022

andrewsykim commented Nov 17, 2022

krol3 commented Nov 28, 2022

sftim left a comment

sftim Nov 28, 2022

leonardpahlke commented Nov 28, 2022

sftim commented Nov 28, 2022

enj commented Nov 28, 2022

enj commented Nov 28, 2022

andrewsykim commented Nov 29, 2022

andrewsykim commented Nov 30, 2022

sftim left a comment

sftim Nov 30, 2022

k8s-ci-robot commented Nov 30, 2022

k8s-ci-robot commented Nov 30, 2022

sftim commented Nov 30, 2022

enj Nov 30, 2022

sftim Nov 30, 2022

andrewsykim Nov 30, 2022

	\| `APIServerIdentity` \| `false` \| Alpha \| 1.20 \| 1.26 \|
	\| `APIServerIdentity` \| `false` \| Alpha \| 1.20 \| 1.25 \|


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

		Starting in Kubernetes v1.26, each `kube-apiserver` uses the Lease API to publish its identity to the

kep-1965: update doc references for APIServerIdentity #37921

kep-1965: update doc references for APIServerIdentity #37921

Conversation

andrewsykim commented Nov 16, 2022

netlify bot commented Nov 16, 2022 • edited Loading

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

sftim commented Nov 16, 2022

andrewsykim commented Nov 16, 2022

sftim commented Nov 16, 2022

andrewsykim commented Nov 17, 2022

krol3 commented Nov 28, 2022

sftim left a comment

Choose a reason for hiding this comment

sftim Nov 28, 2022

Choose a reason for hiding this comment

leonardpahlke commented Nov 28, 2022

sftim commented Nov 28, 2022

enj commented Nov 28, 2022

enj commented Nov 28, 2022

andrewsykim commented Nov 29, 2022

andrewsykim commented Nov 30, 2022

sftim left a comment

Choose a reason for hiding this comment

sftim Nov 30, 2022

Choose a reason for hiding this comment

k8s-ci-robot commented Nov 30, 2022

k8s-ci-robot commented Nov 30, 2022

sftim commented Nov 30, 2022

enj Nov 30, 2022

Choose a reason for hiding this comment

sftim Nov 30, 2022

Choose a reason for hiding this comment

andrewsykim Nov 30, 2022

Choose a reason for hiding this comment

netlify bot commented Nov 16, 2022 •

edited

Loading