New in version 2.1.
The below requirements are needed on the host that executes this module.
Parameter |
Choices/Defaults |
Comments |
---|---|---|
api_version
|
Default:
default provided by docker-py
|
The version of the Docker API running on the Docker Host. Defaults to the latest version of the API supported by docker-py.
aliases: docker_api_version |
auto_remove
(added in 2.4) |
|
enable auto-removal of the container on daemon side when the container's process exits
|
blkio_weight
|
|
Block IO (relative weight), between 10 and 1000.
|
cacert_path
|
|
Use a CA certificate when performing server verification by providing the path to a CA certificate file.
aliases: tls_ca_cert |
capabilities
|
|
List of capabilities to add to the container.
|
cert_path
|
|
Path to the client's TLS certificate file.
aliases: tls_client_cert |
cleanup
(added in 2.2) |
|
Use with detach=false to remove the container after successful execution.
|
command
|
|
Command to execute when the container starts. A command may be either a string or a list. Prior to version 2.4, strings were split on commas.
|
cpu_period
|
Default:
no
|
Limit CPU CFS (Completely Fair Scheduler) period
|
cpu_quota
|
Default:
no
|
Limit CPU CFS (Completely Fair Scheduler) quota
|
cpu_shares
|
|
CPU shares (relative weight).
|
cpuset_cpus
|
|
CPUs in which to allow execution
1,3 or 1-3 . |
cpuset_mems
|
|
Memory nodes (MEMs) in which to allow execution
0-3 or 0,1 |
detach
|
|
Enable detached mode to leave the container running in background. If disabled, the task will reflect the status of the container run (failed if the command failed).
|
devices
|
|
List of host device bindings to add to the container. Each binding is a mapping expressed in the format: <path_on_host>:<path_in_container>:<cgroup_permissions>
|
dns_search_domains
|
|
List of custom DNS search domains.
|
dns_servers
|
|
List of custom DNS servers.
|
docker_host
|
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, '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'.
aliases: docker_url |
domainname
(added in 2.5) |
|
Container domainname.
|
entrypoint
|
|
Command that overwrites the default ENTRYPOINT of the image.
|
env
|
|
Dictionary of key,value pairs.
|
env_file
(added in 2.2) |
|
Path to a file containing environment variables FOO=BAR.
If variable also present in
env , then env value will override.Requires docker-py >= 1.4.0.
|
etc_hosts
|
|
Dict of host-to-IP mappings, where each host name is a key in the dictionary. Each host name will be added to the container's /etc/hosts file.
|
exposed_ports
|
|
List of additional container ports which informs Docker that the container listens on the specified network ports at runtime. If the port is already exposed using EXPOSE in a Dockerfile, it does not need to be exposed again.
aliases: exposed |
force_kill
|
|
Use the kill command when stopping a running container.
|
groups
|
|
List of additional group names and/or IDs that the container process will run as.
|
hostname
|
|
Container hostname.
|
ignore_image
(added in 2.2) |
|
When
state is present or started the module compares the configuration of an existing container to requested configuration. The evaluation includes the image version. If the image version in the registry does not match the container, the container will be recreated. Stop this behavior by setting ignore_image to True. |
image
|
|
Repository path and tag used to create the container. If an image is not found or pull is true, the image will be pulled from the registry. If no tag is included, 'latest' will be used.
|
interactive
|
|
Keep stdin open after a container is launched, even if not attached.
|
ipc_mode
|
|
Set the IPC mode for the container. Can be one of 'container:<name|id>' to reuse another container's IPC namespace or 'host' to use the host's IPC namespace within the container.
|
keep_volumes
|
|
Retain volumes associated with a removed container.
|
kernel_memory
|
Default:
no
|
Kernel memory limit (format: <number>[<unit>]). Number is a positive integer. Unit can be one of b, k, m, or g. Minimum is 4M.
|
key_path
|
|
Path to the client's TLS key file.
aliases: tls_client_key |
kill_signal
|
|
Override default signal used to kill a running container.
|
labels
|
|
Dictionary of key value pairs.
|
links
|
|
List of name aliases for linked containers in the format
container_name:alias |
log_driver
|
|
Specify the logging driver. Docker uses json-file by default.
|
log_options
|
|
Dictionary of options specific to the chosen log_driver. See https://docs.docker.com/engine/admin/logging/overview/ for details.
|
mac_address
|
|
Container MAC address (e.g. 92:d0:c6:0a:29:33)
|
memory
|
Default:
no
|
Memory limit (format: <number>[<unit>]). Number is a positive integer. Unit can be one of b, k, m, or g
|
memory_reservation
|
Default:
no
|
Memory soft limit (format: <number>[<unit>]). Number is a positive integer. Unit can be one of b, k, m, or g
|
memory_swap
|
Default:
no
|
Total memory limit (memory + swap, format:<number>[<unit>]). Number is a positive integer. Unit can be one of b, k, m, or g.
|
memory_swappiness
|
Default:
no
|
Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.
|
name
required |
|
Assign a name to a new container or match an existing container.
When identifying an existing container name may be a name or a long or short container ID.
|
network_mode
|
|
Connect the container to a network.
|
networks
(added in 2.2) |
|
List of networks the container belongs to.
Each network is a dict with keys
name , ipv4_address , ipv6_address , links , aliases .For each network
name is required, all other keys are optional.If included,
links or aliases are lists.For examples of the data structure and usage see EXAMPLES below.
To remove a container from one or more networks, use the
purge_networks option. |
oom_killer
|
|
Whether or not to disable OOM Killer for the container.
|
oom_score_adj
(added in 2.2) |
Default:
no
|
An integer value containing the score given to the container in order to tune OOM killer preferences.
|
paused
|
|
Use with the started state to pause running processes inside the container.
|
pid_mode
|
|
Set the PID namespace mode for the container. Currently only supports 'host'.
|
privileged
|
|
Give extended privileges to the container.
|
published_ports
|
|
List of ports to publish from the container to the host.
Use docker CLI syntax:
8000 , 9000:8000 , or 0.0.0.0:9000:8000 , where 8000 is a container port, 9000 is a host port, and 0.0.0.0 is a host interface.Container ports must be exposed either in the Dockerfile or via the
expose option.A value of all will publish all exposed container ports to random host ports, ignoring any other mappings.
If
networks parameter is provided, will inspect each network to see if there exists a bridge network with optional parameter com.docker.network.bridge.host_binding_ipv4. If such a network is found, then published ports where no host IP address is specified will be bound to the host IP pointed to by com.docker.network.bridge.host_binding_ipv4. Note that the first bridge network with a com.docker.network.bridge.host_binding_ipv4 value encountered in the list of networks is the one that will be used.aliases: ports |
pull
|
|
If true, always pull the latest version of an image. Otherwise, will only pull an image when missing.
|
purge_networks
(added in 2.2) |
|
Remove the container from ALL networks not included in
networks parameter.Any default networks such as bridge, if not found in
networks , will be removed as well. |
read_only
|
|
Mount the container's root file system as read-only.
|
recreate
|
|
Use with present and started states to force the re-creation of an existing container.
|
restart
|
|
Use with started state to force a matching container to be stopped and restarted.
|
restart_policy
|
|
Container restart policy. Place quotes around no option.
|
restart_retries
|
Default:
no
|
Use with restart policy to control maximum number of restart attempts.
|
security_opts
|
|
List of security options in the form of
"label:user:User" |
shm_size
|
|
Size of `/dev/shm`. The format is `<number><unit>`. `number` must be greater than `0`. Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g` (gigabytes).
Omitting the unit defaults to bytes. If you omit the size entirely, the system uses `64m`.
|
ssl_version
|
Default:
1.0
|
Provide a valid SSL version number. Default value determined by docker-py, currently 1.0.
|
state
|
|
absent - A container matching the specified name will be stopped and removed. Use force_kill to kill the container rather than stopping it. Use keep_volumes to retain volumes associated with the removed container.
present - Asserts the existence of a container matching the name and any provided configuration parameters. If no container matches the name, a container will be created. If a container matches the name but the provided configuration does not match, the container will be updated, if it can be. If it cannot be updated, it will be removed and re-created with the requested config. Image version will be taken into account when comparing configuration. To ignore image version use the ignore_image option. Use the recreate option to force the re-creation of the matching container. Use force_kill to kill the container rather than stopping it. Use keep_volumes to retain volumes associated with a removed container.
started - Asserts there is a running container matching the name and any provided configuration. If no container matches the name, a container will be created and started. If a container matching the name is found but the configuration does not match, the container will be updated, if it can be. If it cannot be updated, it will be removed and a new container will be created with the requested configuration and started. Image version will be taken into account when comparing configuration. To ignore image version use the ignore_image option. Use recreate to always re-create a matching container, even if it is running. Use restart to force a matching container to be stopped and restarted. Use force_kill to kill a container rather than stopping it. Use keep_volumes to retain volumes associated with a removed container.
stopped - Asserts that the container is first present, and then if the container is running moves it to a stopped state. Use force_kill to kill a container rather than stopping it.
|
stop_signal
|
|
Override default signal used to stop the container.
|
stop_timeout
|
|
Number of seconds to wait for the container to stop before sending SIGKILL.
|
sysctls
(added in 2.4) |
|
Dictionary of key,value pairs.
|
timeout
|
Default:
60
|
The maximum amount of time in seconds to wait on a response from the API.
|
tls
|
|
Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server.
|
tls_hostname
|
Default:
localhost
|
When verifying the authenticity of the Docker Host server, provide the expected name of the server.
|
tls_verify
|
|
Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server.
|
tmpfs
(added in 2.4) |
|
Mount a tmpfs directory
|
trust_image_content
|
|
If
yes , skip image verification. |
tty
|
|
Allocate a pseudo-TTY.
|
ulimits
|
|
List of ulimit options. A ulimit is specified as
nofile:262144:262144 |
user
|
|
Sets the username or UID used and optionally the groupname or GID for the specified command.
Can be [ user | user:group | uid | uid:gid | user:gid | uid:group ]
|
userns_mode
(added in 2.5) |
|
User namespace to use
|
uts
|
|
Set the UTS namespace mode for the container.
|
volume_driver
|
|
The container volume driver.
|
volumes
|
|
List of volumes to mount within the container.
Use docker CLI-style syntax:
/host:/container[:mode] You can specify a read mode for the mount with either
ro or rw .SELinux hosts can additionally use
z or Z to use a shared or private label for the volume. |
volumes_from
|
|
List of container names or Ids to get volumes from.
|
working_dir
(added in 2.4) |
|
Path to the working directory.
|
Note
- name: Create a data container
docker_container:
name: mydata
image: busybox
volumes:
- /data
- name: Re-create a redis container
docker_container:
name: myredis
image: redis
command: redis-server --appendonly yes
state: present
recreate: yes
exposed_ports:
- 6379
volumes_from:
- mydata
- name: Restart a container
docker_container:
name: myapplication
image: someuser/appimage
state: started
restart: yes
links:
- "myredis:aliasedredis"
devices:
- "/dev/sda:/dev/xvda:rwm"
ports:
- "8080:9000"
- "127.0.0.1:8081:9001/udp"
env:
SECRET_KEY: ssssh
- name: Container present
docker_container:
name: mycontainer
state: present
image: ubuntu:14.04
command: sleep infinity
- name: Stop a container
docker_container:
name: mycontainer
state: stopped
- name: Start 4 load-balanced containers
docker_container:
name: "container{{ item }}"
recreate: yes
image: someuser/anotherappimage
command: sleep 1d
with_sequence: count=4
- name: remove container
docker_container:
name: ohno
state: absent
- name: Syslogging output
docker_container:
name: myservice
image: busybox
log_driver: syslog
log_options:
syslog-address: tcp://my-syslog-server:514
syslog-facility: daemon
# NOTE: in Docker 1.13+ the "syslog-tag" option was renamed to "tag" for
# older docker installs, use "syslog-tag" instead
tag: myservice
- name: Create db container and connect to network
docker_container:
name: db_test
image: "postgres:latest"
networks:
- name: "{{ docker_network_name }}"
- name: Start container, connect to network and link
docker_container:
name: sleeper
image: ubuntu:14.04
networks:
- name: TestingNet
ipv4_address: "172.1.1.100"
aliases:
- sleepyzz
links:
- db_test:db
- name: TestingNet2
- name: Start a container with a command
docker_container:
name: sleepy
image: ubuntu:14.04
command: ["sleep", "infinity"]
- name: Add container to networks
docker_container:
name: sleepy
networks:
- name: TestingNet
ipv4_address: 172.1.1.18
links:
- sleeper
- name: TestingNet2
ipv4_address: 172.1.10.20
- name: Update network with aliases
docker_container:
name: sleepy
networks:
- name: TestingNet
aliases:
- sleepyz
- zzzz
- name: Remove container from one network
docker_container:
name: sleepy
networks:
- name: TestingNet2
purge_networks: yes
- name: Remove container from all networks
docker_container:
name: sleepy
purge_networks: yes
Common return values are documented here, the following are the fields unique to this module:
Key |
Returned |
Description |
---|---|---|
docker_container
dict
|
always |
Before 2.3 this was 'ansible_docker_container' but was renamed due to conflicts with the connection plugin.
Facts representing the current state of the container. Matches the docker inspection output.
Note that facts are not part of registered vars but accessible directly.
Empty if
state is absentIf detached is False, will include Output attribute containing any output from container run.
Sample:
{ "AppArmorProfile": "", "Args": [], "Config": { "AttachStderr": false, "AttachStdin": false, "AttachStdout": false, "Cmd": [ "/usr/bin/supervisord" ], "Domainname": "", "Entrypoint": null, "Env": [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" ], "ExposedPorts": { "443/tcp": {}, "80/tcp": {} }, "Hostname": "8e47bf643eb9", "Image": "lnmp_nginx:v1", "Labels": {}, "OnBuild": null, "OpenStdin": false, "StdinOnce": false, "Tty": false, "User": "", "Volumes": { "/tmp/lnmp/nginx-sites/logs/": {} }, ... }
|
This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.
Hint
If you notice any issues in this documentation you can edit this document to improve it.