Restructure k8s documentation (#2193)

As suggested in
https://github.com/woodpecker-ci/woodpecker/discussions/2160.

- Simplified wording
- Referenced helm chart
- Removed "experimental" banner as the k8s backend is quite stable I'd
say (after using it for months now)
- Add example for `resources` definition`

---------
Co-authored-by: Anbraten <anton@ju60.de>

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,42 +1,49 @@
 # Kubernetes backend
 
-:::caution
+:::info
-Kubernetes support is still experimental and not all pipeline features are fully supported yet.
+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.
-Check the [current state](https://github.com/woodpecker-ci/woodpecker/issues/1513)
 :::
 
-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.
 
-## Configuration
+## General Configuration
 
-### `WOODPECKER_BACKEND_K8S_NAMESPACE`
+These env vars can be set in the `env:` sections of both `server` and `agent`.
-> Default: `woodpecker`
+They do not need to be set for both but only for the part to which it is relevant to.
+
+```yml
+server:
+  env:
+    WOODPECKER_SESSION_EXPIRES: "300h"
+    [...]
+
+agent:
+  env:
+    [...]
+```
+
+- `WOODPECKER_BACKEND_K8S_NAMESPACE` (default: `woodpecker`)
 
   The namespace to create worker pods in.
 
-### `WOODPECKER_BACKEND_K8S_VOLUME_SIZE`
+- `WOODPECKER_BACKEND_K8S_VOLUME_SIZE` (default: `10G`)
-> Default: `10G`
 
   The volume size of the pipeline volume.
 
-### `WOODPECKER_BACKEND_K8S_STORAGE_CLASS`
+- `WOODPECKER_BACKEND_K8S_STORAGE_CLASS` (default: empty)
-> Default: empty
 
   The storage class to use for the pipeline volume.
 
-### `WOODPECKER_BACKEND_K8S_STORAGE_RWX`
+- `WOODPECKER_BACKEND_K8S_STORAGE_RWX` (default: `true`)
-> 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.
 
-### `WOODPECKER_BACKEND_K8S_POD_LABELS`
+- `WOODPECKER_BACKEND_K8S_POD_LABELS` (default: empty)
-> Default: empty
 
   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`
+- `WOODPECKER_BACKEND_K8S_POD_ANNOTATIONS` (default: empty)
-> Default: empty
 
   Additional annotations to apply to worker pods. Must be a YAML object, e.g. `{"example.com/test-annotation":"test-value"}`.
 
@@ -45,7 +52,26 @@ Additional annotations to apply to worker pods. Must be a YAML object, e.g. `{"e
 ### 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"
+    [...]
+```

docs/docs/30-administration/80-kubernetes.md

@@ -1,72 +0,0 @@
-# Kubernetes
-
-Woodpecker does support Kubernetes as a backend. See the [Kubernetes backend configuration](./22-backends/40-kubernetes.md#configuration) for backend-specific options.
-
-:::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/9#issuecomment-483979755)
-:::
-
-## Deploy with HELM
-
-Deploying Woodpecker with [HELM](https://helm.sh/docs/) is the recommended way.
-Have a look at the `values.yaml` config files for all available settings.
-
-### Preparation
-
-```shell
-# create agent secret
-kubectl create secret generic woodpecker-secret \
-  --namespace <namespace> \
-  --from-literal=WOODPECKER_AGENT_SECRET=$(openssl rand -hex 32)
-
-# add credentials for your forge
-kubectl create secret generic woodpecker-github-client \
-  --namespace <namespace> \
-  --from-literal=WOODPECKER_GITHUB_CLIENT=xxxxxxxx
-
-kubectl create secret generic woodpecker-github-secret \
-  --namespace <namespace> \
-  --from-literal=WOODPECKER_GITHUB_SECRET=xxxxxxxx
-
-# add helm repo
-helm repo add woodpecker https://woodpecker-ci.org/
-```
-
-### Woodpecker server
-
-```shell
-# Install
-helm upgrade --install woodpecker-server --namespace <namespace> woodpecker/woodpecker-server
-
-# Uninstall
-helm delete woodpecker-server
-```
-
-### Woodpecker agent
-
-```shell
-# Install
-helm upgrade --install woodpecker-agent --namespace <namespace> woodpecker/woodpecker-agent
-
-# Uninstall
-helm delete woodpecker-agent
-```
-
-## 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"
-    [...]
-```