salt.states.docker_image¶

Management of Docker images

salt myminion pip.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.

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.mod_watch(name, sfun=None, **kwargs)¶

The docker_image watcher, called to invoke the watch command.

Note

This state exists to support special handling of the watch requisite. It should not be called directly.

Parameters for this function should be set by the state being triggered.

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

Ensure that an image is present. The image can either be pulled from a Docker registry, built from a Dockerfile, or loaded from a saved image. Image names can be specified either using repo:tag notation, or just the repo name (in which case a tag of latest is assumed). Repo identifier is mandatory, we don't assume the default repository is docker hub.

If neither of the build or load 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:mytag:
  docker_image.present

build

Path to directory on the Minion containing a Dockerfile

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


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

New in version 2016.11.0.

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

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:mytag:
  docker_image.present:
    - load: salt://path/to/image.tar

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:mytag:
  docker_image.present:
    - 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