Add docker_prune sample to remove everything, including non-dangling images

[nicosingh]

SUMMARY

Add docker_prune example to remove everything, including non-dangling images.

ISSUE TYPE

• Docs Pull Request

+label: docsite_pr

SUMMARY

Given the condition that (by default) docker system prune only removes dangling images, it would be a good idea to show an example using dangling=true filter.

ISSUE TYPE

• Docs Pull Request

COMPONENT NAME

docker_prune.py

ADDITIONAL INFORMATION

N/A

[ansibot]

The test ansible-test sanity --test validate-modules [explain] failed with 1 error:

lib/ansible/modules/cloud/docker/docker_prune.py:113:15: E311 EXAMPLES is not valid YAML

The test ansible-test sanity --test yamllint [explain] failed with 1 error:

lib/ansible/modules/cloud/docker/docker_prune.py:113:15: error EXAMPLES: syntax error: mapping values are not allowed here

click here for bot help

[ansibot]

cc @DBendit @WojciechowskiPiotr @akshay196 @danihodovic @dariko @felixfontein @jwitko @kassiansun @tbouvet
click here for bot help

[felixfontein]

There's one problem with this example: dangling: false is the default value for the dangling filter, so your example does the same thing as the example above it. (See documentation of prune_images.)

So maybe you should change the description of the example above to "(including non-dangling images)", and change the description of this example to '(excluding non-dangling images, i.e. same behavior as docker system prune)" and set dangling: true.

[nicosingh]

There's one problem with this example: dangling: false is the default value for the dangling filter, so your example does the same thing as the example above it. (See documentation of prune_images.)

Are you sure about it?. I made a test, having two images (one dangling, and the other non-dangling):

/tmp # docker images | grep hello-world
hello-world                                                        latest              f09fe80eb0e7        2 weeks ago          109MB
hello-world                                                        <none>              fce289e99eb9        7 weeks ago          1.84kB

And no containers using them:

/tmp # docker ps -a
CONTAINER ID        IMAGE                                                                                COMMAND             CREATED             STATUS              PORTS               NAMES
b3a5edcc0739        test-ansible:latest   "sh"                14 minutes ago      Up 14 minutes                           recursing_beaver

Using default values with docker_prune:

/tmp # cat docker-prune.yml
---
- name:               docker compose up
  hosts:              localhost
  tasks:
  - name:             docker system prune
    docker_prune:
      containers:     yes
      images:         yes
      networks:       yes
      volumes:        yes
      builder_cache:  yes

After running the playbook, the non-dangling image (not used by any containers) is still there:

/tmp # ansible-playbook docker-prune.yml -v
No config file found; using defaults
 [WARNING]: No inventory was parsed, only implicit localhost is available

 [WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all'


PLAY [docker compose up] *********************************************************************************************************************************************************************************************************************

TASK [Gathering Facts] ***********************************************************************************************************************************************************************************************************************
ok: [localhost]

TASK [docker system prune] *******************************************************************************************************************************************************************************************************************
ok: [localhost] => {"builder_cache_space_reclaimed": 0, "changed": false, "containers": [], "containers_space_reclaimed": 0, "images": [], "images_space_reclaimed": 0, "networks": [], "volumes": [], "volumes_space_reclaimed": 0}

PLAY RECAP ***********************************************************************************************************************************************************************************************************************************
localhost                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

/tmp # docker images | grep hello-world
hello-world                                                        latest              f09fe80eb0e7        2 weeks ago         109MB

I think this is the expected behavior, since docker system prune includes dangling images only, by default.

Let me know if I'm wrong!. In that case, the suggested example should not be there 😬.

By the way, these are the versions of Docker/API/Ansible:

/tmp # ansible --version
ansible 2.8.0.dev0
  config file = None
  configured module search path = [u'/root/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/lib/python2.7/site-packages/ansible-2.8.0.dev0-py2.7.egg/ansible
  executable location = /usr/bin/ansible
  python version = 2.7.15 (default, Aug 16 2018, 14:17:09) [GCC 6.4.0]

/tmp # docker version
Client:
 Version:           18.06.1-ce
 API version:       1.38
 Go version:        go1.10.1
 Git commit:        d72f525745
 Built:             Wed Sep  5 20:39:22 2018
 OS/Arch:           linux/amd64
 Experimental:      false

Server: Docker Engine - Community
 Engine:
  Version:          18.09.2
  API version:      1.39 (minimum version 1.12)
  Go version:       go1.10.6
  Git commit:       6247962
  Built:            Sun Feb 10 04:13:06 2019
  OS/Arch:          linux/amd64
  Experimental:     true

[felixfontein]

No, I'm not sure, I find the documentation a bit confusing :) I've also just tested it, you're totally right: specifying dangling: false does actually delete all images not used by running containers.

[felixfontein]

shipit

[pilou-]

bot_status

[felixfontein]

@nicosingh thanks a lot for adding this example! It will appear (together with the new module) in Ansible 2.8.
@gundalow thanks for merging!