salt.modules.dockerio

Management of dockers

New in version 2014.1.0.

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 running salt. The version of docker-py should support version 1.12 of docker remote API..

  • For now, you need docker-py 0.3.2

    pip install docker-py==0.3.2

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 registries blocks for them to be aggregated, their id just 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

Would be the equivalent to:

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

Registry dialog methods

  • login
  • push
  • pull

Docker management

  • version
  • info

Image management

You have those methods:

  • search
  • inspect_image
  • get_images
  • remove_image
  • import_image
  • build
  • tag

Container management

You have those methods:

  • start
  • stop
  • restart
  • kill
  • wait
  • get_containers
  • inspect_container
  • remove_container
  • is_running
  • top
  • ports
  • logs
  • diff
  • commit
  • create_container
  • export
  • get_container_root

Runtime execution within a specific already existing and running container

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

You have those 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

You can either:

  • give the url/branch/docker_dir
  • give a path on the file system
path
URL or path in the filesystem to the dockerfile
tag
Tag of the image
quiet
quiet mode
nocache
do not use docker image cache
rm
remove intermediate commits
timeout
timeout is seconds before aborting

CLI Example:

salt '*' docker.build
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/imageName to commit to
tag
optional tag
message
optional commit message
author
optional author
conf
optional conf

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)

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
environment
environment variable mapping ({'foo':'BAR'})
ports
ports redirections ({'222': {}})
volumes

list of volumes mapping:

(['/mountpoint/in/container:/guest/foo',
  '/same/path/mounted/point'])
tty
attach ttys
stdin_open
let stdin open
name
name given to container

EG:

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

CLI Example:

salt '*' docker.create_container <image>
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

Parameters:container (string) -- Container id
Return type:boolean:

CLI Example:

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

Export a container to a file

container
container id
path
path to the export

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)

Get a list of mappings representing all containers

all
Return all containers
trunc
Set it to True to have the short ID
host
Include the Docker host's ipv4 and ipv6 address in return

Returns a mapping of something which looks like container

CLI Example:

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

List docker images

Parameters:
  • name (string) -- A repository name to filter on
  • quiet (boolean) -- Only show image ids
  • all (boolean) -- Show all images
Return type:

dict

Returns:

A status message with the command output

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

Parameters:
  • src (string) -- The content to import (URL, absolute path to a tarball)
  • repo (string) -- The repository to import to
  • tag (string) -- An optional tag to set

CLI Example:

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

Get the version information about docker

Return type:dict
Returns:A status message with the command output

CLI Example:

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

Get container information. This is similar to the docker inspect command.

Parameters:container (string) -- The id of the container to inspect
Return type:dict
Returns:A status message with the command output

CLI Example:

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

Inspect the status of an image and return relative data

CLI Example:

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

Is this container running

container
Container id

Return boolean

CLI Example:

salt '*' docker.is_running <container_id>
salt.modules.dockerio.kill(container)

Kill a running container

Parameters:container (string) -- The container id to kill
Return type:dict
Returns:A status message with the command output ex:
 {'id': 'abcdef123456789',
'status': True}

CLI Example:

salt '*' docker.kill <container id>
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 <container_id>
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/Public for a specific 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>
salt.modules.dockerio.pull(repo, tag=None)

Pulls an image from any registry. See above documentation for how to configure authenticated access.

Parameters:
  • repo (string) --

    The repository to pull. [registryurl://]REPOSITORY_NAME_image eg:

    index.docker.io:MyRepo/image
    superaddress.cdn:MyRepo/image
    MyRepo/image
  • tag (string) -- The specific tag to pull
Return type:

dict

Returns:

A status message with the command output Example:

----------
comment:
    Image NAME was pulled (ID
id:
    None
out:
    ----------
    - id:
        2c80228370c9
    - status:
        Download complete
    ----------
    - id:
        2c80228370c9
    - progress:
        [=========================>                         ]
    - status:
        Downloading
    ----------
    - id:
        2c80228370c9
    - status
        Pulling image (latest) from foo/ubuntubox
    ----------
    - status:
        Pulling repository foo/ubuntubox
status:
    True

CLI Example:

salt '*' docker.pull <repository> [tag]
salt.modules.dockerio.push(repo)

Pushes an image from any registry See this top level documentation to know how to configure authenticated access

repo

[registryurl://]REPOSITORY_NAME_image eg:

index.docker.io:MyRepo/image
superaddress.cdn:MyRepo/image
MyRepo/image

CLI Example:

salt '*' docker.push <repo>
salt.modules.dockerio.remove_container(container, force=False, v=False)

Removes a container from a docker installation

container
Container id to remove
force
By default, do not remove a running container, set this to remove it unconditionally
v
verbose mode

Return True or False in the status mapping and also any information about docker in status['out']

CLI Example:

salt '*' docker.remove_container <container_id>
salt.modules.dockerio.remove_image(image)

Remove an image from a system.

Parameters:image (string) -- The image to remove
Return type:string
Returns:A status message.

CLI Example:

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

Restart a running container

Parameters:
  • container (string) -- The container id to restart
  • timeout -- Wait for a timeout to let the container exit gracefully before killing it
Return type:

dict

Returns:

A status message with the command output ex:

 {'id': 'abcdef123456789',
'status': True}

CLI Example:

salt '*' docker.restart <container id>
salt.modules.dockerio.retcode(container, cmd)

Wrapper for cmdmod.retcode inside a container context

container
container id (or grain)
Other params:
See cmdmod documentation

The return is a bit different as we use the docker struct, The output of the command is in 'out' The result is false if command failed

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)
Other params:
See cmdmod documentation

The return is a bit different as we use the docker struct, The output of the command is in 'out' The 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)
Other params:
See cmdmod documentation

The return is a bit different as we use the docker struct, The output of the command is in 'out' The result if false if command failed

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)
Other params:
See cmdmod documentation

The return is a bit different as we use the docker struct, The output of the command is in 'out' The 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)
Other params:
See cmdmod documentation

The return is a bit different as we use the docker struct, The output of the command is in 'out' The 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.script(container, source, args=None, cwd=None, stdin=None, runas=None, shell='/bin/bash', env=None, template='jinja', umask=None, timeout=None, reset_system_locale=True, no_clean=False, saltenv='base')

Same usage as cmd.script but running inside a container context

container
container id or grain
others params and documentation
See cmd.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 <container id> salt://docker_script.py
salt.modules.dockerio.script_retcode(container, source, cwd=None, stdin=None, runas=None, shell='/bin/bash', env=None, template='jinja', umask=None, timeout=None, reset_system_locale=True, no_clean=False, saltenv='base')

Same usage as cmd.script_retcode but running inside a container context

container
container id or grain
others params and documentation
See cmd.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

Parameters:term (string) -- The search keyword to query

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 the specified container

container
Container id
Returns the status mapping as usual
{'id': id of the container,
'status': True if started }

CLI Example:

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

Stop a running container

Parameters:
  • container (string) -- The container id to stop
  • timeout (int) -- Wait for a timeout to let the container exit gracefully before killing it
Return type:

dict

Returns:

A status message with the command output ex:

{'id': 'abcdef123456789',
 'status': True}

CLI Example:

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

Tag an image into a repository

Parameters:
  • image (string) -- The image to tag
  • repository (string) -- The repository to tag the image
  • tag (string) -- The tag to apply
  • force (boolean) -- Forces application of the tag

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

Returns in the 'out' status mapping a mapping for those running processes:

{
     'Titles': top titles list,
     'processes': list of ordered by
                  titles processes information,
     'mprocesses': list of mappings processes information
     constructed above the upon information
}

CLI Example:

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

Get docker version

CLI Example:

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

Blocking wait for a container exit gracefully without timeout killing it

container
Container id
Return container id if successful
{'id': id of the container,
'status': True if stopped }

CLI Example:

salt '*' docker.wait <container id>

Current Salt release: 2014.1.6

Docs for previous releases on salt.rtfd.org.

Table Of Contents

Previous topic

salt.modules.dnsutil

Next topic

salt.modules.dpkg

Upcoming SaltStack Events