Management of Docker containers
New in version Beryllium.
This is the state module to accompany the dockerng
execution module.
Note
To pull from a Docker registry, authentication must be configured. See here for more information on how to configure access to docker registries in Pillar data.
salt.states.dockerng.
absent
(name, force=False)¶Ensure that a container is absent
True
to remove the container even if it is runningUsage 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).
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).
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)¶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
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.
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
True
to force Salt to pull/build/load the
image even if it is already present.salt.states.dockerng.
mod_watch
(name, sfun=None, **kwargs)¶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
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.
True
to force Salt to re-create the container
irrespective of whether or not it is configured as desired.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.False
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.
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 to run in the container
foo:
dockerng.running:
- image: bar/baz:latest
- command: bash
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
Domain name of the container
foo:
dockerng.running:
- image: bar/baz:latest
- hostname: domain.tld
Leave stdin open
foo:
dockerng.running:
- image: bar/baz:latest
- interactive: True
Attach TTYs
foo:
dockerng.running:
- image: bar/baz:latest
- tty: True
If True
, run command
in the background (daemon mode)
foo:
dockerng.running:
- image: bar/baz:latest
- detach: False
User under which to run docker
foo:
dockerng.running:
- image: bar/baz:latest
- user: foo
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
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 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
If True
, networking will be disabled within the container
foo:
dockerng.running:
- image: bar/baz:latest
- network_disabled: True
Working directory inside the container
foo:
dockerng.running:
- image: bar/baz:latest
- working_dir: /var/log/nginx
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
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.
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
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 (relative weight)
foo:
dockerng.running:
- image: bar/baz:latest
- cpu_shares: 0.5
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"
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
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.
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.
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
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
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
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
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
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
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
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
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.
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.
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.
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.
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
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).
True
to unpause any paused containers before stopping. If
unset, then an error will be raised for any container that was paused.False
to suppress that error.