salt.modules.dockerio

Management of Docker Containers

New in version 2014.1.0.

Deprecated since version 2015.8.0: Future feature development will be done only in dockerng. See the documentation for this module for information on the deprecation path.

Note

The DockerIO integration is still in beta; the API is subject to change

General Notes

As we use states, we don't want to be continuously popping dockers, so we will map each container id (or image) with a grain whenever it is relevant.

As a corollary, we will resolve a container id either directly by the id or try to find a container id matching something stocked in grain.

Installation Prerequisites

  • You will need the docker-py python package in your python installation path that is running salt. Its version should support Docker Remote API v1.12.

    Currently, docker-py 0.6.0 is known to support Docker Remote API v1.12

    pip install docker-py==0.6.0
    

Prerequisite Pillar Configuration for Authentication

  • To push or pull you will need to be authenticated as the docker-py bindings require it

  • For this to happen, you will need to configure a mapping in the pillar representing your per URL authentication bits:

    docker-registries:
        registry_url:
            email: foo@foo.com
            password: s3cr3t
            username: foo
    
  • You need at least an entry to the default docker index:

    docker-registries:
        https://index.docker.io/v1/:
            email: foo@foo.com
            password: s3cr3t
            username: foo
    
  • You can define multiple registry blocks for them to be aggregated. The only thing to keep in mind is that their ID must finish with -docker-registries:

    ac-docker-registries:
        https://index.bar.io/v1/:
            email: foo@foo.com
            password: s3cr3t
            username: foo
    
    ab-docker-registries:
        https://index.foo.io/v1/:
            email: foo@foo.com
            password: s3cr3t
            username: foo
    

    This could be also written as:

    docker-registries:
        https://index.bar.io/v1/:
            email: foo@foo.com
            password: s3cr3t
            username: foo
        https://index.foo.io/v1/:
            email: foo@foo.com
            password: s3cr3t
            username: foo
    

Runtime Execution within a specific, already existing/running container

Idea is to use lxc-attach to execute inside the container context. We do not want to use docker run but want to execute something inside a running container.

These are the available methods:

salt.modules.dockerio.build(path=None, tag=None, quiet=False, fileobj=None, nocache=False, rm=True, timeout=None)

Build a docker image from a dockerfile or an URL

path
url/branch/docker_dir or path on the filesystem to the dockerfile
tag
tag of the image
quiet
quiet mode, Default is False
nocache
do not use docker image cache, Default is False
rm
remove intermediate commits, Default is True
timeout
timeout value before aborting (in seconds)

CLI Example:

salt '*' docker.build vieux/apache
salt '*' docker.build github.com/creack/docker-firefox
salt.modules.dockerio.commit(container, repository=None, tag=None, message=None, author=None, conf=None)

Commit a container (promotes it to an image)

container
container id
repository
repository/image to commit to
tag
tag of the image (Optional)
message
commit message (Optional)
author
author name (Optional)
conf
conf (Optional)

CLI Example:

salt '*' docker.commit <container id>
salt.modules.dockerio.create_container(image, 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, name=None, cpu_shares=None, cpuset=None, binds=None)

Create a new container

image
image to create the container from
command
command to execute while starting
hostname
hostname of the container
user
user to run docker as
detach
daemon mode, Default is True
environment
environment variable mapping ({'foo':'BAR'})
ports
port redirections ({'222': {}})
volumes

list of volume mappings in either local volume, bound volume, or read-only bound volume form:

(['/var/lib/mysql/', '/usr/local/etc/ssl:/etc/ssl', '/etc/passwd:/etc/passwd:ro'])
binds

complete dictionary of bound volume mappings:

{ '/usr/local/etc/ssl/certs/internal.crt': {
    'bind': '/etc/ssl/certs/com.example.internal.crt',
    'ro': True
    },
  '/var/lib/mysql': {
    'bind': '/var/lib/mysql/',
    'ro': False
    }
}

This dictionary is suitable for feeding directly into the Docker API, and all keys are required. (see http://docker-py.readthedocs.org/en/latest/volumes/)

tty
attach ttys, Default is False
stdin_open
let stdin open, Default is False
name
name given to container
cpu_shares
CPU shares (relative weight)
cpuset
CPUs in which to allow execution ('0-3' or '0,1')

CLI Example:

salt '*' docker.create_container o/ubuntu volumes="['/s','/m:/f']"
salt.modules.dockerio.diff(container)

Get container diffs

container
container id

CLI Example:

salt '*' docker.diff <container id>
salt.modules.dockerio.exists(container)

Check if a given container exists

container
container id

Returns True if container exists otherwise returns False

CLI Example:

salt '*' docker.exists <container id>
salt.modules.dockerio.export(container, path)

Export a container to a file

container
container id
path
path to which file is to be exported

CLI Example:

salt '*' docker.export <container id>
salt.modules.dockerio.get_container_root(container)

Get the container rootfs path

container
container id or grain

CLI Example:

salt '*' docker.get_container_root <container id>
salt.modules.dockerio.get_containers(all=True, trunc=False, since=None, before=None, limit=-1, host=False, inspect=False)

Get a list of mappings representing all containers

all
return all containers, Default is True
trunc
set it to True to have the short ID, Default is False
host
include the Docker host's ipv4 and ipv6 address in return, Default is False
inspect
Get more granular information about each container by running a docker inspect

CLI Example:

salt '*' docker.get_containers
salt '*' docker.get_containers host=True
salt '*' docker.get_containers host=True inspect=True
salt.modules.dockerio.get_images(name=None, quiet=False, all=True)

List docker images

name
repository name
quiet
only show image id, Default is False
all
show all images, Default is True

CLI Example:

salt '*' docker.get_images <name> [quiet=True|False] [all=True|False]
salt.modules.dockerio.import_image(src, repo, tag=None)

Import content from a local tarball or a URL to a docker image

src
content to import (URL or absolute path to a tarball)
repo
repository to import to
tag
set tag of the image (Optional)

CLI Example:

salt '*' docker.import_image <src> <repo> [tag]
salt.modules.dockerio.info()

Get the version information about docker. This is similar to docker info command

CLI Example:

salt '*' docker.info
salt.modules.dockerio.inspect_container(container)

Get container information. This is similar to docker inspect command but only for containers

container
container id

CLI Example:

salt '*' docker.inspect_container <container id>
salt.modules.dockerio.inspect_image(image)

Inspect the status of an image and return relative data. This is similar to docker inspect command but only for images.

image
name of the image

CLI Example:

salt '*' docker.inspect_image <image>
salt.modules.dockerio.is_running(container)

Check if the specified container is running

container
container id

Returns True if container is running otherwise returns False

CLI Example:

salt '*' docker.is_running <container id>
salt.modules.dockerio.kill(container, signal=None)

Kill a running container

container
container id
signal

signal to send

New in version 2015.8.0.

CLI Example:

salt '*' docker.kill <container id>
salt.modules.dockerio.load(imagepath)

Load the specified file at imagepath into docker that was generated from a docker save command e.g. docker load < imagepath

imagepath
imagepath to docker tar file

CLI Example:

salt '*' docker.load /path/to/image
salt.modules.dockerio.login(url=None, username=None, password=None, email=None)

Wrapper to the docker.py login method (does not do much yet)

url
registry url to authenticate to
username
username to authenticate
password
password to authenticate
email
email to authenticate

CLI Example:

salt '*' docker.login <url> <username> <password> <email>
salt.modules.dockerio.logs(container)

Return logs for a specified container

container
container id

CLI Example:

salt '*' docker.logs <container id>
salt.modules.dockerio.port(container, private_port)

Private port mapping allocation information. This method is broken on docker-py side. Just use the result of inspect to mangle port allocation

container
container id
private_port
private port on the container to query for

CLI Example:

salt '*' docker.port <container id> <private port>
salt.modules.dockerio.pull(repo, tag=None, insecure_registry=False)

Pulls an image from any registry. See documentation at top of this page to configure authenticated access

repo
name of repository
tag
specific tag to pull (Optional)
insecure_registry
set as True to use insecure (non HTTPS) registry. Default is False (only available if using docker-py >= 0.5.0)

CLI Example:

salt '*' docker.pull <repository> [tag]
salt.modules.dockerio.push(repo, tag=None, quiet=False, insecure_registry=False)

Pushes an image to any registry. See documentation at top of this page to configure authenticated access

repo
name of repository
tag
specific tag to push (Optional)
quiet
set as True to quiet output, Default is False
insecure_registry
set as True to use insecure (non HTTPS) registry. Default is False (only available if using docker-py >= 0.5.0)

CLI Example:

salt '*' docker.push <repository> [tag] [quiet=True|False]
salt.modules.dockerio.remove_container(container, force=False, v=False)

Remove a container from a docker installation

container
container id
force
remove a running container, Default is False
v
remove the volumes associated to the container, Default is False

CLI Example:

salt '*' docker.remove_container <container id> [force=True|False] [v=True|False]
salt.modules.dockerio.remove_image(image)

Remove an image from a system.

image
name of image

CLI Example:

salt '*' docker.remove_image <image>
salt.modules.dockerio.restart(container, timeout=10)

Restart a running container

container
container id
timeout
timeout for container to exit gracefully before killing it, Default is 10 seconds

CLI Example:

salt '*' docker.restart <container id> [timeout=20]
salt.modules.dockerio.retcode(container, cmd)

Wrapper for cmdmod.retcode inside a container context

container
container id (or grain)
cmd
command to execute

Note

The return is True or False depending on the commands success.

Warning

Be advised that this function allows for raw shell access to the named container! If allowing users to execute this directly it may allow more rights than intended!

CLI Example:

salt '*' docker.retcode <container id> 'ls -l /etc'
salt.modules.dockerio.run(container, cmd)

Wrapper for cmdmod.run inside a container context

container
container id (or grain)
cmd
command to execute

Note

The return is a bit different as we use the docker struct. Output of the command is in 'out' and result is always True.

Warning

Be advised that this function allows for raw shell access to the named container! If allowing users to execute this directly it may allow more rights than intended!

CLI Example:

salt '*' docker.run <container id> 'ls -l /etc'
salt.modules.dockerio.run_all(container, cmd)

Wrapper for cmdmod.run_all inside a container context

container
container id (or grain)
cmd
command to execute

Note

The return is a bit different as we use the docker struct. Output of the command is in 'out' and result is False if command failed to execute.

Warning

Be advised that this function allows for raw shell access to the named container! If allowing users to execute this directly it may allow more rights than intended!

CLI Example:

salt '*' docker.run_all <container id> 'ls -l /etc'
salt.modules.dockerio.run_stderr(container, cmd)

Wrapper for cmdmod.run_stderr inside a container context

container
container id (or grain)
cmd
command to execute

Note

The return is a bit different as we use the docker struct. Output of the command is in 'out' and result is always True.

Warning

Be advised that this function allows for raw shell access to the named container! If allowing users to execute this directly it may allow more rights than intended!

CLI Example:

salt '*' docker.run_stderr <container id> 'ls -l /etc'
salt.modules.dockerio.run_stdout(container, cmd)

Wrapper for cmdmod.run_stdout inside a container context

container
container id (or grain)
cmd
command to execute

Note

The return is a bit different as we use the docker struct. Output of the command is in 'out' and result is always True.

Warning

Be advised that this function allows for raw shell access to the named container! If allowing users to execute this directly it may allow more rights than intended!

CLI Example:

salt '*' docker.run_stdout <container id> 'ls -l /etc'
salt.modules.dockerio.save(image, filename)

New in version 2015.5.0.

Save the specified image to filename from docker e.g. docker save image > filename

image
name of image
filename
The filename of the saved docker image

CLI Example:

salt '*' docker.save arch_image /path/to/save/image
salt.modules.dockerio.script(container, source, args=None, cwd=None, stdin=None, runas=None, shell='/bin/sh', env=None, template='jinja', umask=None, timeout=None, reset_system_locale=True, no_clean=False, saltenv='base')

Wrapper for cmdmod.script inside a container context

container
container id (or grain)
additional parameters
See cmd.script

Warning

Be advised that this function allows for raw shell access to the named container! If allowing users to execute this directly it may allow more rights than intended!

Download a script from a remote location and execute the script in the container. The script can be located on the salt master file server or on an HTTP/FTP server.

The script will be executed directly, so it can be written in any available programming language.

The script can also be formatted as a template, the default is jinja. Arguments for the script can be specified as well.

CLI Example:

salt '*' docker.script <container id> salt://docker_script.py
salt '*' docker.script <container id> salt://scripts/runme.sh 'arg1 arg2 "arg 3"'
salt '*' docker.script <container id> salt://scripts/windows_task.ps1 args=' -Input c:\tmp\infile.txt' shell='powershell'

A string of standard input can be specified for the command to be run using the stdin parameter. This can be useful in cases where sensitive information must be read from standard input:

CLI Example:

salt '*' docker.script <container id> salt://scripts/runme.sh stdin='one\ntwo\nthree\nfour\nfive\n'
salt.modules.dockerio.script_retcode(container, source, cwd=None, stdin=None, runas=None, shell='/bin/sh', env=None, template='jinja', umask=None, timeout=None, reset_system_locale=True, no_clean=False, saltenv='base')

Wrapper for cmdmod.script_retcode inside a container context

container
container id (or grain)
additional parameters
See cmd.script_retcode

Warning

Be advised that this function allows for raw shell access to the named container! If allowing users to execute this directly it may allow more rights than intended!

CLI Example:

salt '*' docker.script_retcode <container id> salt://docker_script.py
salt.modules.dockerio.search(term)

Search for an image on the registry

term
search keyword

CLI Example:

salt '*' docker.search <term>
salt.modules.dockerio.start(container, binds=None, port_bindings=None, lxc_conf=None, publish_all_ports=None, links=None, privileged=False, dns=None, volumes_from=None, network_mode=None, restart_policy=None, cap_add=None, cap_drop=None)

Start the specified container

container
container id

CLI Example:

salt '*' docker.start <container id>
salt.modules.dockerio.stop(container, timeout=10)

Stop a running container

container
container id
timeout
timeout for container to exit gracefully before killing it, Default is 10 seconds

CLI Example:

salt '*' docker.stop <container id> [timeout=20]
salt.modules.dockerio.tag(image, repository, tag=None, force=False)

Tag an image into a repository

image
name of image
repository
name of repository
tag
tag to apply (Optional)
force
force apply tag, Default is False

CLI Example:

salt '*' docker.tag <image> <repository> [tag] [force=True|False]
salt.modules.dockerio.top(container)

Run the docker top command on a specific container

container
container id

CLI Example:

salt '*' docker.top <container id>
salt.modules.dockerio.version()

Get docker version

CLI Example:

salt '*' docker.version
salt.modules.dockerio.wait(container)

Wait for a container to exit gracefully

container
container id

CLI Example:

salt '*' docker.wait <container id>