salt.states.dockerio

Manage Docker containers

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

Note

This state module requires docker-py which supports Docker Remote API version 1.6.

Available Functions

  • 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
        - ports:
            "5000/tcp":
                HostIp: ""
                HostPort: "5000"
    

    Note

    The port_bindings 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

Note

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=0, 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
Environment variables for the container, either
  • a mapping of key, values
  • a list of mappings of key, values
ports
List of ports definitions, either:
  • a port to map
  • a mapping of mapping portInHost : PortInContainer
volumes
List of volumes

For other parameters, see absolutely first the 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.

Note

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

Note

See first the documentation for salt file.managed <http://docs.saltstack.com/en/latest/ref/states/all/_ salt.states.file.html#salt.states.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

Note

See first the documentation for salt file.managed <http://docs.saltstack.com/en/latest/ref/states/all/_ salt.states.file.html#salt.states.file.managed>

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)

Note

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

Note

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)

Run a command in a specific container

You can match by either name or 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=0, 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
Environment variables for the container, either
  • a mapping of key, values
  • a list of mappings of key, values
ports
List of ports definitions, either:
  • a port to map
  • a mapping of mapping 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 create a volume in the container:

- volumes:
  - "/var/log/service"

For read-write mounting, use the short form (note that the notion of source:target from docker is preserved):

- volumes:
  - /var/log/service: /var/log/service

Or, 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 (mostly for backwards compatibility) a 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.

New in version Beryllium.

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.

Note

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.

Note

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