From f2c540f3fa7efd24fcccc9f28762a9ccd4f203cf Mon Sep 17 00:00:00 2001
From: Magdalena Dziadosz <160592158+MagdaDziadosz@users.noreply.github.com>
Date: Tue, 24 Dec 2024 07:53:22 +0100
Subject: [PATCH] [BOP-1475] Improve custom worker profiles docs (#272)

Co-authored-by: Kory <57411706+KoryKessel-Mirantis@users.noreply.github.com>
---
 .../docs/configuration/kubernetes/kubelet.md  | 55 +++++++++++++++----
 1 file changed, 43 insertions(+), 12 deletions(-)

diff --git a/content/docs/configuration/kubernetes/kubelet.md b/content/docs/configuration/kubernetes/kubelet.md
index df8fe0df..462a035a 100644
--- a/content/docs/configuration/kubernetes/kubelet.md
+++ b/content/docs/configuration/kubernetes/kubelet.md
@@ -83,25 +83,56 @@ spec:
             nodefs.inodesFree: 5%
 ```
 
+{{< callout type="warning" >}}
+To ensure your custom profile works correctly:
+
+- Cross-check `featureGates` in the custom profile against the official
+  Kubernetes [list of removed feature gates](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates-removed/), as adding a removed feature gate will prevent the kubelet from starting. 
+- Include only namespaced `sysctls` when you configure `allowedUnsafeSysctls`, as non-namespaced `sysctls` are unsupported by the kubelet and will prevent
+  it from starting.
+{{< /callout >}}
+
 ### Apply a custom profile to a node
 
-Hosts can be assigned a custom profile through the `hosts` section of the MKE
-configuration file, whereas the profile name is an installation time argument for
-the host.
+You can assign a custom profile through the `hosts` section of the MKE
+configuration file, whereas the profile name is an installation time argument
+for the host.
 
 The following example configuration applies the `hardworker` custom profile to
 the `localhost` node:
 
 ```yaml
-  hosts:
-  - role: single
-    ssh:
-      address: localhost
-      keyPath: ~/.ssh/id_rsa
-      port: 22
-      user: root
-      installFlags:
-        - --profile=hardworker
+hosts:
+- role: single
+  installFlags:
+    - --profile=hardworker
+  ssh:
+    address: localhost
+    keyPath: ~/.ssh/id_rsa
+    port: 22
+    user: root
+```
+
+### Debug worker profiles
+
+If an invalid worker profile is provided, the kubelet assigned to use the profile may
+fail to start. If a node takes on the `NotReady` state following the application of a worker
+profile, it is likely due to an incorrect worker profile configuration.
+
+To debug a worker profile:
+
+1. SSH into the corresponding `NotReady` node.
+2. Check the logs of k0sworker system service `journalctl -u k0sworker` for errors. 
+3. If the worker node does not show any errors, SSH into a manager node.
+4. Check the logs of the k0scontroller system service
+   `journalctl -u k0scontroller` for errors. Repeat the process for every
+   manager node until you find errors related to kubelet or to worker profiles.
+
+Example of a k0scontroller error caused by an incorrect value for the
+`memoryThrottlingFactor` parameter in the worker profile:
+
+```bash
+k0s[1619032]: time="2024-11-11 22:25:03" level=error msg="Failed to recover from previously failed reconciliation" component=workerconfig.Reconciler error="failed to generate resources for worker configuration: failed to decode worker profile \"hardworker\": error unmarshaling JSON: while decoding JSON: json: cannot unmarshal string into Go struct field KubeletConfiguration.memoryThrottlingFactor of type float64"
 ```
 
 ## Precedence of kubelet configuration