Improve Lease concept (#38307)

* Improve Lease concept

* Write “heartbeat” consistently

(within Lease concept page).

Author: Tim Bannister

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

@@ -6,30 +6,32 @@ weight: 30
 
 <!-- overview -->
 
-Distributed systems often have a need for "leases", which provides a mechanism to lock shared resources and coordinate activity between nodes.
-In Kubernetes, the "lease" concept is represented by `Lease` objects in the `coordination.k8s.io` API group, which are used for system-critical
-capabilities like node heart beats and component-level leader election.
+Distributed systems often have a need for _leases_, which provide a mechanism to lock shared resources
+and coordinate activity between members of a set.
+In Kubernetes, the lease concept is represented by [Lease](/docs/reference/kubernetes-api/cluster-resources/lease-v1/)
+objects in the `coordination.k8s.io` {{< glossary_tooltip text="API Group" term_id="api-group" >}},
+which are used for system-critical capabilities such as node heartbeats and component-level leader election.
 
 <!-- body -->
 
-## Node Heart Beats
+## Node heartbeats {#node-heart-beats}
 
-Kubernetes uses the Lease API to communicate kubelet node heart beats to the Kubernetes API server.
+Kubernetes uses the Lease API to communicate kubelet node heartbeats to the Kubernetes API server.
 For every `Node` , there is a `Lease` object with a matching name in the `kube-node-lease`
-namespace. Under the hood, every kubelet heart beat is an UPDATE request to this `Lease` object, updating
+namespace. Under the hood, every kubelet heartbeat is an **update** request to this `Lease` object, updating
 the `spec.renewTime` field for the Lease. The Kubernetes control plane uses the time stamp of this field
 to determine the availability of this `Node`.
 
 See [Node Lease objects](/docs/concepts/architecture/nodes/#heartbeats) for more details.
 
-## Leader Election
+## Leader election
 
-Leases are also used in Kubernetes to ensure only one instance of a component is running at any given time.
+Kubernetes also uses Leases to ensure only one instance of a component is running at any given time.
 This is used by control plane components like `kube-controller-manager` and `kube-scheduler` in
 HA configurations, where only one instance of the component should be actively running while the other
 instances are on stand-by.
 
-## API Server Identity
+## API server identity
 
 {{< feature-state for_k8s_version="v1.26" state="beta" >}}
 
@@ -43,22 +45,23 @@ You can inspect Leases owned by each kube-apiserver by checking for lease object
 with the name `kube-apiserver-<sha256-hash>`. Alternatively you can use the label selector `k8s.io/component=kube-apiserver`:
 
 ```shell
-$ kubectl -n kube-system get lease -l k8s.io/component=kube-apiserver
+kubectl -n kube-system get lease -l k8s.io/component=kube-apiserver
+```
+```
 NAME                                        HOLDER                                                                           AGE
 kube-apiserver-c4vwjftbvpc5os2vvzle4qg27a   kube-apiserver-c4vwjftbvpc5os2vvzle4qg27a_9cbf54e5-1136-44bd-8f9a-1dcd15c346b4   5m33s
 kube-apiserver-dz2dqprdpsgnm756t5rnov7yka   kube-apiserver-dz2dqprdpsgnm756t5rnov7yka_84f2a85d-37c1-4b14-b6b9-603e62e4896f   4m23s
 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
+The SHA256 hash used in the lease name is based on the OS hostname as seen by that API server. 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
+will take over existing Leases using a new holder identity, as opposed to instantiating new Lease objects. You can check the
 hostname used by kube-apisever by checking the value of the `kubernetes.io/hostname` label:
 
 ```shell
-$ kubectl -n kube-system get lease kube-apiserver-c4vwjftbvpc5os2vvzle4qg27a -o yaml
+kubectl -n kube-system get lease kube-apiserver-c4vwjftbvpc5os2vvzle4qg27a -o yaml
 ```
-
 ```yaml
 apiVersion: coordination.k8s.io/v1
 kind: Lease
@@ -78,3 +81,23 @@ spec:
 ```
 
 Expired leases from kube-apiservers that no longer exist are garbage collected by new kube-apiservers after 1 hour.
+
+You can disable API server identity leases by disabling the `APIServerIdentity`
+[feature gate](/docs/reference/command-line-tools-reference/feature-gates/).
+
+## Workloads {#custom-workload}
+
+Your own workload can define its own use of Leases. For example, you might run a custom
+{{< glossary_tooltip term_id="controller" text="controller" >}} where a primary or leader member
+performs operations that its peers do not. You define a Lease so that the controller replicas can select
+or elect a leader, using the Kubernetes API for coordination.
+If you do use a Lease, it's a good practice to define a name for the Lease that is obviously linked to
+the product or component. For example, if you have a component named Example Foo, use a Lease named
+`example-foo`.
+
+If a cluster operator or another end user could deploy multiple instances of a component, select a name
+prefix and pick a mechanism (such as hash of the name of the Deployment) to avoid name collisions
+for the Leases.
+
+You can use another approach so long as it achieves the same outcome: different software products do
+not conflict with one another.

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

@@ -274,7 +274,7 @@ availability of each node, and to take action when failures are detected.
 For nodes there are two forms of heartbeats:
 
 * updates to the `.status` of a Node
-* [Lease](/docs/reference/kubernetes-api/cluster-resources/lease-v1/) objects
+* [Lease](/docs/concepts/architecture/leases/) objects
   within the `kube-node-lease`
   {{< glossary_tooltip term_id="namespace" text="namespace">}}.
   Each Node has an associated Lease object.

content/en/docs/concepts/overview/working-with-objects/namespaces.md

@@ -44,7 +44,7 @@ Kubernetes starts with four initial namespaces:
 : Kubernetes includes this namespace so that you can start using your new cluster without first creating a namespace.
 
 `kube-node-lease`
-: This namespace holds [Lease](/docs/reference/kubernetes-api/cluster-resources/lease-v1/) objects associated with each node. Node leases allow the kubelet to send [heartbeats](/docs/concepts/architecture/nodes/#heartbeats) so that the control plane can detect node failure.
+: This namespace holds [Lease](/docs/concepts/architecture/leases/) objects associated with each node. Node leases allow the kubelet to send [heartbeats](/docs/concepts/architecture/nodes/#heartbeats) so that the control plane can detect node failure.
 
 `kube-public`
 : This namespace is readable by *all* clients (including those not authenticated). This namespace is mostly reserved for cluster usage, in case that some resources should be visible and readable publicly throughout the whole cluster. The public aspect of this namespace is only a convention, not a requirement.

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

@@ -383,7 +383,7 @@ Each feature gate is designed for enabling/disabling a specific feature:
   to see the requesting subject's authentication information.
   See [API access to authentication information for a client](/docs/reference/access-authn-authz/authentication/#self-subject-review)
   for more details.
-- `APIServerIdentity`: Assign each API server an ID in a cluster.
+- `APIServerIdentity`: Assign each API server an ID in a cluster, using a [Lease](/docs/concepts/architecture/leases).
 - `APIServerTracing`: Add support for distributed tracing in the API server.
   See [Traces for Kubernetes System Components](/docs/concepts/cluster-administration/system-traces) for more details.
 - `AdvancedAuditing`: Enable [advanced auditing](/docs/tasks/debug/debug-cluster/audit/#advanced-audit)