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.

Warning

This state module is beta. The API is subject to change. No promise as to performance or functionality is yet present.

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/Dockerfile
    
  • pulled

    ubuntu:
      docker.pulled
    
  • installed

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

    my_service:
        docker.running:
            - container: mysuperdocker
            - port_bindings:
                "5000/tcp":
                    HostIp: ""
                    HostPort: "5000"
    
  • absent

    mys_old_uperdocker:
       docker.absent
    
  • run

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

Note

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

We should add magic to all methods to also match containers by name now that the 'naming link' stuff has been merged in docker. This applies for exemple to:

  • running
  • absent
  • run
  • script
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, 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
Tag of the image
path
URL (e.g. url/branch/docker_dir/dockerfile) or filesystem path to the dockerfile
salt.states.dockerio.installed(name, image, 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, *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
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.mod_watch(name, sfun=None, *args, **kw)
salt.states.dockerio.present(name)

If a container with the given name is not present, this state will fail. (docker inspect)

name:
container id
salt.states.dockerio.pulled(name, force=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 saltack a way to identify yourself via pillar, see in the salt.modules.dockerio execution module how to ident yourself via the pillar.

name
Tag of the image
force
Pull even if the image is already pulled
salt.states.dockerio.run(name, cid=None, hostname=None, stateful=False, 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
state_id
state_id
stateful
stateful mode
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, container=None, port_bindings=None, binds=None, publish_all_ports=False, links=None, lxc_conf=None, privileged=False)

Ensure that a container is running. (docker inspect)

name
name of the service
container
name of the container to start
binds

like -v of docker run command

- binds:
    - /var/log/service: /var/log/service

publish_all_ports

links

Link several container together

- links:
    name_other_container: alias_for_other_container
port_bindings
List of ports to expose on host system
  • a mapping port's guest, hostname's host and port's host.
- port_bindings:
    "5000/tcp":
        HostIp: ""
        HostPort: "5000"
salt.states.dockerio.script(name, cid=None, hostname=None, state_id=None, stateful=False, onlyif=None, unless=None, docked_onlyif=None, docked_unless=None, *args, **kwargs)

Run a command in a specific container

XXX: TODO: IMPLEMENT

Matching can be done by either name or hostname

name
command to run in the docker
cid
Container id
state_id
State Id
stateful
stateful mode
onlyif
Only execute cmd if statement on the host return 0
unless
Do not execute cmd if statement on the host return 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

Current Salt release: 2014.1.0

Docs for previous releases on salt.rtfd.org.

Table Of Contents

Previous topic

salt.states.disk

Next topic

salt.states.eselect

Upcoming SaltStack Events