Warning
This module will be removed from Salt in version 3009 in favor of the docker Salt Extension.
Management of Docker Containers
New in version 2015.8.0.
Changed in version 2017.7.0: This module has replaced the legacy docker execution module.
docker Python module
Note
Older releases of the Python bindings for Docker were called docker-py in
PyPI. All releases of docker, and releases of docker-py >= 1.6.0 are
supported. These python bindings can easily be installed using
pip.install
:
salt myminion pip.install docker
To upgrade from docker-py to docker, you must first uninstall docker-py, and then install docker:
salt myminion pip.uninstall docker-py
salt myminion pip.install docker
If you have previously performed a docker login
from the minion, then the
credentials saved in ~/.docker/config.json
will be used for any actions
which require authentication. If not, then credentials can be configured in
any of the following locations:
Minion config file
Grains
Pillar data
Master config file (requires pillar_opts
to be set to True
in Minion config file in order to work)
Important
Versions prior to 3000 require that Docker credentials are configured in Pillar data. Be advised that Pillar data is still recommended though, because this keeps the configuration from being stored on the Minion.
Also, keep in mind that if one gets your ~/.docker/config.json
, the
password can be decoded from its contents.
The configuration schema is as follows:
docker-registries:
<registry_url>:
username: <username>
password: <password>
For example:
docker-registries:
hub:
username: foo
password: s3cr3t
Note
As of the 2016.3.7, 2016.11.4, and 2017.7.0 releases of Salt, credentials
for the Docker Hub can be configured simply by specifying hub
in place
of the registry URL. In earlier releases, it is necessary to specify the
actual registry URL for the Docker Hub (i.e.
https://index.docker.io/v1/
).
More than one registry can be configured. Salt will look for Docker credentials
in the docker-registries
Pillar key, as well as any key ending in
-docker-registries
. For example:
docker-registries:
'https://mydomain.tld/registry:5000':
username: foo
password: s3cr3t
foo-docker-registries:
https://index.foo.io/v1/:
username: foo
password: s3cr3t
bar-docker-registries:
https://index.bar.io/v1/:
username: foo
password: s3cr3t
To login to the configured registries, use the docker.login
function. This only needs to be done once for a
given registry, and it will store/update the credentials in
~/.docker/config.json
.
Note
For Salt releases before 2016.3.7 and 2016.11.4, docker.login
is not available. Instead, Salt will try to
authenticate using each of your configured registries for each push/pull,
behavior which is not correct and has been resolved in newer releases.
The following configuration options can be set to fine-tune how Salt uses Docker:
docker.url
: URL to the docker service (default: local socket).
docker.version
: API version to use (should not need to be set manually in
the vast majority of cases)
docker.exec_driver
: Execution driver to use, one of nsenter
,
lxc-attach
, or docker-exec
. See the Executing Commands Within a
Running Container section for more details on how
this config parameter is used.
These configuration options are retrieved using config.get
(click the link for further information).
Note
With the release of Docker 1.13.1, the Execution Driver has been removed.
Starting in versions 2016.3.6, 2016.11.4, and 2017.7.0, Salt defaults to
using docker exec
to run commands in containers, however for older Salt
releases it will be necessary to set the docker.exec_driver
config
option to either docker-exec
or nsenter
for Docker versions 1.13.1
and newer.
Multiple methods exist for executing commands within Docker containers:
lxc-attach: Default for older versions of docker
nsenter: Enters container namespace to run command
docker-exec: Native support for executing commands in Docker containers (added in Docker 1.3)
Adding a configuration option (see config.get
) called docker.exec_driver
will tell Salt which
execution driver to use:
docker.exec_driver: docker-exec
If this configuration option is not found, Salt will use the appropriate
interface (either nsenter or lxc-attach) based on the Execution Driver
value returned from docker info
. docker-exec will not be used by default,
as it is presently (as of version 1.6.2) only able to execute commands as the
effective user of the container. Thus, if a USER
directive was used to run
as a non-privileged user, docker-exec would be unable to perform the action as
root. Salt can still use docker-exec as an execution driver, but must be
explicitly configured (as in the example above) to do so at this time.
If possible, try to manually specify the execution driver, as it will save Salt a little work.
This execution module provides functions that shadow those from the cmd
module. They are as follows:
Return the Python representation of s
(a str
instance
containing a JSON document).
New in version 2019.2.0.
Apply states! This function will call highstate or state.sls based on the
arguments passed in, apply
is intended to be the main gateway for
all state executions.
CLI Example:
salt 'docker' docker.apply web01
salt 'docker' docker.apply web01 test
salt 'docker' docker.apply web01 test,pkgs
Changed in version 2018.3.0: If the built image should be tagged, then the repository and tag must
now be passed separately using the repository
and tag
arguments, rather than together in the (now deprecated) image
argument.
Builds a docker image from a Dockerfile or a URL
Path to directory on the Minion containing a Dockerfile
Optional repository name for the image being built
New in version 2018.3.0.
Tag name for the image (required if repository
is passed)
New in version 2018.3.0.
Deprecated since version 2018.3.0: Use both repository
and tag
instead
Set to False
to force the build process not to use the Docker image
cache, and pull all required intermediate image layers
Remove intermediate containers created during build
If True
: an API_Response
key will be present in the return
data, containing the raw output from the Docker API.
Allows for a file-like object containing the contents of the Dockerfile
to be passed in place of a file path
argument. This argument should
not be used from the CLI, only from other Salt code.
Allows for an alternative Dockerfile to be specified. Path to alternative Dockefile is relative to the build path for the Docker container.
New in version 2016.11.0.
A dictionary of build arguments provided to the docker build process.
RETURN DATA
A dictionary containing one or more of the following keys:
Id
- ID of the newly-built image
Time_Elapsed
- Time in seconds taken to perform the build
Intermediate_Containers
- IDs of containers created during the course
of the build process
(Only present if rm=False)
Images
- A dictionary containing one or more of the following keys:Already_Pulled
- Layers that that were already present on the
Minion
Pulled
- Layers that that were pulled
(Only present if the image specified by the "repository" and "tag" arguments was not present on the Minion, or if cache=False)
Status
- A string containing a summary of the pull action (usually a
message saying that an image was downloaded, or that it was up to date).
(Only present if the image specified by the "repository" and "tag" arguments was not present on the Minion, or if cache=False)
CLI Example:
salt myminion docker.build /path/to/docker/build/dir
salt myminion docker.build https://github.com/myuser/myrepo.git repository=myimage tag=latest
salt myminion docker.build /path/to/docker/build/dir dockerfile=Dockefile.different repository=myimage tag=dev
Executes a Salt function inside a running container
New in version 2016.11.0.
The container does not need to have Salt installed, but Python is required.
Container name or ID
Salt execution module function
CLI Example:
salt myminion docker.call test.ping
salt myminion test.arg arg1 arg2 key1=val1
salt myminion dockerng.call compassionate_mirzakhani test.arg arg1 arg2 key1=val1
Changed in version 2018.3.0: The repository and tag must now be passed separately using the
repository
and tag
arguments, rather than together in the (now
deprecated) image
argument.
Commits a container, thereby promoting it to an image. Equivalent to
running the docker commit
Docker CLI command.
Container name or ID to commit
Repository name for the image being committed
New in version 2018.3.0.
Tag name for the image
New in version 2018.3.0.
Deprecated since version 2018.3.0: Use both repository
and tag
instead
Commit message (Optional)
Author name (Optional)
RETURN DATA
A dictionary containing the following keys:
Id
- ID of the newly-created image
Image
- Name of the newly-created image
Time_Elapsed
- Time in seconds taken to perform the commit
CLI Example:
salt myminion docker.commit mycontainer myuser/myimage mytag
This function is an alias of compare_containers
.
New in version 2017.7.0.
Changed in version 2018.3.0: Renamed from
docker.compare_container
todocker.compare_containers
(old function name remains as an alias)Compare two containers' Config and and HostConfig and return any differences between the two.
- first
Name or ID of first container
- second
Name or ID of second container
- ignore
A comma-separated list (or Python list) of keys to ignore when comparing. This is useful when comparing two otherwise identical containers which have different hostnames.
CLI Examples:
salt myminion docker.compare_containers foo bar salt myminion docker.compare_containers foo bar ignore=Hostname
New in version 2018.3.0.
Returns the differences between two containers' networks. When a network is
only present one of the two containers, that network's diff will simply be
represented with True
for the side of the diff in which the network is
present) and False
for the side of the diff in which the network is
absent.
This function works by comparing the contents of both containers'
Networks
keys (under NetworkSettings
) in the return data from
docker.inspect_container
. Because each network contains
some items that either A) only set at runtime, B) naturally varying from
container to container, or both, by default the following keys in each
network are examined:
Aliases
Links
IPAMConfig
The exception to this is if IPAMConfig
is unset (i.e. null) in one
container but not the other. This happens when no static IP configuration
is set, and automatic IP configuration is in effect. So, in order to report
on changes between automatic IP configuration in one container and static
IP configuration in another container (as we need to do for the
docker_container.running
state), automatic IP configuration will also be checked in these cases.
This function uses the docker.compare_container_networks
minion config option to determine which keys to examine. This provides
flexibility in the event that features added in a future Docker release
necessitate changes to how Salt compares networks. In these cases, rather
than waiting for a new Salt release one can just set
docker.compare_container_networks
.
Changed in version 3000: This config option can now also be set in pillar data and grains.
Additionally, it can be set in the master config file, provided that
pillar_opts
is enabled on the minion.
Note
The checks for automatic IP configuration described above only apply if
IPAMConfig
is among the keys set for static IP checks in
docker.compare_container_networks
.
Name or ID of first container (old)
Name or ID of second container (new)
CLI Example:
salt myminion docker.compare_container_networks foo bar
New in version 2017.7.0.
Changed in version 2018.3.0: Renamed from docker.compare_container
to
docker.compare_containers
(old function name remains as an alias)
Compare two containers' Config and and HostConfig and return any differences between the two.
Name or ID of first container
Name or ID of second container
A comma-separated list (or Python list) of keys to ignore when comparing. This is useful when comparing two otherwise identical containers which have different hostnames.
CLI Examples:
salt myminion docker.compare_containers foo bar
salt myminion docker.compare_containers foo bar ignore=Hostname
New in version 2018.3.0.
Compare two networks and return any differences between the two
Name or ID of first container
Name or ID of second container
A comma-separated list (or Python list) of keys to ignore when comparing.
CLI Example:
salt myminion docker.compare_network foo bar
New in version 2015.8.3.
Changed in version 2017.7.0: Support for ipv4_address
argument added
Changed in version 2018.3.0: All arguments are now passed through to connect_container_to_network(), allowing for any new arguments added to this function to be supported automagically.
Connect container to network. See the connect_container_to_network() docs for information on supported arguments.
Container name or ID
Network name or ID
CLI Examples:
salt myminion docker.connect_container_to_network web-1 mynet
salt myminion docker.connect_container_to_network web-1 mynet ipv4_address=10.20.0.10
salt myminion docker.connect_container_to_network web-1 1f9d2454d0872b68dd9e8744c6e7a4c66b86f10abaccc21e14f7f014f729b2bc
New in version 2018.3.0.
Return a list of running containers attached to the specified network
Network name
If True
, return extended info about each container (IP
configuration, etc.)
CLI Example:
salt myminion docker.connected net_name
Copy a file from inside a container to the Minion
Container name
Path of the file on the container's filesystem
Destination on the Minion. Must be an absolute path. If the destination is a directory, the file will be copied into that directory.
Unless this option is set to True
, then if a file exists at the
location specified by the dest
argument, an error will be raised.
Create the parent directory on the container if it does not already exist.
RETURN DATA
A boolean (True
if successful, otherwise False
)
CLI Example:
salt myminion docker.copy_from mycontainer /var/log/nginx/access.log /home/myuser
Copy a file from the host into a container
Container name
File to be copied to the container. Can be a local path on the Minion or a remote file from the Salt fileserver.
Destination on the container. Must be an absolute path. If the destination is a directory, the file will be copied into that directory.
If not passed, the execution driver will be detected as described above.
Unless this option is set to True
, then if a file exists at the
location specified by the dest
argument, an error will be raised.
Create the parent directory on the container if it does not already exist.
RETURN DATA
A boolean (True
if successful, otherwise False
)
CLI Example:
salt myminion docker.copy_to mycontainer /tmp/foo /root/foo
This function is an alias of copy_from
.
Copy a file from inside a container to the Minion
- name
Container name
- source
Path of the file on the container's filesystem
- dest
Destination on the Minion. Must be an absolute path. If the destination is a directory, the file will be copied into that directory.
- overwriteFalse
Unless this option is set to
True
, then if a file exists at the location specified by thedest
argument, an error will be raised.- makedirsFalse
Create the parent directory on the container if it does not already exist.
RETURN DATA
A boolean (
True
if successful, otherwiseFalse
)CLI Example:
salt myminion docker.copy_from mycontainer /var/log/nginx/access.log /home/myuser
Create a new container
Image from which to create the container
Name for the new container. If not provided, Docker will randomly generate one for you (it will be included in the return data).
If True
, start container after creating it
New in version 2018.3.0.
This function translates Salt CLI or SLS input into the format which docker-py expects. However, in the event that Salt's translation logic fails (due to potential changes in the Docker Remote API, or to bugs in the translation code), this argument can be used to exert granular control over which arguments are translated and which are not.
Pass this argument as a comma-separated list (or Python list) of
arguments, and translation for each passed argument name will be
skipped. Alternatively, pass True
and all translation will be
skipped.
Skipping tranlsation allows for arguments to be formatted directly in the format which docker-py expects. This allows for API changes and other issues to be more easily worked around. An example of using this option to skip translation would be:
salt myminion docker.create image=centos:7.3.1611 skip_translate=environment environment="{'FOO': 'bar'}"
See the following links for more information:
Since many of docker-py's arguments differ in name from their CLI
counterparts (with which most Docker users are more familiar), Salt
detects usage of these and aliases them to the docker-py version of
that argument. However, if both the alias and the docker-py version of
the same argument (e.g. env
and environment
) are used, an error
will be raised. Set this argument to True
to suppress these errors
and keep the docker-py version of the argument.
For parameters which accept IP addresses as input, IP address
validation will be performed. To disable, set this to False
Timeout in seconds for the Docker client. This is not a timeout for this function, but for receiving a response from the API.
Note
This is only used if Salt needs to pull the requested image.
CONTAINER CONFIGURATION ARGUMENTS
Enable auto-removal of the container on daemon side when the
container’s process exits (analogous to running a docker container with
--rm
on the CLI).
Examples:
auto_remove=True
rm=True
Files/directories to bind mount. Each bind mount should be passed in one of the following formats:
<host_path>:<container_path>
- host_path
is mounted within
the container as container_path
with read-write access.
<host_path>:<container_path>:<selinux_context>
- host_path
is
mounted within the container as container_path
with read-write
access. Additionally, the specified selinux context will be set
within the container.
<host_path>:<container_path>:<read_only>
- host_path
is
mounted within the container as container_path
, with the
read-only or read-write setting explicitly defined.
<host_path>:<container_path>:<read_only>,<selinux_context>
-
host_path
is mounted within the container as container_path
,
with the read-only or read-write setting explicitly defined.
Additionally, the specified selinux context will be set within the
container.
<read_only>
can be either ro
for read-write access, or ro
for read-only access. When omitted, it is assumed to be read-write.
<selinux_context>
can be z
if the volume is shared between
multiple containers, or Z
if the volume should be private.
Note
When both <read_only>
and <selinux_context>
are specified,
there must be a comma before <selinux_context>
.
Binds can be expressed as a comma-separated list or a Python list, however in cases where both ro/rw and an selinux context are specified, the binds must be specified as a Python list.
Examples:
binds=/srv/www:/var/www:ro
binds=/srv/www:/var/www:rw
binds=/srv/www:/var/www
binds="['/srv/www:/var/www:ro,Z']"
binds="['/srv/www:/var/www:rw,Z']"
binds=/srv/www:/var/www:Z
Note
The second and third examples above are equivalent to each other, as are the last two examples.
Block IO weight (relative weight), accepts a weight value between 10 and 1000.
Example: blkio_weight=100
Block IO weight (relative device weight), specified as a list of
expressions in the format PATH:WEIGHT
Example: blkio_weight_device=/dev/sda:100
List of capabilities to add within the container. Can be passed as a comma-separated list or a Python list. Requires Docker 1.2.0 or newer.
Examples:
cap_add=SYS_ADMIN,MKNOD
cap_add="[SYS_ADMIN, MKNOD]"
List of capabilities to drop within the container. Can be passed as a comma-separated string or a Python list. Requires Docker 1.2.0 or newer.
Examples:
cap_drop=SYS_ADMIN,MKNOD
,
cap_drop="[SYS_ADMIN, MKNOD]"
Command to run in the container
Example: command=bash
or cmd=bash
Changed in version 2015.8.1: cmd
is now also accepted
CPUs on which which to allow execution, specified as a string
containing a range (e.g. 0-3
) or a comma-separated list of CPUs
(e.g. 0,1
).
Examples:
cpuset_cpus="0-3"
cpuset="0,1"
Memory nodes on which which to allow execution, specified as a string
containing a range (e.g. 0-3
) or a comma-separated list of MEMs
(e.g. 0,1
). Only effective on NUMA systems.
Examples:
cpuset_mems="0-3"
cpuset_mems="0,1"
The length of a CPU period in microseconds
Example: cpu_group=100000
Microseconds of CPU time that the container can get in a CPU period
Example: cpu_period=50000
CPU shares (relative weight), specified as an integer between 2 and 1024.
Example: cpu_shares=512
If True
, run the container's command in the background (daemon
mode)
Example: detach=True
List of host devices to expose within the container
Examples:
devices="/dev/net/tun,/dev/xvda1:/dev/xvda1,/dev/xvdb1:/dev/xvdb1:r"
devices="['/dev/net/tun', '/dev/xvda1:/dev/xvda1', '/dev/xvdb1:/dev/xvdb1:r']"
Limit read rate (bytes per second) from a device, specified as a list
of expressions in the format PATH:RATE
, where RATE
is either an
integer number of bytes, or a string ending in kb
, mb
, or
gb
.
Examples:
device_read_bps="/dev/sda:1mb,/dev/sdb:5mb"
device_read_bps="['/dev/sda:100mb', '/dev/sdb:5mb']"
Limit read rate (I/O per second) from a device, specified as a list
of expressions in the format PATH:RATE
, where RATE
is a number
of I/O operations.
Examples:
device_read_iops="/dev/sda:1000,/dev/sdb:500"
device_read_iops="['/dev/sda:1000', '/dev/sdb:500']"
Limit write rate (bytes per second) from a device, specified as a list
of expressions in the format PATH:RATE
, where RATE
is either an
integer number of bytes, or a string ending in kb
, mb
or
gb
.
Examples:
device_write_bps="/dev/sda:100mb,/dev/sdb:50mb"
device_write_bps="['/dev/sda:100mb', '/dev/sdb:50mb']"
Limit write rate (I/O per second) from a device, specified as a list
of expressions in the format PATH:RATE
, where RATE
is a number
of I/O operations.
Examples:
device_write_iops="/dev/sda:1000,/dev/sdb:500"
device_write_iops="['/dev/sda:1000', '/dev/sdb:500']"
List of DNS nameservers. Can be passed as a comma-separated list or a Python list.
Examples:
dns=8.8.8.8,8.8.4.4
dns="['8.8.8.8', '8.8.4.4']"
Note
To skip IP address validation, use validate_ip_addrs=False
Additional options to be added to the container’s resolv.conf
file
Example: dns_opt=ndots:9
List of DNS search domains. Can be passed as a comma-separated list or a Python list.
Examples:
dns_search=foo1.domain.tld,foo2.domain.tld
dns_search="[foo1.domain.tld, foo2.domain.tld]"
The domain name to use for the container
Example: domainname=domain.tld
Entrypoint for the container. Either a string (e.g. "mycmd --arg1
--arg2"
) or a Python list (e.g. "['mycmd', '--arg1', '--arg2']"
)
Examples:
entrypoint="cat access.log"
entrypoint="['cat', 'access.log']"
Either a dictionary of environment variable names and their values, or
a Python list of strings in the format VARNAME=value
.
Examples:
environment='VAR1=value,VAR2=value'
environment="['VAR1=value', 'VAR2=value']"
environment="{'VAR1': 'value', 'VAR2': 'value'}"
Additional hosts to add to the container's /etc/hosts file. Can be passed as a comma-separated list or a Python list. Requires Docker 1.3.0 or newer.
Examples:
extra_hosts=web1:10.9.8.7,web2:10.9.8.8
extra_hosts="['web1:10.9.8.7', 'web2:10.9.8.8']"
extra_hosts="{'web1': '10.9.8.7', 'web2': '10.9.8.8'}"
Note
To skip IP address validation, use validate_ip_addrs=False
List of additional group names and/or IDs that the container process will run as
Examples:
group_add=web,network
group_add="['web', 'network']"
Hostname of the container. If not provided, and if a name
has been
provided, the hostname
will default to the name
that was
passed.
Example: hostname=web1
Warning
If the container is started with network_mode=host
, the
hostname will be overridden by the hostname of the Minion.
Leave stdin open, even if not attached
Examples:
interactive=True
stdin_open=True
Set the IPC mode for the container. The default behavior is to create a private IPC namespace for the container, but this option can be used to change that behavior:
container:<container_name_or_id>
reuses another container shared
memory, semaphores and message queues
host
: use the host's shared memory, semaphores and message queues
Examples:
ipc_mode=container:foo
ipc=host
Warning
Using host
gives the container full access to local shared
memory and is therefore considered insecure.
Specifies the type of isolation technology used by containers
Example: isolation=hyperv
Note
The default value on Windows server is process
, while the
default value on Windows client is hyperv
. On Linux, only
default
is supported.
Add metadata to the container. Labels can be set both with and without values:
Examples:
labels=foo,bar=baz
labels="['foo', 'bar=baz']"
Changed in version 2018.3.0: Labels both with and without values can now be mixed. Earlier releases only permitted one method or the other.
Link this container to another. Links should be specified in the format
<container_name_or_id>:<link_alias>
. Multiple links can be passed,
ether as a comma separated list or a Python list.
Examples:
links=web1:link1,web2:link2
,
links="['web1:link1', 'web2:link2']"
links="{'web1': 'link1', 'web2': 'link2'}"
Set container's logging driver. Requires Docker 1.6 or newer.
Example:
log_driver=syslog
Note
The logging driver feature was improved in Docker 1.13 introducing option name changes. Please see Docker's Configure logging drivers documentation for more information.
Config options for the log_driver
config option. Requires Docker
1.6 or newer.
Example:
log_opt="syslog-address=tcp://192.168.0.42,syslog-facility=daemon"
log_opt="['syslog-address=tcp://192.168.0.42', 'syslog-facility=daemon']"
log_opt="{'syslog-address': 'tcp://192.168.0.42', 'syslog-facility': 'daemon'}"
Additional LXC configuration parameters to set before starting the container.
Examples:
lxc_conf="lxc.utsname=docker,lxc.arch=x86_64"
lxc_conf="['lxc.utsname=docker', 'lxc.arch=x86_64']"
lxc_conf="{'lxc.utsname': 'docker', 'lxc.arch': 'x86_64'}"
Note
These LXC configuration parameters will only have the desired effect if the container is using the LXC execution driver, which has been deprecated for some time.
MAC address to use for the container. If not specified, a random MAC address will be used.
Example: mac_address=01:23:45:67:89:0a
Memory limit. Can be specified in bytes or using single-letter units
(i.e. 512M
, 2G
, etc.). A value of 0
(the default) means no
memory limit.
Examples:
mem_limit=512M
memory=1073741824
Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.
Example: mem_swappiness=60
Total memory limit (memory plus swap). Set to -1
to disable swap. A
value of 0
means no swap limit.
Examples:
memswap_limit=1G
memory_swap=2147483648
If True
, networking will be disabled within the container
Example: network_disabled=True
One of the following:
bridge
- Creates a new network stack for the container on the
docker bridge
none
- No networking (equivalent of the Docker CLI argument
--net=none
). Not to be confused with Python's None
.
container:<name_or_id>
- Reuses another container's network stack
host
- Use the host's network stack inside the container
Warning
Using host
mode gives the container full access to the hosts
system's services (such as D-Bus), and is therefore considered
insecure.
Examples:
network_mode=null
network_mode=container:web1
Whether to disable OOM killer
Example: oom_kill_disable=False
An integer value containing the score given to the container in order to tune OOM killer preferences
Example: oom_score_adj=500
Set to host
to use the host container's PID namespace within the
container. Requires Docker 1.5.0 or newer.
Example: pid_mode=host
Set the container's PID limit. Set to -1
for unlimited.
Example: pids_limit=2000
Bind exposed ports which were exposed using the ports
argument to
docker.create
. These
should be passed in the same way as the --publish
argument to the
docker run
CLI command:
ip:hostPort:containerPort
- Bind a specific IP and port on the
host to a specific port within the container.
ip::containerPort
- Bind a specific IP and an ephemeral port to a
specific port within the container.
hostPort:containerPort
- Bind a specific port on all of the
host's interfaces to a specific port within the container.
containerPort
- Bind an ephemeral port on all of the host's
interfaces to a specific port within the container.
Multiple bindings can be separated by commas, or passed as a Python list. The below two examples are equivalent:
port_bindings="5000:5000,2123:2123/udp,8080"
port_bindings="['5000:5000', '2123:2123/udp', 8080]"
Port bindings can also include ranges:
port_bindings="14505-14506:4505-4506"
Note
When specifying a protocol, it must be passed in the
containerPort
value, as seen in the examples above.
A list of ports to expose on the container. Can be passed as comma-separated list or a Python list. If the protocol is omitted, the port will be assumed to be a TCP port.
Examples:
ports=1111,2222/udp
ports="[1111, '2222/udp']"
If True
, runs the exec process with extended privileges
Example: privileged=True
Publish all ports to the host
Example: publish_all_ports=True
If True
, mount the container’s root filesystem as read only
Example: read_only=True
Set a restart policy for the container. Must be passed as a string in
the format policy[:retry_count]
where policy
is one of
always
, unless-stopped
, or on-failure
, and retry_count
is an optional limit to the number of retries. The retry count is ignored
when using the always
or unless-stopped
restart policy.
Examples:
restart_policy=on-failure:5
restart_policy=always
Security configuration for MLS systems such as SELinux and AppArmor. Can be passed as a comma-separated list or a Python list.
Examples:
security_opt=apparmor:unconfined,param2:value2
security_opt='["apparmor:unconfined", "param2:value2"]'
Important
Some security options can contain commas. In these cases, this argument must be passed as a Python list, as splitting by comma will result in an invalid configuration.
Note
See the documentation for security_opt at https://docs.docker.com/engine/reference/run/#security-configuration
Size of /dev/shm
Example: shm_size=128M
The signal used to stop the container. The default is SIGTERM
.
Example: stop_signal=SIGRTMIN+3
Timeout to stop the container, in seconds
Example: stop_timeout=5
Storage driver options for the container
Examples:
storage_opt='dm.basesize=40G'
storage_opt="['dm.basesize=40G']"
storage_opt="{'dm.basesize': '40G'}"
Set sysctl options for the container
Examples:
sysctl='fs.nr_open=1048576,kernel.pid_max=32768'
sysctls="['fs.nr_open=1048576', 'kernel.pid_max=32768']"
sysctls="{'fs.nr_open': '1048576', 'kernel.pid_max': '32768'}"
A map of container directories which should be replaced by tmpfs mounts, and their corresponding mount options. Can be passed as Python list of PATH:VALUE mappings, or a Python dictionary. However, since commas usually appear in the values, this option cannot be passed as a comma-separated list.
Examples:
tmpfs="['/run:rw,noexec,nosuid,size=65536k', '/var/lib/mysql:rw,noexec,nosuid,size=600m']"
tmpfs="{'/run': 'rw,noexec,nosuid,size=65536k', '/var/lib/mysql': 'rw,noexec,nosuid,size=600m'}"
Attach TTYs
Example: tty=True
List of ulimits. These limits should be passed in the format
<ulimit_name>:<soft_limit>:<hard_limit>
, with the hard limit being
optional. Can be passed as a comma-separated list or a Python list.
Examples:
ulimits="nofile=1024:1024,nproc=60"
ulimits="['nofile=1024:1024', 'nproc=60']"
User under which to run exec process
Example: user=foo
Sets the user namsepace mode, when the user namespace remapping option is enabled.
Example: userns_mode=host
List of directories to expose as volumes. Can be passed as a comma-separated list or a Python list.
Examples:
volumes=/mnt/vol1,/mnt/vol2
volume="['/mnt/vol1', '/mnt/vol2']"
Container names or IDs from which the container will get volumes. Can be passed as a comma-separated list or a Python list.
Example: volumes_from=foo
, volumes_from=foo,bar
,
volumes_from="[foo, bar]"
Sets the container's volume driver
Example: volume_driver=foobar
Working directory inside the container
Examples:
working_dir=/var/log/nginx
workdir=/var/www/myapp
RETURN DATA
A dictionary containing the following keys:
Id
- ID of the newly-created container
Name
- Name of the newly-created container
CLI Example:
# Create a data-only container
salt myminion docker.create myuser/mycontainer volumes="/mnt/vol1,/mnt/vol2"
# Create a CentOS 7 container that will stay running once started
salt myminion docker.create centos:7 name=mycent7 interactive=True tty=True command=bash
Changed in version 2018.3.0: Support added for network configuration options other than driver
and driver_opts
, as well as IPAM configuration.
Create a new network
Note
This function supports all arguments for network and IPAM pool
configuration which are available for the release of docker-py
installed on the minion. For that reason, the arguments described below
in the NETWORK CONFIGURATION ARGUMENTS and IP ADDRESS
MANAGEMENT (IPAM)
sections may not accurately reflect what is available on the minion.
The docker.get_client_args
function can be used to check
the available arguments for the installed version of docker-py (they
are found in the network_config
and ipam_config
sections of the
return data), but Salt will not prevent a user from attempting to use
an argument which is unsupported in the release of Docker which is
installed. In those cases, network creation be attempted but will fail.
Network name
This function translates Salt CLI or SLS input into the format which docker-py expects. However, in the event that Salt's translation logic fails (due to potential changes in the Docker Remote API, or to bugs in the translation code), this argument can be used to exert granular control over which arguments are translated and which are not.
Pass this argument as a comma-separated list (or Python list) of
arguments, and translation for each passed argument name will be
skipped. Alternatively, pass True
and all translation will be
skipped.
Skipping tranlsation allows for arguments to be formatted directly in the format which docker-py expects. This allows for API changes and other issues to be more easily worked around. See the following links for more information:
New in version 2018.3.0.
Since many of docker-py's arguments differ in name from their CLI
counterparts (with which most Docker users are more familiar), Salt
detects usage of these and aliases them to the docker-py version of
that argument. However, if both the alias and the docker-py version of
the same argument (e.g. options
and driver_opts
) are used, an error
will be raised. Set this argument to True
to suppress these errors
and keep the docker-py version of the argument.
New in version 2018.3.0.
For parameters which accept IP addresses as input, IP address
validation will be performed. To disable, set this to False
Note
When validating subnets, whether or not the IP portion of the subnet is a valid subnet boundary will not be checked. The IP will portion will be validated, and the subnet size will be checked to confirm it is a valid number (1-32 for IPv4, 1-128 for IPv6).
New in version 2018.3.0.
NETWORK CONFIGURATION ARGUMENTS
Network driver
Example: driver=macvlan
Options for the network driver. Either a dictionary of option names and
values or a Python list of strings in the format varname=value
.
Examples:
driver_opts='macvlan_mode=bridge,parent=eth0'
driver_opts="['macvlan_mode=bridge', 'parent=eth0']"
driver_opts="{'macvlan_mode': 'bridge', 'parent': 'eth0'}"
If True
, checks for networks with duplicate names. Since networks
are primarily keyed based on a random ID and not on the name, and
network name is strictly a user-friendly alias to the network which is
uniquely identified using ID, there is no guaranteed way to check for
duplicates. This option providess a best effort, checking for any
networks which have the same name, but it is not guaranteed to catch
all name collisions.
Example: check_duplicate=False
If True
, restricts external access to the network
Example: internal=True
Add metadata to the network. Labels can be set both with and without values:
Examples (with values):
labels="label1=value1,label2=value2"
labels="['label1=value1', 'label2=value2']"
labels="{'label1': 'value1', 'label2': 'value2'}"
Examples (without values):
labels=label1,label2
labels="['label1', 'label2']"
Enable IPv6 on the network
Example: enable_ipv6=True
Note
While it should go without saying, this argument must be set to
True
to configure an IPv6 subnet. Also, if this option is
turned on without an IPv6 subnet explicitly configured, you will
get an error unless you have set up a fixed IPv6 subnet. Consult
the Docker IPv6 docs for information on how to do this.
If True
, and the network is in the global scope, non-service
containers on worker nodes will be able to connect to the network.
Example: attachable=True
Note
While support for this option was added in API version 1.24, its value was not added to the inpsect results until API version 1.26. The version of Docker which is available for CentOS 7 runs API version 1.24, meaning that while Salt can pass this argument to the API, it has no way of knowing the value of this config option in an existing Docker network.
Specify the network's scope (local
, global
or swarm
)
Example: scope=local
If True
, create an ingress network which provides the routing-mesh in
swarm mode
Example: ingress=True
IP ADDRESS MANAGEMENT (IPAM)
This function supports networks with either IPv4, or both IPv4 and IPv6. If
configuring IPv4, then you can pass the IPAM arguments as shown below, as
individual arguments on the Salt CLI. However, if configuring IPv4 and
IPv6, the arguments must be passed as a list of dictionaries, in the
ipam_pools
argument. See the CLI Examples below. These docs also
have more information on these arguments.
IPAM ARGUMENTS
IPAM driver to use, if different from the default one
Example: ipam_driver=foo
Options for the IPAM driver. Either a dictionary of option names
and values or a Python list of strings in the format
varname=value
.
Examples:
ipam_opts='foo=bar,baz=qux'
ipam_opts="['foo=bar', 'baz=quz']"
ipam_opts="{'foo': 'bar', 'baz': 'qux'}"
IPAM POOL ARGUMENTS
Subnet in CIDR format that represents a network segment
Example: subnet=192.168.50.0/25
Allocate container IP from a sub-range within the subnet
Subnet in CIDR format that represents a network segment
Example: iprange=192.168.50.64/26
IPv4 gateway for the master subnet
Example: gateway=192.168.50.1
A dictionary of mapping container names to IP addresses which should be
allocated for them should they connect to the network. Either a
dictionary of option names and values or a Python list of strings in
the format host=ipaddr
.
Examples:
aux_addresses='foo.bar.tld=192.168.50.10,hello.world.tld=192.168.50.11'
aux_addresses="['foo.bar.tld=192.168.50.10', 'hello.world.tld=192.168.50.11']"
aux_addresses="{'foo.bar.tld': '192.168.50.10', 'hello.world.tld': '192.168.50.11'}"
CLI Examples:
salt myminion docker.create_network web_network driver=bridge
# IPv4
salt myminion docker.create_network macvlan_network driver=macvlan driver_opts="{'parent':'eth0'}" gateway=172.20.0.1 subnet=172.20.0.0/24
# IPv4 and IPv6
salt myminion docker.create_network mynet ipam_pools='[{"subnet": "10.0.0.0/24", "gateway": "10.0.0.1"}, {"subnet": "fe3f:2180:26:1::60/123", "gateway": "fe3f:2180:26:1::61"}]'
Create a new volume
New in version 2015.8.4.
name of volume
Driver of the volume
Options for the driver volume
CLI Example:
salt myminion docker.create_volume my_volume driver=local
Return top-level images (those on which no other images depend) which do not have a tag assigned to them. These include:
Images which were once tagged but were later untagged, such as those which were superseded by committing a new copy of an existing tagged image.
Images which were loaded using docker.load
(or the docker load
Docker CLI
command), but not tagged.
Remove these images
If True
, and if prune=True
, then forcibly remove these images.
RETURN DATA
If prune=False
, the return data will be a list of dangling image IDs.
If prune=True
, the return data will be a dictionary with each key being
the ID of the dangling image, and the following information for each image:
Comment
- Any error encountered when trying to prune a dangling image
(Only present if prune failed)
Removed
- A boolean (True
if prune was successful, False
if
not)
CLI Example:
salt myminion docker.dangling
salt myminion docker.dangling prune=True
Returns the containers and images, if any, which depend on the given image
Name or ID of image
RETURN DATA
A dictionary containing the following keys:
Containers
- A list of containers which depend on the specified image
Images
- A list of IDs of images which depend on the specified image
CLI Example:
salt myminion docker.depends myimage
salt myminion docker.depends 0123456789ab
Get information on changes made to container's filesystem since it was
created. Equivalent to running the docker diff
Docker CLI command.
Container name or ID
RETURN DATA
A dictionary containing any of the following keys:
Added
- A list of paths that were added.
Changed
- A list of paths that were changed.
Deleted
- A list of paths that were deleted.
These keys will only be present if there were changes, so if the container has no differences the return dict will be empty.
CLI Example:
salt myminion docker.diff mycontainer
New in version 2018.3.0.
Runs docker.disconnect_container_from_network
on all
containers connected to the specified network, and returns the names of all
containers that were disconnected.
Network name or ID
CLI Examples:
salt myminion docker.disconnect_all_containers_from_network mynet
salt myminion docker.disconnect_all_containers_from_network 1f9d2454d0872b68dd9e8744c6e7a4c66b86f10abaccc21e14f7f014f729b2bc
New in version 2015.8.3.
Disconnect container from network
Container name or ID
Network name or ID
CLI Examples:
salt myminion docker.disconnect_container_from_network web-1 mynet
salt myminion docker.disconnect_container_from_network web-1 1f9d2454d0872b68dd9e8744c6e7a4c66b86f10abaccc21e14f7f014f729b2bc
Check if a given container exists
Container name or ID
RETURN DATA
A boolean (True
if the container exists, otherwise False
)
CLI Example:
salt myminion docker.exists mycontainer
Exports a container to a tar archive. It can also optionally compress that tar archive, and push it up to the Master.
Container name or ID
Absolute path on the Minion where the container will be exported
Unless this option is set to True
, then if a file exists at the
location specified by the path
argument, an error will be raised.
If True
, then if the parent directory of the file specified by the
path
argument does not exist, Salt will attempt to create it.
Can be set to any of the following:
gzip
or gz
for gzip compression
bzip2
or bz2
for bzip2 compression
xz
or lzma
for XZ compression (requires xz-utils, as well
as the lzma
module from Python 3.3, available in Python 2 and
Python 3.0-3.2 as backports.lzma)
This parameter can be omitted and Salt will attempt to determine the
compression type by examining the filename passed in the path
parameter.
If True
, the container will be pushed to the master using
cp.push
.
Note
This requires file_recv
to be set to True
on the
Master.
RETURN DATA
A dictionary will containing the following keys:
Path
- Path of the file that was exported
Push
- Reports whether or not the file was successfully pushed to the
Master
(Only present if push=True)
Size
- Size of the file, in bytes
Size_Human
- Size of the file, in human-readable units
Time_Elapsed
- Time in seconds taken to perform the export
CLI Examples:
salt myminion docker.export mycontainer /tmp/mycontainer.tar
salt myminion docker.export mycontainer /tmp/mycontainer.tar.xz push=True
This function is an alias of pause
.
Pauses a container
- name
Container name or ID
RETURN DATA
A dictionary will be returned, containing the following keys:
status
- A dictionary showing the prior state of the container as well as the new state
result
- A boolean noting whether or not the action was successful
comment
- Only present if the container cannot be pausedCLI Example:
salt myminion docker.pause mycontainer
New in version 2016.3.6,2016.11.4,2017.7.0.
Changed in version 2017.7.0: Replaced the container config args with the ones from the API's
create_container
function.
Changed in version 2018.3.0: Added ability to limit the input to specific client functions
Many functions in Salt have been written to support the full list of arguments for a given function in the docker-py Low-level API. However, depending on the version of docker-py installed on the minion, the available arguments may differ. This function will get the arguments for various functions in the installed version of docker-py, to be used as a reference.
An optional list of categories for which to limit the return. This is useful if only a specific set of arguments is desired, and also keeps other function's argspecs from needlessly being examined.
AVAILABLE LIMITS
create_container
- arguments accepted by create_container() (used
by docker.create
)
host_config
- arguments accepted by create_host_config() (used to
build the host config for docker.create
)
connect_container_to_network
- arguments used by
connect_container_to_network() to construct an endpoint config when
connecting to a network (used by
docker.connect_container_to_network
)
create_network
- arguments accepted by create_network() (used by
docker.create_network
)
ipam_config
- arguments used to create an IPAM pool (used by
docker.create_network
in the process of constructing an IPAM config dictionary)
CLI Example:
salt myminion docker.get_client_args
salt myminion docker.get_client_args logs
salt myminion docker.get_client_args create_container,connect_container_to_network
Apply a highstate to the running container
New in version 2019.2.0.
The container does not need to have Salt installed, but Python is required.
Container name or ID
Specify the environment from which to retrieve the SLS indicated by the mods parameter.
CLI Example:
salt myminion docker.highstate compassionate_mirzakhani
Return the history for an image. Equivalent to running the docker
history
Docker CLI command.
Container name or ID
If True
, the return data will simply be a list of the commands run
to build the container.
$ salt myminion docker.history nginx:latest quiet=True
myminion:
- FROM scratch
- ADD file:ef063ed0ae9579362871b9f23d2bc0781ef7cd4de6ac822052cf6c9c5a12b1e2 in /
- CMD [/bin/bash]
- MAINTAINER NGINX Docker Maintainers "docker-maint@nginx.com"
- apt-key adv --keyserver pgp.mit.edu --recv-keys 573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62
- echo "deb http://nginx.org/packages/mainline/debian/ wheezy nginx" >> /etc/apt/sources.list
- ENV NGINX_VERSION=1.7.10-1~wheezy
- apt-get update && apt-get install -y ca-certificates nginx=${NGINX_VERSION} && rm -rf /var/lib/apt/lists/*
- ln -sf /dev/stdout /var/log/nginx/access.log
- ln -sf /dev/stderr /var/log/nginx/error.log
- VOLUME [/var/cache/nginx]
- EXPOSE map[80/tcp:{} 443/tcp:{}]
- CMD [nginx -g daemon off;]
https://github.com/saltstack/salt/pull/22421
RETURN DATA
If quiet=False
, the return value will be a list of dictionaries
containing information about each step taken to build the image. The keys
in each step include the following:
Command
- The command executed in this build step
Id
- Layer ID
Size
- Cumulative image size, in bytes
Size_Human
- Cumulative image size, in human-readable units
Tags
- Tag(s) assigned to this layer
Time_Created_Epoch
- Time this build step was completed (Epoch
time)
Time_Created_Local
- Time this build step was completed (Minion's
local timezone)
CLI Example:
salt myminion docker.exists mycontainer
Returns information about the Docker images on the Minion. Equivalent to
running the docker images
Docker CLI command.
If True
, untagged images will also be returned
If True
, a docker inspect
will be run on each image returned.
RETURN DATA
A dictionary with each key being an image ID, and each value some general info about that image (time created, size, tags associated with the image, etc.)
CLI Example:
salt myminion docker.images
salt myminion docker.images all=True
Changed in version 2018.3.0: The repository and tag must now be passed separately using the
repository
and tag
arguments, rather than together in the (now
deprecated) image
argument.
Imports content from a local tarball or a URL as a new docker image
Content to import (URL or absolute path to a tarball). URL can be a
file on the Salt fileserver (i.e.
salt://path/to/rootfs/tarball.tar.xz
. To import a file from a
saltenv other than base
(e.g. dev
), pass it at the end of the
URL (ex. salt://path/to/rootfs/tarball.tar.xz?saltenv=dev
).
Repository name for the image being imported
New in version 2018.3.0.
Tag name for the image
New in version 2018.3.0.
Deprecated since version 2018.3.0: Use both repository
and tag
instead
If True
an api_response
key will be present in the return data,
containing the raw output from the Docker API.
RETURN DATA
A dictionary containing the following keys:
Id
- ID of the newly-created image
Image
- Name of the newly-created image
Time_Elapsed
- Time in seconds taken to perform the commit
CLI Example:
salt myminion docker.import /tmp/cent7-minimal.tar.xz myuser/centos
salt myminion docker.import /tmp/cent7-minimal.tar.xz myuser/centos:7
salt myminion docker.import salt://dockerimages/cent7-minimal.tar.xz myuser/centos:7
Returns a dictionary of system-wide information. Equivalent to running
the docker info
Docker CLI command.
CLI Example:
salt myminion docker.info
Changed in version 2017.7.0: Volumes and networks are now checked, in addition to containers and images.
This is a generic container/image/volume/network inspecton function. It will run the following functions in order:
The first of these to find a match will be returned.
Container/image/volume/network name or ID
RETURN DATA
A dictionary of container/image/volume/network information
CLI Example:
salt myminion docker.inspect mycontainer
salt myminion docker.inspect busybox
Retrieves container information. Equivalent to running the docker
inspect
Docker CLI command, but will only look for container information.
Container name or ID
RETURN DATA
A dictionary of container information
CLI Example:
salt myminion docker.inspect_container mycontainer
salt myminion docker.inspect_container 0123456789ab
Retrieves image information. Equivalent to running the docker inspect
Docker CLI command, but will only look for image information.
Note
To inspect an image, it must have been pulled from a registry or built locally. Images on a Docker registry which have not been pulled cannot be inspected.
Image name or ID
RETURN DATA
A dictionary of image information
CLI Examples:
salt myminion docker.inspect_image busybox
salt myminion docker.inspect_image centos:6
salt myminion docker.inspect_image 0123456789ab
Inspect Network
ID of network
CLI Example:
salt myminion docker.inspect_network 1f9d2454d0872b68dd9e8744c6e7a4c66b86f10abaccc21e14f7f014f729b2bc
Inspect Volume
New in version 2015.8.4.
Name of volume
CLI Example:
salt myminion docker.inspect_volume my_volume
Kill all processes in a running container instead of performing a graceful shutdown
Container name or ID
RETURN DATA
A dictionary will be returned, containing the following keys:
status
- A dictionary showing the prior state of the container as
well as the new state
result
- A boolean noting whether or not the action was successful
comment
- Only present if the container cannot be killed
CLI Example:
salt myminion docker.kill mycontainer
Returns a list of the IDs of layers belonging to the specified image, with the top-most layer (the one correspnding to the passed name) appearing last.
Image name or ID
CLI Example:
salt myminion docker.layers centos:7
Returns a list of containers by name. This is different from
docker.ps
in that
docker.ps
returns its results
organized by container ID.
If True
, stopped containers will be included in return data
CLI Example:
salt myminion docker.list_containers
Returns a list of tagged images
CLI Example:
salt myminion docker.list_tags
Changed in version 2018.3.0: If the loaded image should be tagged, then the repository and tag must
now be passed separately using the repository
and tag
arguments, rather than together in the (now deprecated) image
argument.
Load a tar archive that was created using docker.save
(or via the Docker CLI using docker save
).
Path to docker tar archive. Path can be a file on the Minion, or the
URL of a file on the Salt fileserver (i.e.
salt://path/to/docker/saved/image.tar
). To load a file from a
saltenv other than base
(e.g. dev
), pass it at the end of the
URL (ex. salt://path/to/rootfs/tarball.tar.xz?saltenv=dev
).
If specified, the topmost layer of the newly-loaded image will be
tagged with the specified repo using docker.tag
. If a repository name is provided, then
the tag
argument is also required.
New in version 2018.3.0.
Tag name to go along with the repository name, if the loaded image is to be tagged.
New in version 2018.3.0.
Deprecated since version 2018.3.0: Use both repository
and tag
instead
RETURN DATA
A dictionary will be returned, containing the following keys:
Path
- Path of the file that was saved
Layers
- A list containing the IDs of the layers which were loaded.
Any layers in the file that was loaded, which were already present on the
Minion, will not be included.
Image
- Name of tag applied to topmost layer
(Only present if tag was specified and tagging was successful)
Time_Elapsed
- Time in seconds taken to load the file
Warning
- Message describing any problems encountered in attempt to
tag the topmost layer
(Only present if tag was specified and tagging failed)
CLI Example:
salt myminion docker.load /path/to/image.tar
salt myminion docker.load salt://path/to/docker/saved/image.tar repository=myuser/myimage tag=mytag
New in version 2016.3.7,2016.11.4,2017.7.0.
Performs a docker login
to authenticate to one or more configured
repositories. See the documentation at the top of this page to configure
authentication credentials.
Multiple registry URLs (matching those configured in Pillar) can be passed, and Salt will attempt to login to just those registries. If no registry URLs are provided, Salt will attempt to login to all configured registries.
RETURN DATA
A dictionary containing the following keys:
Results
- A dictionary mapping registry URLs to the authentication
result. True
means a successful login, False
means a failed
login.
Errors
- A list of errors encountered during the course of this
function.
CLI Example:
salt myminion docker.login
salt myminion docker.login hub
salt myminion docker.login hub https://mydomain.tld/registry/
New in version 3001.
Performs a docker logout
to remove the saved authentication details for
one or more configured repositories.
Multiple registry URLs (matching those configured in Pillar) can be passed, and Salt will attempt to logout of just those registries. If no registry URLs are provided, Salt will attempt to logout of all configured registries.
RETURN DATA
A dictionary containing the following keys:
Results
- A dictionary mapping registry URLs to the authentication
result. True
means a successful logout, False
means a failed
logout.
Errors
- A list of errors encountered during the course of this
function.
CLI Example:
salt myminion docker.logout
salt myminion docker.logout hub
salt myminion docker.logout hub https://mydomain.tld/registry/
Changed in version 2018.3.0: Support for all of docker-py's logs() function's arguments, with the
exception of stream
.
Returns the logs for the container. An interface to docker-py's logs() function.
Container name or ID
Return stdout lines
Return stdout lines
Show timestamps
Output specified number of lines at the end of logs. Either an integer
number of lines or the string all
.
Show logs since the specified time, passed as a UNIX epoch timestamp.
Optionally, if timelib is installed on the minion the timestamp can be
passed as a string which will be resolved to a date using
timelib.strtodatetime()
.
If True
, this function will block until the container exits and
return the logs when it does. The default behavior is to return what is
in the log at the time this function is executed.
CLI Examples:
# All logs
salt myminion docker.logs mycontainer
# Last 100 lines of log
salt myminion docker.logs mycontainer tail=100
# Just stderr
salt myminion docker.logs mycontainer stdout=False
# Logs since a specific UNIX timestamp
salt myminion docker.logs mycontainer since=1511688459
# Flexible format for "since" argument (requires timelib)
salt myminion docker.logs mycontainer since='1 hour ago'
salt myminion docker.logs mycontainer since='1 week ago'
salt myminion docker.logs mycontainer since='1 fortnight ago'
Changed in version 2017.7.0: The names
and ids
can be passed as a comma-separated list now,
as well as a Python list.
Changed in version 2018.3.0: The Containers
key for each network is no longer always empty.
List existing networks
Filter by name
Filter by id
CLI Example:
salt myminion docker.networks names=network-web
salt myminion docker.networks ids=1f9d2454d0872b68dd9e8744c6e7a4c66b86f10abaccc21e14f7f014f729b2bc
Pauses a container
Container name or ID
RETURN DATA
A dictionary will be returned, containing the following keys:
status
- A dictionary showing the prior state of the container as
well as the new state
result
- A boolean noting whether or not the action was successful
comment
- Only present if the container cannot be paused
CLI Example:
salt myminion docker.pause mycontainer
Returns the PID of a container
Container name or ID
CLI Example:
salt myminion docker.pid mycontainer
salt myminion docker.pid 0123456789ab
Returns port mapping information for a given container. Equivalent to
running the docker port
Docker CLI command.
Container name or ID
Changed in version 2019.2.0: This value can now be a pattern expression (using the pattern-matching characters defined in fnmatch). If a pattern expression is used, this function will return a dictionary mapping container names which match the pattern to the mappings for those containers. When no pattern expression is used, a dictionary of the mappings for the specified container name will be returned.
If specified, get information for that specific port. Can be specified
either as a port number (i.e. 5000
), or as a port number plus the
protocol (i.e. 5000/udp
).
If this argument is omitted, all port mappings will be returned.
RETURN DATA
A dictionary of port mappings, with the keys being the port and the values being the mapping(s) for that port.
CLI Examples:
salt myminion docker.port mycontainer
salt myminion docker.port mycontainer 5000
salt myminion docker.port mycontainer 5000/udp
New in version 2019.2.0.
Prune Docker's various subsystems
Note
This requires docker-py version 2.1.0 or later.
If True
, prunes stopped containers (documentation)
If True
, prunes unused images (documentation)
If False
, prunes unreferenced networks (documentation)
If True
, clears the builder cache
Note
Only supported in Docker 17.07.x and newer. Additionally, filters do not apply to this argument.
If True
, prunes unreferenced volumes (documentation)
If True
, prunes containers, images, networks, and builder cache.
Assumed to be True
if none of containers
, images
,
networks
, or build
are set to True
.
Note
volumes=True
must still be used to prune volumes
dangling=True
(images only) - remove only dangling images
until=<timestamp>
- only remove objects created before given
timestamp. Not applicable to volumes. See the documentation links
above for examples of valid time expressions.
label
- only remove objects matching the label expression. Valid
expressions include labelname
or labelname=value
.
CLI Examples:
salt myminion docker.prune system=True
salt myminion docker.prune system=True until=12h
salt myminion docker.prune images=True dangling=True
salt myminion docker.prune images=True label=foo,bar=baz
Returns information about the Docker containers on the Minion. Equivalent
to running the docker ps
Docker CLI command.
If True
, stopped containers will also be returned
If True
, local host's network topology will be included
If True
, a docker inspect
will be run on each container
returned.
A dictionary of filters to be processed on the container list. Available filters:
exited (int): Only containers with specified exit code
status (str): One of restarting, running, paused, exited
label (str): format either "key" or "key=value"
RETURN DATA
A dictionary with each key being an container ID, and each value some general info about that container (time created, name, command, etc.)
CLI Example:
salt myminion docker.ps
salt myminion docker.ps all=True
salt myminion docker.ps filters="{'label': 'role=web'}"
Changed in version 2018.3.0: If no tag is specified in the image
argument, all tags for the
image will be pulled. For this reason is it recommended to pass
image
using the repo:tag
notation.
Pulls an image from a Docker registry
Image to be pulled
If True
, the Docker client will permit the use of insecure
(non-HTTPS) registries.
If True
, an API_Response
key will be present in the return
data, containing the raw output from the Docker API.
Note
This may result in a lot of additional return data, especially for larger images.
Timeout in seconds for the Docker client. This is not a timeout for this function, but for receiving a response from the API.
RETURN DATA
A dictionary will be returned, containing the following keys:
Layers
- A dictionary containing one or more of the following keys:Already_Pulled
- Layers that that were already present on the
Minion
Pulled
- Layers that that were pulled
Status
- A string containing a summary of the pull action (usually a
message saying that an image was downloaded, or that it was up to date).
Time_Elapsed
- Time in seconds taken to perform the pull
CLI Example:
salt myminion docker.pull centos
salt myminion docker.pull centos:6
Changed in version 2015.8.4: The Id
and Image
keys are no longer present in the return data.
This is due to changes in the Docker Remote API.
Pushes an image to a Docker registry. See the documentation at top of this page to configure authentication credentials.
Image to be pushed. If just the repository name is passed, then all
tagged images for the specified repo will be pushed. If the image name
is passed in repo:tag
notation, only the specified image will be
pushed.
If True
, the Docker client will permit the use of insecure
(non-HTTPS) registries.
If True
, an API_Response
key will be present in the return
data, containing the raw output from the Docker API.
Timeout in seconds for the Docker client. This is not a timeout for this function, but for receiving a response from the API.
RETURN DATA
A dictionary will be returned, containing the following keys:
Layers
- A dictionary containing one or more of the following keys:Already_Pushed
- Layers that that were already present on the
Minion
Pushed
- Layers that that were pushed
Time_Elapsed
- Time in seconds taken to perform the push
CLI Example:
salt myminion docker.push myuser/mycontainer
salt myminion docker.push myuser/mycontainer:mytag
Remove a network
Network name or ID
CLI Examples:
salt myminion docker.remove_network mynet
salt myminion docker.remove_network 1f9d2454d0872b68dd9e8744c6e7a4c66b86f10abaccc21e14f7f014f729b2bc
Remove a volume
New in version 2015.8.4.
Name of volume
CLI Example:
salt myminion docker.remove_volume my_volume
New in version 2017.7.0.
Renames a container. Returns True
if successful, and raises an error if
the API returns one. If unsuccessful and the API returns no error (should
not happen), then False
will be returned.
Name or ID of existing container
New name to assign to container
CLI Example:
salt myminion docker.rename foo bar
New in version 2018.3.0.
Given an image name (or partial image ID), return the full image ID. If no
match is found among the locally-pulled images, then False
will be
returned.
CLI Examples:
salt myminion docker.resolve_image_id foo
salt myminion docker.resolve_image_id foo:bar
salt myminion docker.resolve_image_id 36540f359ca3
New in version 2017.7.2.
Changed in version 2018.3.0: Instead of matching against pulled tags using
docker.list_tags
, this
function now simply inspects the passed image name using
docker.inspect_image
and returns the first matching tag. If no matching tags are found, it
is assumed that the passed image is an untagged image ID, and the full
ID is returned.
Inspects the specified image name and returns the first matching tag in the
inspect results. If the specified image is not pulled locally, this
function will return False
.
Image name to resolve. If the image is found but there are no tags, this means that the image name passed was an untagged image. In this case the image ID will be returned.
If True
, a list of all matching tags will be returned. If the image
is found but there are no tags, then a list will still be returned, but
it will simply contain the image ID.
New in version 2018.3.0.
Deprecated since version 2018.3.0.
CLI Examples:
salt myminion docker.resolve_tag busybox
salt myminion docker.resolve_tag centos:7 all=True
salt myminion docker.resolve_tag c9f378ac27d9
Restarts a container
Container name or ID
Timeout in seconds after which the container will be killed (if it has not yet gracefully shut down)
RETURN DATA
A dictionary will be returned, containing the following keys:
status
- A dictionary showing the prior state of the container as
well as the new state
result
- A boolean noting whether or not the action was successful
restarted
- If restart was successful, this key will be present and
will be set to True
.
CLI Examples:
salt myminion docker.restart mycontainer
salt myminion docker.restart mycontainer timeout=20
Run cmd.retcode
within a container
Container name or ID in which to run the command
Command to run
If not passed, the execution driver will be detected as described above.
Standard input to be used for the command
Level at which to log the output from the command. Set to quiet
to
suppress logging.
Use SaltStack's utils.vt to stream output to console.
If not passed, only a sane default PATH environment variable will be
set. If True
, all environment variables from the container's host
will be kept. Otherwise, a comma-separated list (or Python list) of
environment variable names can be passed, and those environment
variables will be kept.
CLI Example:
salt myminion docker.retcode mycontainer 'ls -l /etc'
Removes a container
Container name or ID
If True
, the container will be killed first before removal, as the
Docker API will not permit a running container to be removed. This
option is set to False
by default to prevent accidental removal of
a running container.
If True
, the container will be stopped first before removal, as the
Docker API will not permit a running container to be removed. This
option is set to False
by default to prevent accidental removal of
a running container.
New in version 2017.7.0.
Optional timeout to be passed to docker.stop
if stopping the container.
New in version 2018.3.0.
Also remove volumes associated with container
RETURN DATA
A list of the IDs of containers which were removed
CLI Example:
salt myminion docker.rm mycontainer
salt myminion docker.rm mycontainer force=True
Removes an image
Name (in repo:tag
notation) or ID of image.
If True
, the image will be removed even if the Minion has
containers created from that image
If True
, untagged parent image layers will be removed as well, set
this to False
to keep them.
RETURN DATA
A dictionary will be returned, containing the following two keys:
Layers
- A list of the IDs of image layers that were removed
Tags
- A list of the tags that were removed
Errors
- A list of any errors that were encountered
CLI Examples:
salt myminion docker.rmi busybox
salt myminion docker.rmi busybox force=True
salt myminion docker.rmi foo bar baz
Run cmd.run
within a container
Container name or ID in which to run the command
Command to run
If not passed, the execution driver will be detected as described above.
Standard input to be used for the command
Level at which to log the output from the command. Set to quiet
to
suppress logging.
Use SaltStack's utils.vt to stream output to console.
If not passed, only a sane default PATH environment variable will be
set. If True
, all environment variables from the container's host
will be kept. Otherwise, a comma-separated list (or Python list) of
environment variable names can be passed, and those environment
variables will be kept.
CLI Example:
salt myminion docker.run mycontainer 'ls -l /etc'
Run cmd.run_all
within a container
Note
While the command is run within the container, it is initiated from the host. Therefore, the PID in the return dict is from the host, not from the container.
Container name or ID in which to run the command
Command to run
If not passed, the execution driver will be detected as described above.
Standard input to be used for the command
Level at which to log the output from the command. Set to quiet
to
suppress logging.
Use SaltStack's utils.vt to stream output to console.
If not passed, only a sane default PATH environment variable will be
set. If True
, all environment variables from the container's host
will be kept. Otherwise, a comma-separated list (or Python list) of
environment variable names can be passed, and those environment
variables will be kept.
CLI Example:
salt myminion docker.run_all mycontainer 'ls -l /etc'
New in version 2018.3.0.
Equivalent to docker run
on the Docker CLI. Runs the container, waits
for it to exit, and returns the container's logs when complete.
Note
Not to be confused with docker.run
, which provides a cmd.run
-like interface for executing commands in a
running container.
This function accepts the same arguments as docker.create
, with the exception of start
. In
addition, it accepts the arguments from docker.logs
, with the exception of follow
, to
control how logs are returned. Finally, the bg
argument described below
can be used to optionally run the container in the background (the default
behavior is to block until the container exits).
If True
, this function will not wait for the container to exit and
will not return its logs. It will however return the container's name
and ID, allowing for docker.logs
to be used to view the logs.
Note
The logs will be inaccessible once the container exits if
auto_remove
is set to True
, so keep this in mind.
If True
, and if the named container already exists, this will
remove the existing container. The default behavior is to return a
False
result when the container already exists.
If True
, and the named container already exists, and replace
is also set to True
, then the container will be forcibly removed.
Otherwise, the state will not proceed and will return a False
result.
Networks to which the container should be connected. If automatic IP configuration is being used, the networks can be a simple list of network names. If custom IP configuration is being used, then this argument must be passed as a dictionary.
CLI Examples:
salt myminion docker.run_container myuser/myimage command=/usr/local/bin/myscript.sh
# Run container in the background
salt myminion docker.run_container myuser/myimage command=/usr/local/bin/myscript.sh bg=True
# Connecting to two networks using automatic IP configuration
salt myminion docker.run_container myuser/myimage command='perl /scripts/sync.py' networks=net1,net2
# net1 using automatic IP, net2 using static IPv4 address
salt myminion docker.run_container myuser/myimage command='perl /scripts/sync.py' networks='{"net1": {}, "net2": {"ipv4_address": "192.168.27.12"}}'
Run cmd.run_stderr
within a
container
Container name or ID in which to run the command
Command to run
If not passed, the execution driver will be detected as described above.
Standard input to be used for the command
Level at which to log the output from the command. Set to quiet
to
suppress logging.
Use SaltStack's utils.vt to stream output to console.
If not passed, only a sane default PATH environment variable will be
set. If True
, all environment variables from the container's host
will be kept. Otherwise, a comma-separated list (or Python list) of
environment variable names can be passed, and those environment
variables will be kept.
CLI Example:
salt myminion docker.run_stderr mycontainer 'ls -l /etc'
Run cmd.run_stdout
within a
container
Container name or ID in which to run the command
Command to run
If not passed, the execution driver will be detected as described above.
Standard input to be used for the command
Level at which to log the output from the command. Set to quiet
to
suppress logging.
Use SaltStack's utils.vt to stream output to console.
If not passed, only a sane default PATH environment variable will be
set. If True
, all environment variables from the container's host
will be kept. Otherwise, a comma-separated list (or Python list) of
environment variable names can be passed, and those environment
variables will be kept.
CLI Example:
salt myminion docker.run_stdout mycontainer 'ls -l /etc'
Saves an image and to a file on the minion. Equivalent to running the
docker save
Docker CLI command, but unlike docker save
this will
also work on named images instead of just images IDs.
Name or ID of image. Specify a specific tag by using the repo:tag
notation.
Absolute path on the Minion where the image will be exported
Unless this option is set to True
, then if the destination file
exists an error will be raised.
If True
, then if the parent directory of the file specified by the
path
argument does not exist, Salt will attempt to create it.
Can be set to any of the following:
gzip
or gz
for gzip compression
bzip2
or bz2
for bzip2 compression
xz
or lzma
for XZ compression (requires xz-utils, as well
as the lzma
module from Python 3.3, available in Python 2 and
Python 3.0-3.2 as backports.lzma)
This parameter can be omitted and Salt will attempt to determine the
compression type by examining the filename passed in the path
parameter.
Note
Since the Docker API does not support docker save
, compression
will be a bit slower with this function than with
docker.export
since the
image(s) will first be saved and then the compression done
afterwards.
If True
, the container will be pushed to the master using
cp.push
.
Note
This requires file_recv
to be set to True
on the
Master.
RETURN DATA
A dictionary will be returned, containing the following keys:
Path
- Path of the file that was saved
Push
- Reports whether or not the file was successfully pushed to the
Master
(Only present if push=True)
Size
- Size of the file, in bytes
Size_Human
- Size of the file, in human-readable units
Time_Elapsed
- Time in seconds taken to perform the save
CLI Examples:
salt myminion docker.save centos:7 /tmp/cent7.tar
salt myminion docker.save 0123456789ab cdef01234567 /tmp/saved.tar
Run cmd.script
within a container
Note
While the command is run within the container, it is initiated from the host. Therefore, the PID in the return dict is from the host, not from the container.
Container name or ID
Path to the script. Can be a local path on the Minion or a remote file from the Salt fileserver.
A string containing additional command-line options to pass to the script.
Templating engine to use on the script before running.
If not passed, the execution driver will be detected as described above.
Standard input to be used for the script
Level at which to log the output from the script. Set to quiet
to
suppress logging.
Use SaltStack's utils.vt to stream output to console.
If not passed, only a sane default PATH environment variable will be
set. If True
, all environment variables from the container's host
will be kept. Otherwise, a comma-separated list (or Python list) of
environment variable names can be passed, and those environment
variables will be kept.
CLI Example:
salt myminion docker.script mycontainer salt://docker_script.py
salt myminion docker.script mycontainer salt://scripts/runme.sh 'arg1 arg2 "arg 3"'
salt myminion docker.script mycontainer salt://scripts/runme.sh stdin='one\ntwo\nthree\nfour\nfive\n' output_loglevel=quiet
Run cmd.script_retcode
within a container
Container name or ID
Path to the script. Can be a local path on the Minion or a remote file from the Salt fileserver.
A string containing additional command-line options to pass to the script.
Templating engine to use on the script before running.
If not passed, the execution driver will be detected as described above.
Standard input to be used for the script
Level at which to log the output from the script. Set to quiet
to
suppress logging.
Use SaltStack's utils.vt to stream output to console.
If not passed, only a sane default PATH environment variable will be
set. If True
, all environment variables from the container's host
will be kept. Otherwise, a comma-separated list (or Python list) of
environment variable names can be passed, and those environment
variables will be kept.
CLI Example:
salt myminion docker.script_retcode mycontainer salt://docker_script.py
salt myminion docker.script_retcode mycontainer salt://scripts/runme.sh 'arg1 arg2 "arg 3"'
salt myminion docker.script_retcode mycontainer salt://scripts/runme.sh stdin='one\ntwo\nthree\nfour\nfive\n' output_loglevel=quiet
Searches the registry for an image
Search keyword
Limit results to official builds
Limit results to trusted builds
RETURN DATA
A dictionary with each key being the name of an image, and the following information for each image:
Description
- Image description
Official
- A boolean (True
if an official build, False
if
not)
Stars
- Number of stars the image has on the registry
Trusted
- A boolean (True
if a trusted build, False
if not)
CLI Example:
salt myminion docker.search centos
salt myminion docker.search centos official=True
Send a signal to a container. Signals can be either strings or numbers, and
are defined in the Standard Signals section of the signal(7)
manpage. Run man 7 signal
on a Linux host to browse this manpage.
Container name or ID
Signal to send to container
RETURN DATA
If the signal was successfully sent, True
will be returned. Otherwise,
an error will be raised.
CLI Example:
salt myminion docker.signal mycontainer SIGHUP
Apply the states defined by the specified SLS modules to the running container
New in version 2016.11.0.
The container does not need to have Salt installed, but Python is required.
Container name or ID
A string containing comma-separated list of SLS with defined states to apply to the container.
Specify the environment from which to retrieve the SLS indicated by the mods parameter.
Specify a Pillar environment to be used when applying states. This
can also be set in the minion config file using the
pillarenv
option. When neither the
pillarenv
minion config option nor this CLI argument is
used, all Pillar environments will be merged together.
New in version 2018.3.0.
Custom Pillar values, passed as a dictionary of key-value pairs
Note
Values passed this way will override Pillar values set via
pillar_roots
or an external Pillar source.
New in version 2018.3.0.
CLI Example:
salt myminion docker.sls compassionate_mirzakhani mods=rails,web
Changed in version 2018.3.0: The repository and tag must now be passed separately using the
repository
and tag
arguments, rather than together in the (now
deprecated) image
argument.
Build a Docker image using the specified SLS modules on top of base image
New in version 2016.11.0.
The base image does not need to have Salt installed, but Python is required.
Repository name for the image to be built
New in version 2018.3.0.
Tag name for the image to be built
New in version 2018.3.0.
Deprecated since version 2018.3.0: Use both repository
and tag
instead
Name or ID of the base image
A string containing comma-separated list of SLS with defined states to apply to the base image.
Specify the environment from which to retrieve the SLS indicated by the mods parameter.
Specify a Pillar environment to be used when applying states. This
can also be set in the minion config file using the
pillarenv
option. When neither the
pillarenv
minion config option nor this CLI argument is
used, all Pillar environments will be merged together.
New in version 2018.3.0.
Custom Pillar values, passed as a dictionary of key-value pairs
Note
Values passed this way will override Pillar values set via
pillar_roots
or an external Pillar source.
New in version 2018.3.0.
when set to True the container will not be committed at the end of the build. The dryrun succeed also when the state contains errors.
RETURN DATA
A dictionary with the ID of the new container. In case of a dryrun, the state result is returned and the container gets removed.
CLI Example:
salt myminion docker.sls_build imgname base=mybase mods=rails,web
Start a container
Container name or ID
RETURN DATA
A dictionary will be returned, containing the following keys:
status
- A dictionary showing the prior state of the container as
well as the new state
result
- A boolean noting whether or not the action was successful
comment
- Only present if the container cannot be started
CLI Example:
salt myminion docker.start mycontainer
Returns the state of the container
Container name or ID
RETURN DATA
A string representing the current state of the container (either
running
, paused
, or stopped
)
CLI Example:
salt myminion docker.state mycontainer
Stops a running container
Container name or ID
If True
and the container is paused, it will be unpaused before
attempting to stop the container.
Timeout in seconds after which the container will be killed (if it has not yet gracefully shut down)
Changed in version 2017.7.0: If this argument is not passed, then the container's configuration
will be checked. If the container was created using the
stop_timeout
argument, then the configured timeout will be
used, otherwise the timeout will be 10 seconds.
RETURN DATA
A dictionary will be returned, containing the following keys:
status
- A dictionary showing the prior state of the container as
well as the new state
result
- A boolean noting whether or not the action was successful
comment
- Only present if the container can not be stopped
CLI Examples:
salt myminion docker.stop mycontainer
salt myminion docker.stop mycontainer unpause=True
salt myminion docker.stop mycontainer timeout=20
Changed in version 2018.3.0: The repository and tag must now be passed separately using the
repository
and tag
arguments, rather than together in the (now
deprecated) image
argument.
Tag an image into a repository and return True
. If the tag was
unsuccessful, an error will be raised.
ID of image
Repository name for the image to be built
New in version 2018.3.0.
Tag name for the image to be built
New in version 2018.3.0.
Deprecated since version 2018.3.0: Use both repository
and tag
instead
Force apply tag
CLI Example:
salt myminion docker.tag 0123456789ab myrepo/mycontainer mytag
Runs the docker top command on a specific container
Container name or ID
CLI Example:
RETURN DATA
A list of dictionaries containing information about each process
salt myminion docker.top mycontainer
salt myminion docker.top 0123456789ab
This function is an alias of unpause
.
Unpauses a container
- name
Container name or ID
RETURN DATA
A dictionary will be returned, containing the following keys:
status
- A dictionary showing the prior state of the container as well as the new state
result
- A boolean noting whether or not the action was successful
comment
- Only present if the container can not be unpausedCLI Example:
salt myminion docker.pause mycontainer
Unpauses a container
Container name or ID
RETURN DATA
A dictionary will be returned, containing the following keys:
status
- A dictionary showing the prior state of the container as
well as the new state
result
- A boolean noting whether or not the action was successful
comment
- Only present if the container can not be unpaused
CLI Example:
salt myminion docker.pause mycontainer
Returns a dictionary of Docker version information. Equivalent to running
the docker version
Docker CLI command.
CLI Example:
salt myminion docker.version
List existing volumes
New in version 2015.8.4.
There is one available filter: dangling=true
CLI Example:
salt myminion docker.volumes filters="{'dangling': True}"
Wait for the container to exit gracefully, and return its exit code
Note
This function will block until the container is stopped.
Container name or ID
Boolean flag that prevents execution to fail, if a container is already stopped.
Boolean flag to report execution as failure if exit_status
is different than 0.
RETURN DATA
A dictionary will be returned, containing the following keys:
status
- A dictionary showing the prior state of the container as
well as the new state
result
- A boolean noting whether or not the action was successful
exit_status
- Exit status for the container
comment
- Only present if the container is already stopped
CLI Example:
salt myminion docker.wait mycontainer