community.docker.docker_prune module – Allows to prune various docker objects

Note

This module is part of the community.docker collection (version 4.1.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.docker. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.docker.docker_prune.

Synopsis

  • Allows to run docker container prune, docker image prune, docker network prune and docker volume prune via the Docker API.

Requirements

The below requirements are needed on the host that executes this module.

  • Docker API >= 1.25

  • backports.ssl_match_hostname (when using TLS on Python 2)

  • paramiko (when using SSH with use_ssh_client=false)

  • pyOpenSSL (when using TLS)

  • pywin32 (when using named pipes on Windows 32)

  • requests

Parameters

Parameter

Comments

api_version

aliases: docker_api_version

string

The version of the Docker API running on the Docker Host.

Defaults to the latest version of the API supported by this collection and the docker daemon.

If the value is not specified in the task, the value of environment variable DOCKER_API_VERSION will be used instead. If the environment variable is not set, the default value will be used.

Default: "auto"

builder_cache

boolean

Whether to prune the builder cache.

Choices:

  • false ← (default)

  • true

builder_cache_all

boolean

added in community.docker 3.10.0

Whether to remove all types of build cache.

Choices:

  • false ← (default)

  • true

builder_cache_filters

dictionary

added in community.docker 3.10.0

A dictionary of filter values used for selecting images to delete.

For example, until: 10m.

See the API documentation for more information on possible filters.

builder_cache_keep_storage

string

added in community.docker 3.10.0

Amount of disk space to keep for cache in format <number>[<unit>].”

Number is a positive integer. Unit can be one of B (byte), K (kibibyte, 1024B), M (mebibyte), G (gibibyte), T (tebibyte), or P (pebibyte).

Omitting the unit defaults to bytes.

ca_path

aliases: ca_cert, tls_ca_cert, cacert_path

path

Use a CA certificate when performing server verification by providing the path to a CA certificate file.

If the value is not specified in the task and the environment variable DOCKER_CERT_PATH is set, the file ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.

This option was called ca_cert and got renamed to ca_path in community.docker 3.6.0. The old name has been added as an alias and can still be used.

client_cert

aliases: tls_client_cert, cert_path

path

Path to the client’s TLS certificate file.

If the value is not specified in the task and the environment variable DOCKER_CERT_PATH is set, the file cert.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.

client_key

aliases: tls_client_key, key_path

path

Path to the client’s TLS key file.

If the value is not specified in the task and the environment variable DOCKER_CERT_PATH is set, the file key.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.

containers

boolean

Whether to prune containers.

Choices:

  • false ← (default)

  • true

containers_filters

dictionary

A dictionary of filter values used for selecting containers to delete.

For example, until: 24h.

See the docker documentation for more information on possible filters.

debug

boolean

Debug mode

Choices:

  • false ← (default)

  • true

docker_host

aliases: docker_url

string

The URL or Unix socket path used to connect to the Docker API. To connect to a remote host, provide the TCP connection string. For example, tcp://192.0.2.23:2376. If TLS is used to encrypt the connection, the module will automatically replace tcp in the connection URL with https.

If the value is not specified in the task, the value of environment variable DOCKER_HOST will be used instead. If the environment variable is not set, the default value will be used.

Default: "unix:///var/run/docker.sock"

images

boolean

Whether to prune images.

Choices:

  • false ← (default)

  • true

images_filters

dictionary

A dictionary of filter values used for selecting images to delete.

For example, dangling: true.

See the docker documentation for more information on possible filters.

networks

boolean

Whether to prune networks.

Choices:

  • false ← (default)

  • true

networks_filters

dictionary

A dictionary of filter values used for selecting networks to delete.

See the docker documentation for more information on possible filters.

timeout

integer

The maximum amount of time in seconds to wait on a response from the API.

If the value is not specified in the task, the value of environment variable DOCKER_TIMEOUT will be used instead. If the environment variable is not set, the default value will be used.

Default: 60

tls

boolean

Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server. Note that if validate_certs is set to true as well, it will take precedence.

If the value is not specified in the task, the value of environment variable DOCKER_TLS will be used instead. If the environment variable is not set, the default value will be used.

Choices:

  • false ← (default)

  • true

tls_hostname

string

When verifying the authenticity of the Docker Host server, provide the expected name of the server.

If the value is not specified in the task, the value of environment variable DOCKER_TLS_HOSTNAME will be used instead. If the environment variable is not set, the default value will be used.

Note that this option had a default value localhost in older versions. It was removed in community.docker 3.0.0.

use_ssh_client

boolean

added in community.docker 1.5.0

For SSH transports, use the ssh CLI tool instead of paramiko.

Choices:

  • false ← (default)

  • true

validate_certs

aliases: tls_verify

boolean

Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server.

If the value is not specified in the task, the value of environment variable DOCKER_TLS_VERIFY will be used instead. If the environment variable is not set, the default value will be used.

Choices:

  • false ← (default)

  • true

volumes

boolean

Whether to prune volumes.

Choices:

  • false ← (default)

  • true

volumes_filters

dictionary

A dictionary of filter values used for selecting volumes to delete.

See the docker documentation for more information on possible filters.

Attributes

Attribute

Support

Description

action_group

Action groups: community.docker.docker, docker

Use group/docker or group/community.docker.docker in module_defaults to set defaults for this module.

check_mode

Support: none

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Notes

Note

Examples

- name: Prune containers older than 24h
  community.docker.docker_prune:
    containers: true
    containers_filters:
      # only consider containers created more than 24 hours ago
      until: 24h

- name: Prune containers with labels
  community.docker.docker_prune:
    containers: true
    containers_filters:
      # Prune containers whose "foo" label has value "bar", and
      # whose "bam" label has value "baz". If you only want to
      # compare one label, you can provide it as a string instead
      # of a list with one element.
      label:
        - foo=bar
        - bam=baz
      # Prune containers whose label "bar" does *not* have value
      # "baz". If you want to avoid more than one label, you can
      # provide a list of multiple label-value pairs.
      "label!": bar=baz

- name: Prune everything
  community.docker.docker_prune:
    containers: true
    images: true
    networks: true
    volumes: true
    builder_cache: true

- name: Prune everything (including non-dangling images)
  community.docker.docker_prune:
    containers: true
    images: true
    images_filters:
      dangling: false
    networks: true
    volumes: true
    builder_cache: true

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

builder_cache_caches_deleted

list / elements=string

added in community.docker 3.10.0

The build caches that were deleted.

Returned: builder_cache=true and API version is 1.39 or later

Sample: []

builder_cache_space_reclaimed

integer

Amount of reclaimed disk space from builder cache pruning in bytes.

Returned: builder_cache=true

Sample: 0

containers

list / elements=string

List of IDs of deleted containers.

Returned: containers=true

Sample: []

containers_space_reclaimed

integer

Amount of reclaimed disk space from container pruning in bytes.

Returned: containers=true

Sample: 0

images

list / elements=string

List of IDs of deleted images.

Returned: images=true

Sample: []

images_space_reclaimed

integer

Amount of reclaimed disk space from image pruning in bytes.

Returned: images=true

Sample: 0

networks

list / elements=string

List of IDs of deleted networks.

Returned: networks=true

Sample: []

volumes

list / elements=string

List of IDs of deleted volumes.

Returned: volumes=true

Sample: []

volumes_space_reclaimed

integer

Amount of reclaimed disk space from volumes pruning in bytes.

Returned: volumes=true

Sample: 0

Authors

  • Felix Fontein (@felixfontein)