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
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.
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
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
- Image Management- Container ManagementRuntime Execution within a specific, already existing/running container--------------------------------------------------------------------------Idea is to use `lxc-attach <http://linux.die.net/man/1/lxc-attach>`_ to executeinside the container context.We do not want to use ``docker run`` but want to execute something inside arunning container.These are the available methods:- :py:func:`retcode<salt.modules.dockerio.retcode>`- :py:func:`run<salt.modules.dockerio.run>`- :py:func:`run_all<salt.modules.dockerio.run_all>`- :py:func:`run_stderr<salt.modules.dockerio.run_stderr>`- :py:func:`run_stdout<salt.modules.dockerio.run_stdout>`- :py:func:`script<salt.modules.dockerio.script>`- :py:func:`script_retcode<salt.modules.dockerio.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
FalseFalseTrueCLI 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)
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
True({'foo':'BAR'})({'222': {}})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'])
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 https://docker-py.readthedocs.io/en/latest/volumes/)
FalseFalseCLI Example:
salt '*' docker.create_container o/ubuntu volumes="['/s','/m:/f']"
salt.modules.dockerio.diff(container)¶Get container diffs
CLI Example:
salt '*' docker.diff <container id>
salt.modules.dockerio.exists(container)¶Check if a given container exists
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
CLI Example:
salt '*' docker.export <container id>
salt.modules.dockerio.get_container_root(container)¶Get the container rootfs path
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
TrueFalseFalseCLI 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
FalseTrueCLI 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
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
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.
CLI Example:
salt '*' docker.inspect_image <image>
salt.modules.dockerio.is_running(container)¶Check if the specified container is running
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
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
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)
CLI Example:
salt '*' docker.login <url> <username> <password> <email>
salt.modules.dockerio.logs(container)¶Return logs for a specified container
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
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
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
True to quiet output, Default is FalseTrue 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
FalseFalseCLI 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.
CLI Example:
salt '*' docker.remove_image <image>
salt.modules.dockerio.restart(container, timeout=10)¶Restart a running container
10 secondsCLI Example:
salt '*' docker.restart <container id> [timeout=20]
salt.modules.dockerio.retcode(container, cmd)¶Wrapper for cmdmod.retcode inside a container context
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
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
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
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
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
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/bash', template='jinja', umask=None, timeout=None, reset_system_locale=True, no_clean=False, saltenv='base')¶Wrapper for cmdmod.script inside a container context
cmd.scriptWarning
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/bash', template='jinja', umask=None, timeout=None, reset_system_locale=True, no_clean=False, saltenv='base')¶Wrapper for cmdmod.script_retcode inside a container context
cmd.script_retcodeWarning
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
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
CLI Example:
salt '*' docker.start <container id>
salt.modules.dockerio.stop(container, timeout=10)¶Stop a running container
10 secondsCLI Example:
salt '*' docker.stop <container id> [timeout=20]
salt.modules.dockerio.tag(image, repository, tag=None, force=False)¶Tag an image into a repository
FalseCLI Example:
salt '*' docker.tag <image> <repository> [tag] [force=True|False]
salt.modules.dockerio.top(container)¶Run the docker top command on a specific container
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
CLI Example:
salt '*' docker.wait <container id>