Kubernetes documentation enhancements (#4374)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Thomas Anderson <127358482+zc-devs@users.noreply.github.com>
Co-authored-by: 6543 <6543@obermui.de>
Co-authored-by: Robert Kaussow <xoxys@rknet.org>
Co-authored-by: Robert Kaussow <mail@thegeeklab.de>

docs/docs/30-administration/05-deployment-methods/20-kubernetes.md

@@ -7,3 +7,44 @@ The chart contains two sub-charts, `server` and `agent` which are automatically
 The chart started off with two independent charts but was merged into one to simplify the deployment at start of 2023.
 
 A couple of backend-specific config env vars exists which are described in the [kubernetes backend docs](../22-backends/40-kubernetes.md).
+
+## Metrics
+
+Please see [Prometheus](../40-advanced/90-prometheus.md) for general information on configuration and usage.
+
+For Kubernetes, you must set the following values when deploying via Helm chart to enable in-cluster metrics gathering:
+
+```yaml
+metrics:
+  enabled: true
+  port: 9001
+```
+
+This activates the `/metrics` endpoint on port `9001` without authentication. This port is not exposed externally by default. Use the instructions at [Prometheus](../40-advanced/90-prometheus.md) if you want to enable authenticated external access to metrics.
+
+To enable Prometheus pod monitoring discovery, you must also make the following settings:
+
+<!-- cspell:disable -->
+
+```yaml
+prometheus:
+  podmonitor:
+    enabled: true
+    interval: 60s
+    labels: {}
+```
+
+<!-- cspell:enable -->
+
+### Troubleshooting Metrics
+
+If you are not receiving metrics despite the steps above, ensure that in your Prometheus configuration either your namespace is explicitly configured in `podMonitorNamespaceSelector` or the selectors are disabled.
+
+```yaml
+# Search all available namespaces
+podMonitorNamespaceSelector:
+  matchLabels: {}
+# Enable all available pod monitors
+podMonitorSelector:
+  matchLabels: {}
+```

docs/docs/30-administration/22-backends/40-kubernetes.md

@@ -50,6 +50,21 @@ See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/container
 `serviceAccountName` specifies the name of the ServiceAccount which the Pod will mount. This service account must be created externally.
 See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/security/service-accounts/) for more information on using service accounts.
 
+```yaml
+steps:
+  - name: 'My kubernetes step'
+    image: alpine
+    commands:
+      - echo "Hello world"
+    backend_options:
+      kubernetes:
+        # Use the service account `default` in the current namespace.
+        # This usually the same as wherever woodpecker is deployed.
+        serviceAccountName: default
+```
+
+To give steps access to the Kubernetes API via service account, take a look at [RBAC Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
+
 ### Node selector
 
 `nodeSelector` specifies the labels which are used to select the node on which the job will be executed.
@@ -119,7 +134,19 @@ steps:
 ### Volumes
 
 To mount volumes a PersistentVolume (PV) and PersistentVolumeClaim (PVC) are needed on the cluster which can be referenced in steps via the `volumes` option.
-Assuming a PVC named `woodpecker-cache` exists, it can be referenced as follows in a step:
+
+Persistent volumes must be created manually. Use the Kubernetes [Persistent Volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) documentation as a reference.
+
+_If your PVC is not highly available or NFS-based, you may also need to integrate affinity settings to ensure that your steps are executed on the correct node._
+
+NOTE: If you plan to use this volume in more than one workflow concurrently, make sure you have configured the PVC in `RWX` mode. Keep in mind that this feature must be supported by the used CSI driver:
+
+```yaml
+accessModes:
+  - ReadWriteMany
+```
+
+Assuming a PVC named `woodpecker-cache` exists, it can be referenced as follows in a plugin step:
 
 ```yaml
 steps:
@@ -133,6 +160,19 @@ steps:
     [...]
 ```
 
+Or as follows when using a normal image:
+
+```yaml
+steps:
+  - name: "Edit cache"
+    image: alpine:latest
+    volumes:
+      - woodpecker-cache:/woodpecker/src/cache
+    commands:
+      - echo "Hello World" > /woodpecker/src/cache/output.txt
+    [...]
+```
+
 ### Security context
 
 Use the following configuration to set the [Security Context](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) for the Pod/container running a given pipeline step: