From 9918d51a62d03c364670c7cedc9d3cd88f0e4d75 Mon Sep 17 00:00:00 2001 From: Thomas Anderson <127358482+zc-devs@users.noreply.github.com> Date: Fri, 8 Mar 2024 17:12:50 +0300 Subject: [PATCH] Documentation improvements (#3376) --- docs/docs/20-usage/41-registries.md | 4 + .../30-administration/10-server-config.md | 24 ----- .../22-backends/40-kubernetes.md | 64 +++++++++++--- docs/docs/30-administration/40-encryption.md | 87 ------------------- 4 files changed, 56 insertions(+), 123 deletions(-) delete mode 100644 docs/docs/30-administration/40-encryption.md diff --git a/docs/docs/20-usage/41-registries.md b/docs/docs/20-usage/41-registries.md index b87ae55c4..8508da876 100644 --- a/docs/docs/20-usage/41-registries.md +++ b/docs/docs/20-usage/41-registries.md @@ -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). diff --git a/docs/docs/30-administration/10-server-config.md b/docs/docs/30-administration/10-server-config.md index f9cf1fe94..4b6e0ce10 100644 --- a/docs/docs/30-administration/10-server-config.md +++ b/docs/docs/30-administration/10-server-config.md @@ -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 diff --git a/docs/docs/30-administration/22-backends/40-kubernetes.md b/docs/docs/30-administration/22-backends/40-kubernetes.md index 2da6c6545..e878b6a4f 100644 --- a/docs/docs/30-administration/22-backends/40-kubernetes.md +++ b/docs/docs/30-administration/22-backends/40-kubernetes.md @@ -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/). diff --git a/docs/docs/30-administration/40-encryption.md b/docs/docs/30-administration/40-encryption.md deleted file mode 100644 index 2f1970082..000000000 --- a/docs/docs/30-administration/40-encryption.md +++ /dev/null @@ -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: - -- and -- - -::: - -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. - - - -### Configuration - - - -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.