| 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) |