Merge pull request #5331 from k0sproject/backport-4214-to-release-1.29

[Backport release-1.29] Update and enhance reset docs

docs/reset.md

@@ -1,63 +1,94 @@
-# Uninstall/Reset
+# Reset (Uninstall)
 
-k0s can be uninstalled locally with `k0s reset` command and remotely with `k0sctl reset` command. They remove all k0s-related files from the host.
+Resetting k0s nodes essentially reverts them to a pre-k0s state. This operation
+is particularly useful in scenarios where you need to cleanly remove k0s from
+nodes, either for troubleshooting purposes or as a precursor to a fresh
+installation. It is designed to remove all components, configurations, and data
+associated with k0s from a node. This includes, but is not limited to, the
+following:
 
-`reset` operates under the assumption that k0s is installed as a service on the host.
+* Processes and containers: Terminates all running k0s processes to ensure that
+  there are no active components left. This includes all container processes
+  managed by the Container Runtime.
+* Data stored on the node: Deletes the whole k0s data directory, which includes
+  * all k0s-related configuration files, including those used for cluster setup
+    and node-specific settings,
+  * all data stores managed by k0s, including etcd or kine data for cluster
+    state and any temporary files created during operation,
+  * and all certificates and other key material generated by k0s for node
+    authentication and communication within the cluster.
+* Network settings: Reverts any network configurations made by k0s, such as
+  network interfaces or iptables rules set up specifically for cluster
+  communication. This is done on a best effort basis. It's recommended that you
+  reboot the host after a reset to ensure that there are no k0s remnants in the
+  host's network configuration.
+* Registration with the host's init system: Reverts the registration done by
+  `k0s install`. After a reset, k0s won't be automatically started when the host
+  boots.
 
-## Uninstall a k0s node locally
+After a successful reset, the k0s binary itself remains. It can then be used to
+join another cluster or create a new one.
 
-To prevent accidental triggering, `k0s reset` will not run if the k0s service is running, so you must first stop the service:
+It's important to understand that performing a reset is a destructive operation
+that will result in the loss of all data and configurations related to k0s on
+the affected nodes. Therefore, it should be performed with care, ideally after
+ensuring that all necessary data has been backed up or that the cluster can be
+safely disassembled without data loss.
+
+K0s can be reset locally on a host using the `k0s reset` command. Whole clusters
+can be reset remotely with the `k0sctl reset` command.
+
+## Reset a k0s node locally
+
+To ensure operational safety, `k0s reset` includes a safeguard that prevents it
+from being executed while k0s is running, so it must be stopped first:
 
 1. Stop the service:
 
-    ```shell
+    ```console
     sudo k0s stop
     ```
 
 2. Invoke the `reset` command:
 
-    ```shell
+    ```console
     $ sudo k0s reset
-    INFO[2021-06-29 13:08:39] * containers steps
-    INFO[2021-06-29 13:08:44] successfully removed k0s containers!
-    INFO[2021-06-29 13:08:44] no config file given, using defaults
-    INFO[2021-06-29 13:08:44] * remove k0s users step:
-    INFO[2021-06-29 13:08:44] no config file given, using defaults
-    INFO[2021-06-29 13:08:44] * uninstall service step
-    INFO[2021-06-29 13:08:44] Uninstalling the k0s service
-    INFO[2021-06-29 13:08:45] * remove directories step
-    INFO[2021-06-29 13:08:45] * CNI leftovers cleanup step
-    INFO k0s cleanup operations done. To ensure a full reset, a node reboot is recommended.
+    WARN[2024-03-28 09:15:36] To ensure a full reset, a node reboot is recommended.
     ```
 
-## Uninstall a k0s cluster using k0sctl
+## Reset a k0s cluster remotely using k0sctl
 
-k0sctl can be used to connect each node and remove all k0s-related files and processes from the hosts.
+K0sctl can be used to connect and reset all cluster nodes in a single command.
 
 1. Invoke `k0sctl reset` command:
 
-    ```shell
+    ```console
     $ k0sctl reset --config k0sctl.yaml
-    k0sctl v0.9.0 Copyright 2021, k0sctl authors.
-
+    k0sctl v0.17.4 Copyright 2023, k0sctl authors.
+    Anonymized telemetry of usage will be sent to the authors.
+    By continuing to use k0sctl you agree to these terms:
+    https://k0sproject.io/licenses/eula
     ? Going to reset all of the hosts, which will destroy all configuration and data, Are you sure? Yes
-    INFO ==> Running phase: Connect to hosts 
-    INFO [ssh] 13.53.43.63:22: connected              
-    INFO [ssh] 13.53.218.149:22: connected            
-    INFO ==> Running phase: Detect host operating systems 
-    INFO [ssh] 13.53.43.63:22: is running Ubuntu 20.04.2 LTS 
-    INFO [ssh] 13.53.218.149:22: is running Ubuntu 20.04.2 LTS 
-    INFO ==> Running phase: Prepare hosts    
-    INFO ==> Running phase: Gather k0s facts 
-    INFO [ssh] 13.53.43.63:22: found existing configuration 
-    INFO [ssh] 13.53.43.63:22: is running k0s controller version {{{ extra.k8s_version }}}+k0s.0
-    INFO [ssh] 13.53.218.149:22: is running k0s worker version {{{ extra.k8s_version }}}+k0s.0
-    INFO [ssh] 13.53.43.63:22: checking if worker  has joined 
-    INFO ==> Running phase: Reset hosts      
-    INFO [ssh] 13.53.43.63:22: stopping k0s           
-    INFO [ssh] 13.53.218.149:22: stopping k0s         
-    INFO [ssh] 13.53.218.149:22: running k0s reset    
-    INFO [ssh] 13.53.43.63:22: running k0s reset      
-    INFO ==> Running phase: Disconnect from hosts 
-    INFO ==> Finished in 8s                  
+    INFO ==> Running phase: Connect to hosts
+    INFO [ssh] 13.53.43.63:22: connected
+    INFO [ssh] 13.53.218.149:22: connected
+    INFO ==> Running phase: Detect host operating systems
+    INFO [ssh] 13.53.43.63:22: is running Ubuntu 22.04.4 LTS
+    INFO [ssh] 13.53.218.149:22: is running Ubuntu 22.04.4 LTS
+    INFO ==> Running phase: Acquire exclusive host lock
+    INFO ==> Running phase: Prepare hosts
+    INFO ==> Running phase: Gather k0s facts
+    INFO [ssh] 13.53.43.63:22: found existing configuration
+    INFO [ssh] 13.53.43.63:22: is running k0s controller version v{{{ extra.k8s_version }}}+k0s.0
+    INFO [ssh] 13.53.218.149:22: is running k0s worker version v{{{ extra.k8s_version }}}+k0s.0
+    INFO [ssh] 13.53.43.63:22: checking if worker  has joined
+    INFO ==> Running phase: Reset workers
+    INFO [ssh] 13.53.218.149:22: reset
+    INFO ==> Running phase: Reset controllers
+    INFO [ssh] 13.53.43.63:22: reset
+    INFO ==> Running phase: Reset leader
+    INFO [ssh] 13.53.43.63:22: reset
+    INFO ==> Running phase: Release exclusive host lock
+    INFO ==> Running phase: Disconnect from hosts
+    INFO ==> Finished in 8s
     ```

mkdocs.yml

@@ -29,7 +29,7 @@ nav:
       - Upgrade: upgrade.md
       - Backup/Restore: backup.md
       - Remove/Replace a controller: remove_controller.md
-      - Uninstall: reset.md
+      - Reset (Uninstall): reset.md
   - Usage:
       - Configuration Options: configuration.md
       - Dynamic Configuration: dynamic-configuration.md