salt.states.dockerng¶

Why Make a Second Docker State Module?¶

We have received a lot of feedback on our Docker support. In the process of implementing recommended improvements, it became obvious that major changes needed to be made to the functions and return data. In the end, a complete rewrite was done.

The changes being too significant, it was decided that making a separate execution module and state module (called dockerng) would be the best option. This will give users a couple release cycles to modify their scripts, SLS files, etc. to use the new functionality, rather than forcing users to change everything immediately.

In the Nitrogen release of Salt (due in 2017), this execution module will take the place of the default Docker execution module, and backwards-compatible naming will be maintained for a couple releases after that to allow users time to replace references to dockerng with docker.

salt.states.dockerng.absent(name, force=False)¶

Ensure that a container is absent

name

Name of the container

force

: False

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

Usage Examples:

mycontainer:
  dockerng.absent

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

salt.states.dockerng.image_absent(name=None, images=None, force=False)¶

Ensure that an image is absent from the Minion. Image names can be specified either using repo:tag notation, or just the repo name (in which case a tag of latest is assumed).

images

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

remove_images:
  dockerng.image_absent:
    - names:
      - busybox
      - centos:6
      - nginx

remove_images:
  dockerng.image_absent:
    - images:
      - busybox
      - centos:6
      - nginx

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

force

: False

Salt will fail to remove any images currently in use by a container. Set this option to true to remove the image even if it is already present.

Note

This option can also be overridden by Pillar data. If the Minion has a pillar variable named dockerng.running.force which is set to True, it will turn on this option. This pillar variable can even be set at runtime. For example:

salt myminion state.sls docker_stuff pillar="{dockerng.force: True}"

If this pillar variable is present and set to False, then it will turn off this option.

For more granular control, setting a pillar variable named dockerng.force.image_name will affect only the named image.

salt.states.dockerng.image_present(name, build=None, load=None, force=False, insecure_registry=False, client_timeout=60, **kwargs)¶

Ensure that an image is present. The image can either be pulled from a Docker registry, built from a Dockerfile, or loaded from a saved image. Image names can be specified either using repo:tag notation, or just the repo name (in which case a tag of latest is assumed).

If neither of the build or load arguments are used, then Salt will pull from the configured registries. If the specified image already exists, it will not be pulled unless force is set to True. Here is an example of a state that will pull an image from the Docker Hub:

myuser/myimage:mytag:
  dockerng.image_present

build

Path to directory on the Minion containing a Dockerfile

myuser/myimage:mytag:
  dockerng.image_present:
    - build: /home/myuser/docker/myimage

The image will be built using dockerng.build and the specified image name and tag will be applied to it.

load

Loads a tar archive created with dockerng.load (or the docker load Docker CLI command), and assigns it the specified repo and tag.

myuser/myimage:mytag:
  dockerng.image_present:
    - load: salt://path/to/image.tar

force

: False

Set this parameter to True to force Salt to pull/build/load the image even if it is already present.

client_timeout

Timeout in seconds for the Docker client. This is not a timeout for the state, but for receiving a response from the API.

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

salt.states.dockerng.network_absent(name, driver=None)¶

Ensure that a network is absent.

name

Name of the network

Usage Examples:

network_foo:
  dockerng.network_absent

salt.states.dockerng.network_present(name, driver=None, containers=None)¶

Ensure that a network is present.

name

Name of the network

driver

Type of driver for that network.

containers:

List of container names that should be part of this network

Usage Examples:

network_foo:
  dockerng.network_present

network_bar:
  dockerng.network_present
    - name: bar
    - containers:
        - cont1
        - cont2

salt.states.dockerng.running(name, image=None, force=False, stop_timeout=10, validate_ip_addrs=True, watch_action='force', client_timeout=60, start=True, **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. Image names can be specified either using repo:tag notation, or just the repo name (in which case a tag of latest is assumed).

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 dockerng.image_present should be used to manage the image.

force

: False

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

stop_timeout

: 10

If the container needs to be replaced, the container will be stopped using dockerng.stop. The value of this parameter will be passed to dockerng.stop as the timeout value, telling Docker how long to wait for a graceful shutdown before killing the container.

validate_ip_addrs

: True

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

watch_action

: force

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:
  dockerng.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.

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.

Note

This is only used if Salt needs to pull the requested image.

CONTAINER CONFIGURATION PARAMETERS

command or cmd

Command to run in the container

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

OR

foo:
  dockerng.running:
    - image: bar/baz:latest
    - cmd: bash

Changed in version 2015.8.1: cmd is now also accepted

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.

foo:
  dockerng.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:
  dockerng.running:
    - image: bar/baz:latest
    - hostname: web1
    - network_mode: host

domainname

Domain name of the container

foo:
  dockerng.running:
    - image: bar/baz:latest
    - hostname: domain.tld

interactive

: False

Leave stdin open

foo:
  dockerng.running:
    - image: bar/baz:latest
    - interactive: True

tty

: False

Attach TTYs

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

detach

: True

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

foo:
  dockerng.running:
    - image: bar/baz:latest
    - detach: False

user

User under which to run docker

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

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:
  dockerng.running:
    - image: bar/baz:latest
    - memory: 512M

memory_swap

: -1

Total memory limit (memory plus swap). Set to -1 to disable swap. A value of 0 means no swap limit.

foo:
  dockerng.running:
    - image: bar/baz:latest
    - memory_swap: 1G

mac_address

MAC address to use for the container. If not specified, a random MAC address will be used.

foo:
  dockerng.running:
    - image: bar/baz:latest
    - mac_address: 01:23:45:67:89:0a

network_disabled

: False

If True, networking will be disabled within the container

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

working_dir

Working directory inside the container

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

entrypoint

Entrypoint for the container

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

The entrypoint can also be specified as a list of arguments:

foo:
  dockerng.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 two examples are equivalent:

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

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

Note

Values must be strings. Otherwise it will be considered as an error.

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:
  dockerng.running:
    - image: bar/baz:latest
    - ports: 1111,2222/udp

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

volumes

: None

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

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

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

cpu_shares

CPU shares (relative weight)

foo:
  dockerng.running:
    - image: bar/baz:latest
    - cpu_shares: 0.5

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:
  dockerng.running:
    - image: bar/baz:latest
    - cpuset: "0,1"

binds

Files/directories to bind mount. Each bind mount should be passed in the format <host_path>:<container_path>:<read_only>, where <read_only> is one of rw (for read-write access) or ro (for read-only access).

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

Binds can be passed as a YAML list instead of a comma-separated list:

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

Optionally, the read-only information can be left off the end and the bind mount will be assumed to be read-write. The example below is equivalent to the one above:

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

port_bindings

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 passed as a Python list. The below two examples are equivalent:

foo:
  dockerng.running:
    - image: bar/baz:latest
    - port_bindings: "5000:5000,2123:2123/udp,8080"

foo:
  dockerng.running:
    - image: bar/baz:latest
    - port_bindings:
      - 5000:5000
      - 2123:2123/udp
      - "8080"

Note

When configuring bindings for UDP ports, the protocol must be passed in the containerPort value, as seen in the examples above.

lxc_conf

Additional LXC configuration parameters to set before starting the container.

foo:
  dockerng.running:
    - image: bar/baz:latest
    - lxc_conf:
      - lxc.utsname: docker

Note

These LXC configuration parameters will only have the desired effect if the container is using the LXC execution driver, which has not been the default for some time.

publish_all_ports

: False

Allocates a random host port for each port exposed using the ports parameter

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

links

Link this container to another. Links should be specified in the format <container_name_or_id>:<link_alias>. Multiple links can be passed, either as a comma separated list or a YAML list. The below two examples are equivalent:

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

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

dns

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

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

foo:
  dockerng.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_search

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

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

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

volumes_from

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

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

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

network_mode

: bridge

One of the following:

• bridge - Creates a new network stack for the container on the docker bridge

• null - No networking (equivalent of the Docker CLI argument --net=none)

• container:<name_or_id> - Reuses another container's network stack

• host - Use the host's network stack inside the container

• Any name that identifies an existing network that might be created with dockerng.network_present.

  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:
  dockerng.running:
    - image: bar/baz:latest
    - network_mode: null

restart_policy

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 or on-failure, and retry_count is an optional limit to the number of retries. The retry count is ignored when using the always restart policy.

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

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

cap_add

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

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

foo:
  dockerng.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 passed as a comma-separated list or a Python list. The below two examples are equivalent:

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

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

Note

This option requires Docker 1.2.0 or newer.

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. The below two exampels are equivalent:

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

foo:
  dockerng.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.

pid_mode

Set to host to use the host container's PID namespace within the container

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

Note

This option requires Docker 1.5.0 or newer.

labels

Add Metadata to the container. Can be a list of strings/dictionaries or a dictionary of strings (keys and values).

foo:
  dockerng.running:
    - image: bar/baz:latest
    - labels:
        - LABEL1
        - LABEL2

foo:
  dockerng.running:
    - image: bar/baz:latest
    - labels:
        KEY1: VALUE1
        KEY2: VALUE2

foo:
  dockerng.running:
    - image: bar/baz:latest
    - labels:
      - KEY1: VALUE1
      - KEY2: VALUE2

start

: True

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.

salt.states.dockerng.stopped(name=None, containers=None, stop_timeout=10, unpause=False, error_on_absent=True)¶

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:
  dockerng.stopped:
    - names:
      - foo
      - bar
      - baz

stopped_containers:
  dockerng.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).

stop_timeout

: 10

Timeout for graceful shutdown of the container. If this timeout is exceeded, the container will be killed.

unpause

: False

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_absent

: True

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

salt.states.dockerng.volume_absent(name, driver=None)¶

Ensure that a volume is absent.

New in version 2015.8.4.

name

Name of the volume

Usage Examples:

volume_foo:
  dockerng.volume_absent

salt.states.dockerng.volume_present(name, driver=None, driver_opts=None, force=False)¶

Ensure that a volume is present.

New in version 2015.8.4.

Changed in version 2015.8.6: This function no longer deletes and re-creates a volume if the existing volume's driver does not match the driver parameter (unless the force parameter is set to True).

name

Name of the volume

driver

Type of driver for that volume. If None and the volume does not yet exist, the volume will be created using Docker's default driver. If None and the volume does exist, this function does nothing, even if the existing volume's driver is not the Docker default driver. (To ensure that an existing volume's driver matches the Docker default, you must explicitly name Docker's default driver here.)

driver_opts

Options for the volume driver

force

: False

If the volume already exists but the existing volume's driver does not match the driver specified by the driver parameter, this parameter controls whether the function errors out (if False) or deletes and re-creates the volume (if True).

New in version 2015.8.6.

Usage Examples:

volume_foo:
  dockerng.volume_present

volume_bar:
  dockerng.volume_present
    - name: bar
    - driver: local
    - driver_opts:
        foo: bar

volume_bar:
  dockerng.volume_present
    - name: bar
    - driver: local
    - driver_opts:
        - foo: bar
        - option: value