mirror of
https://github.com/woodpecker-ci/woodpecker.git
synced 2024-11-23 02:11:01 +00:00
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>
This commit is contained in:
Patrick Schratz
GitHub
parent
4d83ea0de8
commit
1f95675365
3 changed files with 80 additions and 98 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
## Configuration
|
||||
## General Configuration
|
||||
|
||||
### `WOODPECKER_BACKEND_K8S_NAMESPACE`
|
||||
> Default: `woodpecker`
|
||||
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.
|
||||
|
||||
The namespace to create worker pods in.
|
||||
```yml
|
||||
server:
|
||||
env:
|
||||
WOODPECKER_SESSION_EXPIRES: "300h"
|
||||
[...]
|
||||
|
||||
### `WOODPECKER_BACKEND_K8S_VOLUME_SIZE`
|
||||
> Default: `10G`
|
||||
agent:
|
||||
env:
|
||||
[...]
|
||||
```
|
||||
|
||||
The volume size of the pipeline volume.
|
||||
- `WOODPECKER_BACKEND_K8S_NAMESPACE` (default: `woodpecker`)
|
||||
|
||||
### `WOODPECKER_BACKEND_K8S_STORAGE_CLASS`
|
||||
> Default: empty
|
||||
The namespace to create worker pods in.
|
||||
|
||||
The storage class to use for the pipeline volume.
|
||||
- `WOODPECKER_BACKEND_K8S_VOLUME_SIZE` (default: `10G`)
|
||||
|
||||
### `WOODPECKER_BACKEND_K8S_STORAGE_RWX`
|
||||
> Default: `true`
|
||||
The volume size of the pipeline volume.
|
||||
|
||||
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_STORAGE_CLASS` (default: empty)
|
||||
|
||||
### `WOODPECKER_BACKEND_K8S_POD_LABELS`
|
||||
> Default: empty
|
||||
The storage class to use for the pipeline volume.
|
||||
|
||||
Additional labels to apply to worker pods. Must be a YAML object, e.g. `{"example.com/test-label":"test-value"}`.
|
||||
- `WOODPECKER_BACKEND_K8S_STORAGE_RWX` (default: `true`)
|
||||
|
||||
### `WOODPECKER_BACKEND_K8S_POD_ANNOTATIONS`
|
||||
> Default: empty
|
||||
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.
|
||||
|
||||
Additional annotations to apply to worker pods. Must be a YAML object, e.g. `{"example.com/test-annotation":"test-value"}`.
|
||||
- `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"}`.
|
||||
|
||||
- `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"}`.
|
||||
|
||||
## 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"
|
||||
[...]
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
[...]
|
||||
```
|
||||
Loading…
Reference in a new issue