salt.states.docker_image

Management of Docker images

New in version 2017.7.0.

depends:docker Python module

Note

Older releases of the Python bindings for Docker were called docker-py in PyPI. All releases of docker, and releases of docker-py >= 1.6.0 are supported. These python bindings can easily be installed using pip.install:

salt myminion pip.install docker

To upgrade from docker-py to docker, you must first uninstall docker-py, and then install docker:

salt myminion pip.uninstall docker-py
salt myminion pip.install docker

These states were moved from the docker state module (formerly called dockerng) in the 2017.7.0 release.

Note

To pull from a Docker registry, authentication must be configured. See here for more information on how to configure access to docker registries in Pillar data.

salt.states.docker_image.absent(name=None, images=None, force=False)

Ensure that an image is absent from the Minion. Image names can be specified either using repo:tag notation, or just the repo name (in which case a tag of latest is assumed).

images

Run this state on more than one image at a time. The following two examples accomplish the same thing:

remove_images:
  docker_image.absent:
    - names:
      - busybox
      - centos:6
      - nginx
remove_images:
  docker_image.absent:
    - images:
      - busybox
      - centos:6
      - nginx

However, the second example will be a bit quicker since Salt will do all the deletions in a single run, rather than executing the state separately on each image (as it would in the first example).

force
: False

Salt will fail to remove any images currently in use by a container. Set this option to true to remove the image even if it is already present.

Note

This option can also be overridden by Pillar data. If the Minion has a pillar variable named docker.running.force which is set to True, it will turn on this option. This pillar variable can even be set at runtime. For example:

salt myminion state.sls docker_stuff pillar="{docker.force: True}"

If this pillar variable is present and set to False, then it will turn off this option.

For more granular control, setting a pillar variable named docker.force.image_name will affect only the named image.

salt.states.docker_image.present(name, tag=None, build=None, load=None, force=False, insecure_registry=False, client_timeout=60, dockerfile=None, sls=None, base='opensuse/python', saltenv='base', **kwargs)

Changed in version Oxygen: The tag argument has been added. It is now required unless pulling from a registry.

Ensure that an image is present. The image can either be pulled from a Docker registry, built from a Dockerfile, loaded from a saved image, or built by running SLS files against a base image.

If none of the build, load, or sls arguments are used, then Salt will pull from the configured registries. If the specified image already exists, it will not be pulled unless force is set to True. Here is an example of a state that will pull an image from the Docker Hub:

myuser/myimage:
  docker_image.present:
    - tag: mytag
tag

Tag name for the image. Required when using build, load, or sls to create the image, but optional if pulling from a repository.

New in version Oxygen.

build

Path to directory on the Minion containing a Dockerfile

myuser/myimage:
  docker_image.present:
    - build: /home/myuser/docker/myimage
    - tag: mytag

myuser/myimage:
  docker_image.present:
    - build: /home/myuser/docker/myimage
    - tag: mytag
    - dockerfile: Dockerfile.alternative

The image will be built using docker.build and the specified image name and tag will be applied to it.

New in version 2016.11.0.

load

Loads a tar archive created with docker.load (or the docker load Docker CLI command), and assigns it the specified repo and tag.

myuser/myimage:
  docker_image.present:
    - load: salt://path/to/image.tar
    - tag: mytag
force
: False
Set this parameter to True to force Salt to pull/build/load the image even if it is already present.
client_timeout
Timeout in seconds for the Docker client. This is not a timeout for the state, but for receiving a response from the API.
dockerfile

Allows for an alternative Dockerfile to be specified. Path to alternative Dockefile is relative to the build path for the Docker container.

New in version 2016.11.0.

sls

Allow for building of image with docker.sls_build by specifying the SLS files with which to build. This can be a list or comma-seperated string.

myuser/myimage:
  docker_image.present:
    - tag: latest
    - sls:
        - webapp1
        - webapp2
    - base: centos
    - saltenv: base
base
Base image with which to start docker.sls_build
saltenv
Environment from which to pull SLS files for docker.sls_build