docker_image – Manage docker images
docker_image – Manage docker images
Synopsis
- Build, load or pull an image, making the image available for creating containers. Also supports tagging an image into a repository and archiving an image to a .tar file.
- Since Ansible 2.8, it is recommended to explicitly specify the image’s source (source can be
build
,load
,pull
orlocal
). This will be required from Ansible 2.12 on.
Requirements
The below requirements are needed on the host that executes this module.
- Docker API >= 1.20
- Docker SDK for Python: Please note that the docker-py Python module has been superseded by docker (see here for details). For Python 2.6,
docker-py
must be used. Otherwise, it is recommended to install thedocker
Python module. Note that both modules should not be installed at the same time. Also note that when both modules are installed and one of them is uninstalled, the other might no longer function and a reinstall of it is required. - Docker SDK for Python >= 1.8.0 (use docker-py for Python 2.6)
Parameters
Parameter | Choices/Defaults | Comments | ||
---|---|---|---|---|
api_version string |
Default: "auto" |
The version of the Docker API running on the Docker Host. Defaults to the latest version of the API supported by Docker SDK for Python and the docker daemon. If the value is not specified in the task, the value of environment variable
| ||
archive_path path added in 2.1 |
Use with state | |||
build dictionary added in 2.8 |
Specifies options used for building images. | |||
args dictionary |
Provide a dictionary of Docker expects the value to be a string. For convenience any non-string values will be converted to strings. Requires Docker API >= 1.21. | |||
cache_from list |
List of image names to consider as cache source. | |||
container_limits dictionary |
A dictionary of limits applied to each container created by the build process. | |||
cpusetcpus string |
CPUs in which to allow execution, e.g., "0-3", "0,1". | |||
cpushares integer |
CPU shares (relative weight). | |||
memory integer |
Set memory limit for build. | |||
memswap integer |
Total memory (memory + swap), -1 to disable swap. | |||
dockerfile string |
Use with state This can also include a relative path (relative to path). | |||
http_timeout integer |
Timeout for HTTP requests during the image build operation. Provide a positive integer value for the number of seconds. | |||
network string |
The network to use for | |||
nocache boolean |
|
Do not use cache when building an image. | ||
path path / required |
Use with state 'present' to build an image. Will be the path to a directory containing the context and Dockerfile for building an image. | |||
pull boolean |
|
When building an image downloads any updates to the FROM image in Dockerfile. The default is currently | ||
rm boolean |
|
Remove intermediate containers after build. | ||
use_config_proxy boolean |
|
If set to Needs Docker SDK for Python >= 3.7.0. | ||
buildargs dictionary added in 2.2 |
Provide a dictionary of Docker expects the value to be a string. For convenience any non-string values will be converted to strings. Requires Docker API >= 1.21. Please use build.args instead. This option will be removed in Ansible 2.12. | |||
ca_cert 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
| |||
client_cert path |
Path to the client's TLS certificate file. If the value is not specified in the task and the environment variable
| |||
client_key path |
Path to the client's TLS key file. If the value is not specified in the task and the environment variable
| |||
container_limits dictionary added in 2.1 |
A dictionary of limits applied to each container created by the build process. Please use build.container_limits instead. This option will be removed in Ansible 2.12. | |||
cpusetcpus string |
CPUs in which to allow execution, e.g., "0-3", "0,1". | |||
cpushares integer |
CPU shares (relative weight). | |||
memory integer |
Set memory limit for build. | |||
memswap integer |
Total memory (memory + swap), -1 to disable swap. | |||
debug boolean |
|
Debug mode | ||
docker_host string |
Default: "unix://var/run/docker.sock" |
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, If the value is not specified in the task, the value of environment variable
| ||
dockerfile string added in 2.0 |
Use with state This can also include a relative path (relative to path). Please use build.dockerfile instead. This option will be removed in Ansible 2.12. | |||
force boolean added in 2.1 |
|
Use with state absent to un-tag and remove all images matching the specified name. Use with state Please stop using this option, and use the more specialized force options force_source, force_absent and force_tag instead. This option will be removed in Ansible 2.12. | ||
force_absent boolean added in 2.8 |
|
Use with state absent to un-tag and remove all images matching the specified name. | ||
force_source boolean added in 2.8 |
|
Use with state | ||
force_tag boolean added in 2.8 |
|
Use with state | ||
http_timeout integer added in 2.1 |
Timeout for HTTP requests during the image build operation. Provide a positive integer value for the number of seconds. Please use build.http_timeout instead. This option will be removed in Ansible 2.12. | |||
load_path path added in 2.2 |
Use with state Set source to | |||
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) are not supported. | |||
nocache boolean |
|
Do not use cache when building an image. Please use build.nocache instead. This option will be removed in Ansible 2.12. | ||
path path |
Use with state 'present' to build an image. Will be the path to a directory containing the context and Dockerfile for building an image. Set source to Please use build.path instead. This option will be removed in Ansible 2.12.
| |||
pull boolean added in 2.1 |
|
When building an image downloads any updates to the FROM image in Dockerfile. Please use build.pull instead. This option will be removed in Ansible 2.12. The default is currently | ||
push boolean added in 2.2 |
|
Push the image to the registry. Specify the registry as part of the name or repository parameter. | ||
repository string added in 2.1 |
Full path to a repository. Use with state | |||
rm boolean added in 2.1 |
|
Remove intermediate containers after build. Please use build.rm instead. This option will be removed in Ansible 2.12. | ||
source string added in 2.8 |
|
Determines where the module will try to retrieve the image from. Use Use Use Use Before Ansible 2.12, the value of this option will be auto-detected to be backwards compatible, but a warning will be issued if it is not explicitly specified. From Ansible 2.12 on, auto-detection will be disabled and this option will be made mandatory. | ||
ssl_version string |
Provide a valid SSL version number. Default value determined by ssl.py module. If the value is not specified in the task, the value of environment variable | |||
state string |
|
Make assertions about the state of an image. When When By default the image will be pulled from Docker Hub, or the registry specified in the image's name. Note that this will change in Ansible 2.12, so to make sure that you are pulling, set source to
| ||
tag string |
Default: "latest" |
Used to select an image when pulling. Will be added to the image when pushing, tagging or building. Defaults to latest. If name parameter format is name:tag, then tag value from name will take precedence. | ||
timeout integer |
Default: 60 |
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 | ||
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 If the value is not specified in the task, the value of environment variable | ||
tls_hostname string |
Default: "localhost" |
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 | ||
use_tls string added in 2.0 |
|
DEPRECATED. Whether to use tls to connect to the docker daemon. Set to
Will be removed in Ansible 2.11. | ||
validate_certs 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
|
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_SSL_VERSION
,DOCKER_TLS
,DOCKER_TLS_VERIFY
andDOCKER_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://docker-py.readthedocs.io/en/stable/machine/ for more details. - When connecting to Docker daemon with TLS, you might need to install additional Python packages. For the Docker SDK for Python, version 2.4 or newer, this can be done by installing
docker[tls]
with pip. - Note that the Docker SDK for Python only allows to specify the path to the Docker configuration for very few functions. In general, it will use
$HOME/.docker/config.json
if theDOCKER_CONFIG
environment variable is not specified, and use$DOCKER_CONFIG/config.json
otherwise.
Examples
- name: pull an image
docker_image:
name: pacur/centos-7
source: pull
- name: Tag and push to docker hub
docker_image:
name: pacur/centos-7:56
repository: dcoppenhagan/myimage:7.56
push: yes
source: local
- name: Tag and push to local registry
docker_image:
# Image will be centos:7
name: centos
# Will be pushed to localhost:5000/centos:7
repository: localhost:5000/centos
tag: 7
push: yes
source: local
- name: Add tag latest to image
docker_image:
name: myimage:7.1.2
repository: myimage:latest
# As 'latest' usually already is present, we need to enable overwriting of existing tags:
force_tag: yes
source: local
- name: Remove image
docker_image:
state: absent
name: registry.ansible.com/chouseknecht/sinatra
tag: v1
- name: Build an image and push it to a private repo
docker_image:
build:
path: ./sinatra
name: registry.ansible.com/chouseknecht/sinatra
tag: v1
push: yes
source: build
- name: Archive image
docker_image:
name: registry.ansible.com/chouseknecht/sinatra
tag: v1
archive_path: my_sinatra.tar
source: local
- name: Load image from archive and push to a private registry
docker_image:
name: localhost:5000/myimages/sinatra
tag: v1
push: yes
load_path: my_sinatra.tar
source: load
- name: Build image and with build args
docker_image:
name: myimage
build:
path: /path/to/build/dir
args:
log_volume: /var/log/myapp
listen_port: 8080
source: build
- name: Build image using cache source
docker_image:
name: myimage:latest
build:
path: /path/to/build/dir
# Use as cache source for building myimage
cache_from:
- nginx:latest
- alpine:3.8
source: build
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description |
---|---|---|
image dictionary |
success |
Image inspection results for the affected image.
|
Status
- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]
Authors
- Pavel Antonov (@softzilla)
- Chris Houseknecht (@chouseknecht)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/docker_image_module.html