mirror of
https://github.com/woodpecker-ci/woodpecker.git
synced 2024-12-27 10:50:33 +00:00
Documentation improvements (#3376)
This commit is contained in:
Thomas Anderson
GitHub
parent
89c826f401
commit
9918d51a62
4 changed files with 56 additions and 123 deletions
|
|
@ -35,6 +35,10 @@ Example registry hostname matching logic:
|
|||
- Hostname `docker.io` matches `bradyrydzewski/golang`
|
||||
- Hostname `docker.io` matches `bradyrydzewski/golang:latest`
|
||||
|
||||
:::note
|
||||
The flow above doesn't work in Kubernetes. There is [workaround](../30-administration/22-backends/40-kubernetes.md#images-from-private-registries).
|
||||
:::
|
||||
|
||||
## Global registry support
|
||||
|
||||
To make a private registry globally available, check the [server configuration docs](../30-administration/10-server-config.md#global-registry-setting).
|
||||
|
|
|
|||
|
|
@ -441,30 +441,6 @@ WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/woodpecker?
|
|||
|
||||
Read the value for `WOODPECKER_DATABASE_DATASOURCE` from the specified filepath
|
||||
|
||||
### `WOODPECKER_ENCRYPTION_KEY`
|
||||
|
||||
> Default: empty
|
||||
|
||||
Encryption key used to encrypt secrets in DB. See [secrets encryption](./40-encryption.md)
|
||||
|
||||
### `WOODPECKER_ENCRYPTION_KEY_FILE`
|
||||
|
||||
> Default: empty
|
||||
|
||||
Read the value for `WOODPECKER_ENCRYPTION_KEY` from the specified filepath
|
||||
|
||||
### `WOODPECKER_ENCRYPTION_TINK_KEYSET_FILE`
|
||||
|
||||
> Default: empty
|
||||
|
||||
Filepath to encryption keyset used to encrypt secrets in DB. See [secrets encryption](./40-encryption.md)
|
||||
|
||||
### `WOODPECKER_ENCRYPTION_DISABLE`
|
||||
|
||||
> Default: empty
|
||||
|
||||
Boolean flag to decrypt secrets in DB and disable server encryption. See [secrets encryption](./40-encryption.md)
|
||||
|
||||
### `WOODPECKER_PROMETHEUS_AUTH_TOKEN`
|
||||
|
||||
> Default: empty
|
||||
|
|
|
|||
|
|
@ -6,6 +6,12 @@ toc_max_heading_level: 2
|
|||
|
||||
The kubernetes backend executes steps inside standalone pods. A temporary PVC is created for the lifetime of the pipeline to transfer files between steps.
|
||||
|
||||
## Images from private registries
|
||||
|
||||
In order to pull private container images defined in your pipeline YAML you must provide [registry credentials in Kubernetes secret](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/).
|
||||
As the secret is Agent-wide, it has to be placed in namespace defined by `WOODPECKER_BACKEND_K8S_NAMESPACE`.
|
||||
Besides, you need to provide the secret name to Agent via `WOODPECKER_BACKEND_K8S_PULL_SECRET_NAMES`.
|
||||
|
||||
## Job specific configuration
|
||||
|
||||
### Resources
|
||||
|
|
@ -32,14 +38,16 @@ steps:
|
|||
cpu: 1000m
|
||||
```
|
||||
|
||||
### `serviceAccountName`
|
||||
You can use [Limit Ranges](https://kubernetes.io/docs/concepts/policy/limit-range/) if you want to set the limits by per-namespace basis.
|
||||
|
||||
Specify the name of the ServiceAccount which the build pod will mount. This serviceAccount must be created externally.
|
||||
See the [kubernetes documentation](https://kubernetes.io/docs/concepts/security/service-accounts/) for more information on using serviceAccounts.
|
||||
### Service account
|
||||
|
||||
### `nodeSelector`
|
||||
`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.
|
||||
|
||||
Specifies the label which is used to select the node on which the job will be executed.
|
||||
### Node selector
|
||||
|
||||
`nodeSelector` specifies the labels which are used to select the node on which the job will be executed.
|
||||
|
||||
Labels defined here will be appended to a list which already contains `"kubernetes.io/arch"`.
|
||||
By default `"kubernetes.io/arch"` is inferred from the agents' platform. One can override it by setting that label in the `nodeSelector` section of the `backend_options`.
|
||||
|
|
@ -66,9 +74,11 @@ And then overwrite the `nodeSelector` in the `backend_options` section of the st
|
|||
kubernetes.io/arch: "${ARCH}"
|
||||
```
|
||||
|
||||
### `tolerations`
|
||||
You can use [PodNodeSelector](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#podnodeselector) admission controller if you want to set the node selector by per-namespace basis.
|
||||
|
||||
When you use nodeSelector and the node pool is configured with Taints, you need to specify the Tolerations. Tolerations allow the scheduler to schedule pods with matching taints.
|
||||
### Tolerations
|
||||
|
||||
When you use `nodeSelector` and the node pool is configured with Taints, you need to specify the Tolerations. Tolerations allow the scheduler to schedule pods with matching taints.
|
||||
See the [kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) for more information on using tolerations.
|
||||
|
||||
Example pipeline configuration:
|
||||
|
|
@ -102,8 +112,8 @@ steps:
|
|||
|
||||
### 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:
|
||||
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 `volumes` option.
|
||||
Assuming a PVC named `woodpecker-cache` exists, it can be referenced as follows in a step:
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
|
|
@ -117,9 +127,9 @@ steps:
|
|||
[...]
|
||||
```
|
||||
|
||||
### `securityContext`
|
||||
### Security context
|
||||
|
||||
Use the following configuration to set the `securityContext` for the pod/container running a given pipeline step:
|
||||
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:
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
|
|
@ -154,7 +164,31 @@ spec:
|
|||
[...]
|
||||
```
|
||||
|
||||
See the [kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) for more information on using `securityContext`.
|
||||
You can also restrict a container's syscalls with [seccomp](https://kubernetes.io/docs/tutorials/security/seccomp/) profile
|
||||
|
||||
```yaml
|
||||
backend_options:
|
||||
kubernetes:
|
||||
securityContext:
|
||||
seccompProfile:
|
||||
type: Localhost
|
||||
localhostProfile: profiles/audit.json
|
||||
```
|
||||
|
||||
or restrict a container's access to resources by specifying [AppArmor](https://kubernetes.io/docs/tutorials/security/apparmor/) profile
|
||||
|
||||
```yaml
|
||||
backend_options:
|
||||
kubernetes:
|
||||
securityContext:
|
||||
apparmorProfile:
|
||||
type: Localhost
|
||||
localhostProfile: k8s-apparmor-example-deny-write
|
||||
```
|
||||
|
||||
:::note
|
||||
AppArmor syntax follows [KEP-24](https://github.com/kubernetes/enhancements/blob/fddcbb9cbf3df39ded03bad71228265ac6e5215f/keps/sig-node/24-apparmor/README.md).
|
||||
:::
|
||||
|
||||
## Tips and tricks
|
||||
|
||||
|
|
@ -215,3 +249,9 @@ Additional annotations to apply to worker pods. Must be a YAML object, e.g. `{"e
|
|||
> Default: `false`
|
||||
|
||||
Determines if containers must be required to run as non-root users.
|
||||
|
||||
### `WOODPECKER_BACKEND_K8S_PULL_SECRET_NAMES`
|
||||
|
||||
> Default: empty
|
||||
|
||||
Secret names to pull images from private repositories. See, how to [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/).
|
||||
|
|
|
|||
|
|
@ -1,87 +0,0 @@
|
|||
# Secrets encryption
|
||||
|
||||
:::danger
|
||||
Secrets encryption is currently broken and therefore disabled by default. It will be fixed in an upcoming release.
|
||||
|
||||
Check:
|
||||
|
||||
- <https://github.com/woodpecker-ci/woodpecker/issues/1541> and
|
||||
- <https://github.com/woodpecker-ci/woodpecker/pull/2300>
|
||||
|
||||
:::
|
||||
|
||||
By default, Woodpecker does not encrypt secrets in its database. You can enable encryption
|
||||
using simple AES key or more advanced [Google TINK](https://developers.google.com/tink) encryption.
|
||||
|
||||
## Common
|
||||
|
||||
### Enabling secrets encryption
|
||||
|
||||
To enable secrets encryption and encrypt all existing secrets in database set
|
||||
`WOODPECKER_ENCRYPTION_KEY`, `WOODPECKER_ENCRYPTION_KEY_FILE` or `WOODPECKER_ENCRYPTION_TINK_KEYSET_PATH` environment
|
||||
variable depending on encryption method of your choice.
|
||||
|
||||
After encryption is enabled you will be unable to start Woodpecker server without providing valid encryption key!
|
||||
|
||||
### Disabling encryption and decrypting all secrets
|
||||
|
||||
To disable secrets encryption and decrypt database you need to start server with valid
|
||||
`WOODPECKER_ENCRYPTION_KEY` or `WOODPECKER_ENCRYPTION_TINK_KEYSET_FILE` environment variable set depending on
|
||||
enabled encryption method, and `WOODPECKER_ENCRYPTION_DISABLE` set to true.
|
||||
|
||||
After secrets was decrypted server will proceed working in unencrypted mode. You will not need to use "disable encryption"
|
||||
variable or encryption keys to start server anymore.
|
||||
|
||||
## AES
|
||||
|
||||
Simple AES encryption.
|
||||
|
||||
### Configuration
|
||||
|
||||
You can manage encryption on server using these environment variables:
|
||||
|
||||
- `WOODPECKER_ENCRYPTION_KEY` - encryption key
|
||||
- `WOODPECKER_ENCRYPTION_KEY_FILE` - file to read encryption key from
|
||||
- `WOODPECKER_ENCRYPTION_DISABLE` - disable encryption flag used to decrypt all data on server
|
||||
|
||||
## TINK
|
||||
|
||||
TINK uses AEAD encryption instead of simple AES and supports key rotation.
|
||||
|
||||
<!-- markdownlint-disable no-duplicate-heading -->
|
||||
|
||||
### Configuration
|
||||
|
||||
<!-- markdownlint-enable no-duplicate-heading -->
|
||||
|
||||
You can manage encryption on server using these two environment variables:
|
||||
|
||||
- `WOODPECKER_ENCRYPTION_TINK_KEYSET_FILE` - keyset filepath
|
||||
- `WOODPECKER_ENCRYPTION_DISABLE` - disable encryption flag used to decrypt all data on server
|
||||
|
||||
### Encryption keys
|
||||
|
||||
You will need plaintext AEAD-compatible Google TINK keyset to encrypt your data.
|
||||
|
||||
To generate it and then rotate keys if needed, install `tinkey`([installation guide](https://developers.google.com/tink/install-tinkey))
|
||||
|
||||
Keyset contains one or more keys, used to encrypt or decrypt your data, and primary key ID, used to determine which key
|
||||
to use while encrypting new data.
|
||||
|
||||
Keyset generation example:
|
||||
|
||||
```bash
|
||||
tinkey create-keyset --key-template AES256_GCM --out-format json --out keyset.json
|
||||
```
|
||||
|
||||
### Key rotation
|
||||
|
||||
Use `tinkey` to rotate encryption keys in your existing keyset:
|
||||
|
||||
```bash
|
||||
tinkey rotate-keyset --in keyset_v1.json --out keyset_v2.json --key-template AES256_GCM
|
||||
```
|
||||
|
||||
Then you just need to replace server keyset file with the new one. At the moment server detects new encryption
|
||||
keyset it will re-encrypt all existing secrets with the new key, so you will be unable to start server with previous
|
||||
keyset anymore.
|
||||
Loading…
Reference in a new issue