salt.modules.dockermod

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.

depends: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

Authentication

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 Pillar data. 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.

Configuration Options

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).

Executing Commands Within a Running Container

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:

Detailed Function Documentation

salt.modules.dockermod.build(path=None, image=None, cache=True, rm=True, api_response=False, fileobj=None, dockerfile=None, buildargs=None)

Builds a docker image from a Dockerfile or a URL

path
Path to directory on the Minion containing a Dockerfile
image
Image to be built, in repo:tag notation. If just the repository name is passed, a tag name of latest will be assumed. If building from a URL, this parameted can be omitted.
cache
: True
Set to False to force the build process not to use the Docker image cache, and pull all required intermediate image layers
rm
: True
Remove intermediate containers created during build
api_response
: False
If True: an API_Response key will be present in the return data, containing the raw output from the Docker API.
fileobj
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.
dockerfile

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 develop.

buildargs
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 "image" argument 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 "image" argument was not present on the Minion, or if cache=False)

CLI Example:

salt myminion docker.build /path/to/docker/build/dir image=myimage:dev
salt myminion docker.build https://github.com/myuser/myrepo.git image=myimage:latest

.. versionadded:: develop

salt myminion docker.build /path/to/docker/build/dir dockerfile=Dockefile.different image=myimage:dev
salt.modules.dockermod.call(name, function, *args, **kwargs)

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.

name
Container name or ID
function
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
salt.modules.dockermod.commit(name, image, message=None, author=None)

Commits a container, thereby promoting it to an image. Equivalent to running the docker commit Docker CLI command.

name
Container name or ID to commit
image
Image to be committed, in repo:tag notation. If just the repository name is passed, a tag name of latest will be assumed.
message
Commit message (Optional)
author
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
salt myminion docker.commit mycontainer myuser/myimage:mytag
salt.modules.dockermod.compare_container(first, second, ignore=None)

New in version 2017.7.0.

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.
salt.modules.dockermod.connect_container_to_network(container, network_id, ipv4_address=None)

Connect container to network.

container
Container name or ID
network_id
ID of network
ipv4_address

The IPv4 address to connect to the container

New in version 2017.7.0.

CLI Example:

salt myminion docker.connect_container_from_network web-1 1f9d2454d0872b68dd9e8744c6e7a4c66b86f10abaccc21e14f7f014f729b2bc
salt.modules.dockermod.copy_from(name, *args, **kwargs)

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.
overwrite
: False
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.
makedirs
: False
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
salt.modules.dockermod.copy_to(name, *args, **kwargs)

Copy a file from the host into a container

name
Container name
source
File to be copied to the container. Can be a local path on the Minion or a remote file from the Salt fileserver.
dest
Destination on the container. Must be an absolute path. If the destination is a directory, the file will be copied into that directory.
exec_driver
: None
If not passed, the execution driver will be detected as described above.
overwrite
: False
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.
makedirs
: False
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
salt.modules.dockermod.create(*args, **kwargs)

Create a new container

image
Image from which to create the container
name
Name for the new container. If not provided, Docker will randomly generate one for you (it will be included in the return data).
skip_translate

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:

ignore_collisions
: False
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.
validate_ip_addrs
: True
For parameters which accept IP addresses as input, IP address validation will be performed. To disable, set this to False
client_timeout
: 60

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

auto_remove (or rm)
: False

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
binds

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.

blkio_weight

Block IO weight (relative weight), accepts a weight value between 10 and 1000.

Example: blkio_weight=100

blkio_weight_device

Block IO weight (relative device weight), specified as a list of expressions in the format PATH:WEIGHT

Example: blkio_weight_device=/dev/sda:100

cap_add

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]"
cap_drop

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 (or cmd)

Command to run in the container

Example: command=bash or cmd=bash

Changed in version 2015.8.1: cmd is now also accepted

cpuset_cpus (or cpuset)

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"
cpuset_mems

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"
cpu_group

The length of a CPU period in microseconds

Example: cpu_group=100000

cpu_period

Microseconds of CPU time that the container can get in a CPU period

Example: cpu_period=50000

cpu_shares

CPU shares (relative weight), specified as an integer between 2 and 1024.

Example: cpu_shares=512

detach
: False

If True, run the container's command in the background (daemon mode)

Example: detach=True

devices

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']"
device_read_bps

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']"
device_read_iops

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']"
device_write_bps

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']"
device_read_iops

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_read_iops="/dev/sda:1000,/dev/sdb:500"
  • device_read_iops="['/dev/sda:1000', '/dev/sdb:500']"
dns

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

dns_opt

Additional options to be added to the container’s resolv.conf file

Example: dns_opt=ndots:9

dns_search

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]"
domainname

The domain name to use for the container

Example: domainname=domain.tld

entrypoint

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']"
environment (or env)

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'}"
extra_hosts

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

group_add

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

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.

interactive (or stdin_open): False

Leave stdin open, even if not attached

Examples:

  • interactive=True
  • stdin_open=True
ipc_mode (or ipc)

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.

isolation

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.

labels (or label)

Add metadata to the container. 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']"
links

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'}"
log_driver

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.

log_opt

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
lxc_conf

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

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

mem_limit (or memory)
: 0

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
mem_swappiness

Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.

Example: mem_swappiness=60

memswap_limit (or memory_swap)
: -1

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
network_disabled
: False

If True, networking will be disabled within the container

Example: network_disabled=True

network_mode
: bridge

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
oom_kill_disable

Whether to disable OOM killer

Example: oom_kill_disable=False

oom_score_adj

An integer value containing the score given to the container in order to tune OOM killer preferences

Example: oom_score_adj=500

pid_mode

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

pids_limit

Set the container's PID limit. Set to -1 for unlimited.

Example: pids_limit=2000

port_bindings (or publish)

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.

ports

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']"
privileged
: False

If True, runs the exec process with extended privileges

Example: privileged=True

publish_all_ports (or publish_all): False

Publish all ports to the host

Example: publish_all_ports=True

read_only
: False

If True, mount the container’s root filesystem as read only

Example: read_only=True

restart_policy (or restart)

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_opt

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

shm_size

Size of /dev/shm

Example: shm_size=128M

stop_signal

The signal used to stop the container. The default is SIGTERM.

Example: stop_signal=SIGRTMIN+3

stop_timeout

Timeout to stop the container, in seconds

Example: stop_timeout=5

storage_opt

Storage driver options for the container

Examples:

  • storage_opt='dm.basesize=40G'
  • storage_opt="['dm.basesize=40G']"
  • storage_opt="{'dm.basesize': '40G'}"
sysctls (or sysctl)

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'}"
tmpfs

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'}"
tty
: False

Attach TTYs

Example: tty=True

ulimits (or ulimit)

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

User under which to run exec process

Example: user=foo

userns_mode (or user_ns_mode)

Sets the user namsepace mode, when the user namespace remapping option is enabled.

Example: userns_mode=host

volumes (or volume)

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']"
volumes_from

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]"

volume_driver

Sets the container's volume driver

Example: volume_driver=foobar

working_dir (or workdir)

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
salt.modules.dockermod.create_network(name, driver=None)

Create a new network

network_id
ID of network
driver
Driver of the network

CLI Example:

salt myminion docker.create_network web_network driver=bridge
salt.modules.dockermod.create_volume(name, driver=None, driver_opts=None)

Create a new volume

New in version 2015.8.4.

name
name of volume
driver
Driver of the volume
driver_opts
Options for the driver volume

CLI Example:

salt myminion docker.create_volume my_volume driver=local
salt.modules.dockermod.dangling(prune=False, force=False)

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.
prune
: False
Remove these images
force
: False
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
salt.modules.dockermod.depends(name)

Returns the containers and images, if any, which depend on the given image

name
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
salt.modules.dockermod.diff(name, *args, **kwargs)

Get information on changes made to container's filesystem since it was created. Equivalent to running the docker diff Docker CLI command.

name
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
salt.modules.dockermod.disconnect_container_from_network(container, network_id)

Disconnect container from network.

container
Container name or ID
network_id
ID of network

CLI Example:

salt myminion docker.disconnect_container_from_network web-1 1f9d2454d0872b68dd9e8744c6e7a4c66b86f10abaccc21e14f7f014f729b2bc
salt.modules.dockermod.exists(name)

Check if a given container exists

name
Container name or ID

RETURN DATA

A boolean (True if the container exists, otherwise False)

CLI Example:

salt myminion docker.exists mycontainer
salt.modules.dockermod.export(name, *args, **kwargs)

Exports a container to a tar archive. It can also optionally compress that tar archive, and push it up to the Master.

name
Container name or ID
path
Absolute path on the Minion where the container will be exported
overwrite
: False
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.
makedirs
: False
If True, then if the parent directory of the file specified by the path argument does not exist, Salt will attempt to create it.
compression
: None

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.

push
: False

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
salt.modules.dockermod.get_client_args()

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.

Returns the args for docker-py's low-level API, organized by args for container creation, host config, and networking config.

CLI Example:

salt myminion docker.get_client_args
salt.modules.dockermod.history(name, quiet=False)

Return the history for an image. Equivalent to running the docker history Docker CLI command.

name
Container name or ID
quiet
: False

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
salt.modules.dockermod.images(verbose=False, **kwargs)

Returns information about the Docker images on the Minion. Equivalent to running the docker images Docker CLI command.

all
: False
If True, untagged images will also be returned
verbose
: False
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
salt.modules.dockermod.import(source, image, api_response=False)

Imports content from a local tarball or a URL as a new docker image

source
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).
image
Image to be created by the import, in repo:tag notation. If just the repository name is passed, a tag name of latest will be assumed.
api_response
: False
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
salt.modules.dockermod.info()

Returns a dictionary of system-wide information. Equivalent to running the docker info Docker CLI command.

CLI Example:

salt myminion docker.info
salt.modules.dockermod.inspect(name)

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.

name
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
salt.modules.dockermod.inspect_container(name, *args, **kwargs)

Retrieves container information. Equivalent to running the docker inspect Docker CLI command, but will only look for container information.

name
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
salt.modules.dockermod.inspect_image(name)

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.

name
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
salt.modules.dockermod.inspect_network(network_id)

Inspect Network

network_id
ID of network

CLI Example:

salt myminion docker.inspect_network 1f9d2454d0872b68dd9e8744c6e7a4c66b86f10abaccc21e14f7f014f729b2bc
salt.modules.dockermod.inspect_volume(name)

Inspect Volume

New in version 2015.8.4.

name
Name of volume

CLI Example:

salt myminion docker.inspect_volume my_volume
salt.modules.dockermod.kill(*args, **kwargs)

Kill all processes in a running container instead of performing a graceful shutdown

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 killed

CLI Example:

salt myminion docker.kill mycontainer
salt.modules.dockermod.layers(name)

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.

name
Image name or ID

CLI Example:

salt myminion docker.layers centos:7
salt.modules.dockermod.list_containers(**kwargs)

Returns a list of containers by name. This is different from docker.ps in that docker.ps returns its results organized by container ID.

all
: False
If True, stopped containers will be included in return data

CLI Example:

salt myminion docker.inspect_image <image>
salt.modules.dockermod.list_tags()

Returns a list of tagged images

CLI Example:

salt myminion docker.list_tags
salt.modules.dockermod.load(path, image=None)

Load a tar archive that was created using docker.save (or via the Docker CLI using docker save).

path
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).
image
: None
If specified, the topmost layer of the newly-loaded image will be tagged with the specified repo and tag using docker.tag. The image name should be specified in repo:tag notation. If just the repository name is passed, a tag name of latest will be assumed.

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 attemp 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 image=myuser/myimage:mytag
salt.modules.dockermod.login(*registries)

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/
salt.modules.dockermod.logs(name)

Returns the logs for the container. Equivalent to running the docker logs Docker CLI command.

name
Container name or ID

CLI Example:

salt myminion docker.logs mycontainer
salt.modules.dockermod.networks(names=None, ids=None)

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.

List existing networks

names
Filter by name
ids
Filter by id

CLI Example:

salt myminion docker.networks names=network-web
salt myminion docker.networks ids=1f9d2454d0872b68dd9e8744c6e7a4c66b86f10abaccc21e14f7f014f729b2bc
salt.modules.dockermod.pause(*args, **kwargs)

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 paused

CLI Example:

salt myminion docker.pause mycontainer
salt.modules.dockermod.pid(name, *args, **kwargs)

Returns the PID of a container

name
Container name or ID

CLI Example:

salt myminion docker.pid mycontainer
salt myminion docker.pid 0123456789ab
salt.modules.dockermod.port(name, *args, **kwargs)

Returns port mapping information for a given container. Equivalent to running the docker port Docker CLI command.

name
Container name or ID
private_port
: None

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
salt.modules.dockermod.ps(filters=None, **kwargs)

Returns information about the Docker containers on the Minion. Equivalent to running the docker ps Docker CLI command.

all
: False
If True, stopped containers will also be returned
host: False
If True, local host's network topology will be included
verbose
: False
If True, a docker inspect will be run on each container returned.
filters: None

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'}"
salt.modules.dockermod.pull(image, insecure_registry=False, api_response=False, client_timeout=60)

Pulls an image from a Docker registry

image
Image to be pulled, in repo:tag notation. If just the repository name is passed, a tag name of latest will be assumed.
insecure_registry
: False
If True, the Docker client will permit the use of insecure (non-HTTPS) registries.
api_response
: False

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.

client_timeout
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
salt.modules.dockermod.push(image, insecure_registry=False, api_response=False, client_timeout=60)

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

Image to be pushed, in repo:tag notation.

Changed in version 2015.8.4: If just the repository name is passed, then all tagged images for the specified repo will be pushed. In prior releases, a tag of latest was assumed if the tag was omitted.

insecure_registry
: False
If True, the Docker client will permit the use of insecure (non-HTTPS) registries.
api_response
: False
If True, an API_Response key will be present in the return data, containing the raw output from the Docker API.
client_timeout
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
salt.modules.dockermod.remove_network(network_id)

Remove a network

network_id
ID of network

CLI Example:

salt myminion docker.remove_network 1f9d2454d0872b68dd9e8744c6e7a4c66b86f10abaccc21e14f7f014f729b2bc
salt.modules.dockermod.remove_volume(name)

Remove a volume

New in version 2015.8.4.

name
Name of volume

CLI Example:

salt myminion docker.remove_volume my_volume
salt.modules.dockermod.rename(name, new_name)

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
Name or ID of existing container
new_name
New name to assign to container

CLI Example:

salt myminion docker.rename foo bar
salt.modules.dockermod.resolve_tag(name, tags=None)

New in version 2017.7.2,Oxygen.

Given an image tag, check the locally-pulled tags (using docker.list_tags) and return the matching tag. This helps disambiguate differences on some platforms where images from the Docker Hub are prefixed with docker.io/. If an image name with no tag is passed, a tag of latest is assumed.

If the specified image is not pulled locally, this function will return False.

tags
An optional Python list of tags to check against. If passed, then docker.list_tags will not be run to get a list of tags. This is useful when resolving a number of tags at the same time.

CLI Examples:

salt myminion docker.resolve_tag busybox
salt myminion docker.resolve_tag busybox:latest
salt.modules.dockermod.restart(name, *args, **kwargs)

Restarts a container

name
Container name or ID
timeout
: 10
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
salt.modules.dockermod.retcode(name, cmd, exec_driver=None, stdin=None, python_shell=True, output_loglevel='debug', use_vt=False, ignore_retcode=False, keep_env=None)

Run cmd.retcode within a container

name
Container name or ID in which to run the command
cmd
Command to run
exec_driver
: None
If not passed, the execution driver will be detected as described above.
stdin
: None
Standard input to be used for the command
output_loglevel
: debug
Level at which to log the output from the command. Set to quiet to suppress logging.
use_vt
: False
Use SaltStack's utils.vt to stream output to console.
keep_env
: None
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'
salt.modules.dockermod.rm(*args, **kwargs)

Removes a container

name
Container name or ID
force
: False
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.
stop
: False

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.

volumes
: False
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
salt.modules.dockermod.rmi(*names, **kwargs)

Removes an image

name
Name (in repo:tag notation) or ID of image.
force
: False
If True, the image will be removed even if the Minion has containers created from that image
prune
: True
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
salt.modules.dockermod.run(name, cmd, exec_driver=None, stdin=None, python_shell=True, output_loglevel='debug', use_vt=False, ignore_retcode=False, keep_env=None)

Run cmd.run within a container

name
Container name or ID in which to run the command
cmd
Command to run
exec_driver
: None
If not passed, the execution driver will be detected as described above.
stdin
: None
Standard input to be used for the command
output_loglevel
: debug
Level at which to log the output from the command. Set to quiet to suppress logging.
use_vt
: False
Use SaltStack's utils.vt to stream output to console.
keep_env
: None
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'
salt.modules.dockermod.run_all(name, cmd, exec_driver=None, stdin=None, python_shell=True, output_loglevel='debug', use_vt=False, ignore_retcode=False, keep_env=None)

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.

name
Container name or ID in which to run the command
cmd
Command to run
exec_driver
: None
If not passed, the execution driver will be detected as described above.
stdin
: None
Standard input to be used for the command
output_loglevel
: debug
Level at which to log the output from the command. Set to quiet to suppress logging.
use_vt
: False
Use SaltStack's utils.vt to stream output to console.
keep_env
: None
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'
salt.modules.dockermod.run_stderr(name, cmd, exec_driver=None, stdin=None, python_shell=True, output_loglevel='debug', use_vt=False, ignore_retcode=False, keep_env=None)

Run cmd.run_stderr within a container

name
Container name or ID in which to run the command
cmd
Command to run
exec_driver
: None
If not passed, the execution driver will be detected as described above.
stdin
: None
Standard input to be used for the command
output_loglevel
: debug
Level at which to log the output from the command. Set to quiet to suppress logging.
use_vt
: False
Use SaltStack's utils.vt to stream output to console.
keep_env
: None
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'
salt.modules.dockermod.run_stdout(name, cmd, exec_driver=None, stdin=None, python_shell=True, output_loglevel='debug', use_vt=False, ignore_retcode=False, keep_env=None)

Run cmd.run_stdout within a container

name
Container name or ID in which to run the command
cmd
Command to run
exec_driver
: None
If not passed, the execution driver will be detected as described above.
stdin
: None
Standard input to be used for the command
output_loglevel
: debug
Level at which to log the output from the command. Set to quiet to suppress logging.
use_vt
: False
Use SaltStack's utils.vt to stream output to console.
keep_env
: None
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'
salt.modules.dockermod.save(name, path, overwrite=False, makedirs=False, compression=None, **kwargs)

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
Name or ID of image. Specify a specific tag by using the repo:tag notation.
path
Absolute path on the Minion where the image will be exported
overwrite
: False
Unless this option is set to True, then if the destination file exists an error will be raised.
makedirs
: False
If True, then if the parent directory of the file specified by the path argument does not exist, Salt will attempt to create it.
compression
: None

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.

push
: False

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
salt.modules.dockermod.script(name, source, saltenv='base', args=None, template=None, exec_driver=None, stdin=None, python_shell=True, output_loglevel='debug', ignore_retcode=False, use_vt=False, keep_env=None)

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.

name
Container name or ID
source
Path to the script. Can be a local path on the Minion or a remote file from the Salt fileserver.
args
A string containing additional command-line options to pass to the script.
template
: None
Templating engine to use on the script before running.
exec_driver
: None
If not passed, the execution driver will be detected as described above.
stdin
: None
Standard input to be used for the script
output_loglevel
: debug
Level at which to log the output from the script. Set to quiet to suppress logging.
use_vt
: False
Use SaltStack's utils.vt to stream output to console.
keep_env
: None
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
salt.modules.dockermod.script_retcode(name, source, saltenv='base', args=None, template=None, exec_driver=None, stdin=None, python_shell=True, output_loglevel='debug', ignore_retcode=False, use_vt=False, keep_env=None)

Run cmd.script_retcode within a container

name
Container name or ID
source
Path to the script. Can be a local path on the Minion or a remote file from the Salt fileserver.
args
A string containing additional command-line options to pass to the script.
template
: None
Templating engine to use on the script before running.
exec_driver
: None
If not passed, the execution driver will be detected as described above.
stdin
: None
Standard input to be used for the script
output_loglevel
: debug
Level at which to log the output from the script. Set to quiet to suppress logging.
use_vt
: False
Use SaltStack's utils.vt to stream output to console.
keep_env
: None
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
salt.modules.dockermod.search(name, official=False, trusted=False)

Searches the registry for an image

name
Search keyword
official
: False
Limit results to official builds
trusted
: False
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
salt.modules.dockermod.signal(*args, **kwargs)

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.

name
Container name or ID
signal
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
salt.modules.dockermod.sls(name, mods=None, saltenv='base', **kwargs)

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.

name
Container name or ID
mods
: None
A string containing comma-separated list of SLS with defined states to apply to the container.
saltenv
: base
Specify the environment from which to retrieve the SLS indicated by the mods parameter.

CLI Example:

salt myminion docker.sls compassionate_mirzakhani mods=rails,web
salt.modules.dockermod.sls_build(name, base='opensuse/python', mods=None, saltenv='base', dryrun=False, **kwargs)

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.

name
Image name to be built and committed
base
: opensuse/python
Name or ID of the base image
mods
: None
A string containing comma-separated list of SLS with defined states to apply to the base image.
saltenv
: base
Specify the environment from which to retrieve the SLS indicated by the mods parameter.
base
the base image
mods
the state modules to execute during build
saltenv
the salt environment to use
dryrun: False
when set to True the container will not be commited 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
salt.modules.dockermod.start(*args, **kwargs)

Start 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 started

CLI Example:

salt myminion docker.start mycontainer
salt.modules.dockermod.state(name, *args, **kwargs)

Returns the state of the container

name
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
salt.modules.dockermod.stop(*args, **kwargs)

Stops a running container

name
Container name or ID
unpause
: False
If True and the container is paused, it will be unpaused before attempting to stop the container.
timeout

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
salt.modules.dockermod.tag(name, image, force=False)

Tag an image into a repository and return True. If the tag was unsuccessful, an error will be raised.

name
ID of image
image
Tag to apply to the image, in repo:tag notation. If just the repository name is passed, a tag name of latest will be assumed.
force
: False
Force apply tag

CLI Example:

salt myminion docker.tag 0123456789ab myrepo/mycontainer
salt myminion docker.tag 0123456789ab myrepo/mycontainer:mytag
salt.modules.dockermod.top(name, *args, **kwargs)

Runs the docker top command on a specific container

name
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
salt.modules.dockermod.unpause(*args, **kwargs)

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 unpaused

CLI Example:

salt myminion docker.pause mycontainer
salt.modules.dockermod.version()

Returns a dictionary of Docker version information. Equivalent to running the docker version Docker CLI command.

CLI Example:

salt myminion docker.version
salt.modules.dockermod.volumes(filters=None)

List existing volumes

New in version 2015.8.4.

filters
There is one available filter: dangling=true

CLI Example:

salt myminion docker.volumes filters="{'dangling': True}"
salt.modules.dockermod.wait(name, ignore_already_stopped=False, fail_on_exit_status=False)

Wait for the container to exit gracefully, and return its exit code

Note

This function will block until the container is stopped.

name
Container name or ID
ignore_already_stopped
Boolean flag that prevent execution to fail, if a container is already stopped.
fail_on_exit_status
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