2022-08-30 22:29:48 +02:00
---
name: Docker Buildx
2024-01-13 11:23:26 +01:00
icon: https://codeberg.org/woodpecker-plugins/docker-buildx/raw/branch/main/docker.svg
2022-08-30 22:29:48 +02:00
description: plugin to build multiarch Docker images with buildx
2024-01-14 23:40:27 +01:00
author: Woodpecker Authors
2022-09-25 19:25:16 +02:00
tags: [docker, image, container, build]
containerImage: woodpeckerci/plugin-docker-buildx
containerImageUrl: https://hub.docker.com/r/woodpeckerci/plugin-docker-buildx
2023-01-10 16:01:05 +01:00
url: https://codeberg.org/woodpecker-plugins/docker-buildx
2022-08-30 22:29:48 +02:00
---
2023-05-02 21:25:49 +02:00
Woodpecker CI plugin to build multiarch Docker images with buildx. This plugin is a fork of [thegeeklab/drone-docker-buildx ](https://github.com/thegeeklab/drone-docker-buildx/ ) which itself is a fork of [drone-plugins/drone-docker ](https://github.com/drone-plugins/drone-docker ).
2022-08-30 22:29:48 +02:00
## Features
- Build without push
- Use custom registries
2022-09-27 22:33:05 +02:00
- Build based on existing tags when needed
2022-11-10 15:01:35 +01:00
- Push to multiple registries/repos
2022-09-27 22:33:05 +02:00
It will automatically generate buildkit configuration to use custom CA certificate if following conditions are met:
- Setting `buildkit_config` is not set
2022-10-08 16:02:02 +02:00
- Custom `registry` /`logins` value is provided
2022-09-27 22:33:05 +02:00
- File exists `/etc/docker/certs.d/<registry-value>/ca.crt`
> NB! To mount custom CA you can use Woodpecker CI runner configuration environment `WOODPECKER_BACKEND_DOCKER_VOLUMES` with value `/etc/ssl/certs:/etc/ssl/certs:ro,/etc/docker/certs.d:/etc/docker/certs.d:ro`. And have created file `/etc/docker/certs.d/<registry-value>/ca.crt` with CA certificate on runner server host.
2022-08-30 22:29:48 +02:00
## Settings
2024-02-02 21:25:30 +01:00
2023-12-30 14:50:43 +01:00
| Settings Name | Default | Description |
2024-02-02 21:25:30 +01:00
| ------------------------- | ------------------------------- | ---------------------------------------------------- |
2023-12-30 14:50:43 +01:00
| `dry-run` | `false` | disables docker push |
| `repo` | _none_ | sets repository name for the image (can be a list) |
| `username` | _none_ | sets username to authenticates with |
| `password` | _none_ | sets password / token to authenticates with |
| `aws_access_key_id` | _none_ | sets AWS_ACCESS_KEY_ID for AWS ECR auth |
| `aws_secret_access_key` | _none_ | sets AWS_SECRET_ACCESS_KEY for AWS ECR auth |
| `aws_region` | `us-east-1` | sets AWS_DEFAULT_REGION for AWS ECR auth |
| `password` | _none_ | sets password / token to authenticates with |
| `email` | _none_ | sets email address to authenticates with |
| `registry` | `https://index.docker.io/v1/` | sets docker registry to authenticate with |
| `dockerfile` | `Dockerfile` | sets dockerfile to use for the image build |
| `tag` /`tags` | _none_ | sets repository tags to use for the image |
| `platforms` | _none_ | sets target platform for build |
2022-08-30 22:29:48 +02:00
2022-11-06 14:29:57 +01:00
## auto_tag
2022-11-10 15:01:35 +01:00
If set to true, it will use the `default_tag` ("latest") on tag event or default branch.
If it's a tag event it will also assume sem versioning and add tags accordingly (`x`, `x.x` and `x.x.x` ).
2022-11-06 14:29:57 +01:00
If it's not a tag event, and no default branch, automated tags are skipped.
2022-08-30 22:29:48 +02:00
## Examples
2023-05-02 21:25:49 +02:00
```yaml
2023-12-30 14:50:43 +01:00
publish-next-agent:
image: woodpeckerci/plugin-docker-buildx
secrets: [docker_username, docker_password]
settings:
repo: woodpeckerci/woodpecker-agent
dockerfile: docker/Dockerfile.agent.multiarch
platforms: windows/amd64,darwin/amd64,darwin/arm64,freebsd/amd64,linux/amd64,linux/arm64/v8
tag: next
when:
branch: ${CI_REPO_DEFAULT_BRANCH}
event: push
2022-08-30 22:29:48 +02:00
```
2023-05-02 21:25:49 +02:00
```yaml
2023-12-30 14:50:43 +01:00
publish:
image: woodpeckerci/plugin-docker-buildx
settings:
platforms: linux/386,linux/amd64,linux/arm/v6,linux/arm64/v8,linux/ppc64le,linux/riscv64,linux/s390x
repo: codeberg.org/${CI_REPO_OWNER}/hello
registry: codeberg.org
tags: latest
username: ${CI_REPO_OWNER}
password:
from_secret: cb_token
2022-08-30 22:29:48 +02:00
```
2023-05-02 21:25:49 +02:00
```yaml
2023-12-30 14:50:43 +01:00
docker-build:
image: woodpeckerci/plugin-docker-buildx
settings:
repo: codeberg.org/${CI_REPO_OWNER}/hello
registry: codeberg.org
2024-01-03 15:19:40 +01:00
dry-run: true
2023-12-30 14:50:43 +01:00
output: type=oci,dest=${CI_REPO_OWNER}-hello.tar
2022-09-20 18:02:35 +02:00
```
2022-08-30 22:29:48 +02:00
## Advanced Settings
2024-02-02 21:25:30 +01:00
| Settings Name | Default | Description |
| ------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mirror` | _none_ | sets a registry mirror to pull images |
| `storage_driver` | _none_ | sets the docker daemon storage driver |
| `storage_path` | `/var/lib/docker` | sets the docker daemon storage path |
| `bip` | _none_ | allows the docker daemon to bride ip address |
| `mtu` | _none_ | sets docker daemon custom mtu setting |
| `custom_dns` | _none_ | sets custom docker daemon dns server |
| `custom_dns_search` | _none_ | sets custom docker daemon dns search domain |
| `insecure` | `false` | allows the docker daemon to use insecure registries |
| `ipv6` | `false` | enables docker daemon IPv6 support |
| `experimental` | `false` | enables docker daemon experimental mode |
| `debug` | `false` | enables verbose debug mode for the docker daemon |
| `daemon_off` | `false` | disables the startup of the docker daemon |
| `buildkit_debug` | `false` | enables debug output of buildkit |
| `buildkit_config` | _none_ | sets content of the docker[buildkit TOML config](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md) |
| `buildkit_driveropt` | _none_ | adds one or multiple`--driver-opt` buildx arguments for the default buildkit builder instance |
| `tags_file` | _none_ | overrides the`tags` option with values in a file named `.tags` ; multiple tags can be specified separated by a newline |
| `context` | `.` | sets the path of the build context to use |
| `auto_tag` | `false` | generates tag names automatically based on git branch and git tag, tags supplied via`tags` are additionally added to the auto_tags without suffix |
| `default_suffix"` /`auto_tag_suffix` | _none_ | generates tag names with the given suffix |
| `default_tag` | `latest` | overrides the default tag name used when generating with`auto_tag` enabled |
| `label` /`labels` | _none_ | sets labels to use for the image in format`< name > =< value > ` |
| `default_labels` /`auto_labels` | `true` | sets docker image labels based on git information |
| `build_args` | _none_ | sets custom build arguments for the build |
| `build_args_from_env` | _none_ | forwards environment variables as custom arguments to the build |
| `quiet` | `false` | enables suppression of the build output |
| `target` | _none_ | sets the build target to use |
| `cache_from` | _none_ | sets configuration for cache source |
| `cache_to` | _none_ | sets configuration for cache export |
| `cache_images` | _none_ | a list of images to use as cache. |
| `pull_image` | `true` | enforces to pull base image at build time |
| `compress` | `false` | enables compression of the build context using gzip |
| `config` | _none_ | sets content of the docker daemon json config |
| `purge` | `true` | enables cleanup of the docker environment at the end of a build |
| `no_cache` | `false` | disables the usage of cached intermediate containers |
| `add_host` | _none_ | sets additional host:ip mapping |
| `output` | _none_ | sets build output in format`type=< type > [,< key > =< value > ]` |
| `logins` | _none_ | option to log into multiple registries |
| `env_file` | _none_ | load env vars from specified file |
| `ecr_create_repository` | `false` | creates the ECR repository if it does not exist |
| `ecr_lifecycle_policy` | _none_ | AWS ECR lifecycle policy |
| `ecr_repository_policy` | _none_ | AWS ECR repository policy |
| `ecr_scan_on_push` | _none_ | AWS: whether to enable image scanning on push |
2022-10-08 16:02:02 +02:00
## Multi registry push example
Only supported with `woodpecker >= 1.0.0` (next-da997fa3).
2023-05-02 21:25:49 +02:00
```yaml
2022-10-08 16:02:02 +02:00
settings:
repo: a6543/tmp,codeberg.org/6543/tmp
tag: demo
logins:
- registry: https://index.docker.io/v1/
username: a6543
password:
from_secret: docker_token
2024-01-18 19:28:42 +01:00
mirrors:
- "my-docker-mirror-host.local"
2022-10-08 16:02:02 +02:00
- registry: https://codeberg.org
username: "6543"
password:
from_secret: cb_token
2023-12-30 14:50:43 +01:00
- registry: https://< account-id > .dkr.ecr.< region > .amazonaws.com
aws_region: < region >
aws_access_key_id:
from_secret: aws_access_key_id
aws_secret_access_key:
from_secret: aws_secret_access_key
2022-10-08 16:02:02 +02:00
```
2023-10-25 11:58:02 +02:00
## Using `plugin-docker-buildx` behind a proxy
When performing a docker build behind a corporate proxy one needs to pass through the proxy settings to the plugin.
```yaml
variables:
# proxy config
- proxy_conf: & proxy_conf
2023-12-30 14:50:43 +01:00
- http_proxy: "http://X.Y.Z.Z:3128"
- https_proxy: "http://X.Y.Z.Z:3128"
- no_proxy: ".my-subdomain.com"
2023-10-25 11:58:02 +02:00
# deployment targets
2023-12-30 14:50:43 +01:00
- & publish_repos "codeberg.org/test"
2023-10-25 11:58:02 +02:00
# logins for deployment targets
- publish_logins: & publish_logins
2023-12-30 14:50:43 +01:00
- registry: https://codeberg.org
username:
from_secret: CODEBERG_USER
password:
from_secret: CODEBERG_TOKEN
2023-10-25 11:58:02 +02:00
steps:
test:
image: woodpeckerci/plugin-docker-buildx:2
environment:
# adding proxy in env for the plugin runtime itself.
- < < : * proxy_conf
privileged: true
settings:
2024-01-03 15:19:40 +01:00
dry-run: true
2023-10-25 11:58:02 +02:00
repo: *publish_repos
dockerfile: Dockerfile.multi
platforms: linux/amd64
auto_tag: true
logins: *publish_logins
# Adding custom dns server to lookup internal Docker Hub mirror.
# custom_dns:
# - 192.168.55.31
# - 192.168.55.32
# Adding an optional Docker Hub mirror for the nested dockerd.
# mirror: https://my-mirror.example.com
build_args:
# passthrough proxy config to the build process and Dockerfile CMDs itself.
- < < : * proxy_conf
2023-12-30 14:50:43 +01:00
# add driver-opt http config to tell buildkit + buildx to resolve external checksums through a proxy.
2023-10-25 11:58:02 +02:00
buildkit_driveropt:
2023-12-30 14:50:43 +01:00
- "env.http_proxy=http://X.Y.Z.Z:3128"
- "env.https_proxy=http://X.Y.Z.Z:3128"
- "env.no_proxy=.my-subdomain.com"
```
2024-02-02 21:25:30 +01:00
## Using cache images
You can provide a list of images to use for cache.
These cache images are built with mode=max, image-manifest=true, and oci-mediatypes=true.
This is to provide better usage of cache and better compatibility with image stores like Harbor.
```yaml
steps:
build:
image: woodpeckerci/plugin-docker-buildx
settings:
repo: hari/radiant
cache_images:
- hari/radiant:cache
- harbor.example.com/hari/radiant:cache
logins:
- registry: https://index.docker.io/v1/
username: hari
password:
from_secret: docker_password
- registry: https://harbor.example.com
username: hari
password:
from_secret: harbor_password
```
## Using other cache types
You can specify cache_to and cache_from to use specific settings.
For example you can configure an s3 object as cache.
More details can be found [in the docker docs ](https://docs.docker.com/build/cache/backends/ ).
```yaml
steps:
build:
image: woodpeckerci/plugin-docker-buildx
settings:
repo: hari/radiant
cache_to: type=s3,region=east,bucket=mystuff,name=radiant-cache
cache_from: type=s3,region=east,bucket=mystuff,name=radiant-cache
```
