Debian Codegraph @

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

raw
1 #!/usr/bin/python
2 # coding: utf-8 -*-
3
4 # Copyright (c) 2023, Takuya Nishimura <@nishipy>
5 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
6 from __future__ import absolute_import, division, print_function
7
8 __metaclass__ = type
9
10 DOCUMENTATION = r"""
11 module: podman_container_exec
12 author:
13 - Takuya Nishimura (@nishipy)
14 short_description: Executes a command in a running container.
15 description:
16 - Executes a command in a running container.
17 options:
18 name:
19 description:
20 - Name of the container where the command is executed.
21 type: str
22 required: true
23 command:
24 description:
25 - The command to run in the container.
26 - One of the I(command) or I(args) is required.
27 type: str
28 argv:
29 description:
30 - Passes the command as a list rather than a string.
31 - One of the I(command) or I(args) is required.
32 type: list
33 elements: str
34 detach:
35 description:
36 - If true, the command runs in the background.
37 - The exec session is automatically removed when it completes.
38 type: bool
39 default: false
40 env:
41 description:
42 - Set environment variables.
43 type: dict
44 executable:
45 description:
46 - The path to the podman executable.
47 type: str
48 default: podman
49 privileged:
50 description:
51 - Give extended privileges to the container.
52 type: bool
53 default: false
54 tty:
55 description:
56 - Allocate a pseudo-TTY.
57 type: bool
58 default: false
59 user:
60 description:
61 - The username or UID used and, optionally, the groupname or GID for the specified command.
62 - Both user and group may be symbolic or numeric.
63 type: str
64 workdir:
65 description:
66 - Working directory inside the container.
67 type: str
68 requirements:
69 - podman
70 notes:
71 - See L(the Podman documentation,https://docs.podman.io/en/latest/markdown/podman-exec.1.html) for details of podman-exec(1).
72 """
73
74 EXAMPLES = r"""
75 - name: Execute a command with workdir
76 containers.podman.podman_container_exec:
77 name: ubi8
78 command: "cat redhat-release"
79 workdir: /etc
80
81 - name: Execute a command with a list of args and environment variables
82 containers.podman.podman_container_exec:
83 name: test_container
84 argv:
85 - /bin/sh
86 - -c
87 - echo $HELLO $BYE
88 env:
89 HELLO: hello world
90 BYE: goodbye world
91
92 - name: Execute command in background by using detach
93 containers.podman.podman_container_exec:
94 name: detach_container
95 command: "cat redhat-release"
96 detach: true
97 """
98
99 RETURN = r"""
100 stdout:
101 type: str
102 returned: success
103 description:
104 - The standard output of the command executed in the container.
105 stderr:
106 type: str
107 returned: success
108 description:
109 - The standard output of the command executed in the container.
110 rc:
111 type: int
112 returned: success
113 sample: 0
114 description:
115 - The exit code of the command executed in the container.
116 exec_id:
117 type: str
118 returned: success and I(detach=true)
119 sample: f99002e34c1087fd1aa08d5027e455bf7c2d6b74f019069acf6462a96ddf2a47
120 description:
121 - The ID of the exec session.
122 """
123
124
125 import shlex
126 try:
127 from ansible.module_utils.common.text.converters import to_text # noqa: F402
128 except ImportError:
129 from ansible.module_utils.common.text import to_text # noqa: F402
130 from ansible.module_utils.basic import AnsibleModule
131 from ansible_collections.containers.podman.plugins.module_utils.podman.common import (
132 run_podman_command,
133 )
134
135
136 def run_container_exec(module: AnsibleModule) -> dict:
137 """
138 Execute podman-container-exec for the given options
139 """
140 exec_with_args = ["container", "exec"]
141 # podman_container_exec always returns changed=true
142 changed = True
143 exec_options = []
144
145 name = module.params["name"]
146 argv = module.params["argv"]
147 command = module.params["command"]
148 detach = module.params["detach"]
149 env = module.params["env"]
150 privileged = module.params["privileged"]
151 tty = module.params["tty"]
152 user = module.params["user"]
153 workdir = module.params["workdir"]
154 executable = module.params["executable"]
155
156 if command is not None:
157 argv = shlex.split(command)
158
159 if detach:
160 exec_options.append("--detach")
161
162 if env is not None:
163 for key, value in env.items():
164 if not isinstance(value, str):
165 module.fail_json(msg="Specify string value %s on the env field" % (value))
166
167 to_text(value, errors="surrogate_or_strict")
168 exec_options += ["--env", "%s=%s" % (key, value)]
169
170 if privileged:
171 exec_options.append("--privileged")
172
173 if tty:
174 exec_options.append("--tty")
175
176 if user is not None:
177 exec_options += ["--user", to_text(user, errors="surrogate_or_strict")]
178
179 if workdir is not None:
180 exec_options += ["--workdir", to_text(workdir, errors="surrogate_or_strict")]
181
182 exec_options.append(name)
183 exec_options.extend(argv)
184
185 exec_with_args.extend(exec_options)
186
187 rc, stdout, stderr = run_podman_command(
188 module=module, executable=executable, args=exec_with_args, ignore_errors=True
189 )
190
191 result = {
192 "changed": changed,
193 "podman_command": exec_options,
194 "rc": rc,
195 "stdout": stdout,
196 "stderr": stderr,
197 }
198
199 if detach:
200 result["exec_id"] = stdout.replace("\n", "")
201
202 return result
203
204
205 def main():
206 argument_spec = {
207 "name": {
208 "type": "str",
209 "required": True,
210 },
211 "command": {
212 "type": "str",
213 },
214 "argv": {
215 "type": "list",
216 "elements": "str",
217 },
218 "detach": {
219 "type": "bool",
220 "default": False,
221 },
222 "executable": {
223 "type": "str",
224 "default": "podman",
225 },
226 "env": {
227 "type": "dict",
228 },
229 "privileged": {
230 "type": "bool",
231 "default": False,
232 },
233 "tty": {
234 "type": "bool",
235 "default": False,
236 },
237 "user": {
238 "type": "str",
239 },
240 "workdir": {
241 "type": "str",
242 },
243 }
244
245 module = AnsibleModule(
246 argument_spec=argument_spec,
247 supports_check_mode=True,
248 required_one_of=[("argv", "command")],
249 )
250
251 result = run_container_exec(module)
252 module.exit_json(**result)
253
254
255 if __name__ == "__main__":
256 main()