leases: add more details on API Server Identity #38196

andrewsykim · 2022-11-30T15:45:28Z

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

netlify · 2022-11-30T15:45:33Z

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

Name	Link
🔨 Latest commit	`917dee9`
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-vnext-staging/deploys/6387a1649dea6a0008ee4213

andrewsykim · 2022-11-30T15:45:48Z

/assign @mo @sftim

k8s-ci-robot · 2022-11-30T15:45:51Z

@andrewsykim: GitHub didn't allow me to assign the following users: mo.

Note that only kubernetes members with read permissions, repo collaborators and people who have commented on this issue/PR can be assigned. Additionally, issues/PRs can only have 10 assignees at the same time.
For more information please see the contributor guide

In response to this:

/assign @mo @sftim

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/test-infra repository.

enj · 2022-11-30T16:01:26Z

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

+```
+
+The SHA256 hash used in the lease name is based on the OS hostname as seen by kube-apiserver. Each kube-apiserver should be
+configured to use a hostname that is unique within the cluster. New instances of kube-apiserver that use the same hostname


Can we document the use of the kubernetes.io/hostname label as well?

See #38196 (comment)

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

sftim · 2022-11-30T17:12:38Z

~~@enj would you be willing to propose those changes in a follow-up PR? I especially want the essentials to land, even as I also want this new page to see improvements.~~

Oops. This is the follow up PR!

sftim · 2022-11-30T17:13:26Z

We should get a tech review on this one.

enj · 2022-11-30T17:15:04Z

We should get a tech review on this one.

@deads2k and @lavalamp are good candidates here

enj

One minor nit.

enj · 2022-11-30T18:23:18Z

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

+```
+$ kubectl -n kube-system get lease kube-apiserver-c4vwjftbvpc5os2vvzle4qg27a -o yaml
+apiVersion: coordination.k8s.io/v1


Can you split this into two code blocks, one with shell syntax, the other with yaml syntax?

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

leonardpahlke · 2022-12-01T01:47:27Z

/cc @deads2k @lavalamp
PTAL, thanks!

deads2k · 2022-12-01T19:21:28Z

/lgtm

k8s-ci-robot · 2022-12-01T19:21:35Z

LGTM label has been added.

Git tree hash: 0d317e8f2d3291f5808b70ae78582ebba14fdca9

sftim

Some more feedback (see inline comments)

The label k8s.io/component is not registered. Please document it in https://kubernetes.io/docs/reference/labels-annotations-taints/

(if feasible: switch to using control-plane.kubernetes.io/component, before the v1.26 release, so that end users don't confuse it with the app.kubernetes.io/component label).

We can also release with this and then deprecate k8s.io/component in v1.27 but that's a bit of a shame to have to do.

Optionally, document what happens when an API server runs as a Pod (eg for nesting a control plane).

That might be best saved for a post-release blog for the release when this feature graduates to stable.

sftim · 2022-12-01T19:23:40Z

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

+$ kubectl -n kube-system get lease -l k8s.io/component=kube-apiserver
+NAME                                        HOLDER                                                                           AGE


Please split this - see don't include the command prompt and separate commands from output.

sftim · 2022-12-01T19:24:16Z

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

+kube-apiserver-fyloo45sdenffw2ugwaz3likua   kube-apiserver-fyloo45sdenffw2ugwaz3likua_c5ffa286-8a9a-45d4-91e7-61118ed58d2e   4m43s
+```
+
+The SHA256 hash used in the lease name is based on the OS hostname as seen by kube-apiserver. Each kube-apiserver should be


Which is true:

Suggested change

The SHA256 hash used in the lease name is based on the OS hostname as seen by kube-apiserver. Each kube-apiserver should be

The SHA256 hash used in the Lease name is based on the OS hostname as seen by kube-apiserver.

The API server coerces its hostname string to lowercase before hashing it. Each kube-apiserver

should be

or

Suggested change

The SHA256 hash used in the lease name is based on the OS hostname as seen by kube-apiserver. Each kube-apiserver should be

The SHA256 hash used in the Lease name is based on the OS hostname as seen by kube-apiserver.

Each kube-apiserver should be

?

sftim · 2022-12-01T19:25:58Z

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

+  creationTimestamp: "2022-11-30T15:37:15Z"
+  labels:
+    k8s.io/component: kube-apiserver
+    kubernetes.io/hostname: kind-control-plane


https://kubernetes.io/docs/reference/labels-annotations-taints/ lists that this label is used on Nodes (only)

Either:

fix the Kubernetes code not to label Leases with this official label

allowed, but a bit weird to make up a new one that is so similar

update https://kubernetes.io/docs/reference/labels-annotations-taints/ to record that it is also used for leases that are associated with nodes

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

sftim · 2022-12-01T19:31:02Z

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

+
+The SHA256 hash used in the lease name is based on the OS hostname as seen by kube-apiserver. Each kube-apiserver should be
+configured to use a hostname that is unique within the cluster. New instances of kube-apiserver that use the same hostname
+will take over existing Leases using a new holder identity, as opposed to instantiating new lease objects. You can check the


(nit)

Suggested change

will take over existing Leases using a new holder identity, as opposed to instantiating new lease objects. You can check the

will take over existing Leases using a new holder identity, as opposed to instantiating new Leases.

You can check the

sftim · 2022-12-01T19:32:36Z

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

+spec:
+  holderIdentity: kube-apiserver-c4vwjftbvpc5os2vvzle4qg27a_9cbf54e5-1136-44bd-8f9a-1dcd15c346b4
+  leaseDurationSeconds: 3600
+  renewTime: "2022-11-30T18:04:27.912073Z"


(nit) Ideally, pick a date that is close to the v1.26 release.

sftim · 2022-12-01T19:34:09Z

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

 discover how many instances of `kube-apiserver` are operating the Kubernetes control plane.
 Existence of kube-apiserver leases enables future capabilities that may require coordination between
 each kube-apiserver.


Suggested change

discover how many instances of `kube-apiserver` are operating the Kubernetes control plane.

Existence of kube-apiserver leases enables future capabilities that may require coordination between

each kube-apiserver.

The API server creates these leases in the `kube-system` namespace.

The existence of kube-apiserver Leases also enables adding future capabilities to Kubernetes,

that may require coordination between each kube-apiserver (for example, during cluster

upgrades).

sftim · 2022-12-01T19:34:28Z

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

@@ -38,3 +38,43 @@ rest of the system. While not particularly useful on its own, this provides a me
 discover how many instances of `kube-apiserver` are operating the Kubernetes control plane.
 Existence of kube-apiserver leases enables future capabilities that may require coordination between
 each kube-apiserver.
+
+You can inspect Leases owned by each kube-apiserver by checking for lease objects in the `kube-system` namespace


(nit)

Suggested change

You can inspect Leases owned by each kube-apiserver by checking for lease objects in the `kube-system` namespace

You can inspect Leases owned by each kube-apiserver by checking for Leases in the `kube-system` namespace

sftim · 2022-12-01T19:39:30Z

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

+apiVersion: coordination.k8s.io/v1
+kind: Lease
+metadata:
+  creationTimestamp: "2022-11-30T15:37:15Z"


(nit) Ideally, pick a date that is close to the v1.26 release.

sftim · 2022-12-01T19:39:56Z

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

+  renewTime: "2022-11-30T18:04:27.912073Z"
+```
+
+Expired leases from kube-apiservers that no longer exist are garbage collected by new kube-apiservers after 1 hour.


Is this right:

Suggested change

Expired leases from kube-apiservers that no longer exist are garbage collected by new kube-apiservers after 1 hour.

### API server Lease garbage collection

Expired Leases from kube-apiservers that no longer exist are garbage collected by live kube-apiservers.

The control plane leaves the expired Leases for at least one hour before removing them.

?

We should update https://kubernetes.io/docs/concepts/architecture/garbage-collection/ to link to that heading, which is why I added it.

sftim · 2022-12-05T21:53:11Z

Good enough for alpha, I reckon.

/approve

k8s-ci-robot · 2022-12-05T21:53:18Z

[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

enj · 2022-12-06T17:00:14Z

Good enough for alpha, I reckon.

Except the feature is beta 😂

sftim · 2022-12-06T17:29:27Z

More polish is welcome.

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

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

k8s-ci-robot requested review from bradtopol and kbhawkey November 30, 2022 15:45

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. labels Nov 30, 2022

andrewsykim mentioned this pull request Nov 30, 2022

kep-1965: update doc references for APIServerIdentity #37921

Merged

k8s-ci-robot added the size/S Denotes a PR that changes 10-29 lines, ignoring generated files. label Nov 30, 2022

k8s-ci-robot assigned sftim Nov 30, 2022

enj reviewed Nov 30, 2022

View reviewed changes

andrewsykim force-pushed the kep-1965 branch from 8eddedf to 4580cd5 Compare November 30, 2022 18:05

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

enj reviewed Nov 30, 2022

View reviewed changes

leases: add more details on API Server Identity

917dee9

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

andrewsykim force-pushed the kep-1965 branch from 4580cd5 to 917dee9 Compare November 30, 2022 18:30

k8s-ci-robot requested review from deads2k and lavalamp December 1, 2022 01:47

k8s-ci-robot assigned deads2k Dec 1, 2022

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

sftim reviewed Dec 1, 2022

View reviewed changes

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

k8s-ci-robot merged commit b5881a3 into kubernetes:dev-1.26 Dec 5, 2022

sftim mentioned this pull request Dec 6, 2022

Improve Lease concept #38307

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

leases: add more details on API Server Identity #38196

leases: add more details on API Server Identity #38196

andrewsykim commented Nov 30, 2022

netlify bot commented Nov 30, 2022 •

edited

Loading

andrewsykim commented Nov 30, 2022

k8s-ci-robot commented Nov 30, 2022

enj Nov 30, 2022

andrewsykim Nov 30, 2022

sftim Dec 1, 2022

sftim commented Nov 30, 2022 •

edited

Loading

sftim commented Nov 30, 2022

enj commented Nov 30, 2022

enj left a comment

enj Nov 30, 2022

andrewsykim Dec 1, 2022

leonardpahlke commented Dec 1, 2022

deads2k commented Dec 1, 2022

k8s-ci-robot commented Dec 1, 2022

sftim left a comment

sftim Dec 1, 2022

sftim Dec 1, 2022

sftim Dec 1, 2022

sftim Dec 1, 2022 •

edited

Loading

sftim Dec 1, 2022

sftim Dec 1, 2022

sftim Dec 1, 2022 •

edited

Loading

sftim Dec 1, 2022

sftim Dec 1, 2022

sftim commented Dec 5, 2022

k8s-ci-robot commented Dec 5, 2022

enj commented Dec 6, 2022

sftim commented Dec 6, 2022

		$ kubectl -n kube-system get lease -l k8s.io/component=kube-apiserver
		NAME HOLDER AGE

	The SHA256 hash used in the lease name is based on the OS hostname as seen by kube-apiserver. Each kube-apiserver should be
	The SHA256 hash used in the Lease name is based on the OS hostname as seen by kube-apiserver.
	Each kube-apiserver should be

	will take over existing Leases using a new holder identity, as opposed to instantiating new lease objects. You can check the
	will take over existing Leases using a new holder identity, as opposed to instantiating new Leases.
	You can check the

-discover how many instances of `kube-apiserver` are operating the Kubernetes control plane.
-Existence of kube-apiserver leases enables future capabilities that may require coordination between
-each kube-apiserver.
+The API server creates these leases in the `kube-system` namespace.
+The existence of kube-apiserver Leases also enables adding future capabilities to Kubernetes,
+that may require coordination between each kube-apiserver (for example, during cluster
+upgrades).

	You can inspect Leases owned by each kube-apiserver by checking for lease objects in the `kube-system` namespace
	You can inspect Leases owned by each kube-apiserver by checking for Leases in the `kube-system` namespace

-Expired leases from kube-apiservers that no longer exist are garbage collected by new kube-apiservers after 1 hour.
+### API server Lease garbage collection
+Expired Leases from kube-apiservers that no longer exist are garbage collected by live kube-apiservers.
+The control plane leaves the expired Leases for at least one hour before removing them.

leases: add more details on API Server Identity #38196

leases: add more details on API Server Identity #38196

Conversation

andrewsykim commented Nov 30, 2022

netlify bot commented Nov 30, 2022 • edited Loading

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

andrewsykim commented Nov 30, 2022

k8s-ci-robot commented Nov 30, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sftim commented Nov 30, 2022 • edited Loading

sftim commented Nov 30, 2022

enj commented Nov 30, 2022

enj left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

leonardpahlke commented Dec 1, 2022

deads2k commented Dec 1, 2022

k8s-ci-robot commented Dec 1, 2022

sftim left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sftim Dec 1, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sftim Dec 1, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sftim commented Dec 5, 2022

k8s-ci-robot commented Dec 5, 2022

enj commented Dec 6, 2022

sftim commented Dec 6, 2022

netlify bot commented Nov 30, 2022 •

edited

Loading

sftim commented Nov 30, 2022 •

edited

Loading

sftim Dec 1, 2022 •

edited

Loading

sftim Dec 1, 2022 •

edited

Loading