@ -29,31 +29,34 @@ options:
description :
- enable auto - removal of the container on daemon side when the container ' s process exits
type : bool
default : ' no '
default : no
version_added : " 2.4 "
blkio_weight :
description :
- Block IO ( relative weight ) , between 10 and 1000.
type : int
capabilities :
description :
- List of capabilities to add to the container .
type : list
cap_drop :
description :
- List of capabilities to drop from the container .
type : list
version_added : " 2.7 "
cleanup :
description :
- Use with I ( detach = false ) to remove the container after successful execution .
type : bool
default : ' no '
default : no
version_added : " 2.2 "
command :
description :
- 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 .
- Prior to version 2.4 , strings were split on commas .
type : raw
comparisons :
type : dict
description :
- Allows to specify how properties of existing containers are compared with
module options to decide whether the container should be recreated / updated
@ -72,50 +75,57 @@ options:
- The wildcard option C ( * ) can be used to set one of the default values C ( strict )
or C ( ignore ) to I ( all ) comparisons .
- See the examples for details .
type : dict
version_added : " 2.8 "
cpu_period :
description :
- Limit CPU CFS ( Completely Fair Scheduler ) period
type : int
cpu_quota :
description :
- Limit CPU CFS ( Completely Fair Scheduler ) quota
type : int
cpuset_cpus :
description :
- CPUs in which to allow execution C ( 1 , 3 ) or C ( 1 - 3 ) .
type : str
cpuset_mems :
description :
- Memory nodes ( MEMs ) in which to allow execution C ( 0 - 3 ) or C ( 0 , 1 )
type : str
cpu_shares :
description :
- CPU shares ( relative weight ) .
type : int
detach :
description :
- 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 ) .
type : bool
default : true
default : yes
devices :
description :
- " 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 > "
type : list
device_read_bps :
description :
- " List of device path and read rate (bytes per second) from device. "
type : list
suboptions :
path :
type : str
required : true
description :
- Device path in the container .
rate :
type : str
required : true
required : yes
rate :
description :
- " Device read limit. Format: <number>[<unit>] "
- " Number is a positive integer. Unit can be one of C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
C ( T ) ( tebibyte ) , or C ( P ) ( pebibyte ) "
- " Omitting the unit defaults to bytes. "
type : str
required : yes
version_added : " 2.8 "
device_write_bps :
description :
@ -123,18 +133,18 @@ options:
type : list
suboptions :
path :
type : str
required : true
description :
- Device path in the container .
rate :
type : str
required : true
required : yes
rate :
description :
- " Device read limit. Format: <number>[<unit>] "
- " Number is a positive integer. Unit can be one of C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
C ( T ) ( tebibyte ) , or C ( P ) ( pebibyte ) "
- " Omitting the unit defaults to bytes. "
type : str
required : yes
version_added : " 2.8 "
device_read_iops :
description :
@ -142,16 +152,16 @@ options:
type : list
suboptions :
path :
type : str
required : true
description :
- Device path in the container .
type : str
required : yes
rate :
type : int
required : true
description :
- " Device read limit. "
- " Must be a positive integer. "
type : int
required : yes
version_added : " 2.8 "
device_write_iops :
description :
@ -159,29 +169,33 @@ options:
type : list
suboptions :
path :
type : str
required : true
description :
- Device path in the container .
type : str
required : yes
rate :
type : int
required : true
description :
- " Device read limit. "
- " Must be a positive integer. "
type : int
required : yes
version_added : " 2.8 "
dns_opts :
description :
- list of DNS options
type : list
dns_servers :
description :
- List of custom DNS servers .
type : list
dns_search_domains :
description :
- List of custom DNS search domains .
type : list
domainname :
description :
- Container domainname .
type : str
version_added : " 2.5 "
env :
description :
@ -189,23 +203,27 @@ options:
- Values which might be parsed as numbers , booleans or other types by the YAML parser must be quoted ( e . g . C ( " true " ) ) in order to avoid data loss .
type : dict
env_file :
version_added : " 2.2 "
description :
- Path to a file , present on the target , containing environment variables I ( FOO = BAR ) .
- If variable also present in C ( env ) , then C ( env ) value will override .
type : path
version_added : " 2.2 "
entrypoint :
description :
- Command that overwrites the default ENTRYPOINT of the image .
type : list
etc_hosts :
description :
- 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.
type : dict
exposed_ports :
description :
- 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 .
type : list
aliases :
- exposed
- expose
@ -213,26 +231,27 @@ options:
description :
- Use the kill command when stopping a running container .
type : bool
default : ' no '
default : no
aliases :
- forcekill
groups :
description :
- List of additional group names and / or IDs that the container process will run as .
type : list
healthcheck :
version_added : " 2.8 "
type : dict
description :
- ' Configure a check that is run to determine whether or not containers for this service are " healthy " .
See the docs for the L ( HEALTHCHECK Dockerfile instruction , https : / / docs . docker . com / engine / reference / builder / #healthcheck)
for details on how healthchecks work . '
- ' I(interval), I(timeout) and I(start_period) are specified as durations. They accept duration as a string in a format
that look like : C ( 5 h34m56s ) , C ( 1 m30s ) etc . The supported units are C ( us ) , C ( ms ) , C ( s ) , C ( m ) and C ( h ) '
type : dict
suboptions :
test :
description :
- Command to run to check health .
- Must be either a string or a list . If it is a list , the first item must be one of C ( NONE ) , C ( CMD ) or C ( CMD - SHELL ) .
type : raw
interval :
description :
- ' Time between running the check. (default: 30s) '
@ -249,9 +268,11 @@ options:
description :
- ' Start period for the container to initialize before starting health-retries countdown. (default: 0s) '
type : str
version_added : " 2.8 "
hostname :
description :
- Container hostname .
type : str
ignore_image :
description :
- When C ( state ) is I ( present ) or I ( started ) the module compares the configuration of an existing
@ -260,7 +281,7 @@ options:
recreated . Stop this behavior by setting C ( ignore_image ) to I ( True ) .
- I ( Warning : ) This option is ignored if C ( image ) or C ( * ) is used for the C ( comparisons ) option .
type : bool
default : ' no '
default : no
version_added : " 2.2 "
image :
description :
@ -268,63 +289,72 @@ options:
will be pulled from the registry . If no tag is included , C ( latest ) will be used .
- Can also be an image ID . If this is the case , the image is assumed to be available locally .
The C ( pull ) option is ignored for this case .
type : str
init :
description :
- Run an init inside the container that forwards signals and reaps processes .
This option requires Docker API 1.25 + .
type : bool
default : ' no '
default : no
version_added : " 2.6 "
interactive :
description :
- Keep stdin open after a container is launched , even if not attached .
type : bool
default : ' no '
default : no
ipc_mode :
description :
- 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 .
type : str
keep_volumes :
description :
- Retain volumes associated with a removed container .
type : bool
default : ' yes '
default : yes
kill_signal :
description :
- Override default signal used to kill a running container .
type : str
kernel_memory :
description :
- " Kernel memory limit (format: C(<number>[<unit>])). Number is a positive integer.
Unit can be C ( B ) ( byte ) , C ( K ) ( kibibyte , 1024 B ) , C ( M ) ( mebibyte ) , C ( G ) ( gibibyte ) ,
C ( T ) ( tebibyte ) , or C ( P ) ( pebibyte ) . Minimum is C ( 4 M ) . "
- Omitting the unit defaults to bytes .
type : str
labels :
description :
- Dictionary of key value pairs .
description :
- Dictionary of key value pairs .
type : dict
links :
description :
- List of name aliases for linked containers in the format C ( container_name : alias ) .
- Setting this will force container to be restarted .
type : list
log_driver :
description :
- Specify the logging driver . Docker uses I ( json - file ) by default .
- See L ( here , https : / / docs . docker . com / config / containers / logging / configure / ) for possible choices .
required : false
type : str
log_options :
description :
- Dictionary of options specific to the chosen log_driver . See https : / / docs . docker . com / engine / admin / logging / overview /
for details .
type : dict
aliases :
- log_opt
mac_address :
description :
- Container MAC address ( e . g . 92 : d0 : c6 : 0 a : 29 : 33 )
type : str
memory :
description :
- " Memory limit (format: C(<number>[<unit>])). Number is a positive integer.
Unit can be C ( B ) ( byte ) , C ( K ) ( kibibyte , 1024 B ) , C ( M ) ( mebibyte ) , C ( G ) ( gibibyte ) ,
C ( T ) ( tebibyte ) , or C ( P ) ( pebibyte ) . "
- Omitting the unit defaults to bytes .
type : str
default : ' 0 '
memory_reservation :
description :
@ -332,61 +362,67 @@ options:
Unit can be C ( B ) ( byte ) , C ( K ) ( kibibyte , 1024 B ) , C ( M ) ( mebibyte ) , C ( G ) ( gibibyte ) ,
C ( T ) ( tebibyte ) , or C ( P ) ( pebibyte ) . "
- Omitting the unit defaults to bytes .
type : str
memory_swap :
description :
- " Total memory limit (memory + swap, format: C(<number>[<unit>])).
Number is a positive integer . Unit can be C ( B ) ( byte ) , C ( K ) ( kibibyte , 1024 B ) ,
C ( M ) ( mebibyte ) , C ( G ) ( gibibyte ) , C ( T ) ( tebibyte ) , or C ( P ) ( pebibyte ) . "
- Omitting the unit defaults to bytes .
type : str
memory_swappiness :
description :
- Tune a container ' s memory swappiness behavior. Accepts an integer between 0 and 100.
- If not set , the value will be remain the same if container exists and will be inherited from the host machine if it is ( re - ) created .
type : int
name :
description :
- 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 .
required : true
type : str
required : yes
network_mode :
description :
- Connect the container to a network . Choices are " bridge " , " host " , " none " or " container:<name|id> "
type : str
userns_mode :
description :
- Set the user namespace mode for the container . Currently , the only valid value is C ( host ) .
version_added : " 2.5 "
description :
- Set the user namespace mode for the container . Currently , the only valid value is C ( host ) .
type : str
version_added : " 2.5 "
networks :
description :
- List of networks the container belongs to .
- For examples of the data structure and usage see EXAMPLES below .
- To remove a container from one or more networks , use the C ( purge_networks ) option .
- Note that as opposed to C ( docker run . . . ) , M ( docker_container ) does not remove the default
network if C ( networks ) is specified . You need to explicity use C ( purge_networks ) to enforce
the removal of the default network ( and all other networks not explicitly mentioned in C ( networks ) ) .
version_added : " 2.2 "
type : list
suboptions :
name :
type : str
required : true
description :
- The network ' s name.
ipv4_address :
type : str
description :
- The container ' s IPv4 address in this network.
ipv6_address :
type : str
description :
- The container ' s IPv6 address in this network.
links :
type : list
description :
- A list of containers to link to .
aliases :
type : list
description :
- List of aliases for this container in this network . These names
can be used in the network to reach this container .
description :
- List of networks the container belongs to .
- For examples of the data structure and usage see EXAMPLES below .
- To remove a container from one or more networks , use the C ( purge_networks ) option .
- Note that as opposed to C ( docker run . . . ) , M ( docker_container ) does not remove the default
network if C ( networks ) is specified . You need to explicity use C ( purge_networks ) to enforce
the removal of the default network ( and all other networks not explicitly mentioned in C ( networks ) ) .
type : list
suboptions :
name :
descriptio n:
- The network ' s name.
type : str
required : yes
ipv4_address :
description :
- The container ' s IPv4 address in this network.
type : str
ipv6_address :
description :
- The container ' s IPv6 address in this network.
type : str
links :
description :
- A list of containers to link to .
type : list
aliases :
description :
- List of aliases for this container in this network . These names
can be used in the network to reach this container .
type : list
version_added : " 2.2 "
oom_killer :
description :
- Whether or not to disable OOM Killer for the container .
@ -394,22 +430,24 @@ options:
oom_score_adj :
description :
- An integer value containing the score given to the container in order to tune OOM killer preferences .
type : int
version_added : " 2.2 "
output_logs :
description :
- If set to true , output of the container command will be printed ( only effective when log_driver is set to json - file or journald .
type : bool
default : ' no '
default : no
version_added : " 2.7 "
paused :
description :
- Use with the started state to pause running processes inside the container .
type : bool
default : ' no '
default : no
pid_mode :
description :
- Set the PID namespace mode for the container .
- Note that docker - py < 2.0 only supports ' host ' . Newer versions allow all values supported by the docker daemon .
type : str
pids_limit :
description :
- Set PIDs limit for the container . It accepts an integer value .
@ -420,7 +458,7 @@ options:
description :
- Give extended privileges to the container .
type : bool
default : ' no '
default : no
published_ports :
description :
- List of ports to publish from the container to the host .
@ -440,6 +478,7 @@ options:
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 C ( networks ) is the one that will be used .
type : list
aliases :
- ports
pull :
@ -449,32 +488,33 @@ options:
- I ( Note ) that images are only pulled when specified by name . If the image is specified
as a image ID ( hash ) , it cannot be pulled .
type : bool
default : ' no '
default : no
purge_networks :
description :
- Remove the container from ALL networks not included in C ( networks ) parameter .
- Any default networks such as I ( bridge ) , if not found in C ( networks ) , will be removed as well .
type : bool
default : ' no '
default : no
version_added : " 2.2 "
read_only :
description :
- Mount the container ' s root file system as read-only.
type : bool
default : ' no '
default : no
recreate :
description :
- Use with present and started states to force the re - creation of an existing container .
type : bool
default : ' no '
default : no
restart :
description :
- Use with started state to force a matching container to be stopped and restarted .
type : bool
default : ' no '
default : no
restart_policy :
description :
- Container restart policy . Place quotes around I ( no ) option .
type : str
choices :
- ' no '
- ' on-failure '
@ -482,10 +522,12 @@ options:
- ' unless-stopped '
restart_retries :
description :
- Use with restart policy to control maximum number of restart attempts .
- Use with restart policy to control maximum number of restart attempts .
type : int
runtime :
description :
- Runtime to use for the container .
type : str
version_added : " 2.8 "
shm_size :
description :
@ -493,9 +535,11 @@ options:
Unit can be C ( B ) ( byte ) , C ( K ) ( kibibyte , 1024 B ) , C ( M ) ( mebibyte ) , C ( G ) ( gibibyte ) ,
C ( T ) ( tebibyte ) , or C ( P ) ( pebibyte ) . "
- Omitting the unit defaults to bytes . If you omit the size entirely , the system uses C ( 64 M ) .
type : str
security_opts :
description :
- List of security options in the form of C ( " label:user:User " )
type : list
state :
description :
- ' I(absent) - A container matching the specified name will be stopped and removed. Use force_kill to kill the container
@ -517,6 +561,7 @@ options:
with a removed container . '
- ' I(stopped) - Asserts that the container is first I(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 . '
type : str
default : started
choices :
- absent
@ -526,6 +571,7 @@ options:
stop_signal :
description :
- Override default signal used to stop the container .
type : str
stop_timeout :
description :
- Number of seconds to wait for the container to stop before sending SIGKILL .
@ -536,34 +582,40 @@ options:
the behavior depends on the version of docker . New versions of docker will
always use the container ' s configured C(StopTimeout) value if it has been
configured .
type : int
trust_image_content :
description :
- If C ( yes ) , skip image verification .
type : bool
default : ' no '
default : no
tmpfs :
description :
- Mount a tmpfs directory
type : list
version_added : 2.4
tty :
description :
- Allocate a pseudo - TTY .
type : bool
default : ' no '
default : no
ulimits :
description :
- " List of ulimit options. A ulimit is specified as C(nofile:262144:262144) "
type : list
sysctls :
description :
- Dictionary of key , value pairs .
type : dict
version_added : 2.4
user :
description :
- 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 ] "
type : str
uts :
description :
- Set the UTS namespace mode for the container .
type : str
volumes :
description :
- List of volumes to mount within the container .
@ -575,15 +627,19 @@ options:
private label for the volume .
- " Note that Ansible 2.7 and earlier only supported one mode, which had to be one of C(ro), C(rw),
C ( z ) , and C ( Z ) . "
type : list
volume_driver :
description :
- The container volume driver .
type : str
volumes_from :
description :
- List of container names or Ids to get volumes from .
type : list
working_dir :
description :
- Path to the working directory .
type : str
version_added : " 2.4 "
extends_documentation_fragment :
- docker
@ -2794,7 +2850,7 @@ def main():
env = dict ( type = ' dict ' ) ,
env_file = dict ( type = ' path ' ) ,
etc_hosts = dict ( type = ' dict ' ) ,
exposed_ports = dict ( type = ' list ' , aliases= [ ' exposed ' , ' expose ' ] , elements = ' str ' ) ,
exposed_ports = dict ( type = ' list ' , elements= ' str ' , aliases= [ ' exposed ' , ' expose ' ] ) ,
force_kill = dict ( type = ' bool ' , default = False , aliases = [ ' forcekill ' ] ) ,
groups = dict ( type = ' list ' , elements = ' str ' ) ,
healthcheck = dict ( type = ' dict ' , options = dict (
@ -2825,7 +2881,7 @@ def main():
name = dict ( type = ' str ' , required = True ) ,
network_mode = dict ( type = ' str ' ) ,
networks = dict ( type = ' list ' , elements = ' dict ' , options = dict (
name = dict ( required = True , type = ' str ' ) ,
name = dict ( type = ' str ' , required = True ) ,
ipv4_address = dict ( type = ' str ' ) ,
ipv6_address = dict ( type = ' str ' ) ,
aliases = dict ( type = ' list ' , elements = ' str ' ) ,
@ -2838,18 +2894,18 @@ def main():
pid_mode = dict ( type = ' str ' ) ,
pids_limit = dict ( type = ' int ' ) ,
privileged = dict ( type = ' bool ' , default = False ) ,
published_ports = dict ( type = ' list ' , aliases= [ ' ports ' ] , elements = ' str ' ) ,
published_ports = dict ( type = ' list ' , elements= ' str ' , aliases= [ ' ports ' ] ) ,
pull = dict ( type = ' bool ' , default = False ) ,
purge_networks = dict ( type = ' bool ' , default = False ) ,
read_only = dict ( type = ' bool ' , default = False ) ,
recreate = dict ( type = ' bool ' , default = False ) ,
restart = dict ( type = ' bool ' , default = False ) ,
restart_policy = dict ( type = ' str ' , choices = [ ' no ' , ' on-failure ' , ' always ' , ' unless-stopped ' ] ) ,
restart_retries = dict ( type = ' int ' , default = None ),
runtime = dict ( type = ' str ' , default = None ),
restart_retries = dict ( type = ' int ' ),
runtime = dict ( type = ' str ' ),
security_opts = dict ( type = ' list ' , elements = ' str ' ) ,
shm_size = dict ( type = ' str ' ) ,
state = dict ( type = ' str ' , choices= [ ' absent ' , ' present ' , ' started ' , ' stopped ' ] , default = ' started ' ) ,
state = dict ( type = ' str ' , default= ' started ' , choices= [ ' absent ' , ' present ' , ' started ' , ' stopped ' ] ) ,
stop_signal = dict ( type = ' str ' ) ,
stop_timeout = dict ( type = ' int ' ) ,
sysctls = dict ( type = ' dict ' ) ,