Management of Docker Containers
2014.1.0 新版功能.
2015.8.0 版后已移除: Future feature development will be done only in dockerng
. See the documentation for this module for
information on the deprecation path.
注解
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
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
False
False
True
CLI 范例:
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 范例:
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, 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 http://docker-py.readthedocs.org/en/latest/volumes/)
False
False
CLI 范例:
salt '*' docker.create_container o/ubuntu volumes="['/s','/m:/f']"
salt.modules.dockerio.
diff
(container)¶Get container diffs
CLI 范例:
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 范例:
salt '*' docker.exists <container id>
salt.modules.dockerio.
export
(container, path)¶Export a container to a file
CLI 范例:
salt '*' docker.export <container id>
salt.modules.dockerio.
get_container_root
(container)¶Get the container rootfs path
CLI 范例:
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
True
False
False
CLI 范例:
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
False
True
CLI 范例:
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 范例:
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 范例:
salt '*' docker.info
salt.modules.dockerio.
inspect_container
(container)¶Get container information. This is similar to docker inspect
command but only for containers
CLI 范例:
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 范例:
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 范例:
salt '*' docker.is_running <container id>
salt.modules.dockerio.
kill
(container, signal=None)¶Kill a running container
signal to send
2015.8.0 新版功能.
CLI 范例:
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 范例:
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 范例:
salt '*' docker.login <url> <username> <password> <email>
salt.modules.dockerio.
logs
(container)¶Return logs for a specified container
CLI 范例:
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 范例:
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 范例:
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 False
True
to use insecure (non HTTPS) registry. Default is False
(only available if using docker-py >= 0.5.0)CLI 范例:
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
False
False
CLI 范例:
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 范例:
salt '*' docker.remove_image <image>
salt.modules.dockerio.
restart
(container, timeout=10)¶Restart a running container
10
secondsCLI 范例:
salt '*' docker.restart <container id> [timeout=20]
salt.modules.dockerio.
retcode
(container, cmd)¶Wrapper for cmdmod.retcode
inside a container context
注解
The return is True or False depending on the commands success.
警告
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 范例:
salt '*' docker.retcode <container id> 'ls -l /etc'
salt.modules.dockerio.
run
(container, cmd)¶Wrapper for cmdmod.run
inside a container context
注解
The return is a bit different as we use the docker struct.
Output of the command is in 'out' and result is always True
.
警告
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 范例:
salt '*' docker.run <container id> 'ls -l /etc'
salt.modules.dockerio.
run_all
(container, cmd)¶Wrapper for cmdmod.run_all
inside a container context
注解
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.
警告
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 范例:
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
注解
The return is a bit different as we use the docker struct.
Output of the command is in 'out' and result is always True
.
警告
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 范例:
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
注解
The return is a bit different as we use the docker struct.
Output of the command is in 'out' and result is always True
.
警告
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 范例:
salt '*' docker.run_stdout <container id> 'ls -l /etc'
salt.modules.dockerio.
save
(image, filename)¶2015.5.0 新版功能.
Save the specified image to filename from docker e.g. docker save image > filename
CLI 范例:
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.script
警告
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 范例:
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 范例:
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_retcode
警告
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 范例:
salt '*' docker.script_retcode <container id> salt://docker_script.py
salt.modules.dockerio.
search
(term)¶Search for an image on the registry
CLI 范例:
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 范例:
salt '*' docker.start <container id>
salt.modules.dockerio.
stop
(container, timeout=10)¶Stop a running container
10
secondsCLI 范例:
salt '*' docker.stop <container id> [timeout=20]
salt.modules.dockerio.
tag
(image, repository, tag=None, force=False)¶Tag an image into a repository
False
CLI 范例:
salt '*' docker.tag <image> <repository> [tag] [force=True|False]
salt.modules.dockerio.
top
(container)¶Run the docker top command on a specific container
CLI 范例:
salt '*' docker.top <container id>
salt.modules.dockerio.
version
()¶Get docker version
CLI 范例:
salt '*' docker.version
salt.modules.dockerio.
wait
(container)¶Wait for a container to exit gracefully
CLI 范例:
salt '*' docker.wait <container id>