1#!/usr/local/bin/python3.8
2# coding: utf-8
3#
4# Copyright 2017 Red Hat | Ansible, Alex Grönholm <alex.gronholm@nextday.fi>
5# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
6
7from __future__ import absolute_import, division, print_function
8__metaclass__ = type
9
10
11DOCUMENTATION = '''
12module: docker_volume_info
13short_description: Retrieve facts about Docker volumes
14description:
15  - Performs largely the same function as the "docker volume inspect" CLI subcommand.
16options:
17  name:
18    description:
19      - Name of the volume to inspect.
20    type: str
21    required: yes
22    aliases:
23      - volume_name
24
25extends_documentation_fragment:
26- community.docker.docker
27- community.docker.docker.docker_py_1_documentation
28
29
30author:
31  - Felix Fontein (@felixfontein)
32
33requirements:
34  - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 1.8.0 (use L(docker-py,https://pypi.org/project/docker-py/) for Python 2.6)"
35  - "Docker API >= 1.21"
36'''
37
38EXAMPLES = '''
39- name: Get infos on volume
40  community.docker.docker_volume_info:
41    name: mydata
42  register: result
43
44- name: Does volume exist?
45  ansible.builtin.debug:
46    msg: "The volume {{ 'exists' if result.exists else 'does not exist' }}"
47
48- name: Print information about volume
49  ansible.builtin.debug:
50    var: result.volume
51  when: result.exists
52'''
53
54RETURN = '''
55exists:
56    description:
57      - Returns whether the volume exists.
58    type: bool
59    returned: always
60    sample: true
61volume:
62    description:
63      - Volume inspection results for the affected volume.
64      - Will be C(none) if volume does not exist.
65    returned: success
66    type: dict
67    sample: '{
68            "CreatedAt": "2018-12-09T17:43:44+01:00",
69            "Driver": "local",
70            "Labels": null,
71            "Mountpoint": "/var/lib/docker/volumes/ansible-test-bd3f6172/_data",
72            "Name": "ansible-test-bd3f6172",
73            "Options": {},
74            "Scope": "local"
75        }'
76'''
77
78import traceback
79
80from ansible.module_utils.common.text.converters import to_native
81
82try:
83    from docker.errors import DockerException, NotFound
84except ImportError:
85    # missing Docker SDK for Python handled in ansible.module_utils.docker.common
86    pass
87
88from ansible_collections.community.docker.plugins.module_utils.common import (
89    AnsibleDockerClient,
90    RequestException,
91)
92
93
94def get_existing_volume(client, volume_name):
95    try:
96        return client.inspect_volume(volume_name)
97    except NotFound as dummy:
98        return None
99    except Exception as exc:
100        client.fail("Error inspecting volume: %s" % to_native(exc))
101
102
103def main():
104    argument_spec = dict(
105        name=dict(type='str', required=True, aliases=['volume_name']),
106    )
107
108    client = AnsibleDockerClient(
109        argument_spec=argument_spec,
110        supports_check_mode=True,
111        min_docker_version='1.8.0',
112        min_docker_api_version='1.21',
113    )
114
115    try:
116        volume = get_existing_volume(client, client.module.params['name'])
117
118        client.module.exit_json(
119            changed=False,
120            exists=(True if volume else False),
121            volume=volume,
122        )
123    except DockerException as e:
124        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
125    except RequestException as e:
126        client.fail(
127            'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(to_native(e)),
128            exception=traceback.format_exc())
129
130
131if __name__ == '__main__':
132    main()
133