document kube-apiserver identity

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

@@ -53,6 +53,7 @@ different Kubernetes components.
 | `APIListChunking` | `true` | Beta | 1.9 | |
 | `APIPriorityAndFairness` | `false` | Alpha | 1.17 | |
 | `APIResponseCompression` | `false` | Alpha | 1.7 | |
+| `APIServerIdentity` | `false` | Alpha | 1.20 | |
 | `AppArmor` | `true` | Beta | 1.4 | |
 | `BalanceAttachedNodeVolumes` | `false` | Alpha | 1.11 | |
 | `BoundServiceAccountTokenVolume` | `false` | Alpha | 1.13 | |
@@ -150,6 +151,7 @@ different Kubernetes components.
 | `ServiceTopology` | `false` | Alpha | 1.17 | |
 | `SetHostnameAsFQDN` | `false` | Alpha | 1.19 | 1.19 |
 | `SetHostnameAsFQDN` | `true` | Beta | 1.20 | |
+| `StorageVersionAPI` | `false` | Alpha | 1.20 | |
 | `StorageVersionHash` | `false` | Alpha | 1.14 | 1.14 |
 | `StorageVersionHash` | `true` | Beta | 1.15 | |
 | `Sysctls` | `true` | Beta | 1.11 | |
@@ -379,6 +381,7 @@ Each feature gate is designed for enabling/disabling a specific feature:
 - `APIListChunking`: Enable the API clients to retrieve (`LIST` or `GET`) resources from API server in chunks.
 - `APIPriorityAndFairness`: Enable managing request concurrency with prioritization and fairness at each server. (Renamed from `RequestManagement`)
 - `APIResponseCompression`: Compress the API responses for `LIST` or `GET` requests.
+- `APIServerIdentity`: Assign each kube-apiserver an ID in a cluster.
 - `AppArmor`: Enable AppArmor based mandatory access control on Linux nodes when using Docker.
    See [AppArmor Tutorial](/docs/tutorials/clusters/apparmor/) for more details.
 - `AttachVolumeLimit`: Enable volume plugins to report limits on number of volumes
@@ -531,6 +534,7 @@ Each feature gate is designed for enabling/disabling a specific feature:
 - `StartupProbe`: Enable the [startup](/docs/concepts/workloads/pods/pod-lifecycle/#when-should-you-use-a-startup-probe) probe in the kubelet.
 - `StorageObjectInUseProtection`: Postpone the deletion of PersistentVolume or
   PersistentVolumeClaim objects if they are still being used.
+- `StorageVersionAPI`: Enable the storage version API.
 - `StorageVersionHash`: Allow apiservers to expose the storage version hash in the discovery.
 - `StreamingProxyRedirects`: Instructs the API server to intercept (and follow)
    redirects from the backend (kubelet) for streaming requests.

content/en/docs/tasks/administer-cluster/highly-available-master.md

@@ -170,6 +170,33 @@ to access a replica via its ephemeral public IP, you must skip TLS verification.
 To allow etcd clustering, ports needed to communicate between etcd instances will be opened (for inside cluster communication).
 To make such deployment secure, communication between etcd instances is authorized using SSL.
 
+### API server identity
+
+{{< feature-state state="alpha"  for_k8s_version="v1.20" >}}
+
+The API Server Identity feature is controlled by a
+[feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
+and is not enabled by default. You can activate API Server Identity by enabling
+the feature gate named `APIServerIdentity` when you start the
+{{< glossary_tooltip text="API Server" term_id="kube-apiserver" >}}:
+
+```shell
+kube-apiserver \
+--feature-gates=APIServerIdentity=true \
+ # …and other flags as usual
+```
+
+During bootstrap, each kube-apiserver assigns a unique ID to itself. The ID is
+in the format of `kube-apiserver-{UUID}`. Each kube-apiserver creates a
+[Lease](/docs/reference/generated/kubernetes-api/{{< param "version" >}}//#lease-v1-coordination-k8s-io)
+in the _kube-system_ {{< glossary_tooltip text="namespaces" term_id="namespace">}}.
+The Lease name is the unique ID for the kube-apiserver. The Lease contains a
+label `k8s.io/component=kube-apiserver`. Each kube-apiserver manages deleting
+identity leases for kube-apiservers that are gone.
+
+Enabling this feature is a prerequisite for using features that involve HA API
+server coodination (e.g. the StorageVersion API feature).
+
 ## Additional reading
 
 [Automated HA master deployment - design doc](https://git.k8s.io/community/contributors/design-proposals/cluster-lifecycle/ha_master.md)