From 1c7728fae3b5f2f6ce99580066bed6b2f98167d2 Mon Sep 17 00:00:00 2001 From: Aaron Date: Thu, 14 Nov 2024 02:06:38 -0800 Subject: [PATCH] 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 Co-authored-by: Robert Kaussow --- .../05-deployment-methods/20-kubernetes.md | 41 ++++++++++++++++++ .../22-backends/40-kubernetes.md | 42 ++++++++++++++++++- 2 files changed, 82 insertions(+), 1 deletion(-) diff --git a/docs/docs/30-administration/05-deployment-methods/20-kubernetes.md b/docs/docs/30-administration/05-deployment-methods/20-kubernetes.md index a60c32684..a3a92e043 100644 --- a/docs/docs/30-administration/05-deployment-methods/20-kubernetes.md +++ b/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: + + + +```yaml +prometheus: + podmonitor: + enabled: true + interval: 60s + labels: {} +``` + + + +### 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: {} +``` diff --git a/docs/docs/30-administration/22-backends/40-kubernetes.md b/docs/docs/30-administration/22-backends/40-kubernetes.md index c175fdff4..4b2e4c9af 100644 --- a/docs/docs/30-administration/22-backends/40-kubernetes.md +++ b/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: