salt.modules.dockerio¶

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

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

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 范例:

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 范例:

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

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 范例:

salt '*' docker.create_container o/ubuntu volumes="['/s','/m:/f']"

salt.modules.dockerio.diff(container)¶

Get container diffs

container: container id

CLI 范例:

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 范例:

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 范例:

salt '*' docker.export <container id>

salt.modules.dockerio.get_container_root(container)¶

Get the container rootfs path

container: container id or grain

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

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 范例:

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 范例:

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 范例:

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

container: container id

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.

image: name of the image

CLI 范例:

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 范例:

salt '*' docker.is_running <container id>

salt.modules.dockerio.kill(container, signal=None)¶

Kill a running container

container: container id
signal: 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

imagepath: imagepath to docker tar file

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)

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

CLI 范例:

salt '*' docker.login <url> <username> <password> <email>

salt.modules.dockerio.logs(container)¶

Return logs for a specified container

container: container id

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

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

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

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 范例:

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 范例:

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 范例:

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 范例:

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 范例:

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

注解

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

container: container id (or grain)
cmd: command to execute

注解

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

container: container id (or grain)
cmd: command to execute

注解

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

container: container id (or grain)
cmd: command to execute

注解

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

container: container id (or grain)
cmd: command to execute

注解

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

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

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

container: container id (or grain)
additional parameters: See 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

container: container id (or grain)
additional parameters: See 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

term: search keyword

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

container: container id

CLI 范例:

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 范例:

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 范例:

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 范例:

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

container: container id

CLI 范例:

salt '*' docker.wait <container id>