mirrors/woodpecker
1
0
Fork 0
mirror of https://github.com/woodpecker-ci/woodpecker.git synced 2024-11-26 20:01:02 +00:00
Code Issues Projects Releases Wiki Activity

Restructure k8s documentation (#2193)

Browse source 
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 2023-08-14 03:03:32 +02:00 committed by GitHub
parent 4d83ea0de8
commit 1f95675365
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 80 additions and 98 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
docs/docs/30-administration/00-setup.md
View file

@ -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: You can install Woodpecker on multiple ways:
- Using [docker-compose](#docker-compose) with the official [container images](../80-downloads.md#docker-images) - 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) - Using [binaries](../80-downloads.md)
### docker-compose ### docker-compose
@ -171,6 +171,16 @@ services:
+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} + - 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
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. 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.

94
docs/docs/30-administration/22-backends/40-kubernetes.md
View file

@ -1,51 +1,77 @@
# Kubernetes backend # 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.
The namespace to create worker pods in. ```yml
server:
env:
WOODPECKER_SESSION_EXPIRES: "300h"
[...]
### `WOODPECKER_BACKEND_K8S_VOLUME_SIZE` agent:
> Default: `10G` env:
[...]
```
The volume size of the pipeline volume. - `WOODPECKER_BACKEND_K8S_NAMESPACE` (default: `woodpecker`)
### `WOODPECKER_BACKEND_K8S_STORAGE_CLASS` The namespace to create worker pods in.
> Default: empty
The storage class to use for the pipeline volume. - `WOODPECKER_BACKEND_K8S_VOLUME_SIZE` (default: `10G`)
### `WOODPECKER_BACKEND_K8S_STORAGE_RWX` The volume size of the pipeline volume.
> 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_STORAGE_CLASS` (default: empty)
### `WOODPECKER_BACKEND_K8S_POD_LABELS` The storage class to use for the pipeline volume.
> 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_STORAGE_RWX` (default: `true`)
### `WOODPECKER_BACKEND_K8S_POD_ANNOTATIONS` 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.
> Default: empty
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 ## Job specific configuration
### Resources ### Resources
The kubernetes backend also allows for specifying requests and limits on a per-step basic, most commonly for CPU and memory. 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 ### 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. See the [kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) for more information on using nodeSelector.
Example pipeline configuration: Example pipeline configuration:
```yaml ```yaml
steps: steps:
build: build:
@ -79,3 +106,20 @@ steps:
nodeSelector: nodeSelector:
beta.kubernetes.io/instance-type: p3.8xlarge 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"
[...]
```

72
docs/docs/30-administration/80-kubernetes.md
View file

@ -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"
[...]
```