salt.modules.dockerio¶

Management of Docker Containers

New in version 2014.1.0.

Deprecated since version Beryllium: Future feature development will be done only in docker-ng. 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.5.0 is known to support Docker Remote API v1.12
```
pip install docker-py==0.5.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

Methods¶

Registry Dialog
- login
- push
- pull
Docker Management
- version
- info
Image Management
- search
- inspect_image
- get_images
- remove_image
- import_image
- build
- tag
- save
- load
Container Management
- start
- stop
- restart
- kill
- wait
- get_containers
- inspect_container
- remove_container
- is_running
- top
- port
- logs
- diff
- commit
- create_container
- export
- get_container_root

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:

retcode
run
run_all
run_stderr
run_stdout
script
script_retcode

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=0, ports=None, environment=None, dns=None, volumes=None, volumes_from=None, name=None, cpu_shares=None, cpuset=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:

(['/mountpoint/in/container:/guest/foo', '/same/path/mounted/point'])

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

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