Restructure k8s documentation

docs/docs/30-administration/00-setup.md

@@ -35,7 +35,7 @@ In addition you need at least some kind of database which requires additional re
 You can install Woodpecker on multiple ways:
 
 - Using [docker-compose](#docker-compose) with the official [container images](../80-downloads.md#docker-images)
-- By deploying to a [Kubernetes](./80-kubernetes.md) with manifests or Woodpeckers official Helm charts
+- Using [Kubernetes](./#kubernetes) via the Woodpeckers Helm chart
 - Using [binaries](../80-downloads.md)
 
 ### docker-compose
@@ -171,6 +171,16 @@ services:
 +     - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
 ```
 
+### Kubernetes 
+
+We recommended to deploy Woodpecker using the [Woodpecker helm chart](https://github.com/woodpecker-ci/helm).
+Have a look at the [`values.yaml`](https://github.com/woodpecker-ci/helm/blob/main/values.yaml) config files for all available settings.
+
+The chart contains two subcharts, `server` and `agent` which are automatically configured as needed.
+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).
+
 ## Authentication
 
 Authentication is done using OAuth and is delegated to your forge which is configured by using environment variables. The example above demonstrates basic GitHub integration.

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

@@ -1,51 +1,77 @@
 # Kubernetes backend
 
-:::caution
-Kubernetes support is still experimental and not all pipeline features are fully supported yet.
-
-Check the [current state](https://github.com/woodpecker-ci/woodpecker/issues/1513)
+:::info
+Not all pipeline features are fully supported yet for this backend.
+Check [the Kubernetes overview issue](https://github.com/woodpecker-ci/woodpecker/issues/1513) for a summary.
 :::
 
-The kubernetes backend executes each step inside a newly created pod. A PVC is also created for the lifetime of the pipeline, for transferring files between steps.
+The kubernetes backend executes steps inside standalone pods. A temporary PVC is created for the lifetime of the pipeline to transfer files between steps.
+
+## General Configuration
+
+These env vars can be set in the `env:` sections of both `server` and `agent`.
+They do not need to be set for both but only for the part to which it is relevant to.
 
-## Configuration
+```yml
+server:
+  env:
+    WOODPECKER_SESSION_EXPIRES: "300h"
+    [...]
 
-### `WOODPECKER_BACKEND_K8S_NAMESPACE`
-> Default: `woodpecker`
+agent:
+  env:
+    [...]
+```
+
+- `WOODPECKER_BACKEND_K8S_NAMESPACE` (default: `woodpecker`)
 
-The namespace to create worker pods in.
+  The namespace to create worker pods in.
 
-### `WOODPECKER_BACKEND_K8S_VOLUME_SIZE`
-> Default: `10G`
+- `WOODPECKER_BACKEND_K8S_VOLUME_SIZE` (default: `10G`)
 
-The volume size of the pipeline volume.
+  The volume size of the pipeline volume.
 
-### `WOODPECKER_BACKEND_K8S_STORAGE_CLASS`
-> Default: empty
+- `WOODPECKER_BACKEND_K8S_STORAGE_CLASS` (default: empty)
 
-The storage class to use for the pipeline volume.
+  The storage class to use for the pipeline volume.
 
-### `WOODPECKER_BACKEND_K8S_STORAGE_RWX`
-> Default: `true`
+- `WOODPECKER_BACKEND_K8S_STORAGE_RWX` (default: `true`)
 
-Determines if `RWX` should be used for the pipeline volume's [access mode](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes). If false, `RWO` is used instead.
+  Determines if `RWX` should be used for the pipeline volume's [access mode](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes). If false, `RWO` is used instead.
 
-### `WOODPECKER_BACKEND_K8S_POD_LABELS`
-> Default: empty
+- `WOODPECKER_BACKEND_K8S_POD_LABELS` (default: empty)
 
-Additional labels to apply to worker pods. Must be a YAML object, e.g. `{"example.com/test-label":"test-value"}`.
+  Additional labels to apply to worker pods. Must be a YAML object, e.g. `{"example.com/test-label":"test-value"}`.
 
-### `WOODPECKER_BACKEND_K8S_POD_ANNOTATIONS`
-> Default: empty
+- `WOODPECKER_BACKEND_K8S_POD_ANNOTATIONS` (default: empty)
 
-Additional annotations to apply to worker pods. Must be a YAML object, e.g. `{"example.com/test-annotation":"test-value"}`.
+  Additional annotations to apply to worker pods. Must be a YAML object, e.g. `{"example.com/test-annotation":"test-value"}`.
 
 ## Job specific configuration
 
 ### Resources
 
 The kubernetes backend also allows for specifying requests and limits on a per-step basic, most commonly for CPU and memory.
-See the [kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) for more information on using resources.
+We recommend to add a `resources` definition to all steps to ensure efficient scheduling.
+
+Here is an example definition with an arbitrary `resources` definition below the `backend_options` section:
+
+```yml
+steps:
+  'My kubernetes step':
+    image: alpine
+    commands:
+      - echo "Hello world"
+    backend_options:
+      kubernetes:
+        resources:
+          requests:
+            memory: 200Mi
+            cpu: 100m
+          limits:
+            memory: 400Mi
+            cpu: 1000m
+```
 
 ### serviceAccountName
 
@@ -59,6 +85,7 @@ By default the pod will use "kubernetes.io/arch" inferred from top-level "platfo
 See the [kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) for more information on using nodeSelector.
 
 Example pipeline configuration:
+
 ```yaml
 steps:
   build:
@@ -79,3 +106,20 @@ steps:
         nodeSelector:
           beta.kubernetes.io/instance-type: p3.8xlarge
 ```
+
+### Volumes
+
+To mount volumes a persistent volume (PV) and persistent volume claim (PVC) are needed on the cluster which can be referenced in steps via the `volume:` option.
+Assuming a PVC named "woodpecker-cache" exists, it can be referenced as follows in a step:
+
+```yaml
+steps:
+  "Restore Cache":
+    image: meltwater/drone-cache
+    volumes:
+      - woodpecker-cache:/woodpecker/src/cache
+    settings:
+      mount:
+        - "woodpecker-cache"
+    [...]
+```