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

  forceFalse

    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

  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.

  forceFalse

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