+ + +
+ +
+

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

+
+

Note

+

This module is part of the community.docker collection (version 3.6.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 allos to build Docker images using Docker’s buildx plugin (BuildKit).

    • +
+
+
+

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_cert

+

aliases: 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.

+
+
+
+

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.

+
+

debug

+

boolean

+

Debug mode

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+
+

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.

+

Default: "unix:///var/run/docker.sock"

+
+

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.

+
+

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

    • +
+
+

path

+

path / required

+

The path for the build environment.

+
+

platform

+

string

+

Platform in the format os[/arch[/variant]].

+
+

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"

    • +
+
+

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.

+
+

timeout

+

integer

+

The maximum amount of time in seconds to wait on a response from the API.

+

If the value is not specified in the task, the value of environment variable DOCKER_TIMEOUT will be used instead. If the environment variable is not set, the default value will be used.

+

Default: 60

+
+

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.

+

Note that this option had a default value localhost in older versions. It was removed in community.docker 3.0.0.

+
+
+

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
+
+
+
+
+

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)

    • +
+
+ +
+
+ + +
+