# salt.modules.dockerio

## Management of dockers

New in version Hydrogen.

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 pop continuously dockers, we will map each container id (or image) with a grain whenever it is relevant.
- As a corollary, we will resolve for a container id either directly this container 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.

- For now, you need docker-py from sources:

  > https://github.com/dotcloud/docker-py

### 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
- 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, *args, **kwargs)

  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

  CLI Example:

      salt '*' docker.build

`salt.modules.dockerio.` `commit`(container, repository=None, tag=None, message=None, author=None, conf=None, *args, **kwargs)

  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='/sbin/init', 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, *args, **kwargs)

  Get container diffs

  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'})
  dns
    list of DNS servers
  ports
    ports redirections (['222:22'])
  volumes

    list of volumes mapping:

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

  tty
    attach ttys
  stdin_open
    let stdin open
  volumes_from
    container to get volumes definition from

  EG:

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

  CLI Example:

      salt '*' docker.create_container <image>

`salt.modules.dockerio.` `diff`(container, *args, **kwargs)

  Get container diffs

  container
    container id

  CLI Example:

      salt '*' docker.diff <container id>

`salt.modules.dockerio.` `exists`(container, *args, **kwargs)

  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, *args, **kwargs)

  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, *args, **kwargs)

  Get a list of mappings representing all containers

  all
    Return all containers
  trunc
    Set it to True to have the short ID

  Returns a mapping of something which looks like container

  CLI Example:

      salt '*' docker.get_containers

`salt.modules.dockerio.` `get_images`(name=None, quiet=False, all=True, *args, **kwargs)

  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, *args, **kwargs)

  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`(*args, **kwargs)

  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, *args, **kwargs)

  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, *args, **kwargs)

  Inspect the status of an image and return relative data

  CLI Example:

      salt '*' docker.inspect_image <image>

`salt.modules.dockerio.` `invalid`(m, id=<object object at 0xf65716a8>, comment='We did not get any expectable answer from docker', out=None)

  Return invalid status

`salt.modules.dockerio.` `is_running`(container, *args, **kwargs)

  Is this container running

  container
    Container id

  Return boolean

  CLI Example:

      salt '*' docker.is_running <container id>

`salt.modules.dockerio.` `kill`(container, *args, **kwargs)

  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, *args, **kwargs)

  Wrapper to the docker.py login method, does not do much yet

  CLI Example:

      salt '*' docker.login <container id>

`salt.modules.dockerio.` `logs`(container, *args, **kwargs)

  Return logs for a specified container

  container
    container id

  CLI Example:

      salt '*' docker.logs <container id>

`salt.modules.dockerio.` `port`(container, private_port, *args, **kwargs)

  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, *args, **kwargs)

  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
          - progress:
              complete
          - status:
              Download
          ----------
          - id:
              2c80228370c9
          - progress:
              image (latest) from NAME, endpoint: URL
          - status:
              Pulling
          ----------
          - id:
              2c80228370c9
          - progress:
              image (latest) from foo/ubuntubox
          - status:
              Pulling
          ----------
          - status:
              Pulling repository foo/ubuntubox
      status:
          True

  CLI Example:

      salt '*' docker.pull <repository> [tag]

`salt.modules.dockerio.` `push`(repo, *args, **kwargs)

  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=None, force=False, v=False, *args, **kwargs)

  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, *args, **kwargs)

  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, *args, **kwargs)

  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, *args, **kwargs)

  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, *args, **kwargs)

  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, *args, **kwargs)

  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, *args, **kwargs)

  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, *args, **kwargs)

  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', *nargs, **kwargs)

  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', *args, **kwargs)

  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, *args, **kwargs)

  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, ports=None, *args, **kwargs)

  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, *args, **kwargs)

  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, *args, **kwargs)

  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, *args, **kwargs)

  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 informations,
           'mprocesses': list of mappings processes informations
           constructed above the upon informations
      }

  CLI Example:

      salt '*' docker.top <container id>

`salt.modules.dockerio.` `valid`(m, id=<object object at 0xf65716a8>, comment='', out=None)

  Return valid status

`salt.modules.dockerio.` `version`(*args, **kwargs)

  Get docker version

  CLI Example:

      salt '*' docker.version

`salt.modules.dockerio.` `wait`(container, *args, **kwargs)

  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: 0.17.1

### Table Of Contents

- salt.modules.dockerio
  - Management of dockers
    - General notes
    - Installation prerequisites
    - Prerequisite pillar configuration for authentication
    - Registry dialog methods
    - Docker management
    - Image management
    - Container management
    - Runtime execution within a specific already existing and running container

#### Previous topic

salt.modules.dnsutil

#### Next topic

salt.modules.dpkg

### Quick search

Enter search terms or a module, class or function name.

### Upcoming SaltStack Events

My conferences on Lanyrd