salt.states.dockerng¶

Management of Docker containers

2015.8.0 新版功能.

This is the state module to accompany the dockerng execution module.

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 Carbon release of Salt (due in 2016), 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.

注解

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

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.

注解

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

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

注解

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

注解

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.

注解

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

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

在 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

警告

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

注解

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"

注解

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

注解

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.

security_opt:

Security configuration for MLS systems such as SELinux and AppArmor.

foo:
  dockerng.running:
    - image: bar/baz:latest
    - security_opts:
      - 'apparmor:unconfined'

注解

See the documentation for security_opt at https://docs.docker.com/engine/reference/run/#security-configuration

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

注解

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.

警告

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

注解

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

注解

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

注解

To skip IP address validation, use validate_ip_addrs=False

注解

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

注解

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.

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.

2015.8.4 新版功能.

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

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