mirrors/woodpecker
1
0
Fork 0
mirror of https://github.com/woodpecker-ci/woodpecker.git synced 2025-01-04 06:38:43 +00:00
Code Issues Projects Releases Wiki Activity

Merge branch 'origin/main' into 'next-release/main'

Browse source
This commit is contained in:
oauth 2024-12-27 15:29:30 +00:00
commit 925b629d51
3 changed files with 184 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.cspell.json
View file

@ -39,6 +39,7 @@
"cpuset",
"creativecommons",
"Curr",
"CERTDIR",
"datacenter",
"DATASOURCE",
"Debugf",

93
docs/docs/20-usage/90-advanced-usage.md
View file

@ -127,3 +127,96 @@ WOODPECKER_ENVIRONMENT=first_var:value1,second_var:value2
```
Note that this tightly couples the server and app configurations (where the app is a completely separate application). But this is a good option for truly global variables which should apply to all steps in all pipelines for all apps.
## Docker in docker (dind) setup
:::warning
This set up will only work on trusted repositories and for security reasons should only be used in private environments.
See [project settings](./75-project-settings.md#trusted) to enable "trusted" mode.
:::
The snippet below shows how a step can communicate with the docker daemon running in a `docker:dind` service.
:::note
If your goal is to build/publish OCI images, consider using the [Docker Buildx Plugin](https://woodpecker-ci.org/plugins/Docker%20Buildx) instead.
:::
First we need to define a service running a docker with the `dind` tag.
This service must run in `privileged` mode:
```yaml
services:
- name: docker
image: docker:dind # use 'docker:<major-version>-dind' or similar in production
privileged: true
ports:
- 2376
```
Next, we need to set up TLS communication between the `dind` service and the step that wants to communicate with the docker daemon (unauthenticated TCP connections have been deprecated [as of docker v27](https://github.com/docker/cli/blob/v27.4.0/docs/deprecated.md#unauthenticated-tcp-connections) and will result in an error in v28).
This can be achieved by letting the daemon generate TLS certificates and share them with the client through an agent volume mount (`/opt/woodpeckerci/dind-certs` in the example below).
```diff
services:
- name: docker
image: docker:dind # use 'docker:<major-version>-dind' or similar in production
privileged: true
+ environment:
+ DOCKER_TLS_CERTDIR: /dind-certs
+ volumes:
+ - /opt/woodpeckerci/dind-certs:/dind-certs
ports:
- 2376
```
In the docker client step:
1. Set the `DOCKER_*` environment variables shown below to configure the connection with the daemon.
These generic docker environment variables that are framework-agnostic (e.g. frameworks like [TestContainers](https://testcontainers.com/), [Spring Boot Docker Compose](https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-docker-compose) do all respect them).
2. Mount the volume to the location where the daemon has created the certificates (`/opt/woodpeckerci/dind-certs`)
Test the connection with the docker client:
```diff
steps:
- name: test
image: docker:cli # in production use something like 'docker:<major version>-cli'
+ environment:
+ DOCKER_HOST: "tcp://docker:2376"
+ DOCKER_CERT_PATH: "/dind-certs/client"
+ DOCKER_TLS_VERIFY: "1"
+ volumes:
+ - /opt/woodpeckerci/dind-certs:/dind-certs
commands:
- docker version
```
This step should output the server and client version information if everything has been set up correctly.
Full example:
```yaml
steps:
- name: test
image: docker:cli # use 'docker:<major-version>-cli' or similar in production
environment:
DOCKER_HOST: 'tcp://docker:2376'
DOCKER_CERT_PATH: '/dind-certs/client'
DOCKER_TLS_VERIFY: '1'
volumes:
- /opt/woodpeckerci/dind-certs:/dind-certs
commands:
- docker version
services:
- name: docker
image: docker:dind # use 'docker:<major-version>-dind' or similar in production
privileged: true
environment:
DOCKER_TLS_CERTDIR: /dind-certs
volumes:
- /opt/woodpeckerci/dind-certs:/dind-certs
ports:
- 2376
```

90
docs/versioned_docs/version-2.8/20-usage/90-advanced-usage.md
View file

@ -127,3 +127,93 @@ WOODPECKER_ENVIRONMENT=first_var:value1,second_var:value2
```
Note that this tightly couples the server and app configurations (where the app is a completely separate application). But this is a good option for truly global variables which should apply to all steps in all pipelines for all apps.
## Docker in docker (dind) setup
:::warning
This set up will only work on trusted repositories and for security reasons should only be used in private environments.
See [project settings](./75-project-settings.md#trusted) to enable trusted mode.
:::
The snippet below shows how a step can communicate with the docker daemon via a `docker:dind` service.
:::note
If your aim ist to build/publish OCI images, consider using the [Docker Buildx Plugin](https://woodpecker-ci.org/plugins/Docker%20Buildx) instead.
:::
First we need to define a servie running a docker with the `dind` tag. This service must run in privileged mode:
```yaml
services:
- name: docker
image: docker:27.4-dind
privileged: true
ports:
- 2376
```
Next we need to set up TLS communication between the `dind` service and the step that wants to communicate with the docker daemon (since Unauthenticated TCP connections have been deprecated [as of docker v26](https://github.com/docker/cli/blob/v27.4.0/docs/deprecated.md#unauthenticated-tcp-connections) and will ve removed in release v28).
We can achieve this by letting the daemon generate TLS certificates for us and share them with the client via a volume mount in the agent (`/opt/woodpeckerci/dind-certs` in the example below).
```diff
services:
- name: docker
image: docker:27.4-dind
privileged: true
+ environment:
+ DOCKER_TLS_CERTDIR: /dind-certs
+ volumes:
+ - /opt/woodpeckerci/dind-certs:/dind-certs
ports:
- 2376
```
In the step that needs access to the daemon we need to:
1. Set the `DOCKER_*` environment variables shown below, setting up the connection with the daemon. These are standardized environment variables that should work with the docker client used by your framework of choice (e.g. [TestContainers](https://testcontainers.com/), [Spring Boot Docker Compose](https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-docker-compose) or similar).
2. Mount the volume where the daemon has created the certificates (`/opt/woodpeckerci/dind-certs`)
In this example we test the connection with the vanilla docker client:
```diff
steps:
- name: test
image: docker:27.4-cli
+ environment:
+ DOCKER_HOST: "tcp://docker:2376"
+ DOCKER_CERT_PATH: "/dind-certs/client"27.4-cli
+ DOCKER_TLS_VERIFY: "1"
+ volumes:
+ - /opt/woodpeckerci/dind-certs:/dind-certs
commands:
- docker version
```
This step should output version information of the client and the server if everything has been set correctly.
Complete example:
```yaml
steps:
- name: test
image: docker:27.4-cli
environment:
DOCKER_HOST: "tcp://docker:2376"
DOCKER_CERT_PATH: "/dind-certs/client"27.4-cli
DOCKER_TLS_VERIFY: "1"
volumes:
- /opt/woodpeckerci/dind-certs:/dind-certs
commands:
- docker version
services:
- name: docker
image: docker:27.4-dind
privileged: true
environment:
DOCKER_TLS_CERTDIR: /dind-certs
volumes:
- /opt/woodpeckerci/dind-certs:/dind-certs
ports:
- 2376
```