Leases [page]deterministic

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` [API Group](#gloss:api-group), which are used for system-critical capabilities such as node heartbeats and component-level leader election.

## Node heartbeats {#node-heart-beats}

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 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/#node-heartbeats) for more details.

## Leader election

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.

Read [coordinated leader election](/docs/concepts/cluster-administration/coordinated-leader-election) to learn about how Kubernetes builds on the Lease API to select which component instance acts as leader.

### Kube controller manager lock release on exit

When the `ControllerManagerReleaseLeaderElectionLockOnExit` feature gate is enabled, the `kube-controller-manager` actively releases its leader election lock during leader transitions, rather than waiting for the lock's TTL to expire. This allows a new leader to be elected more quickly, reducing leader transition latency.

## API server identity

Starting in Kubernetes v1.26, each `kube-apiserver` uses the Lease API to publish its identity to the rest of the system. While not particularly useful on its own, this provides a mechanism for clients to 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 with the name `apiserver-<sha256-hash>`. Alternatively you can use the label selector `apiserver.kubernetes.io/identity=kube-apiserver`:

```shell kubectl -n kube-system get lease -l apiserver.kubernetes.io/identity=kube-apiserver ``` ``` NAME HOLDER AGE apiserver-07a5ea9b9b072c4a5f3d1c3702 apiserver-07a5ea9b9b072c4a5f3d1c3702_0c8914f7-0f35-440e-8676-7844977d3a05 5m33s apiserver-7be9e061c59d368b3ddaf1376e apiserver-7be9e061c59d368b3ddaf1376e_84f2a85d-37c1-4b14-b6b9-603e62e4896f 4m23s apiserver-1dfef752bcb36637d2763d1868 apiserver-1dfef752bcb36637d2763d1868_c5ffa286-8a9a-45d4-91e7-61118ed58d2e 4m43s

```

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 hostname used by kube-apiserver by checking the value of the `kubernetes.io/hostname` label:

```shell kubectl -n kube-system get lease apiserver-07a5ea9b9b072c4a5f3d1c3702 -o yaml ``` ```yaml apiVersion: coordination.k8s.io/v1 kind: Lease metadata: creationTimestamp: "2023-07-02T13:16:48Z" labels: apiserver.kubernete …(trimmed)