Debian Codegraph @

ansible_collections/containers/podman/plugins/connection/buildah.py

raw
1 # Based on modern Ansible connection plugin patterns
2 # Copyright (c) 2017 Ansible Project
3 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
4 #
5 # Connection plugin for building container images using buildah tool
6 # https://github.com/containers/buildah
7 #
8 # Rewritten with modern patterns and enhanced functionality
9
10 from __future__ import absolute_import, division, print_function
11
12 __metaclass__ = type
13
14 DOCUMENTATION = """
15 author: Tomas Tomecek (@TomasTomecek)
16 name: buildah
17 short_description: Interact with an existing buildah container
18 description:
19 - Run commands or put/fetch files to an existing container using buildah tool.
20 - Supports container building workflows with enhanced error handling and performance.
21 options:
22 remote_addr:
23 description:
24 - The ID or name of the buildah working container you want to access.
25 default: inventory_hostname
26 vars:
27 - name: inventory_hostname
28 - name: ansible_host
29 - name: ansible_buildah_host
30 env:
31 - name: ANSIBLE_BUILDAH_HOST
32 ini:
33 - section: defaults
34 key: remote_addr
35 remote_user:
36 description:
37 - User specified via name or UID which is used to execute commands inside the container.
38 - For buildah, this affects both run commands and copy operations.
39 ini:
40 - section: defaults
41 key: remote_user
42 env:
43 - name: ANSIBLE_REMOTE_USER
44 vars:
45 - name: ansible_user
46 buildah_executable:
47 description:
48 - Executable for buildah command.
49 default: buildah
50 type: str
51 vars:
52 - name: ansible_buildah_executable
53 env:
54 - name: ANSIBLE_BUILDAH_EXECUTABLE
55 ini:
56 - section: defaults
57 key: buildah_executable
58 buildah_extra_args:
59 description:
60 - Extra arguments to pass to the buildah command line.
61 default: ''
62 type: str
63 ini:
64 - section: defaults
65 key: buildah_extra_args
66 vars:
67 - name: ansible_buildah_extra_args
68 env:
69 - name: ANSIBLE_BUILDAH_EXTRA_ARGS
70 container_timeout:
71 description:
72 - Timeout in seconds for container operations. 0 means no timeout.
73 default: 0
74 type: int
75 vars:
76 - name: ansible_buildah_timeout
77 env:
78 - name: ANSIBLE_BUILDAH_TIMEOUT
79 ini:
80 - section: defaults
81 key: buildah_timeout
82 mount_detection:
83 description:
84 - Enable automatic detection and use of container mount points for file operations.
85 default: true
86 type: bool
87 vars:
88 - name: ansible_buildah_mount_detection
89 env:
90 - name: ANSIBLE_BUILDAH_MOUNT_DETECTION
91 ignore_mount_errors:
92 description:
93 - Continue with copy operations even if container mounting fails.
94 default: true
95 type: bool
96 vars:
97 - name: ansible_buildah_ignore_mount_errors
98 extra_env_vars:
99 description:
100 - Additional environment variables to set in the container.
101 default: {}
102 type: dict
103 vars:
104 - name: ansible_buildah_extra_env
105 working_directory:
106 description:
107 - Set working directory for commands executed in the container.
108 type: str
109 vars:
110 - name: ansible_buildah_working_directory
111 env:
112 - name: ANSIBLE_BUILDAH_WORKING_DIRECTORY
113 auto_commit:
114 description:
115 - Automatically commit changes after successful operations.
116 default: false
117 type: bool
118 vars:
119 - name: ansible_buildah_auto_commit
120 """
121
122 import os
123 import shlex
124 import shutil
125 import subprocess
126
127 from ansible.errors import AnsibleConnectionFailure
128 from ansible.module_utils.common.process import get_bin_path
129 try:
130 from ansible.module_utils.common.text.converters import to_native, to_bytes, to_text # noqa: F402
131 except ImportError:
132 from ansible.module_utils.common.text import to_native, to_bytes, to_text # noqa: F402
133 from ansible.plugins.connection import ConnectionBase, ensure_connect
134 from ansible.utils.display import Display
135
136 display = Display()
137
138
139 class BuildahConnectionError(AnsibleConnectionFailure):
140 """Specific exception for buildah connection issues"""
141
142
143 class ContainerNotFoundError(BuildahConnectionError):
144 """Exception for when container cannot be found"""
145
146
147 class Connection(ConnectionBase):
148 """
149 Modern connection plugin for buildah with enhanced error handling and performance optimizations
150 """
151
152 transport = "containers.podman.buildah"
153 has_pipelining = True
154
155 def __init__(self, play_context, new_stdin, *args, **kwargs):
156 super(Connection, self).__init__(play_context, new_stdin, *args, **kwargs)
157
158 self._container_id = self._play_context.remote_addr
159 self._connected = False
160 self._container_info = None
161 self._mount_point = None
162 self._executable_path = None
163 self._task_uuid = to_text(kwargs.get("task_uuid", ""))
164
165 # No pre-validation caches to preserve performance
166
167 display.vvvv("Using buildah connection from collection", host=self._container_id)
168
169 def _get_buildah_executable(self):
170 """Get and cache buildah executable path with validation"""
171 if self._executable_path is None:
172 executable = self.get_option("buildah_executable")
173 try:
174 self._executable_path = get_bin_path(executable)
175 display.vvvv(f"Found buildah executable: {self._executable_path}", host=self._container_id)
176 except ValueError as e:
177 raise BuildahConnectionError(f"Could not find {executable} in PATH: {e}")
178 return self._executable_path
179
180 def _build_buildah_command(self, cmd_args, include_container=True):
181 """Build complete buildah command with all options"""
182 cmd = [self._get_buildah_executable()]
183
184 # Add global options
185 if self.get_option("buildah_extra_args"):
186 extra_args = shlex.split(to_native(self.get_option("buildah_extra_args"), errors="surrogate_or_strict"))
187 cmd.extend(extra_args)
188
189 # Add subcommand and arguments
190 if isinstance(cmd_args, str):
191 cmd.append(cmd_args)
192 else:
193 cmd.extend(cmd_args)
194
195 # Add container ID if needed
196 if include_container:
197 cmd.append(self._container_id)
198
199 return cmd
200
201 def _run_buildah_command(self, cmd_args, input_data=None, check_rc=False, include_container=True, output_file=None):
202 """Execute buildah command once with error handling"""
203 cmd = self._build_buildah_command(cmd_args, include_container)
204 cmd_bytes = [to_bytes(arg, errors="surrogate_or_strict") for arg in cmd]
205
206 display.vvv(f"BUILDAH EXEC: {' '.join(cmd)}", host=self._container_id)
207
208 # Handle output redirection
209 stdout_fd = subprocess.PIPE
210 if output_file:
211 stdout_fd = open(output_file, "wb")
212
213 try:
214 process = subprocess.Popen(
215 cmd_bytes, stdin=subprocess.PIPE, stdout=stdout_fd, stderr=subprocess.PIPE, shell=False
216 )
217
218 # Only pass timeout if explicitly configured
219 communicate_kwargs = {}
220 container_timeout = self.get_option("container_timeout")
221 if isinstance(container_timeout, int) and container_timeout > 0:
222 communicate_kwargs["timeout"] = container_timeout
223
224 stdout, stderr = process.communicate(input=input_data, **communicate_kwargs)
225
226 if output_file:
227 stdout_fd.close()
228 stdout = b"" # No stdout when redirected to file
229
230 display.vvvvv(f"STDOUT: {stdout}", host=self._container_id)
231 display.vvvvv(f"STDERR: {stderr}", host=self._container_id)
232 display.vvvvv(f"RC: {process.returncode}", host=self._container_id)
233
234 if process.returncode != 0:
235 error_msg = to_text(stderr, errors="surrogate_or_strict").strip()
236 lower = error_msg.lower()
237 if "no such container" in lower or "container not known" in lower or "does not exist" in lower:
238 raise ContainerNotFoundError(f"Container '{self._container_id}' not found")
239 if check_rc:
240 raise BuildahConnectionError(f"Command failed (rc={process.returncode}): {error_msg}")
241
242 return process.returncode, stdout, stderr
243
244 except subprocess.TimeoutExpired:
245 if output_file and "stdout_fd" in locals():
246 stdout_fd.close()
247 process.kill()
248 timeout = self.get_option("container_timeout")
249 raise BuildahConnectionError(f"Command timeout after {timeout}s")
250 except Exception as e:
251 if output_file and "stdout_fd" in locals():
252 stdout_fd.close()
253 raise BuildahConnectionError(f"Command execution failed: {e}")
254
255 # No proactive validation; rely on operation failures for performance
256
257 def _setup_mount_point(self):
258 """Attempt to mount container filesystem for direct access"""
259 if not self.get_option("mount_detection"):
260 return
261
262 try:
263 unused, stdout, unused1 = self._run_buildah_command(["mount"])
264 mount_point = to_text(stdout, errors="surrogate_or_strict").strip()
265
266 if mount_point and os.path.isdir(mount_point):
267 # Ensure mount point has trailing separator for consistency
268 self._mount_point = mount_point.rstrip(os.sep) + os.sep
269 display.vvv(f"Container mounted at: {self._mount_point}", host=self._container_id)
270 else:
271 display.vvv("Container mount point is invalid", host=self._container_id)
272 except Exception as e:
273 if not self.get_option("ignore_mount_errors"):
274 raise BuildahConnectionError(f"Mount setup failed: {e}")
275 display.vvv(f"Mount setup failed, continuing without mount: {e}", host=self._container_id)
276
277 def _connect(self):
278 """Establish connection to container with validation and setup"""
279 super(Connection, self)._connect()
280
281 if self._connected:
282 return
283
284 display.vvv(f"Connecting to buildah container: {self._container_id}", host=self._container_id)
285
286 # No proactive validation to avoid extra subprocess overhead
287
288 self._connected = True
289 display.vvv("Connection established successfully", host=self._container_id)
290
291 @ensure_connect
292 def exec_command(self, cmd, in_data=None, sudoable=False):
293 """Execute command in container with enhanced error handling"""
294 super(Connection, self).exec_command(cmd, in_data=in_data, sudoable=sudoable)
295
296 display.vvv(f"EXEC: {cmd}", host=self._container_id)
297
298 cmd_args_list = shlex.split(to_native(cmd, errors="surrogate_or_strict"))
299 run_cmd = ["run"]
300 # Handle user specification
301 if self.get_option("remote_user") and self.get_option("remote_user") != "root":
302 run_cmd.extend(["--user", self.get_option("remote_user")])
303
304 # Add extra environment variables
305 extra_env = self.get_option("extra_env_vars")
306 if extra_env:
307 for key, value in extra_env.items():
308 run_cmd.extend(["--env", f"{key}={value}"])
309
310 # Set working directory if specified
311 working_dir = self.get_option("working_directory")
312 if working_dir:
313 run_cmd.extend(["--workingdir", working_dir])
314
315 # Add container name first, then command
316 run_cmd.append(self._container_id)
317
318 # Handle privilege escalation for buildah (different from podman)
319 if sudoable and self.get_option("remote_user") != "root":
320 # For buildah, privilege escalation means running as root user
321 # Remove the --user option and don't use sudo inside container
322 run_cmd = [arg for arg in run_cmd if not (arg == "--user" or arg == self.get_option("remote_user"))]
323
324 run_cmd.extend(cmd_args_list)
325
326 # Use include_container=False since we already added container name
327 rc, stdout, stderr = self._run_buildah_command(run_cmd, input_data=in_data, include_container=False)
328
329 # Auto-commit if enabled and command succeeded
330 if rc == 0 and self.get_option("auto_commit"):
331 self._auto_commit_changes()
332 return rc, stdout, stderr
333
334 def _auto_commit_changes(self):
335 """Automatically commit changes if enabled"""
336 try:
337 display.vvv("Auto-committing container changes", host=self._container_id)
338 self._run_buildah_command(["commit"], check_rc=False)
339 except Exception as e:
340 display.warning(f"Auto-commit failed: {e}")
341
342 def put_file(self, in_path, out_path):
343 """Transfer file to container using optimal method"""
344 super(Connection, self).put_file(in_path, out_path)
345 display.vvv(f"PUT: {in_path} -> {out_path}", host=self._container_id)
346
347 # Lazily prepare mount point if needed
348 if self._mount_point is None and self.get_option("mount_detection"):
349 self._setup_mount_point()
350
351 # Use direct filesystem copy if mount point is available
352 if self._mount_point:
353 try:
354 real_out_path = os.path.join(self._mount_point, out_path.lstrip("/"))
355 os.makedirs(os.path.dirname(real_out_path), exist_ok=True)
356 shutil.copy2(in_path, real_out_path)
357 display.vvvv(f"File copied via mount: {real_out_path}", host=self._container_id)
358
359 # Handle ownership when user is specified
360 if self.get_option("remote_user") and self.get_option("remote_user") != "root":
361 try:
362 shutil.chown(real_out_path, user=self.get_option("remote_user"))
363 except (OSError, LookupError) as e:
364 display.vvv(f"Could not change ownership via mount: {e}", host=self._container_id)
365 # Remove the file and fall back to buildah copy
366 try:
367 os.remove(real_out_path)
368 except OSError:
369 pass
370 raise Exception("Ownership change failed, falling back to buildah copy")
371 return
372 except Exception as e:
373 display.vvv(f"Mount copy failed, falling back to buildah copy: {e}", host=self._container_id)
374
375 # Use buildah copy command
376 # buildah copy [options] container src dest
377 copy_cmd = ["copy"]
378
379 # Add chown flag if user specified
380 if self.get_option("remote_user") and self.get_option("remote_user") != "root":
381 copy_cmd.extend(["--chown", self.get_option("remote_user")])
382
383 copy_cmd.extend([self._container_id, in_path, out_path])
384
385 self._run_buildah_command(copy_cmd, include_container=False)
386
387 def fetch_file(self, in_path, out_path):
388 """Retrieve file from container using optimal method"""
389 super(Connection, self).fetch_file(in_path, out_path)
390 display.vvv(f"FETCH: {in_path} -> {out_path}", host=self._container_id)
391
392 # Lazily prepare mount point if needed
393 if self._mount_point is None and self.get_option("mount_detection"):
394 self._setup_mount_point()
395
396 # Use direct filesystem copy if mount point is available
397 if self._mount_point:
398 try:
399 real_in_path = os.path.join(self._mount_point, in_path.lstrip("/"))
400 if os.path.exists(real_in_path):
401 os.makedirs(os.path.dirname(out_path), exist_ok=True)
402 shutil.copy2(real_in_path, out_path)
403 display.vvvv(f"File fetched via mount: {real_in_path}", host=self._container_id)
404 return
405 except Exception as e:
406 display.vvv(f"Mount fetch failed, falling back to buildah run: {e}", host=self._container_id)
407
408 # Use buildah run with cat command and output redirection
409 os.makedirs(os.path.dirname(out_path), exist_ok=True)
410 cat_cmd = ["run", self._container_id, "cat", in_path]
411 self._run_buildah_command(cat_cmd, output_file=out_path, include_container=False)
412
413 def close(self):
414 """Close connection and cleanup resources"""
415 super(Connection, self).close()
416
417 if self._mount_point:
418 try:
419 # Attempt to unmount the container
420 self._run_buildah_command(["umount"], check_rc=False)
421 display.vvvv("Container unmounted successfully", host=self._container_id)
422 except Exception as e:
423 display.vvvv(f"Unmount failed: {e}", host=self._container_id)
424
425 # Auto-commit on close if enabled
426 if self.get_option("auto_commit"):
427 self._auto_commit_changes()
428
429 # Clear caches
430 self._command_cache.clear()
431
432 self._connected = False
433 display.vvv("Connection closed", host=self._container_id)