salt.states.docker_container

Management of Docker containers

depends

docker Python module

salt myminion pip.install docker

salt myminion pip.uninstall docker-py
salt myminion pip.install docker

These states were moved from the docker state module (formerly called dockerng) in the 2017.7.0 release. When running the docker_container.running state for the first time after upgrading to 2017.7.0, your container(s) may be replaced. The changes may show diffs for certain parameters which say that the old value was an empty string, and the new value is None. This is due to the fact that in prior releases Salt was passing empty strings for these values when creating the container if they were undefined in the SLS file, where now Salt simply does not pass any arguments not explicitly defined in the SLS file. Subsequent runs of the state should not replace the container if the configuration remains unchanged.

salt.states.docker_container.absent(name, force=False)

Ensure that a container is absent

name

Name of the container

forceFalse

Set to True to remove the container even if it is running

Usage Examples:

mycontainer:
  docker_container.absent

multiple_containers:
  docker_container.absent:
    - names:
      - foo
      - bar
      - baz

salt.states.docker_container.mod_watch(name, sfun=None, **kwargs)

The docker_container watcher, called to invoke the watch command.

Note

This state exists to support special handling of the watch requisite. It should not be called directly.

Parameters for this function should be set by the state being triggered.

salt.states.docker_container.run(name, image=None, bg=False, failhard=True, replace=False, force=False, skip_translate=None, ignore_collisions=False, validate_ip_addrs=True, client_timeout=60, **kwargs)

New in version 2018.3.0.

Note

If no tag is specified in the image name, and nothing matching the specified image is pulled on the minion, the docker pull that retrieves the image will pull all tags for the image. A tag of latest is not implicit for the pull. For this reason, it is recommended to specify the image in repo:tag notation.

Like the cmd.run state, only for Docker. Does the equivalent of a docker run and returns information about the container that was created, as well as its output.

This state accepts the same arguments as docker_container.running, with the exception of watch_action, start, and shutdown_timeout (though the force argument has a different meaning in this state).

In addition, this state accepts the arguments from docker.logs, with the exception of follow, to control how logs are returned.

Additionally, the following arguments are supported:

creates

A path or list of paths. Only run if one or more of the specified paths do not exist on the minion.

bgFalse

If True, run container in background and do not await or deliver its results.

Note

This may not be useful in cases where other states depend on the results of this state. Also, the logs will be inaccessible once the container exits if auto_remove is set to True, so keep this in mind.

failhardTrue

If True, the state will return a False result if the exit code of the container is non-zero. When this argument is set to False, the state will return a True result regardless of the container's exit code.

Note

This has no effect if bg is set to True.

replaceFalse

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.

forceFalse

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.

CLI Examples:

salt myminion docker.run_container myuser/myimage command=/usr/local/bin/myscript.sh

USAGE EXAMPLE

{% set pkg_version = salt.pillar.get('pkg_version', '1.0-1') %}
build_package:
  docker_container.run:
    - image: myuser/builder:latest
    - binds: /home/myuser/builds:/build_dir
    - command: /scripts/build.sh {{ pkg_version }}
    - creates: /home/myuser/builds/myapp-{{ pkg_version }}.noarch.rpm
    - replace: True
    - networks:
      - mynet
    - require:
      - docker_network: mynet

salt.states.docker_container.running(name, image=None, skip_translate=None, ignore_collisions=False, validate_ip_addrs=True, force=False, watch_action='force', start=True, shutdown_timeout=None, client_timeout=60, networks=None, **kwargs)

Ensure that a container with a specific configuration is present and running

name

Name of the container

image

Image to use for the container

Note

This state will pull the image if it is not present. However, if the image needs to be built from a Dockerfile or loaded from a saved image, or if you would like to use requisites to trigger a replacement of the container when the image is updated, then the docker_image.present state should be used to manage the image.

Changed in version 2018.3.0: If no tag is specified in the image name, and nothing matching the specified image is pulled on the minion, the docker pull that retrieves the image will pull all tags for the image. A tag of latest is no longer implicit for the pull. For this reason, it is recommended to specify the image in repo:tag notation.

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:

For example, imagine that there is an issue with processing the port_bindings argument, and the following configuration no longer works as expected:

mycontainer:
  docker_container.running:
    - image: 7.3.1611
    - port_bindings:
      - 10.2.9.10:8080:80

By using skip_translate, you can forego the input translation and configure the port binding in the format docker-py needs:

mycontainer:
  docker_container.running:
    - image: 7.3.1611
    - skip_translate: port_bindings
    - port_bindings: {8080: [('10.2.9.10', 80)], '4193/udp': 9314}

See the following links for more information:

• docker-py Low-level API

• Docker Engine API

ignore_collisionsFalse

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 so that both CLI and API versions of a given argument are supported. 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_addrsTrue

For parameters which accept IP addresses as input, IP address validation will be performed. To disable, set this to False

forceFalse

Set this parameter to True to force Salt to re-create the container irrespective of whether or not it is configured as desired.

watch_actionforce

Control what type of action is taken when this state watches another state that has changes. The default action is force, which runs the state with force set to True, triggering a rebuild of the container.

If any other value is passed, it will be assumed to be a kill signal. If the container matches the specified configuration, and is running, then the action will be to send that signal to the container. Kill 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. For example:

mycontainer:
  docker_container.running:
    - image: busybox
    - watch_action: SIGHUP
    - watch:
      - file: some_file

Note

If the container differs from the specified configuration, or is not running, then instead of sending a signal to the container, the container will be re-created/started and no signal will be sent.

startTrue

Set to False to suppress starting of the container if it exists, matches the desired configuration, but is not running. This is useful for data-only containers, or for non-daemonized container processes, such as the Django migrate and collectstatic commands. In instances such as this, the container only needs to be started the first time.

shutdown_timeout

If the container needs to be replaced, the container will be stopped using docker.stop. If a shutdown_timout is not set, and the container was created using stop_timeout, that timeout will be used. If neither of these values were set, then a timeout of 10 seconds will be used.

Changed in version 2017.7.0: This option was renamed from stop_timeout to shutdown_timeout to accommodate the stop_timeout container configuration setting.

client_timeout60

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.

NETWORK MANAGEMENT

New in version 2018.3.0.

Changed in version 2019.2.0: If the networks option is used, any networks (including the default bridge network) which are not specified will be disconnected.

The networks argument can be used to ensure that a container is attached to one or more networks. Optionally, arguments can be passed to the networks. In the example below, net1 is being configured with arguments, while net2 and bridge are being configured without arguments:

foo:
  docker_container.running:
    - image: myuser/myimage:foo
    - networks:
      - net1:
        - aliases:
          - bar
          - baz
        - ipv4_address: 10.0.20.50
      - net2
      - bridge
    - require:
      - docker_network: net1
      - docker_network: net2

The supported arguments are the ones from the docker-py's connect_container_to_network function (other than container and net_id).

Important

Unlike with the arguments described in the CONTAINER CONFIGURATION PARAMETERS section below, these network configuration parameters are not translated at all. Consult the connect_container_to_network documentation for the correct type/format of data to pass.

To start a container with no network connectivity (only possible in 2019.2.0 and later) pass this option as an empty list. For example:

foo:
  docker_container.running:
    - image: myuser/myimage:foo
    - networks: []

CONTAINER CONFIGURATION PARAMETERS

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

foo:
  docker_container.running:
    - image: bar/baz:latest
    - auto_remove: 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 rw 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 YAML list. The below two examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - binds: /srv/www:/var/www:ro,/etc/foo.conf:/usr/local/etc/foo.conf:rw

foo:
  docker_container.running:
    - image: bar/baz:latest
    - binds:
      - /srv/www:/var/www:ro
      - /home/myuser/conf/foo.conf:/etc/foo.conf:rw

However, in cases where both ro/rw and an selinux context are combined, the only option is to use a YAML list, like so:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - binds:
      - /srv/www:/var/www:ro,Z
      - /home/myuser/conf/foo.conf:/etc/foo.conf:rw,Z

Since the second bind in the previous example is mounted read-write, the rw and comma can be dropped. For example:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - binds:
      - /srv/www:/var/www:ro,Z
      - /home/myuser/conf/foo.conf:/etc/foo.conf:Z

blkio_weight

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

foo:
  docker_container.running:
    - image: bar/baz:latest
    - blkio_weight: 100

blkio_weight_device

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

foo:
  docker_container.running:
    - image: bar/baz:latest
    - blkio_weight_device: /dev/sda:100

cap_add

List of capabilities to add within the container. Can be expressed as a comma-separated list or a Python list. The below two examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - cap_add: SYS_ADMIN,MKNOD

foo:
  docker_container.running:
    - image: bar/baz:latest
    - cap_add:
      - SYS_ADMIN
      - MKNOD

Note

This option requires Docker 1.2.0 or newer.

cap_drop

List of capabilities to drop within the container. Can be expressed as a comma-separated list or a Python list. The below two examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - cap_drop: SYS_ADMIN,MKNOD

foo:
  docker_container.running:
    - image: bar/baz:latest
    - cap_drop:
      - SYS_ADMIN
      - MKNOD

Note

This option requires Docker 1.2.0 or newer.

command (or cmd)

Command to run in the container

foo:
  docker_container.running:
    - image: bar/baz:latest
    - command: bash

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

foo:
  docker_container.running:
    - image: bar/baz:latest
    - cpuset_cpus: "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.

foo:
  docker_container.running:
    - image: bar/baz:latest
    - cpuset_mems: "0,1"

cpu_group

The length of a CPU period in microseconds

foo:
  docker_container.running:
    - image: bar/baz:latest
    - cpu_group: 100000

cpu_period

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

foo:
  docker_container.running:
    - image: bar/baz:latest
    - cpu_period: 50000

cpu_shares

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

foo:
  docker_container.running:
    - image: bar/baz:latest
    - cpu_shares: 512

detachFalse

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

foo:
  docker_container.running:
    - image: bar/baz:latest
    - detach: True

devices

List of host devices to expose within the container. Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - devices: /dev/net/tun,/dev/xvda1:/dev/xvda1,/dev/xvdb1:/dev/xvdb1:r

foo:
  docker_container.running:
    - image: bar/baz:latest
    - 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. Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - devices_read_bps: /dev/sda:1mb,/dev/sdb:5mb

foo:
  docker_container.running:
    - image: bar/baz:latest
    - devices_read_bps:
      - /dev/sda:1mb
      - /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. Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - devices_read_iops: /dev/sda:1000,/dev/sdb:500

foo:
  docker_container.running:
    - image: bar/baz:latest
    - devices_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. Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - devices_write_bps: /dev/sda:1mb,/dev/sdb:5mb

foo:
  docker_container.running:
    - image: bar/baz:latest
    - devices_write_bps:
      - /dev/sda:1mb
      - /dev/sdb:5mb

device_write_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. Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - devices_write_iops: /dev/sda:1000,/dev/sdb:500

foo:
  docker_container.running:
    - image: bar/baz:latest
    - devices_write_iops:
      - /dev/sda:1000
      - /dev/sdb:500

dns

List of DNS nameservers. Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - dns: 8.8.8.8,8.8.4.4

foo:
  docker_container.running:
    - image: bar/baz:latest
    - 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. Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - dns_opt: ndots:9

foo:
  docker_container.running:
    - image: bar/baz:latest
    - dns_opt:
      - ndots:9

dns_search

List of DNS search domains. Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - dns_search: foo1.domain.tld,foo2.domain.tld

foo:
  docker_container.running:
    - image: bar/baz:latest
    - dns_search:
      - foo1.domain.tld
      - foo2.domain.tld

domainname

The domain name to use for the container

foo:
  docker_container.running:
    - image: bar/baz:latest
    - dommainname: domain.tld

entrypoint

Entrypoint for the container

foo:
  docker_container.running:
    - image: bar/baz:latest
    - entrypoint: "mycmd --arg1 --arg2"

This argument can also be specified as a list:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - entrypoint:
      - mycmd
      - --arg1
      - --arg2

environment

Either a list of variable/value mappings, or a list of strings in the format VARNAME=value. The below three examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - environment:
      - VAR1: value
      - VAR2: value

foo:
  docker_container.running:
    - image: bar/baz:latest
    - environment: 'VAR1=value,VAR2=value'

foo:
  docker_container.running:
    - image: bar/baz:latest
    - environment:
      - VAR1=value
      - VAR2=value

extra_hosts

Additional hosts to add to the container's /etc/hosts file. Can be expressed as a comma-separated list or a Python list. The below two examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - extra_hosts: web1:10.9.8.7,web2:10.9.8.8

foo:
  docker_container.running:
    - image: bar/baz:latest
    - extra_hosts:
      - web1:10.9.8.7
      - web2:10.9.8.8

Note

To skip IP address validation, use validate_ip_addrs=False

Note

This option requires Docker 1.3.0 or newer.

group_add

List of additional group names and/or IDs that the container process will run as. Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - group_add: web,network

foo:
  docker_container.running:
    - image: bar/baz:latest
    - group_add:
      - web
      - network

hostname

Hostname of the container. If not provided, the value passed as the container's``name`` will be used for the hostname.

foo:
  docker_container.running:
    - image: bar/baz:latest
    - hostname: web1

Warning

hostname cannot be set if network_mode is set to host. The below example will result in an error:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - hostname: web1
    - network_mode: host

interactive (or stdin_open)False

Leave stdin open, even if not attached

foo:
  docker_container.running:
    - image: bar/baz:latest
    - interactive: 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

foo:
  docker_container.running:
    - image: bar/baz:latest
    - ipc_mode: container:foo

foo:
  docker_container.running:
    - image: bar/baz:latest
    - ipc_mode: 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

foo:
  docker_container.running:
    - image: bar/baz:latest
    - 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

Add metadata to the container. Labels can be set both with and without values, and labels with values can be passed either as key=value or key: value pairs. For example, while the below would be very confusing to read, it is technically valid, and demonstrates the different ways in which labels can be passed:

mynet:
  docker_network.present:
    - labels:
      - foo
      - bar=baz
      - hello: world

The labels can also simply be passed as a YAML dictionary, though this can be error-prone due to some idiosyncrasies with how PyYAML loads nested data structures:

foo:
  docker_network.present:
    - labels:
        foo: ''
        bar: baz
        hello: world

Changed in version 2018.3.0: Methods for specifying labels can now be mixed. Earlier releases required either labels with or without values.

links

Link this container to another. Links can be specified as a list of mappings or a comma-separated or Python list of expressions in the format <container_name_or_id>:<link_alias>. The below three examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - links:
      - web1: link1
      - web2: link2

foo:
  docker_container.running:
    - image: bar/baz:latest
    - links: web1:link1,web2:link2

foo:
  docker_container.running:
    - image: bar/baz:latest
    - links:
      - web1:link1
      - web2:link2

log_driver and log_opt

Set container's logging driver and options to configure that driver. Requires Docker 1.6 or newer.

foo:
  docker_container.running:
    - image: bar/baz:latest
    - log_driver: syslog
    - log_opt:
      - syslog-address: tcp://192.168.0.42
      - syslog-facility: daemon

The log_opt can also be expressed as a comma-separated or YAML list of key=value pairs. The below two examples are equivalent to the above one:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - log_driver: syslog
    - log_opt: "syslog-address=tcp://192.168.0.42,syslog-facility=daemon"

foo:
  docker_container.running:
    - image: bar/baz:latest
    - log_driver: syslog
    - log_opt:
      - syslog-address=tcp://192.168.0.42
      - syslog-facility=daemon

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.

lxc_conf

Additional LXC configuration parameters to set before starting the container. Either a list of variable/value mappings, or a list of strings in the format VARNAME=value. The below three examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - lxc_conf:
      - lxc.utsname: docker
      - lxc.arch: x86_64

foo:
  docker_container.running:
    - image: bar/baz:latest
    - lxc_conf: lxc.utsname=docker,lxc.arch=x86_64

foo:
  docker_container.running:
    - image: bar/baz:latest
    - 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.

foo:
  docker_container.running:
    - image: bar/baz:latest
    - 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.

foo:
  docker_container.running:
    - image: bar/baz:latest
    - mem_limit: 512M

mem_swappiness

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

foo:
  docker_container.running:
    - image: bar/baz:latest
    - 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.

foo:
  docker_container.running:
    - image: bar/baz:latest
    - memswap_limit: 1G

network_disabledFalse

If True, networking will be disabled within the container

foo:
  docker_container.running:
    - image: bar/baz:latest
    - network_disabled: True

network_modebridge

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.

foo:
  docker_container.running:
    - image: bar/baz:latest
    - network_mode: "none"

foo:
  docker_container.running:
    - image: bar/baz:latest
    - network_mode: container:web1

oom_kill_disable

Whether to disable OOM killer

foo:
  docker_container.running:
    - image: bar/baz:latest
    - oom_kill_disable: False

oom_score_adj

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

foo:
  docker_container.running:
    - image: bar/baz:latest
    - 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.

foo:
  docker_container.running:
    - image: bar/baz:latest
    - pid_mode: host

Note

This option requires Docker 1.5.0 or newer.

pids_limit

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

foo:
  docker_container.running:
    - image: bar/baz:latest
    - pids_limit: 2000

port_bindings (or publish)

Bind exposed ports. Port bindings 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 expressed as a YAML list, and port ranges can be defined using dashes. The below two examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - port_bindings: "4505-4506:14505-14506,2123:2123/udp,8080"

foo:
  docker_container.running:
    - image: bar/baz:latest
    - port_bindings:
      - 4505-4506:14505-14506
      - 2123:2123/udp
      - 8080

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 either be a comma-separated list or a YAML list. If the protocol is omitted, the port will be assumed to be a TCP port. The below two examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - ports: 1111,2222/udp

foo:
  docker_container.running:
    - image: bar/baz:latest
    - ports:
      - 1111
      - 2222/udp

privilegedFalse

If True, runs the exec process with extended privileges

foo:
  docker_container.running:
    - image: bar/baz:latest
    - privileged: True

publish_all_ports (or publish_all)False

Publish all ports to the host

foo:
  docker_container.running:
    - image: bar/baz:latest
    - ports: 8080
    - publish_all_ports: True

read_onlyFalse

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

foo:
  docker_container.running:
    - image: bar/baz:latest
    - 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.

foo:
  docker_container.running:
    - image: bar/baz:latest
    - restart_policy: on-failure:5

bar:
  docker_container.running:
    - image: bar/baz:latest
    - restart_policy: always

security_opt (or security_opts):

Security configuration for MLS systems such as SELinux and AppArmor. Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - security_opt: apparmor:unconfined

foo:
  docker_container.running:
    - image: bar/baz:latest
    - security_opt:
      - apparmor:unconfined

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

foo:
  docker_container.running:
    - image: bar/baz:latest
    - shm_size: 128M

stop_signal

Specify the signal docker will send to the container when stopping. Useful when running systemd as PID 1 inside the container.

foo:
  docker_container.running:
    - image: bar/baz:latest
    - stop_signal: SIGRTMIN+3

Note

This option requires Docker 1.9.0 or newer and docker-py 1.7.0 or newer.

New in version 2016.11.0.

stop_timeout

Timeout to stop the container, in seconds

foo:
  docker_container.running:
    - image: bar/baz:latest
    - stop_timeout: 5

Note

In releases prior to 2017.7.0, this option was not set in the container configuration, but rather this timeout was enforced only when shutting down an existing container to replace it. To remove the ambiguity, and to allow for the container to have a stop timeout set for it, the old stop_timeout argument has been renamed to shutdown_timeout, while stop_timeout now refer's to the container's configured stop timeout.

storage_opt

Storage driver options for the container. Can be either a list of strings in the format option=value, or a list of mappings between option and value. The below three examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - storage_opt:
      - dm.basesize: 40G

foo:
  docker_container.running:
    - image: bar/baz:latest
    - storage_opt: dm.basesize=40G

foo:
  docker_container.running:
    - image: bar/baz:latest
    - storage_opt:
      - dm.basesize=40G

sysctls (or sysctl)

Set sysctl options for the container. Can be either a list of strings in the format option=value, or a list of mappings between option and value. The below three examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - sysctls:
      - fs.nr_open: 1048576
      - kernel.pid_max: 32768

foo:
  docker_container.running:
    - image: bar/baz:latest
    - sysctls: fs.nr_open=1048576,kernel.pid_max=32768

foo:
  docker_container.running:
    - image: bar/baz:latest
    - 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.

foo:
  docker_container.running:
    - image: bar/baz:latest
    - tmpfs:
      - /run: rw,noexec,nosuid,size=65536k

ttyFalse

Attach TTYs

foo:
  docker_container.running:
    - image: bar/baz:latest
    - tty: True

ulimits

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 expressed as a comma-separated list or a YAML list. The below two examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - ulimits: nofile=1024:1024,nproc=60

foo:
  docker_container.running:
    - image: bar/baz:latest
    - ulimits:
      - nofile=1024:1024
      - nproc=60

user

User under which to run exec process

foo:
  docker_container.running:
    - image: bar/baz:latest
    - user: foo

userns_mode (or user_ns_mode)

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

foo:
  docker_container.running:
    - image: bar/baz:latest
    - userns_mode: host

volumes (or volume)

List of directories to expose as volumes. Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - volumes: /mnt/vol1,/mnt/vol2

foo:
  docker_container.running:
    - image: bar/baz:latest
    - volumes:
      - /mnt/vol1
      - /mnt/vol2

volumes_from

Container names or IDs from which the container will get volumes. Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:

foo:
  docker_container.running:
    - image: bar/baz:latest
    - volumes_from: foo

foo:
  docker_container.running:
    - image: bar/baz:latest
    - volumes_from:
      - foo

volume_driver

sets the container's volume driver

foo:
  docker_container.running:
    - image: bar/baz:latest
    - volume_driver: foobar

working_dir (or workdir)

Working directory inside the container

foo:
  docker_container.running:
    - image: bar/baz:latest
    - working_dir: /var/log/nginx

salt.states.docker_container.stopped(name=None, containers=None, shutdown_timeout=None, unpause=False, error_on_absent=True, **kwargs)

Ensure that a container (or containers) is stopped

name

Name or ID of the container

containers

Run this state on more than one container at a time. The following two examples accomplish the same thing:

stopped_containers:
  docker_container.stopped:
    - names:
      - foo
      - bar
      - baz

stopped_containers:
  docker_container.stopped:
    - containers:
      - foo
      - bar
      - baz

However, the second example will be a bit quicker since Salt will stop all specified containers in a single run, rather than executing the state separately on each image (as it would in the first example).

shutdown_timeout

Timeout for graceful shutdown of the container. If this timeout is exceeded, the container will be killed. If this value is not passed, then the container's configured stop_timeout will be observed. If stop_timeout was also unset on the container, then a timeout of 10 seconds will be used.

unpauseFalse

Set to True to unpause any paused containers before stopping. If unset, then an error will be raised for any container that was paused.

error_on_absentTrue

By default, this state will return an error if any of the specified containers are absent. Set this to False to suppress that error.