salt.states.dockerio

管理Docker containers

2015.8.0 版后已移除: Future feature development will be done only in dockerng. See the documentation for this module for information on the deprecation path.

Docker is a lightweight, portable, self-sufficient software container wrapper. The base supported wrapper type is LXC, cgroups, and the Linux Kernel.

注解

This state module requires docker-py version >= 0.6.0 which supports Docker Remote API version 1.12.

可用功能

  • built

    corp/mysuperdocker_img:
      docker.built:
        - path: /path/to/dir/container
    
  • pulled

    ubuntu:
      docker.pulled:
        - tag: latest
    
  • pushed

    corp/mysuperdocker_img:
      docker.pushed
    
  • installed

    mysuperdocker-container:
      docker.installed:
        - name: mysuperdocker
        - hostname: superdocker
        - image: corp/mysuperdocker_img
    
  • loaded

    mysuperdocker-file:
      docker.loaded:
        - name: mysuperdocker
        - source: salt://_files/tmp/docker_image.tar
    
  • running

    my_service:
      docker.running:
        - container: mysuperdocker
        - image: corp/mysuperdocker_img
        - port_bindings:
          - "5000/tcp":
                HostIp: ""
                HostPort: "5000"
    

    注解

    The ports argument above is a dictionary. The double indentation is required for PyYAML to load the data structure properly as a python dictionary. More information can be found here

  • absent

    mys_old_uperdocker:
      docker.absent
    
  • run

    /finish-install.sh:
      docker.run:
        - cid: mysuperdocker
        - unless: grep -q something /var/log/foo
        - docker_unless: grep -q done /install_log
    

Use Cases

Ensures the container is running with the latest image available

my-service-image:
  docker.pulled:
    - name: registry/my-service:latest
    - force: true

my-service-container:
  docker.installed:
    - image: registry/my-service:latest
    - watch:
      - docker: my-service-image

my-service:
  docker.running:
    - container: my-service-container
    - watch:
      - docker: my-service-container

注解

The docker modules are named dockerio because the name 'docker' would conflict with the underlying docker-py library.

salt.states.dockerio.absent(name)

Ensure that the container is absent; if not, it will will be killed and destroyed. (docker inspect)

name:
Either the container name or id
salt.states.dockerio.built(name, tag='latest', path=None, quiet=False, nocache=False, rm=True, force=False, timeout=None, *args, **kwargs)

Build a docker image from a path or URL to a dockerfile. (docker build)

name
Name of the image
tag
tag of the image (defaults to 'latest')
path
URL (e.g. url/branch/docker_dir/dockerfile) or filesystem path to the dockerfile
salt.states.dockerio.installed(name, image, tag='latest', command=None, hostname=None, user=None, detach=True, stdin_open=False, tty=False, mem_limit=None, ports=None, environment=None, dns=None, volumes=None, volumes_from=None, cpu_shares=None, cpuset=None, *args, **kwargs)

Ensure that a container with the given name exists; if not, build a new container from the specified image. (docker run)

name
Name for the container
image
Image from which to build this container
tag
tag of the image (defaults to 'latest')
environment
container的环境变量,可为以下两者中任意一种
  • 一个键值对

  • a list of mappings of key, values
ports
列出端口定义,可为以下两者中任意一种:
  • 一个要映射的端口

  • 一个一对一的映射,portInHost : PortInContainer

volumes
List of volumes (see notes for the running function)

For other parameters, see absolutely first the salt.modules.dockerio execution module and the docker-py python bindings for docker documentation for docker.create_container.

注解

This command does not verify that the named container is running the specified image.

salt.states.dockerio.loaded(name, tag='latest', source=None, source_hash='', force=False)

Load an image into the local docker registry (docker load)

name
Name of the docker image
tag
tag of the image (defaults to 'latest')
source

The source .tar file to download to the minion, created by docker save this source file can be hosted on either the salt master server, or on an HTTP or FTP server.

If the file is hosted on a HTTP or FTP server then the source_hash argument is also required

注解

See first the documentation for Salt file.managed

source_hash
This can be one of the following:
  1. a source hash string
  2. the URI of a file that contains source hash strings
force
Load even if the image exists
salt.states.dockerio.mod_watch(name, sfun=None, *args, **kw)
salt.states.dockerio.present(name, image=None, tag='latest', is_latest=False)

If a container with the given name is not present, this state will fail. Supports optionally checking for specific image/tag (docker inspect)

name:
container id
image:
image the container should be running (defaults to any)
tag:
tag of the image (defaults to 'latest')
is_latest:
also check if the container runs the latest version of the image ( latest defined as the latest pulled onto the local machine)
salt.states.dockerio.pulled(name, tag='latest', force=False, insecure_registry=False, *args, **kwargs)

Pull an image from a docker registry. (docker pull)

注解

See first the documentation for docker login, docker pull, docker push, and docker.import_image (docker import). NOTE that we added in SaltStack a way to authenticate yourself with the Docker Hub Registry by supplying your credentials (username, email & password) using pillars. For more information, see salt.modules.dockerio execution module.

name
Name of the image
tag

该image的tag

force
Pull even if the image is already pulled
insecure_registry
Set to True to allow connections to non-HTTPS registries. Default False.
salt.states.dockerio.pushed(name, tag='latest', insecure_registry=False)

Push an image from a docker registry. (docker push)

注解

See first the documentation for docker login, docker pull, docker push, and docker.import_image (docker import). NOTE that we added in SaltStack a way to authenticate yourself with the Docker Hub Registry by supplying your credentials (username, email & password) using pillars. For more information, see salt.modules.dockerio execution module.

name
Name of the image
tag
Tag of the image [Optional]
insecure_registry
Set to True to allow connections to non-HTTPS registries. Default False.
salt.states.dockerio.run(name, cid=None, hostname=None, onlyif=None, unless=None, docked_onlyif=None, docked_unless=None, *args, **kwargs)

在指定的container中运行一个命令

你可以任意匹配name或hostname

name
command to run in the container
cid
Container id or name
state_id
state_id
onlyif
Only execute cmd if statement on the host returns 0
unless
Do not execute cmd if statement on the host returns 0
docked_onlyif
Only execute cmd if statement in the container returns 0
docked_unless
Do not execute cmd if statement in the container returns 0
salt.states.dockerio.running(name, image, tag='latest', container=None, command=None, hostname=None, user=None, detach=True, stdin_open=False, tty=False, mem_limit=None, ports=None, environment=None, dns=None, volumes=None, volumes_from=None, start=True, cap_add=None, cap_drop=None, privileged=None, lxc_conf=None, network_mode=None, check_is_running=True, publish_all_ports=False, links=None, restart_policy=None, cpu_shares=None, cpuset=None, kill_signal=None, *args, **kwargs)

Ensure that a container is running. If the container does not exist, it will be created from the specified image. (docker run)

name / container
Name for the container
image
Image from which to build this container
tag
tag of the image (defaults to 'latest')
environment
container的环境变量,可为以下两者中任意一种
  • 一个键值对

  • a list of mappings of key, values
ports
列出端口定义,可为以下两者中任意一种:
  • 一个要映射的端口

  • 一个一对一的映射,portInHost : PortInContainer

- ports:
  - "5000/tcp":
        HostIp: ""
        HostPort: "5000"
publish_all_ports
Publish all ports from the port list (default is false, only meaningful if port does not contain portinhost:portincontainer mapping)
volumes

List of volumes to mount or create in the container (like -v of docker run command), mapping host directory to container directory.

To specify a volume in the container in terse list format:

- volumes:
  - "/var/log/service" # container-only volume
  - "/srv/timezone:/etc/timezone" # bound volume
  - "/usr/local/etc/passwd:/etc/passwd:ro" # read-only bound volume

You can also use the short dictionary form (note that the notion of source:target from docker is preserved):

- volumes:
  - /var/log/service: /var/log/service # mandatory read-write implied

Or, alternatively, to specify read-only mounting, use the extended form:

- volumes:
  - /home/user1:
      bind: /mnt/vol2
      ro: True
  - /var/www:
      bind: /mnt/vol1
      ro: False

Or (for backwards compatibility) another dict style:

- volumes:
    /home/user1:
      bind: /mnt/vol2
      ro: True
    /var/www:
      bind: /mnt/vol1
      ro: False
volumes_from
List of containers to share volumes with
dns

List of DNS servers.

- dns:
    - 127.0.0.1
network_mode
  • 'bridge': creates a new network stack for the container on the docker bridge
  • 'none': no networking for this container
  • 'container:[name|id]': reuses another container network stack)
  • 'host': use the host network stack inside the container
- network_mode: host
restart_policy

Restart policy to apply when a container exits (no, on-failure[:max-retry], always)

- restart_policy:
    MaximumRetryCount: 5
    Name: on-failure
cap_add
List of capabilities to add in a container.
cap_drop
List of capabilities to drop in a container.
check_is_running
Enable checking if a container should run or not. Useful for data-only containers that must be linked to another one. e.g. nginx <- static-files
cpu_shares

CPU shares (relative weight)

- cpu_shares: 2
cpuset

CPUs in which to allow execution ('0-3' or '0,1')

- cpuset: '0-3'
kill_signal

If defined, its value will be sent as a kill signal to the running container. i.e. It will use client.kill(signal=kill_signal) instead of client.restart(), when the state is triggered by a watcher requisite.

possible use case: Soft reload of nginx

nginx:
  docker.running:
    - image: some-fictional-registry.com/nginx
    - tag: latest
    - kill_signal: SIGHUP
    - watch:
      - file: /etc/nginx/nginx.conf

This state will ask nginx to reload (instead of restart) each time the /etc/nginx/nginx.conf is modified.

2015.8.0 新版功能.

For other parameters, see salt.modules.dockerio execution module and the docker-py python bindings for docker documentation <https://github.com/dotcloud/docker-py#api>`_ for docker.create_container.

注解

This command does not verify that the named container is running the specified image.

salt.states.dockerio.script(*args, **kw)

Placeholder function for a cmd.script alike.

注解

Not yet implemented. Its implementation might be very similar from salt.states.dockerio.run