fix: Update shoot management guide due to new cert-based kubeconfigs

After introducing Kubernetes 1.27, shoot clusters with Kubernetes
1.26 and beyond will use certificate-based kubeconfig files. We
explain the difference between "old" static kubeconfigs and new
certificate-based ones, and we show how to issue and use them
regardless of the Kubernetes version our shoot cluster uses. Then,
we explain how to rotate static or certificate-based kubeconfigs.

docs/howto/kubernetes/gardener/kubectl.md

@@ -3,40 +3,65 @@ description: How to fetch, verify, and use your kubeconfig with kubectl.
 ---
 # Managing a Kubernetes cluster
 
-Once you [have launched a new cluster](create-shoot-cluster.md), you can interact with it using `kubectl` and a [kubeconfig](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) file.
+Once you [have launched a new cluster](create-shoot-cluster.md), you can interact with it using `kubectl` with a [kubeconfig](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig) file.
 
 ## Prerequisites
 
-You must install the Kubernetes command line tool, `kubectl`, on your local computer, and run commands against your cluster.
-To install `kubectl`, follow [the relevant Kubernetes documentation](https://kubernetes.io/docs/tasks/tools/#kubectl).
+You should install `kubectl`, the Kubernetes command line tool, on your local computer.
+Then, you will be able to issue commands against your clusters.
+To install `kubectl`, follow [the official documentation](https://kubernetes.io/docs/tasks/tools/#kubectl).
 
 ## Extracting the kubeconfig file
 
-Click on the cluster to expand its properties, and open *KubeConfig*.
-
-![KubeConfig tab in {{k8s_management_service}} Shoot view](assets/shoot_kubeconfig.png)
-
-Click the blue button labeled *Download KubeConfig*. Almost
-instantaneously, in the default download folder of your computer, you
-will get a configuration file with a name similar to
-`kubeconfig--<cluster_name>--<region_name>--<project_id>.yaml`. Create a
-directory named `.kube` in your local user's home, then move the YAML
-file you downloaded into it. Rename the YAML to `config`, ending up with
-`~/.kube/config`.
-
-> By default, `kubectl` searches for its configuration in
-> `~/.kube/config`, but you can [modify this
-> behavior](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/)
-> by setting the `KUBECONFIG` environment variable, if needed. For
-> example, if you want to retain the original filename as downloaded,
-> you might use:
->
-> ```bash
-> export KUBECONFIG=~/.kube/kubeconfig--<cluster_name>--<region_name>--<project_id>.yaml
-> ```
->
-> You may prefer this approach if you manage multiple Kubernetes
-> clusters.
+To access your shoot cluster, choose between a *static* and a *certificate-based* kubeconfig file.
+
+* A **static** kubeconfig contains a [static token](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#static-token-file), provides `cluster-admin` privileges to the corresponding shoot cluster, and never expires.
+In {{brand}}, up until and including Kubernetes 1.25, you can generate a static kubeconfig for your shoot cluster.
+
+* A **certificate-based** kubeconfig is valid for a predefined amount of time, during which it can be used for accessing the corresponding shoot cluster with `cluster-admin` privileges.
+The credentials associated with this type of kubeconfig are client certificates with time-limited validity.
+Beginning with Kubernetes version 1.27, you can issue certificate-based kubeconfig files only.
+This will also be the case for shoot clusters based on Kubernetes 1.26.
+
+To get a kubeconfig file for a shoot cluster, in the {{gui}} click on the cluster row to expand its properties and go to the *KubeConfig* tab.
+
+=== "Static kubeconfig"
+    ![KubeConfig tab in {{k8s_management_service}} Shoot view](assets/shoot_kubeconfig.png)
+=== "Certificate-based kubeconfig"
+    Notice that you may set the duration of the kubeconfig file validity.
+
+    ![KubeConfig tab in {{k8s_management_service}} Shoot view](assets/shoot_kubeconfig_cert_01.png)
+
+    The default validity period is one hour, but you may use the drop-down menu to select a different duration.
+
+    ![Select a validity period for kubeconfig](assets/shoot_kubeconfig_cert_02.png)
+
+    When satisfied with the duration, click the green button labeled *Generate config*.
+
+    ![Generate a certificate-based kubeconfig](assets/shoot_kubeconfig_cert_03.png)
+
+    Right below, you will see the contents of your dynamically generated kubeconfig.
+
+    ![Download the newly generated kubeconfig](assets/shoot_kubeconfig_cert_04.png)
+
+To download your kubeconfig, just click the blue button labeled *Download KubeConfig*.
+Almost instantaneously, in the default download folder of your local user account, you will get a configuration file named like so:
+
+```plain
+kubeconfig--<cluster_name>--<region_name>--<project_id>.yaml
+```
+
+Create a directory named `.kube` in your local user's home, then move the YAML file you downloaded into it.
+Rename the YAML to `config`, ending up with `~/.kube/config`.
+By default, `kubectl` searches for its configuration in `~/.kube/config`.
+If necessary, you can [modify this behavior](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig) by setting the `KUBECONFIG` environment variable.
+For example, if you want to retain the original filename exactly as downloaded, you will type something like the following:
+
+```shell
+export KUBECONFIG=~/.kube/kubeconfig--<cluster_name>--<region_name>--<project_id>.yaml
+```
+
+If you manage multiple Kubernetes clusters, you will probably prefer this approach.
 
 ## Verifying your kubeconfig
 
@@ -118,3 +143,38 @@ kubernetes   ClusterIP      100.64.0.1      <none>          443/TCP          3h4
 
 Open a browser to `http://198.51.100.42:8080` (substituting the correct `EXTERNAL-IP` listed for your service).
 You should see the page of the Hello World app.
+
+## Rotating kubeconfig
+
+Whether using a certificate-based kubeconfig file or not, you can rotate it for a fresh one.
+Since certificate-based kubeconfig files have time-bound validity anyway, rotation is standard practice.
+It is also highly recommended to rotate static kubeconfig files periodically;
+even though they never expire, this very fact deems them less secure than certificate-based ones.
+
+In any case, you can rotate an existing kubeconfig using the {{gui}}.
+
+=== "Static kubeconfig"
+    Go to the shoot cluster you want.
+    Click the orange circular :fontawesome-solid-ellipsis: icon at the right-hand side of the cluster row.
+
+    ![Select a validity period for kubeconfig](assets/kubeconfig_static_rotate_01.png)
+
+    Select the *Rotate Kubeconfig* option from the menu that immediately appears.
+
+    ![Select a validity period for kubeconfig](assets/kubeconfig_static_rotate_02.png)
+
+    A window pops up notifying you that the new kubeconfig will have a fresh authentication token, and during the creation of the new kubeconfig, the existing one you might still be using will stop working.
+    When you are ready, click the red *Yes, Rotate kubeconfig* button.
+
+    ![Select a validity period for kubeconfig](assets/kubeconfig_static_rotate_03.png)
+
+    The creation of the new kubeconfig starts, and the whole process might take a minute or two to complete.
+    During that time, you will notice an animated red circular progress indicator at the left-hand side of the cluster row.
+
+    ![Select a validity period for kubeconfig](assets/kubeconfig_static_rotate_04.png)
+
+    When the new kubeconfig is ready, click the blue *Download KubeConfig* button to download it.
+
+    ![Select a validity period for kubeconfig](assets/kubeconfig_static_rotate_05.png)
+=== "Certificate-based kubeconfig"
+    pqrxyz