Debian Codegraph @

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

raw
1 #!/usr/bin/python
2 # Copyright (c) 2025 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 DOCUMENTATION = r"""
10 module: podman_system_connection_info
11 author:
12 - "Sagi Shnaidman (@sshnaidm)"
13 version_added: '1.18.0'
14 short_description: Gather info about podman system connections
15 notes: []
16 description:
17 - Gather info about podman system connections with podman system connection list command.
18 requirements:
19 - "Podman installed on host"
20 options:
21 name:
22 description:
23 - Name of the connection to gather info about
24 - If not provided, info about all connections will be returned
25 type: str
26 executable:
27 description:
28 - Path to C(podman) executable if it is not in the C($PATH) on the
29 machine running C(podman)
30 default: 'podman'
31 type: str
32 """
33
34 EXAMPLES = r"""
35 - name: Gather info about all connections
36 containers.podman.podman_system_connection_info:
37
38 - name: Gather info about specific connection
39 containers.podman.podman_system_connection_info:
40 name: production
41
42 - name: Get connection info and register result
43 containers.podman.podman_system_connection_info:
44 name: staging
45 register: staging_connection
46
47 - name: Display connection URI
48 debug:
49 msg: "Staging connection URI: {{ staging_connection.connections[0].URI }}"
50 when: staging_connection.connections | length > 0
51 """
52
53 RETURN = r"""
54 connections:
55 description: Facts from all or specified connections
56 returned: always
57 type: list
58 sample: [
59 {
60 "Name": "production",
61 "URI": "ssh://[email protected]:22/run/user/0/podman/podman.sock",
62 "Identity": "/home/user/.ssh/id_rsa",
63 "Default": true,
64 "ReadWrite": true
65 },
66 {
67 "Name": "local",
68 "URI": "unix:///run/user/1000/podman/podman.sock",
69 "Identity": "",
70 "Default": false,
71 "ReadWrite": false
72 },
73 {
74 "Name": "development",
75 "URI": "ssh://[email protected]:22/run/user/1000/podman/podman.sock",
76 "Identity": "/home/user/.ssh/dev_rsa",
77 "Default": false,
78 "ReadWrite": true
79 }
80 ]
81 """
82
83 import json
84 from ansible.module_utils.basic import AnsibleModule
85
86
87 def get_connection_info(module, executable, name):
88 """Get connection information from podman system connection list.
89
90 Retrieves connection information by executing 'podman system connection list --format json'
91 and optionally filters the results for a specific connection by name.
92
93 Args:
94 module (AnsibleModule): The Ansible module instance for running commands and error handling
95 executable (str): Path to the podman executable
96 name (str or None): Name of specific connection to filter for, or None to get all connections
97
98 Returns:
99 tuple: A tuple containing:
100 - connections (list): List of connection dictionaries matching the filter criteria
101 - out (str): Raw stdout from the podman command
102 - err (str): Raw stderr from the podman command
103
104 Raises:
105 AnsibleFailJson: If the podman command fails or JSON parsing fails
106
107 Note:
108 When a specific connection name is provided but not found, an empty list is returned
109 rather than failing. This allows for idempotent behavior when checking if connections exist.
110 """
111 command = [executable, "system", "connection", "list", "--format", "json"]
112 rc, out, err = module.run_command(command)
113
114 if rc != 0:
115 module.fail_json(msg="Unable to get list of connections: %s" % err)
116
117 try:
118 connections = json.loads(out) if out.strip() else []
119 except json.JSONDecodeError as e:
120 module.fail_json(msg="Failed to parse connection list JSON: %s" % str(e))
121
122 if name:
123 # Filter for specific connection
124 filtered_connections = [conn for conn in connections if conn.get("Name") == name]
125 # if not filtered_connections:
126 # module.fail_json(msg="Connection '%s' not found" % name)
127 return filtered_connections, out, err
128
129 return connections, out, err
130
131
132 def main():
133 """Main entry point for the podman_system_connection_info Ansible module.
134
135 This function sets up the Ansible module, validates parameters, retrieves connection
136 information from podman, and returns the results in the expected format.
137
138 The module supports check mode and never reports changes since it's an info-gathering
139 module that doesn't modify system state.
140
141 Module Parameters:
142 executable (str): Path to podman executable (default: "podman")
143 name (str, optional): Name of specific connection to get info about.
144 If not provided, returns info about all connections.
145
146 Each connection dictionary may contain the following fields:
147 - Name (str): Connection name
148 - URI (str): Connection URI (ssh://, unix://, tcp://)
149 - Default (bool): Whether this is the default connection
150 - ReadWrite (bool, optional): Read/write access (Podman version dependent)
151 - Identity (str, optional): SSH identity file path (Podman version dependent)
152 - IsMachine (bool, optional): Whether this is a machine connection (Podman version dependent)
153
154 Note:
155 Some fields like ReadWrite, Identity, and IsMachine are optional and may not be present
156 in all Podman versions. The module handles this gracefully.
157 """
158 module = AnsibleModule(
159 argument_spec=dict(executable=dict(type="str", default="podman"), name=dict(type="str")),
160 supports_check_mode=True,
161 )
162
163 name = module.params["name"]
164 executable = module.get_bin_path(module.params["executable"], required=True)
165
166 inspect_results, out, err = get_connection_info(module, executable, name)
167
168 results = {"changed": False, "connections": inspect_results, "stderr": err}
169
170 module.exit_json(**results)
171
172
173 if __name__ == "__main__":
174 main()