From 3a3b77c27e98aed57346ff2714ddfbd8c547d28b Mon Sep 17 00:00:00 2001 From: Thomas Anderson <127358482+zc-devs@users.noreply.github.com> Date: Mon, 12 Feb 2024 11:29:13 +0300 Subject: [PATCH 1/9] Kubernetes documentation improvements --- .../22-backends/40-kubernetes.md | 51 ++++++++++++++----- 1 file changed, 39 insertions(+), 12 deletions(-) diff --git a/docs/docs/30-administration/22-backends/40-kubernetes.md b/docs/docs/30-administration/22-backends/40-kubernetes.md index 2da6c65456..fdffb472bf 100644 --- a/docs/docs/30-administration/22-backends/40-kubernetes.md +++ b/docs/docs/30-administration/22-backends/40-kubernetes.md @@ -32,14 +32,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 +68,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. + +### 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. +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 +106,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 +121,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 +158,30 @@ 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, that AppArmor implementation follows [KEP-24](https://github.com/kubernetes/enhancements/blob/fddcbb9cbf3df39ded03bad71228265ac6e5215f/keps/sig-node/24-apparmor/README.md). + ## Tips and tricks From a11a7786de078a911d059c1c20fde92659de2e4f Mon Sep 17 00:00:00 2001 From: Thomas Anderson <127358482+zc-devs@users.noreply.github.com> Date: Mon, 12 Feb 2024 11:36:22 +0300 Subject: [PATCH 2/9] linter --- docs/docs/30-administration/22-backends/40-kubernetes.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/docs/30-administration/22-backends/40-kubernetes.md b/docs/docs/30-administration/22-backends/40-kubernetes.md index fdffb472bf..2f144fa74d 100644 --- a/docs/docs/30-administration/22-backends/40-kubernetes.md +++ b/docs/docs/30-administration/22-backends/40-kubernetes.md @@ -182,7 +182,6 @@ or restrict a container's access to resources by specifying [AppArmor](https://k Note, that AppArmor implementation follows [KEP-24](https://github.com/kubernetes/enhancements/blob/fddcbb9cbf3df39ded03bad71228265ac6e5215f/keps/sig-node/24-apparmor/README.md). - ## Tips and tricks ### CRI-O From 7529937eae4799c34b6d4fc90407cf54cbe015be Mon Sep 17 00:00:00 2001 From: Thomas Anderson <127358482+zc-devs@users.noreply.github.com> Date: Wed, 6 Mar 2024 21:01:33 +0300 Subject: [PATCH 3/9] Returned the lost pull secrets --- docs/docs/30-administration/22-backends/40-kubernetes.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/docs/30-administration/22-backends/40-kubernetes.md b/docs/docs/30-administration/22-backends/40-kubernetes.md index 2f144fa74d..74b6159a22 100644 --- a/docs/docs/30-administration/22-backends/40-kubernetes.md +++ b/docs/docs/30-administration/22-backends/40-kubernetes.md @@ -241,3 +241,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/). From 252b7c9aee2681e5246398ad35609f03640071a5 Mon Sep 17 00:00:00 2001 From: Thomas Anderson <127358482+zc-devs@users.noreply.github.com> Date: Wed, 6 Mar 2024 21:12:21 +0300 Subject: [PATCH 4/9] AppArmor notes correction --- docs/docs/30-administration/22-backends/40-kubernetes.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/docs/30-administration/22-backends/40-kubernetes.md b/docs/docs/30-administration/22-backends/40-kubernetes.md index 74b6159a22..8fed699d6c 100644 --- a/docs/docs/30-administration/22-backends/40-kubernetes.md +++ b/docs/docs/30-administration/22-backends/40-kubernetes.md @@ -180,7 +180,9 @@ or restrict a container's access to resources by specifying [AppArmor](https://k localhostProfile: k8s-apparmor-example-deny-write ``` -Note, that AppArmor implementation follows [KEP-24](https://github.com/kubernetes/enhancements/blob/fddcbb9cbf3df39ded03bad71228265ac6e5215f/keps/sig-node/24-apparmor/README.md). +:::note +AppArmor syntax follows [KEP-24](https://github.com/kubernetes/enhancements/blob/fddcbb9cbf3df39ded03bad71228265ac6e5215f/keps/sig-node/24-apparmor/README.md). +::: ## Tips and tricks From 75e1fefd88fe46669970c52d016db5492d6120a7 Mon Sep 17 00:00:00 2001 From: Thomas Anderson <127358482+zc-devs@users.noreply.github.com> Date: Thu, 7 Mar 2024 12:25:19 +0300 Subject: [PATCH 5/9] Notes about image pull in Kube --- docs/docs/20-usage/41-registries.md | 4 ++++ docs/docs/30-administration/22-backends/40-kubernetes.md | 6 ++++++ 2 files changed, 10 insertions(+) diff --git a/docs/docs/20-usage/41-registries.md b/docs/docs/20-usage/41-registries.md index b87ae55c43..8508da8767 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/22-backends/40-kubernetes.md b/docs/docs/30-administration/22-backends/40-kubernetes.md index 8fed699d6c..c8f28f7e90 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 From 120ac3a20e44485859e93e43de4e7f86bbaf5a40 Mon Sep 17 00:00:00 2001 From: Thomas Anderson <127358482+zc-devs@users.noreply.github.com> Date: Thu, 7 Mar 2024 12:30:43 +0300 Subject: [PATCH 6/9] Deleted encryption docs --- .../30-administration/10-server-config.md | 24 ----- docs/docs/30-administration/40-encryption.md | 87 ------------------- 2 files changed, 111 deletions(-) delete mode 100644 docs/docs/30-administration/40-encryption.md diff --git a/docs/docs/30-administration/10-server-config.md b/docs/docs/30-administration/10-server-config.md index f9cf1fe946..4b6e0ce10d 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/40-encryption.md b/docs/docs/30-administration/40-encryption.md deleted file mode 100644 index 2f19700823..0000000000 --- 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. From 26a4e531d96828fc8f325173f3661529906ed457 Mon Sep 17 00:00:00 2001 From: Thomas Anderson <127358482+zc-devs@users.noreply.github.com> Date: Fri, 8 Mar 2024 16:18:44 +0300 Subject: [PATCH 7/9] prettier --- .../22-backends/40-kubernetes.md | 64 +++++++++---------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/docs/docs/30-administration/22-backends/40-kubernetes.md b/docs/docs/30-administration/22-backends/40-kubernetes.md index c8f28f7e90..b65e421f08 100644 --- a/docs/docs/30-administration/22-backends/40-kubernetes.md +++ b/docs/docs/30-administration/22-backends/40-kubernetes.md @@ -23,19 +23,19 @@ Here is an example definition with an arbitrary `resources` definition below the ```yaml steps: - - name: 'My kubernetes step' - image: alpine - commands: - - echo "Hello world" - backend_options: - kubernetes: - resources: - requests: - memory: 200Mi - cpu: 100m - limits: - memory: 400Mi - cpu: 1000m + - name: "My kubernetes step" + image: alpine + commands: + - echo "Hello world" + backend_options: + kubernetes: + resources: + requests: + memory: 200Mi + cpu: 100m + limits: + memory: 400Mi + cpu: 1000m ``` You can use [Limit Ranges](https://kubernetes.io/docs/concepts/policy/limit-range/) if you want to set the limits by per-namespace basis. @@ -93,7 +93,7 @@ steps: - go test backend_options: kubernetes: - serviceAccountName: 'my-service-account' + serviceAccountName: "my-service-account" resources: requests: memory: 128Mi @@ -103,10 +103,10 @@ steps: nodeSelector: beta.kubernetes.io/instance-type: p3.8xlarge tolerations: - - key: 'key1' - operator: 'Equal' - value: 'value1' - effect: 'NoSchedule' + - key: "key1" + operator: "Equal" + value: "value1" + effect: "NoSchedule" tolerationSeconds: 3600 ``` @@ -167,23 +167,23 @@ spec: 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 +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 +backend_options: + kubernetes: + securityContext: + apparmorProfile: + type: Localhost + localhostProfile: k8s-apparmor-example-deny-write ``` :::note @@ -198,8 +198,8 @@ CRI-O users currently need to configure the workspace for all workflows in order ```yaml workspace: - base: '/woodpecker' - path: '/' + base: "/woodpecker" + path: "/" ``` See [this issue](https://github.com/woodpecker-ci/woodpecker/issues/2510) for more details. From 188c9c1fde8ded18c57fb26f198c81c5b7bfd1e0 Mon Sep 17 00:00:00 2001 From: qwerty287 <80460567+qwerty287@users.noreply.github.com> Date: Fri, 8 Mar 2024 15:00:28 +0100 Subject: [PATCH 8/9] =?UTF-8?q?reformat,=20finally=E2=80=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../22-backends/40-kubernetes.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/docs/30-administration/22-backends/40-kubernetes.md b/docs/docs/30-administration/22-backends/40-kubernetes.md index b65e421f08..a79b63c182 100644 --- a/docs/docs/30-administration/22-backends/40-kubernetes.md +++ b/docs/docs/30-administration/22-backends/40-kubernetes.md @@ -23,19 +23,19 @@ Here is an example definition with an arbitrary `resources` definition below the ```yaml steps: - - name: "My kubernetes step" - image: alpine - commands: - - echo "Hello world" - backend_options: - kubernetes: - resources: - requests: - memory: 200Mi - cpu: 100m - limits: - memory: 400Mi - cpu: 1000m + - name: "My kubernetes step" + image: alpine + commands: + - echo "Hello world" + backend_options: + kubernetes: + resources: + requests: + memory: 200Mi + cpu: 100m + limits: + memory: 400Mi + cpu: 1000m ``` You can use [Limit Ranges](https://kubernetes.io/docs/concepts/policy/limit-range/) if you want to set the limits by per-namespace basis. From 17321711fc071bb0e5f743a4196e92cd95b27a0e Mon Sep 17 00:00:00 2001 From: qwerty287 Date: Fri, 8 Mar 2024 15:09:16 +0100 Subject: [PATCH 9/9] =?UTF-8?q?fix=20prettier=E2=80=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../22-backends/40-kubernetes.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/docs/30-administration/22-backends/40-kubernetes.md b/docs/docs/30-administration/22-backends/40-kubernetes.md index a79b63c182..e878b6a4f5 100644 --- a/docs/docs/30-administration/22-backends/40-kubernetes.md +++ b/docs/docs/30-administration/22-backends/40-kubernetes.md @@ -23,7 +23,7 @@ Here is an example definition with an arbitrary `resources` definition below the ```yaml steps: - - name: "My kubernetes step" + - name: 'My kubernetes step' image: alpine commands: - echo "Hello world" @@ -93,7 +93,7 @@ steps: - go test backend_options: kubernetes: - serviceAccountName: "my-service-account" + serviceAccountName: 'my-service-account' resources: requests: memory: 128Mi @@ -103,10 +103,10 @@ steps: nodeSelector: beta.kubernetes.io/instance-type: p3.8xlarge tolerations: - - key: "key1" - operator: "Equal" - value: "value1" - effect: "NoSchedule" + - key: 'key1' + operator: 'Equal' + value: 'value1' + effect: 'NoSchedule' tolerationSeconds: 3600 ``` @@ -198,8 +198,8 @@ CRI-O users currently need to configure the workspace for all workflows in order ```yaml workspace: - base: "/woodpecker" - path: "/" + base: '/woodpecker' + path: '/' ``` See [this issue](https://github.com/woodpecker-ci/woodpecker/issues/2510) for more details.