diff --git a/docs/guides/configuration-guide/services/kubernetes.md b/docs/guides/configuration-guide/services/kubernetes.md
new file mode 100644
index 0000000000..42b3d86089
--- /dev/null
+++ b/docs/guides/configuration-guide/services/kubernetes.md
@@ -0,0 +1,51 @@
+---
+sidebar_label: Kubernetes
+---
+
+# Kubernetes
+
+The deployment of the k3s cluster is optional and disabled by default.
+
+The deployment is based on [k3s-ansible](https://github.com/techno-tim/k3s-ansible) and the defaults
+are configured and described in [099-k3s.yml](https://github.com/osism/defaults/blob/main/all/099-k3s.yml)
+
+:::warning
+K3S is currently not installable on nodes that use a layer-3 underlay network by running an FRR
+instance on the node itself. The OSISM integration for this scenario is still pending.
+Metal-LB either uses ARP for the leader election (which cannot work in principle) or starts its own
+FRR instance which conflicts with the FRR instance of the host.
+:::
+
+1. Enable the deployment of the k3s cluster by setting `enable_osism_kubernetes` to `yes`
+
+2. Optional: If you run your environment behind a http proxy, [configure the proxy settings](../proxy.md)
+
+3. The use of more than 3 name servers for the Kubernetes nodes generates a large number of warning messages as only the first three name servers are used.
+
+4. Define the `apiserver_endpoint` with a unused ipv4 address
+
+5. Define the `metal_lb_ip_range` with a range of free ipv4 adresses
+
+6. Create kubernetes token
+
+   ```
+   openssl rand -base64 1024
+   ```
+
+7. Add this token to the secrets file with the name `k3s_token`
+
+   ```
+   make ansible_vault_edit FILE=environments/secrets.yml EDITOR=<your favourite editor>
+   ```
+
+   An example secret:
+   ```
+   k3s_token: |
+      9nfWMSnntyozgwATpsxk/5UFRtW4sRfiDUIFH3JtqUr2vLJ+FN3qdUJyaLFMp0oa
+      O9BsyztqhARd7gBy7yRg9GnD6KcCsM25rCSAD60iRK8ifi7uWyuTKaqruqv+IgsG
+      ...
+      KqvUiYaCkUSKP0jt8oDcoJ4eXjpHpk32yRg7LC+CHUFlqTOvs45NpBOKApH8vlkb
+      u4xdpdxT3TjPSibeQz5BOyFL+2slxxoXMv7p1YR0R68=
+   ```
+
+
diff --git a/docs/guides/deploy-guide/services/kubernetes.md b/docs/guides/deploy-guide/services/kubernetes.md
index 65fd09ab85..80ab70e68e 100644
--- a/docs/guides/deploy-guide/services/kubernetes.md
+++ b/docs/guides/deploy-guide/services/kubernetes.md
@@ -11,6 +11,8 @@ As of OSISM 7, it is possible to create a Kubernetes cluster on all nodes.
 At the moment, this is still optional. In the future, it will be necessary
 to deploy this Kubernetes cluster.
 
+Check the [configuration guide](../../configuration-guide/services) for configuring kubernetes.
+
 :::
 
 1. Deploy the [K3s](https://k3s.io) cluster.
diff --git a/docs/guides/upgrade-guide/services/kubernetes.md b/docs/guides/upgrade-guide/services/kubernetes.md
new file mode 100644
index 0000000000..ec10a0651c
--- /dev/null
+++ b/docs/guides/upgrade-guide/services/kubernetes.md
@@ -0,0 +1,27 @@
+---
+sidebar_label: Kubernetes
+sidebar_position: 12
+---
+
+# Kubernetes
+
+1. Deploy the [K3s](https://k3s.io) cluster.
+
+   ```
+   osism apply -a upgrade kubernetes
+   ```
+
+2. Deploy the [Kubernetes dashboard](https://github.com/kubernetes/dashboard):
+
+   ```
+   osism apply -a upgrade kubernetes-dashboard
+   ```
+
+## Cluster API
+
+Deploy the [Cluster API](https://cluster-api.sigs.k8s.io) management cluster on the K3s cluster:
+
+```
+osism apply -a upgrade clusterapi
+```
+