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

Note

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

You might already have this collection installed if you are using the ansible package. 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.

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

string

Name under which the image is stored under.

If not provided, name and tag will be used.

Optional for outputs[].type=image.

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

See Also

See also

community.docker.docker_image_push

Push Docker images to registries.

community.docker.docker_image_tag

Tag Docker images with new names and/or tags.

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

image

dictionary

Image inspection results for the affected image.

Returned: success

Sample: {}

Authors

  • Felix Fontein (@felixfontein)