docs(kubeadm-upgrade): add consideration on etcd upgrade impact

relates to kubernetes/kubeadm#2991 (comment) Co-authored-by: Lubomir I. Ivanov <[email protected]> Signed-off-by: Clément Nussbaumer <[email protected]>
Andygol · Mar 12, 2024 · 6787093 · 6787093
1 parent 1afbed9
commit 6787093
Showing 1 changed file with 19 additions and 2 deletions.
diff --git a/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade.md b/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade.md
@@ -54,11 +54,28 @@ The upgrade workflow at high level is the following:
   with the purpose of reconfiguring the cluster is not recommended and can have unexpected results. Follow the steps in
   [Reconfiguring a kubeadm cluster](/docs/tasks/administer-cluster/kubeadm/kubeadm-reconfigure) instead.
 
+### Considerations when upgrading etcd
+
+Because the `kube-apiserver` static pod is running at all times (even if you
+have drained the node), when you perform a kubeadm upgrade which includes an
+etcd upgrade, in-flight requests to the server will stall while the new etcd
+static pod is restarting. As a workaround, it is possible to actively stop the
+`kube-apiserver` process a few seconds before starting the `kubeadm upgrade
+apply` command. This permits to complete in-flight requests and close existing
+connections, and minimizes the consequence of the etcd downtime. This can be
+done as follows on control plane nodes:
+
+```shell
+killall -s SIGTERM kube-apiserver # trigger a graceful kube-apiserver shutdown
+sleep 20 # wait a little bit to permit completing in-flight requests
+kubeadm upgrade ... # execute a kubeadm upgrade command
+```
+
 <!-- steps -->
 
 ## Changing the package repository
 
-If you're using the community-owned package repositories (`pkgs.k8s.io`), you need to 
+If you're using the community-owned package repositories (`pkgs.k8s.io`), you need to
 enable the package repository for the desired Kubernetes minor release. This is explained in
 [Changing the Kubernetes package repository](/docs/tasks/administer-cluster/kubeadm/change-package-repository/)
 document.
@@ -320,4 +337,4 @@ and post-upgrade manifest file for a certain component, a backup file for it wil
 `kubeadm upgrade node` does the following on worker nodes:
 
 - Fetches the kubeadm `ClusterConfiguration` from the cluster.
-- Upgrades the kubelet configuration for this node.
+- Upgrades the kubelet configuration for this node.