community.docker.docker_image_build module – Build Docker images using Docker buildx

Note

This module is part of the community.docker collection (version 4.3.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.docker. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.docker.docker_image_build.

New in community.docker 3.6.0

Synopsis 

This module allows you to build Docker images using Docker’s buildx plugin (BuildKit).
Note that the module is not idempotent in the sense of classical Ansible modules. The only idempotence check is whether the built image already exists. This check can be disabled with the rebuild option.

Requirements 

The below requirements are needed on the host that executes this module.

Docker CLI with Docker buildx plugin

Parameters 

Parameter	Comments
api_version aliases: docker_api_version string	The version of the Docker API running on the Docker Host. Defaults to the latest version of the API supported by this collection and the docker daemon. If the value is not specified in the task, the value of environment variable `DOCKER_API_VERSION` will be used instead. If the environment variable is not set, the default value will be used. Default: `"auto"`
args dictionary	Provide a dictionary of `key:value` build arguments that map to Dockerfile ARG directive. Docker expects the value to be a string. For convenience any non-string values will be converted to strings.
ca_path aliases: ca_cert, tls_ca_cert, cacert_path path	Use a CA certificate when performing server verification by providing the path to a CA certificate file. If the value is not specified in the task and the environment variable `DOCKER_CERT_PATH` is set, the file `ca.pem` from the directory specified in the environment variable `DOCKER_CERT_PATH` will be used.
cache_from list / elements=string	List of image names to consider as cache source.
cli_context string	The Docker CLI context to use. Mutually exclusive with `docker_host`.
client_cert aliases: tls_client_cert, cert_path path	Path to the client’s TLS certificate file. If the value is not specified in the task and the environment variable `DOCKER_CERT_PATH` is set, the file `cert.pem` from the directory specified in the environment variable `DOCKER_CERT_PATH` will be used.
client_key aliases: tls_client_key, key_path path	Path to the client’s TLS key file. If the value is not specified in the task and the environment variable `DOCKER_CERT_PATH` is set, the file `key.pem` from the directory specified in the environment variable `DOCKER_CERT_PATH` will be used.
docker_cli path	Path to the Docker CLI. If not provided, will search for Docker CLI on the `PATH`.
docker_host aliases: docker_url string	The URL or Unix socket path used to connect to the Docker API. To connect to a remote host, provide the TCP connection string. For example, `tcp://192.0.2.23:2376`. If TLS is used to encrypt the connection, the module will automatically replace `tcp` in the connection URL with `https`. If the value is not specified in the task, the value of environment variable `DOCKER_HOST` will be used instead. If the environment variable is not set, the default value will be used. Mutually exclusive with `cli_context`. If neither `docker_host` nor `cli_context` are provided, the value `unix:///var/run/docker.sock` is used.
dockerfile string	Provide an alternate name for the Dockerfile to use when building an image. This can also include a relative path (relative to `path`).
etc_hosts dictionary	Extra hosts to add to `/etc/hosts` in building containers, as a mapping of hostname to IP address. Instead of an IP address, the special value `host-gateway` can also be used, which resolves to the host’s gateway IP and allows building containers to connect to services running on the host.
labels dictionary	Dictionary of key value pairs.
name string / required	Image name. Name format will be one of: `name`, `repository/name`, `registry_server:port/name`. When pushing or pulling an image the name can optionally include the tag by appending `:tag_name`. Note that image IDs (hashes) and names with digest cannot be used.
network string	The network to use for `RUN` build instructions.
nocache boolean	Do not use cache when building an image. Choices: `false` ← (default) `true`
outputs list / elements=dictionary added in community.docker 3.10.0	Output destinations. You can provide a list of exporters to export the built image in various places. Note that not all exporters might be supported by the build driver used. Note that depending on how this option is used, no image with name `name` and tag `tag` might be created, which can cause the basic idempotency this module offers to not work. Providing an empty list to this option is equivalent to not specifying it at all. The default behavior is a single entry with `outputs[].type=image`. Note that since community.docker 4.2.0, an entry for `name`/`tag` is added if `outputs` has at least one entry and no entry has type `outputs[].type=image` and includes `name`/`tag` in `outputs[].name`. This is because the module would otherwise pass `--tag name:image` to the buildx plugin, which for some reason overwrites all images in `outputs` by the `name:image` provided in `name`/`tag`.
context string	Name for the Docker context where to import the result. Optional for `outputs[].type=docker`.
dest path	The destination path. Required for `outputs[].type=local`, `outputs[].type=tar`, `outputs[].type=oci`. Optional for `outputs[].type=docker`.
name list / elements=string	Name(s) under which the image is stored under. If not provided, `name` and `tag` will be used. Optional for `outputs[].type=image`. This can be a list of strings since community.docker 4.2.0.
push boolean	Whether to push the built image to a registry. Only used for `outputs[].type=image`. Choices: `false` ← (default) `true`
type string / required	The type of exporter to use. Choices: `"docker"`: This export type writes the single-platform result image as a Docker image specification tarball on the client. Tarballs created by this exporter are also OCI compatible. The destination can be provided in `outputs[].dest`. If not specified, the tar will be loaded automatically to the local image store. The Docker context where to import the result can be provided in `outputs[].context`. `"image"`: This exporter writes the build result as an image or a manifest list. When using this driver, the image will appear in `docker images`. The image name can be provided in `outputs[].name`. If it is not provided, `name` and `tag` will be used. Optionally, image can be automatically pushed to a registry by setting `outputs[].push=true`. `"local"`: This export type writes all result files to a directory on the client. The new files will be owned by the current user. On multi-platform builds, all results will be put in subdirectories by their platform. The destination has to be provided in `outputs[].dest`. `"oci"`: This export type writes the result image or manifest list as an OCI image layout tarball on the client. The destination has to be provided in `outputs[].dest`. `"tar"`: This export type export type writes all result files as a single tarball on the client. On multi-platform builds, all results will be put in subdirectories by their platform. The destination has to be provided in `outputs[].dest`.
path path / required	The path for the build environment.
platform list / elements=string	Platforms in the format `os[/arch[/variant]]`. Since community.docker 3.10.0 this can be a list of platforms, instead of just a single platform.
pull boolean	When building an image downloads any updates to the FROM image in Dockerfile. Choices: `false` ← (default) `true`
rebuild string	Defines the behavior of the module if the image to build (as specified in `name` and `tag`) already exists. Choices: `"never"` ← (default) `"always"`
secrets list / elements=dictionary added in community.docker 3.10.0	Secrets to expose to the build.
env string	Environment value of the secret. Only supported and required for `secrets[].type=env`.
id string / required	The secret identifier. The secret will be made available as a file in the container under `/run/secrets/<id>`.
src path	Source path of the secret. Only supported and required for `secrets[].type=file`.
type string / required	Type of the secret. Choices: `"env"`: Reads the secret from an environment variable on the target. The environment variable must be named in `secrets[].env`. Note that this requires the Buildkit plugin to have version 0.6.0 or newer. `"file"`: Reads the secret from a file on the target. The file must be specified in `secrets[].src`. `"value"`: Provides the secret from a given value `secrets[].value`. Note that the secret will be passed as an environment variable to `docker compose`. Use another mean of transport if you consider this not safe enough. Note that this requires the Buildkit plugin to have version 0.6.0 or newer.
value string	Value of the secret. Note that the secret will be passed as an environment variable to `docker compose`. Use another mean of transport if you consider this not safe enough. Only supported and required for `secrets[].type=value`.
shm_size string	Size of `/dev/shm` in format `<number>[<unit>]`. Number is positive integer. Unit can be `B` (byte), `K` (kibibyte, 1024B), `M` (mebibyte), `G` (gibibyte), `T` (tebibyte), or `P` (pebibyte). Omitting the unit defaults to bytes. If you omit the size entirely, Docker daemon uses `64M`.
tag string	Tag for the image name `name` that is to be tagged. If `name`‘s format is `name:tag`, then the tag value from `name` will take precedence. Default: `"latest"`
target string	When building an image specifies an intermediate build stage by name as a final stage for the resulting image.
tls boolean	Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server. Note that if `validate_certs` is set to `true` as well, it will take precedence. If the value is not specified in the task, the value of environment variable `DOCKER_TLS` will be used instead. If the environment variable is not set, the default value will be used. Choices: `false` ← (default) `true`
tls_hostname string	When verifying the authenticity of the Docker Host server, provide the expected name of the server. If the value is not specified in the task, the value of environment variable `DOCKER_TLS_HOSTNAME` will be used instead. If the environment variable is not set, the default value will be used.
validate_certs aliases: tls_verify boolean	Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server. If the value is not specified in the task, the value of environment variable `DOCKER_TLS_VERIFY` will be used instead. If the environment variable is not set, the default value will be used. Choices: `false` ← (default) `true`

Attributes 

Attribute	Support	Description
action_group	Action groups: community.docker.docker, docker	Use `group/docker` or `group/community.docker.docker` in `module_defaults` to set defaults for this module.
check_mode	Support: full	Can run in `check_mode` and return changed status prediction without modifying target.
diff_mode	Support: none	Will return details on what has changed (or possibly needs changing in `check_mode`), when in diff mode.

Notes 

Note

Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
This module does not use the Docker SDK for Python to communicate with the Docker daemon. It directly calls the Docker CLI program.

Examples 

- name: Build Python 3.12 image
  community.docker.docker_image_build:
    name: localhost/python/3.12:latest
    path: /home/user/images/python
    dockerfile: Dockerfile-3.12

- name: Build multi-platform image
  community.docker.docker_image_build:
    name: multi-platform-image
    tag: "1.5.2"
    path: /home/user/images/multi-platform
    platform:
      - linux/amd64
      - linux/arm64/v8

Return Values 

Common return values are documented here, the following are the fields unique to this module:

Key	Description
command list / elements=string added in community.docker 4.2.0	The command executed. Returned: success and for some failures
image dictionary	Image inspection results for the affected image. Returned: success Sample: `{}`

Authors

Felix Fontein (@felixfontein)

community.docker.docker_image_build module – Build Docker images using Docker buildx

Synopsis 

Requirements 

Parameters 

Attributes 

Notes 

See Also 

Examples 

Return Values 

Authors

Collection links