salt.states.docker_image¶

Management of Docker images

depends:

docker Python module

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).

name

The name of the docker image.

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

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, tag=None, build=None, load=None, force=False, insecure_registry=False, client_timeout=60, dockerfile=None, sls=None, base='opensuse/python', saltenv='base', pillarenv=None, pillar=None, **kwargs)¶

Changed in version 2018.3.0: 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

name

The name of the docker image.

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 2018.3.0.

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.

Changed in version 2018.3.0: The tag must be manually specified using the tag argument.

load

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

myuser/myimage:
  docker_image.present:
    - load: salt://path/to/image.tar
    - tag: mytag

Changed in version 2018.3.0: The tag must be manually specified using the tag argument.

force

Set this parameter to True to force Salt to pull/build/load the image even if it is already present.

insecure_registry

If True, the Docker client will permit the use of insecure (non-HTTPS) registries.

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-separated string.

myuser/myimage:
  docker_image.present:
    - tag: latest
    - sls:
        - webapp1
        - webapp2
    - base: centos
    - saltenv: base

New in version 2017.7.0.

Changed in version 2018.3.0: The tag must be manually specified using the tag argument.

base

Base image with which to start docker.sls_build

New in version 2017.7.0.

saltenv

Specify the environment from which to retrieve the SLS indicated by the mods parameter.

New in version 2017.7.0.

Changed in version 2018.3.0: Now uses the effective saltenv if not explicitly passed. In earlier versions, base was assumed as a default.

pillarenv

Specify a Pillar environment to be used when applying states. This can also be set in the minion config file using the pillarenv option. When neither the pillarenv minion config option nor this CLI argument is used, all Pillar environments will be merged together.

New in version 2018.3.0.

pillar

Custom Pillar values, passed as a dictionary of key-value pairs

Note

Values passed this way will override Pillar values set via pillar_roots or an external Pillar source.

New in version 2018.3.0.

kwargs

Additional keyword arguments to pass to docker.build