Debian Codegraph @

ansible_collections/containers/podman/plugins/modules/podman_search.py

raw
1 #!/usr/bin/python
2 # Copyright (c) 2024 Ansible Project
3 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
4
5 from __future__ import absolute_import, division, print_function
6
7 __metaclass__ = type
8
9
10 DOCUMENTATION = r"""
11 module: podman_search
12 author:
13 - Derek Waters (@derekwaters)
14 short_description: Search for remote images using podman
15 notes:
16 - Podman may required elevated privileges in order to run properly.
17 description:
18 - Search for remote images using C(podman)
19 options:
20 executable:
21 description:
22 - Path to C(podman) executable if it is not in the C($PATH) on the machine running C(podman)
23 default: 'podman'
24 type: str
25 term:
26 description:
27 - The search term to look for. Will search all default registries unless a registry is defined in the search term.
28 type: str
29 required: True
30 limit:
31 description:
32 - Limit the number of image results returned from the search (per image registry)
33 required: False
34 default: 25
35 type: int
36 list_tags:
37 description:
38 - Whether or not to return the list of tags associated with each image
39 required: False
40 default: False
41 type: bool
42
43 """
44
45 EXAMPLES = r"""
46 - name: Search for any rhel images
47 containers.podman.podman_search:
48 term: "rhel"
49 limit: 3
50
51 - name: Gather info on a specific remote image
52 containers.podman.podman_search:
53 term: "myimageregistry.com/ansible-automation-platform/ee-minimal-rhel8"
54
55 - name: Gather tag info on a known remote image
56 containers.podman.podman_search:
57 term: "myimageregistry.com/ansible-automation-platform/ee-minimal-rhel8"
58 list_tags: True
59 """
60
61 RETURN = r"""
62 images:
63 description: info from all or specified images
64 returned: always
65 type: list
66 sample: [
67 {
68 "Automated": "",
69 "Description": "Red Hat Enterprise Linux Atomic Image is a minimal, fully supported base image.",
70 "Index": "registry.access.redhat.com",
71 "Name": "registry.access.redhat.com/rhel7-atomic",
72 "Official": "",
73 "Stars": 0,
74 "Tags": ["1.0", "1.1", "1.1.1-devel"]
75 }
76 ]
77 """
78
79 import json
80
81 from ansible.module_utils.basic import AnsibleModule
82
83
84 def search_images(module, executable, term, limit, list_tags):
85 command = [executable, "search", term, "--format", "json"]
86 command.extend(["--limit", "{0}".format(limit)])
87 if list_tags:
88 command.extend(["--list-tags"])
89
90 rc, out, err = module.run_command(command)
91 if rc != 0 and list_tags and out == "" and "fetching tags list" in err:
92 return out, err
93 if rc != 0:
94 module.fail_json(msg="Unable to gather info for '{0}': {1}".format(term, err))
95 return out, err
96
97
98 def main():
99 module = AnsibleModule(
100 argument_spec=dict(
101 executable=dict(type="str", default="podman"),
102 term=dict(type="str", required=True),
103 limit=dict(type="int", required=False, default=25),
104 list_tags=dict(type="bool", required=False, default=False),
105 ),
106 supports_check_mode=True,
107 )
108
109 executable = module.params["executable"]
110 term = module.params.get("term")
111 limit = module.params.get("limit")
112 list_tags = module.params.get("list_tags")
113 executable = module.get_bin_path(executable, required=True)
114
115 result_str, errors = search_images(module, executable, term, limit, list_tags)
116 if result_str == "":
117 results = []
118 else:
119 try:
120 results = json.loads(result_str)
121 except json.decoder.JSONDecodeError:
122 module.fail_json(msg="Failed to parse JSON output from podman search: {out}".format(out=result_str))
123
124 results = dict(
125 changed=False,
126 images=results,
127 stderr=errors,
128 )
129
130 module.exit_json(**results)
131
132
133 if __name__ == "__main__":
134 main()