ansible/ansible-podman-collections
1
0
Fork 0
mirror of https://github.com/containers/ansible-podman-collections.git synced 2026-02-04 07:11:49 +00:00
Code Activity

Rewrite podman and buildah connections (#962)

Browse source 
* Rewrite podman and buildah connections

---------

Signed-off-by: Sagi Shnaidman <sshnaidm@redhat.com>
This commit is contained in:
Sergey 2025-09-11 20:35:09 +03:00 • committed by GitHub
parent 237bc385b9
commit 991e461ea5
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
38 changed files with 2966 additions and 344 deletions
Download patch file Download diff file Expand all files Collapse all files

468
plugins/connection/buildah.py
View file

@ -1,36 +1,41 @@
# Based on the docker connection plugin
# Based on modern Ansible connection plugin patterns
# Copyright (c) 2017 Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
#
# Connection plugin for building container images using buildah tool
# https://github.com/projectatomic/buildah
# https://github.com/containers/buildah
#
# Written by: Tomas Tomecek (https://github.com/TomasTomecek)
# Rewritten with modern patterns and enhanced functionality
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = """
author: Tomas Tomecek (@TomasTomecek)
name: buildah
short_description: Interact with an existing buildah container
description:
- Run commands or put/fetch files to an existing container using buildah tool.
author: Tomas Tomecek (@TomasTomecek)
name: buildah
- Supports container building workflows with enhanced error handling and performance.
options:
remote_addr:
description:
- The ID of the container you want to access.
- The ID or name of the buildah working container you want to access.
default: inventory_hostname
vars:
- name: ansible_host
- name: inventory_hostname
# keyword:
# - name: hosts
- name: inventory_hostname
- name: ansible_host
- name: ansible_buildah_host
env:
- name: ANSIBLE_BUILDAH_HOST
ini:
- section: defaults
key: remote_addr
remote_user:
description:
- User specified via name or ID which is used to execute commands inside the container.
- User specified via name or UID which is used to execute commands inside the container.
- For buildah, this affects both run commands and copy operations.
ini:
- section: defaults
key: remote_user
@ -38,8 +43,80 @@ DOCUMENTATION = """
- name: ANSIBLE_REMOTE_USER
vars:
- name: ansible_user
# keyword:
# - name: remote_user
buildah_executable:
description:
- Executable for buildah command.
default: buildah
type: str
vars:
- name: ansible_buildah_executable
env:
- name: ANSIBLE_BUILDAH_EXECUTABLE
ini:
- section: defaults
key: buildah_executable
buildah_extra_args:
description:
- Extra arguments to pass to the buildah command line.
default: ''
type: str
ini:
- section: defaults
key: buildah_extra_args
vars:
- name: ansible_buildah_extra_args
env:
- name: ANSIBLE_BUILDAH_EXTRA_ARGS
container_timeout:
description:
- Timeout in seconds for container operations. 0 means no timeout.
default: 0
type: int
vars:
- name: ansible_buildah_timeout
env:
- name: ANSIBLE_BUILDAH_TIMEOUT
ini:
- section: defaults
key: buildah_timeout
mount_detection:
description:
- Enable automatic detection and use of container mount points for file operations.
default: true
type: bool
vars:
- name: ansible_buildah_mount_detection
env:
- name: ANSIBLE_BUILDAH_MOUNT_DETECTION
ignore_mount_errors:
description:
- Continue with copy operations even if container mounting fails.
default: true
type: bool
vars:
- name: ansible_buildah_ignore_mount_errors
extra_env_vars:
description:
- Additional environment variables to set in the container.
default: {}
type: dict
vars:
- name: ansible_buildah_extra_env
working_directory:
description:
- Set working directory for commands executed in the container.
type: str
vars:
- name: ansible_buildah_working_directory
env:
- name: ANSIBLE_BUILDAH_WORKING_DIRECTORY
auto_commit:
description:
- Automatically commit changes after successful operations.
default: false
type: bool
vars:
- name: ansible_buildah_auto_commit
"""
import os
@ -47,7 +124,8 @@ import shlex
import shutil
import subprocess
from ansible.errors import AnsibleError
from ansible.errors import AnsibleConnectionFailure
from ansible.module_utils.common.process import get_bin_path
from ansible.module_utils._text import to_bytes, to_native, to_text
from ansible.plugins.connection import ConnectionBase, ensure_connect
from ansible.utils.display import Display
@ -55,13 +133,19 @@ from ansible.utils.display import Display
display = Display()
# this _has to be_ named Connection
class BuildahConnectionError(AnsibleConnectionFailure):
"""Specific exception for buildah connection issues"""
class ContainerNotFoundError(BuildahConnectionError):
"""Exception for when container cannot be found"""
class Connection(ConnectionBase):
"""
This is a connection plugin for buildah: it uses buildah binary to interact with the containers
Modern connection plugin for buildah with enhanced error handling and performance optimizations
"""
# String used to identify this Connection class from other classes
transport = "containers.podman.buildah"
has_pipelining = True
@ -70,139 +154,277 @@ class Connection(ConnectionBase):
self._container_id = self._play_context.remote_addr
self._connected = False
# container filesystem will be mounted here on host
self._container_info = None
self._mount_point = None
# `buildah inspect` doesn't contain info about what the default user is -- if it's not
# set, it's empty
self.user = self._play_context.remote_user
display.vvvv("Using buildah connection from collection")
self._executable_path = None
self._task_uuid = to_text(kwargs.get("task_uuid", ""))
def _set_user(self):
self._buildah(b"config", [b"--user=" + to_bytes(self.user, errors="surrogate_or_strict")])
# No pre-validation caches to preserve performance
def _buildah(self, cmd, cmd_args=None, in_data=None, outfile_stdout=None):
"""
run buildah executable
display.vvvv("Using buildah connection from collection", host=self._container_id)
:param cmd: buildah's command to execute (str)
:param cmd_args: list of arguments to pass to the command (list of str/bytes)
:param in_data: data passed to buildah's stdin
:param outfile_stdout: file for writing STDOUT to
:return: return code, stdout, stderr
"""
buildah_exec = "buildah"
local_cmd = [buildah_exec]
def _get_buildah_executable(self):
"""Get and cache buildah executable path with validation"""
if self._executable_path is None:
executable = self.get_option("buildah_executable")
try:
self._executable_path = get_bin_path(executable)
display.vvvv(f"Found buildah executable: {self._executable_path}", host=self._container_id)
except ValueError as e:
raise BuildahConnectionError(f"Could not find {executable} in PATH: {e}")
return self._executable_path
if isinstance(cmd, str):
local_cmd.append(cmd)
def _build_buildah_command(self, cmd_args, include_container=True):
"""Build complete buildah command with all options"""
cmd = [self._get_buildah_executable()]
# Add global options
if self.get_option("buildah_extra_args"):
extra_args = shlex.split(to_native(self.get_option("buildah_extra_args"), errors="surrogate_or_strict"))
cmd.extend(extra_args)
# Add subcommand and arguments
if isinstance(cmd_args, str):
cmd.append(cmd_args)
else:
local_cmd.extend(cmd)
if self.user and self.user != "root":
if cmd == "run":
local_cmd.extend(("--user", self.user))
elif cmd == "copy":
local_cmd.extend(("--chown", self.user))
local_cmd.append(self._container_id)
cmd.extend(cmd_args)
if cmd_args:
if isinstance(cmd_args, str):
local_cmd.append(cmd_args)
# Add container ID if needed
if include_container:
cmd.append(self._container_id)
return cmd
def _run_buildah_command(self, cmd_args, input_data=None, check_rc=False, include_container=True, output_file=None):
"""Execute buildah command once with error handling"""
cmd = self._build_buildah_command(cmd_args, include_container)
cmd_bytes = [to_bytes(arg, errors="surrogate_or_strict") for arg in cmd]
display.vvv(f"BUILDAH EXEC: {' '.join(cmd)}", host=self._container_id)
# Handle output redirection
stdout_fd = subprocess.PIPE
if output_file:
stdout_fd = open(output_file, "wb")
try:
process = subprocess.Popen(
cmd_bytes, stdin=subprocess.PIPE, stdout=stdout_fd, stderr=subprocess.PIPE, shell=False
)
# Only pass timeout if explicitly configured
communicate_kwargs = {}
container_timeout = self.get_option("container_timeout")
if isinstance(container_timeout, int) and container_timeout > 0:
communicate_kwargs["timeout"] = container_timeout
stdout, stderr = process.communicate(input=input_data, **communicate_kwargs)
if output_file:
stdout_fd.close()
stdout = b"" # No stdout when redirected to file
display.vvvvv(f"STDOUT: {stdout}", host=self._container_id)
display.vvvvv(f"STDERR: {stderr}", host=self._container_id)
display.vvvvv(f"RC: {process.returncode}", host=self._container_id)
if process.returncode != 0:
error_msg = to_text(stderr, errors="surrogate_or_strict").strip()
lower = error_msg.lower()
if "no such container" in lower or "container not known" in lower or "does not exist" in lower:
raise ContainerNotFoundError(f"Container '{self._container_id}' not found")
if check_rc:
raise BuildahConnectionError(f"Command failed (rc={process.returncode}): {error_msg}")
return process.returncode, stdout, stderr
except subprocess.TimeoutExpired:
if output_file and "stdout_fd" in locals():
stdout_fd.close()
process.kill()
timeout = self.get_option("container_timeout")
raise BuildahConnectionError(f"Command timeout after {timeout}s")
except Exception as e:
if output_file and "stdout_fd" in locals():
stdout_fd.close()
raise BuildahConnectionError(f"Command execution failed: {e}")
# No proactive validation; rely on operation failures for performance
def _setup_mount_point(self):
"""Attempt to mount container filesystem for direct access"""
if not self.get_option("mount_detection"):
return
try:
unused, stdout, unused1 = self._run_buildah_command(["mount"])
mount_point = to_text(stdout, errors="surrogate_or_strict").strip()
if mount_point and os.path.isdir(mount_point):
# Ensure mount point has trailing separator for consistency
self._mount_point = mount_point.rstrip(os.sep) + os.sep
display.vvv(f"Container mounted at: {self._mount_point}", host=self._container_id)
else:
local_cmd.extend(cmd_args)
local_cmd = [to_bytes(i, errors="surrogate_or_strict") for i in local_cmd]
display.vvv("RUN %s" % (local_cmd,), host=self._container_id)
if outfile_stdout:
stdout_fd = open(outfile_stdout, "wb")
else:
stdout_fd = subprocess.PIPE
p = subprocess.Popen(
local_cmd,
shell=False,
stdin=subprocess.PIPE,
stdout=stdout_fd,
stderr=subprocess.PIPE,
)
stdout, stderr = p.communicate(input=in_data)
display.vvvv("STDOUT %s" % to_text(stdout))
display.vvvv("STDERR %s" % to_text(stderr))
display.vvvv("RC CODE %s" % p.returncode)
stdout = to_bytes(stdout, errors="surrogate_or_strict")
stderr = to_bytes(stderr, errors="surrogate_or_strict")
return p.returncode, stdout, stderr
display.vvv("Container mount point is invalid", host=self._container_id)
except Exception as e:
if not self.get_option("ignore_mount_errors"):
raise BuildahConnectionError(f"Mount setup failed: {e}")
display.vvv(f"Mount setup failed, continuing without mount: {e}", host=self._container_id)
def _connect(self):
"""
no persistent connection is being maintained, mount container's filesystem
so we can easily access it
"""
"""Establish connection to container with validation and setup"""
super(Connection, self)._connect()
rc, self._mount_point, stderr = self._buildah("mount")
if rc != 0:
display.v("Failed to mount container %s: %s" % (self._container_id, stderr.strip()))
else:
self._mount_point = self._mount_point.strip() + to_bytes(os.path.sep, errors="surrogate_or_strict")
display.vvvv("MOUNTPOINT %s RC %s STDERR %r" % (self._mount_point, rc, stderr))
if self._connected:
return
display.vvv(f"Connecting to buildah container: {self._container_id}", host=self._container_id)
# No proactive validation to avoid extra subprocess overhead
self._connected = True
display.vvv("Connection established successfully", host=self._container_id)
@ensure_connect
def exec_command(self, cmd, in_data=None, sudoable=False):
"""run specified command in a running OCI container using buildah"""
"""Execute command in container with enhanced error handling"""
super(Connection, self).exec_command(cmd, in_data=in_data, sudoable=sudoable)
# shlex.split has a bug with text strings on Python-2.6 and can only handle text strings on Python-3
display.vvv(f"EXEC: {cmd}", host=self._container_id)
cmd_args_list = shlex.split(to_native(cmd, errors="surrogate_or_strict"))
run_cmd = ["run"]
# Handle user specification
if self.get_option("remote_user") and self.get_option("remote_user") != "root":
run_cmd.extend(["--user", self.get_option("remote_user")])
rc, stdout, stderr = self._buildah("run", cmd_args_list, in_data)
# Add extra environment variables
extra_env = self.get_option("extra_env_vars")
if extra_env:
for key, value in extra_env.items():
run_cmd.extend(["--env", f"{key}={value}"])
display.vvvv("STDOUT %r\nSTDERR %r" % (stderr, stderr))
# Set working directory if specified
working_dir = self.get_option("working_directory")
if working_dir:
run_cmd.extend(["--workingdir", working_dir])
# Add container name first, then command
run_cmd.append(self._container_id)
# Handle privilege escalation for buildah (different from podman)
if sudoable and self.get_option("remote_user") != "root":
# For buildah, privilege escalation means running as root user
# Remove the --user option and don't use sudo inside container
run_cmd = [arg for arg in run_cmd if not (arg == "--user" or arg == self.get_option("remote_user"))]
run_cmd.extend(cmd_args_list)
# Use include_container=False since we already added container name
rc, stdout, stderr = self._run_buildah_command(run_cmd, input_data=in_data, include_container=False)
# Auto-commit if enabled and command succeeded
if rc == 0 and self.get_option("auto_commit"):
self._auto_commit_changes()
return rc, stdout, stderr
def _auto_commit_changes(self):
"""Automatically commit changes if enabled"""
try:
display.vvv("Auto-committing container changes", host=self._container_id)
self._run_buildah_command(["commit"], check_rc=False)
except Exception as e:
display.warning(f"Auto-commit failed: {e}")
def put_file(self, in_path, out_path):
"""Place a local file located in 'in_path' inside container at 'out_path'"""
"""Transfer file to container using optimal method"""
super(Connection, self).put_file(in_path, out_path)
display.vvv("PUT %s TO %s" % (in_path, out_path), host=self._container_id)
if not self._mount_point or self.user:
rc, stdout, stderr = self._buildah("copy", [in_path, out_path])
if rc != 0:
raise AnsibleError(
"Failed to copy file from %s to %s in container %s\n%s"
% (in_path, out_path, self._container_id, stderr)
)
else:
real_out_path = self._mount_point + to_bytes(out_path, errors="surrogate_or_strict")
shutil.copyfile(
to_bytes(in_path, errors="surrogate_or_strict"),
to_bytes(real_out_path, errors="surrogate_or_strict"),
)
display.vvv(f"PUT: {in_path} -> {out_path}", host=self._container_id)
# Lazily prepare mount point if needed
if self._mount_point is None and self.get_option("mount_detection"):
self._setup_mount_point()
# Use direct filesystem copy if mount point is available
if self._mount_point:
try:
real_out_path = os.path.join(self._mount_point, out_path.lstrip("/"))
os.makedirs(os.path.dirname(real_out_path), exist_ok=True)
shutil.copy2(in_path, real_out_path)
display.vvvv(f"File copied via mount: {real_out_path}", host=self._container_id)
# Handle ownership when user is specified
if self.get_option("remote_user") and self.get_option("remote_user") != "root":
try:
shutil.chown(real_out_path, user=self.get_option("remote_user"))
except (OSError, LookupError) as e:
display.vvv(f"Could not change ownership via mount: {e}", host=self._container_id)
# Remove the file and fall back to buildah copy
try:
os.remove(real_out_path)
except OSError:
pass
raise Exception("Ownership change failed, falling back to buildah copy")
return
except Exception as e:
display.vvv(f"Mount copy failed, falling back to buildah copy: {e}", host=self._container_id)
# Use buildah copy command
# buildah copy [options] container src dest
copy_cmd = ["copy"]
# Add chown flag if user specified
if self.get_option("remote_user") and self.get_option("remote_user") != "root":
copy_cmd.extend(["--chown", self.get_option("remote_user")])
copy_cmd.extend([self._container_id, in_path, out_path])
self._run_buildah_command(copy_cmd, include_container=False)
def fetch_file(self, in_path, out_path):
"""obtain file specified via 'in_path' from the container and place it at 'out_path'"""
"""Retrieve file from container using optimal method"""
super(Connection, self).fetch_file(in_path, out_path)
display.vvv("FETCH %s TO %s" % (in_path, out_path), host=self._container_id)
if not self._mount_point:
rc, stdout, stderr = self._buildah(
"run",
["cat", to_bytes(in_path, errors="surrogate_or_strict")],
outfile_stdout=out_path,
)
if rc != 0:
raise AnsibleError(
"Failed to fetch file from %s to %s from container %s\n%s"
% (in_path, out_path, self._container_id, stderr)
)
else:
real_in_path = self._mount_point + to_bytes(in_path, errors="surrogate_or_strict")
shutil.copyfile(
to_bytes(real_in_path, errors="surrogate_or_strict"),
to_bytes(out_path, errors="surrogate_or_strict"),
)
display.vvv(f"FETCH: {in_path} -> {out_path}", host=self._container_id)
# Lazily prepare mount point if needed
if self._mount_point is None and self.get_option("mount_detection"):
self._setup_mount_point()
# Use direct filesystem copy if mount point is available
if self._mount_point:
try:
real_in_path = os.path.join(self._mount_point, in_path.lstrip("/"))
if os.path.exists(real_in_path):
os.makedirs(os.path.dirname(out_path), exist_ok=True)
shutil.copy2(real_in_path, out_path)
display.vvvv(f"File fetched via mount: {real_in_path}", host=self._container_id)
return
except Exception as e:
display.vvv(f"Mount fetch failed, falling back to buildah run: {e}", host=self._container_id)
# Use buildah run with cat command and output redirection
os.makedirs(os.path.dirname(out_path), exist_ok=True)
cat_cmd = ["run", self._container_id, "cat", in_path]
self._run_buildah_command(cat_cmd, output_file=out_path, include_container=False)
def close(self):
"""unmount container's filesystem"""
"""Close connection and cleanup resources"""
super(Connection, self).close()
rc, stdout, stderr = self._buildah("umount")
display.vvvv("RC %s STDOUT %r STDERR %r" % (rc, stdout, stderr))
if self._mount_point:
try:
# Attempt to unmount the container
self._run_buildah_command(["umount"], check_rc=False)
display.vvvv("Container unmounted successfully", host=self._container_id)
except Exception as e:
display.vvvv(f"Unmount failed: {e}", host=self._container_id)
# Auto-commit on close if enabled
if self.get_option("auto_commit"):
self._auto_commit_changes()
# Clear caches
self._command_cache.clear()
self._connected = False
display.vvv("Connection closed", host=self._container_id)

427
plugins/connection/podman.py
View file

@ -1,11 +1,11 @@
# Based on the buildah connection plugin
# Based on modern Ansible connection plugin patterns
# Copyright (c) 2018 Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
#
# Connection plugin to interact with existing podman containers.
# https://github.com/containers/libpod
# https://github.com/containers/podman
#
# Written by: Tomas Tomecek (https://github.com/TomasTomecek)
# Rewritten with modern patterns and enhanced functionality
from __future__ import absolute_import, division, print_function
@ -17,20 +17,26 @@ DOCUMENTATION = """
short_description: Interact with an existing podman container
description:
- Run commands or put/fetch files to an existing container using podman tool.
- Supports both direct execution and filesystem mounting for optimal performance.
options:
remote_addr:
description:
- The ID of the container you want to access.
- The ID or name of the container you want to access.
default: inventory_hostname
vars:
- name: ansible_host
- name: inventory_hostname
- name: ansible_host
- name: ansible_podman_host
env:
- name: ANSIBLE_PODMAN_HOST
ini:
- section: defaults
key: remote_addr
remote_user:
description:
- User specified via name or UID which is used to execute commands inside the container. If you
specify the user via UID, you must set C(ANSIBLE_REMOTE_TMP) to a path that exits
inside the container and is writable by Ansible.
- User specified via name or UID which is used to execute commands inside the container.
- If you specify the user via UID, you must set C(ANSIBLE_REMOTE_TMP) to a path that exists
inside the container and is writable by Ansible.
ini:
- section: defaults
key: remote_user
@ -42,6 +48,7 @@ DOCUMENTATION = """
description:
- Extra arguments to pass to the podman command line.
default: ''
type: str
ini:
- section: defaults
key: podman_extra_args
@ -53,10 +60,63 @@ DOCUMENTATION = """
description:
- Executable for podman command.
default: podman
type: str
vars:
- name: ansible_podman_executable
env:
- name: ANSIBLE_PODMAN_EXECUTABLE
ini:
- section: defaults
key: podman_executable
container_timeout:
description:
- Timeout in seconds for container operations. 0 means no timeout.
default: 0
type: int
vars:
- name: ansible_podman_timeout
env:
- name: ANSIBLE_PODMAN_TIMEOUT
ini:
- section: defaults
key: podman_timeout
mount_detection:
description:
- Enable automatic detection and use of container mount points for file operations.
default: true
type: bool
vars:
- name: ansible_podman_mount_detection
env:
- name: ANSIBLE_PODMAN_MOUNT_DETECTION
ignore_mount_errors:
description:
- Continue with copy operations even if container mounting fails.
default: true
type: bool
vars:
- name: ansible_podman_ignore_mount_errors
extra_env_vars:
description:
- Additional environment variables to set in the container.
default: {}
type: dict
vars:
- name: ansible_podman_extra_env
privilege_escalation_method:
description:
- Method to use for privilege escalation inside container.
default: 'auto'
choices: ['auto', 'sudo', 'su', 'none']
type: str
vars:
- name: ansible_podman_privilege_escalation
working_directory:
description:
- Working directory for commands executed in the container.
type: str
vars:
- name: ansible_podman_working_directory
"""
import os
@ -64,179 +124,276 @@ import shlex
import shutil
import subprocess
from ansible.errors import AnsibleConnectionFailure
from ansible.module_utils.common.process import get_bin_path
from ansible.errors import AnsibleError
from ansible.module_utils._text import to_bytes, to_native
from ansible.module_utils._text import to_bytes, to_native, to_text
from ansible.plugins.connection import ConnectionBase, ensure_connect
from ansible.utils.display import Display
display = Display()
# this _has to be_ named Connection
class PodmanConnectionError(AnsibleConnectionFailure):
"""Specific exception for podman connection issues"""
class ContainerNotFoundError(PodmanConnectionError):
"""Exception for when container cannot be found"""
class Connection(ConnectionBase):
"""
This is a connection plugin for podman. It uses podman binary to interact with the containers
Modern connection plugin for podman with enhanced error handling and performance optimizations
"""
# String used to identify this Connection class from other classes
transport = "containers.podman.podman"
# We know that pipelining does not work with podman. Do not enable it, or
# users will start containers and fail to connect to them.
has_pipelining = False
has_pipelining = True
def __init__(self, play_context, new_stdin, *args, **kwargs):
super(Connection, self).__init__(play_context, new_stdin, *args, **kwargs)
self._container_id = self._play_context.remote_addr
self._connected = False
# container filesystem will be mounted here on host
self._container_info = None
self._mount_point = None
self.user = self._play_context.remote_user
display.vvvv("Using podman connection from collection")
self._executable_path = None
self._task_uuid = to_text(kwargs.get("task_uuid", ""))
def _podman(self, cmd, cmd_args=None, in_data=None, use_container_id=True):
"""
run podman executable
# No pre-validation caches to preserve performance
:param cmd: podman's command to execute (str or list)
:param cmd_args: list of arguments to pass to the command (list of str/bytes)
:param in_data: data passed to podman's stdin
:param use_container_id: whether to append the container ID to the command
:return: return code, stdout, stderr
"""
podman_exec = self.get_option("podman_executable")
try:
podman_cmd = get_bin_path(podman_exec)
except ValueError:
raise AnsibleError("%s command not found in PATH" % podman_exec)
if not podman_cmd:
raise AnsibleError("%s command not found in PATH" % podman_exec)
local_cmd = [podman_cmd]
display.vvvv("Using podman connection from collection", host=self._container_id)
def _get_podman_executable(self):
"""Get and cache podman executable path with validation"""
if self._executable_path is None:
executable = self.get_option("podman_executable")
try:
self._executable_path = get_bin_path(executable)
display.vvvv(f"Found podman executable: {self._executable_path}", host=self._container_id)
except ValueError as e:
raise PodmanConnectionError(f"Could not find {executable} in PATH: {e}")
return self._executable_path
def _build_podman_command(self, cmd_args, include_container=True):
"""Build complete podman command with all options"""
cmd = [self._get_podman_executable()]
# Add global options
if self.get_option("podman_extra_args"):
local_cmd += shlex.split(to_native(self.get_option("podman_extra_args"), errors="surrogate_or_strict"))
if isinstance(cmd, str):
local_cmd.append(cmd)
extra_args = shlex.split(to_native(self.get_option("podman_extra_args"), errors="surrogate_or_strict"))
cmd.extend(extra_args)
# Add subcommand and arguments
if isinstance(cmd_args, str):
cmd.append(cmd_args)
else:
local_cmd.extend(cmd)
cmd.extend(cmd_args)
if use_container_id:
local_cmd.append(self._container_id)
if cmd_args:
local_cmd += cmd_args
local_cmd = [to_bytes(i, errors="surrogate_or_strict") for i in local_cmd]
# Add container ID if needed
if include_container:
cmd.append(self._container_id)
display.vvv("RUN %s" % (local_cmd,), host=self._container_id)
p = subprocess.Popen(
local_cmd,
shell=False,
stdin=subprocess.PIPE,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
)
return cmd
stdout, stderr = p.communicate(input=in_data)
display.vvvvv("STDOUT %s" % stdout)
display.vvvvv("STDERR %s" % stderr)
display.vvvvv("RC CODE %s" % p.returncode)
stdout = to_bytes(stdout, errors="surrogate_or_strict")
stderr = to_bytes(stderr, errors="surrogate_or_strict")
return p.returncode, stdout, stderr
def _run_podman_command(self, cmd_args, input_data=None, check_rc=False, include_container=True):
"""Execute podman command once with error handling"""
cmd = self._build_podman_command(cmd_args, include_container)
cmd_bytes = [to_bytes(arg, errors="surrogate_or_strict") for arg in cmd]
display.vvv(f"PODMAN EXEC: {' '.join(cmd)}", host=self._container_id)
try:
process = subprocess.Popen(
cmd_bytes, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, shell=False
)
# Only pass timeout if explicitly configured
communicate_kwargs = {}
container_timeout = self.get_option("container_timeout")
if isinstance(container_timeout, int) and container_timeout > 0:
communicate_kwargs["timeout"] = container_timeout
stdout, stderr = process.communicate(input=input_data, **communicate_kwargs)
display.vvvvv(f"STDOUT: {stdout}", host=self._container_id)
display.vvvvv(f"STDERR: {stderr}", host=self._container_id)
display.vvvvv(f"RC: {process.returncode}", host=self._container_id)
if process.returncode != 0:
error_msg = to_text(stderr, errors="surrogate_or_strict").strip()
lower = error_msg.lower()
if "no such container" in lower or "does not exist" in lower or "container not known" in lower:
self._connected = False
raise ContainerNotFoundError(f"Container '{self._container_id}' not found")
if check_rc:
raise PodmanConnectionError(f"Command failed (rc={process.returncode}): {error_msg}")
return process.returncode, stdout, stderr
except subprocess.TimeoutExpired:
process.kill()
timeout_val = self.get_option("container_timeout")
self._connected = False
raise PodmanConnectionError(f"Command timeout after {timeout_val}s")
except Exception as e:
raise PodmanConnectionError(f"Command execution failed: {e}")
# No proactive validation; rely on operation failures for performance
def _setup_mount_point(self):
"""Attempt to mount container filesystem for direct access (lightweight)"""
if not self.get_option("mount_detection"):
return
try:
rc, stdout, stderr = self._run_podman_command(["mount"])
if rc == 0:
mount_point = to_text(stdout, errors="surrogate_or_strict").strip()
if mount_point and os.path.isdir(mount_point):
self._mount_point = mount_point
display.vvv(f"Container mounted at: {self._mount_point}", host=self._container_id)
else:
display.vvv("Container mount point is invalid", host=self._container_id)
else:
display.vvv(
f"Container mount failed: {to_text(stderr, errors='surrogate_or_strict')}", host=self._container_id
)
except Exception as e:
if not self.get_option("ignore_mount_errors"):
raise PodmanConnectionError(f"Mount setup failed: {e}")
display.vvv(f"Mount setup failed, continuing without mount: {e}", host=self._container_id)
def _connect(self):
"""
no persistent connection is being maintained, mount container's filesystem
so we can easily access it
"""
"""Establish connection to container with validation and setup"""
super(Connection, self)._connect()
rc, self._mount_point, stderr = self._podman("mount")
if rc != 0:
display.vvvv("Failed to mount container %s: %s" % (self._container_id, stderr.strip()))
elif not os.listdir(self._mount_point.strip()):
display.vvvv("Failed to mount container with CGroups2: empty dir %s" % self._mount_point.strip())
self._mount_point = None
else:
self._mount_point = self._mount_point.strip()
display.vvvvv("MOUNTPOINT %s RC %s STDERR %r" % (self._mount_point, rc, stderr))
if self._connected:
return
display.vvv(f"Connecting to container: {self._container_id}", host=self._container_id)
self._connected = True
display.vvv("Connection established successfully", host=self._container_id)
@ensure_connect
def exec_command(self, cmd, in_data=None, sudoable=False):
"""run specified command in a running OCI container using podman"""
"""Execute command in container with enhanced error handling"""
super(Connection, self).exec_command(cmd, in_data=in_data, sudoable=sudoable)
# shlex.split has a bug with text strings on Python-2.6 and can only handle text strings on Python-3
display.vvv(f"EXEC: {cmd}", host=self._container_id)
cmd_args_list = shlex.split(to_native(cmd, errors="surrogate_or_strict"))
exec_args_list = ["exec"]
if self.user:
exec_args_list.extend(("--user", self.user))
exec_cmd = ["exec"]
rc, stdout, stderr = self._podman(exec_args_list, cmd_args_list, in_data)
# Add interactive flag only when input is provided
if in_data is not None:
exec_cmd.append("-i")
display.vvvvv("STDOUT %r STDERR %r" % (stderr, stderr))
# Handle user specification
if self.get_option("remote_user"):
exec_cmd.extend(["--user", self.get_option("remote_user")])
# Add extra environment variables
extra_env = self.get_option("extra_env_vars")
if extra_env:
for key, value in extra_env.items():
exec_cmd.extend(["--env", f"{key}={value}"])
# Handle privilege escalation only when explicitly requested
privilege_method = self.get_option("privilege_escalation_method")
if sudoable and privilege_method != "none" and privilege_method != "auto":
if privilege_method == "sudo":
cmd_args_list = ["sudo", "-n"] + cmd_args_list
elif privilege_method == "su":
cmd_args_list = ["su", "-c", " ".join(shlex.quote(arg) for arg in cmd_args_list)]
# Add working directory option
workdir = self.get_option("working_directory")
if workdir:
exec_cmd.extend(["--workdir", workdir])
# Combine exec command: podman exec [options] container_id command
full_cmd = exec_cmd + [self._container_id] + cmd_args_list
rc, stdout, stderr = self._run_podman_command(full_cmd, input_data=in_data, include_container=False)
return rc, stdout, stderr
def put_file(self, in_path, out_path):
"""Place a local file located in 'in_path' inside container at 'out_path'"""
"""Transfer file to container using optimal method"""
super(Connection, self).put_file(in_path, out_path)
display.vvv("PUT %s TO %s" % (in_path, out_path), host=self._container_id)
if not self._mount_point or self.user:
rc, stdout, stderr = self._podman(
"cp",
[in_path, self._container_id + ":" + out_path],
use_container_id=False,
)
if rc != 0:
rc, stdout, stderr = self._podman(
"cp",
["--pause=false", in_path, self._container_id + ":" + out_path],
use_container_id=False,
)
if rc != 0:
raise AnsibleError(
"Failed to copy file from %s to %s in container %s\n%s"
% (in_path, out_path, self._container_id, stderr)
)
if self.user:
rc, stdout, stderr = self._podman("exec", ["chown", self.user, out_path])
if rc != 0:
raise AnsibleError(
"Failed to chown file %s for user %s in container %s\n%s"
% (out_path, self.user, self._container_id, stderr)
)
else:
real_out_path = self._mount_point + to_bytes(out_path, errors="surrogate_or_strict")
shutil.copyfile(
to_bytes(in_path, errors="surrogate_or_strict"),
to_bytes(real_out_path, errors="surrogate_or_strict"),
)
display.vvv(f"PUT: {in_path} -> {out_path}", host=self._container_id)
# Lazily prepare mount point if needed
if self._mount_point is None and self.get_option("mount_detection"):
self._setup_mount_point()
# Use direct filesystem copy if mount point is available and no user specified
if self._mount_point and not self.get_option("remote_user"):
try:
real_out_path = os.path.join(self._mount_point, out_path.lstrip("/"))
os.makedirs(os.path.dirname(real_out_path), exist_ok=True)
shutil.copy2(in_path, real_out_path)
display.vvvv(f"File copied via mount: {real_out_path}", host=self._container_id)
return
except Exception as e:
display.vvv(f"Mount copy failed, falling back to podman cp: {e}", host=self._container_id)
# Use podman cp command
copy_cmd = ["cp", "--pause=false", in_path, f"{self._container_id}:{out_path}"]
self._run_podman_command(copy_cmd, include_container=False, check_rc=True)
# Change ownership if user specified
if self.get_option("remote_user"):
chown_cmd = [
"exec",
"--user",
"root",
self._container_id,
"chown",
self.get_option("remote_user"),
out_path,
]
try:
self._run_podman_command(chown_cmd, include_container=False, check_rc=True)
except PodmanConnectionError as e:
display.warning(f"Failed to change file ownership: {e}")
def fetch_file(self, in_path, out_path):
"""obtain file specified via 'in_path' from the container and place it at 'out_path'"""
"""Retrieve file from container using optimal method"""
super(Connection, self).fetch_file(in_path, out_path)
display.vvv("FETCH %s TO %s" % (in_path, out_path), host=self._container_id)
if not self._mount_point:
rc, stdout, stderr = self._podman(
"cp",
[self._container_id + ":" + in_path, out_path],
use_container_id=False,
)
if rc != 0:
raise AnsibleError(
"Failed to fetch file from %s to %s from container %s\n%s"
% (in_path, out_path, self._container_id, stderr)
)
else:
real_in_path = self._mount_point + to_bytes(in_path, errors="surrogate_or_strict")
shutil.copyfile(
to_bytes(real_in_path, errors="surrogate_or_strict"),
to_bytes(out_path, errors="surrogate_or_strict"),
)
display.vvv(f"FETCH: {in_path} -> {out_path}", host=self._container_id)
# Lazily prepare mount point if needed
if self._mount_point is None and self.get_option("mount_detection"):
self._setup_mount_point()
# Use direct filesystem copy if mount point is available
if self._mount_point:
try:
real_in_path = os.path.join(self._mount_point, in_path.lstrip("/"))
if os.path.exists(real_in_path):
os.makedirs(os.path.dirname(out_path), exist_ok=True)
shutil.copy2(real_in_path, out_path)
display.vvvv(f"File fetched via mount: {real_in_path}", host=self._container_id)
return
except Exception as e:
display.vvv(f"Mount fetch failed, falling back to podman cp: {e}", host=self._container_id)
# Use podman cp command
copy_cmd = ["cp", "--pause=false", f"{self._container_id}:{in_path}", out_path]
self._run_podman_command(copy_cmd, include_container=False, check_rc=True)
def close(self):
"""unmount container's filesystem"""
"""Close connection and cleanup resources"""
super(Connection, self).close()
# we actually don't need to unmount since the container is mounted anyway
# rc, stdout, stderr = self._podman("umount")
# display.vvvvv("RC %s STDOUT %r STDERR %r" % (rc, stdout, stderr))
if self._mount_point:
try:
# Attempt to unmount (optional, container keeps mount anyway)
self._run_podman_command(["umount"], check_rc=False)
display.vvvv("Container unmounted successfully", host=self._container_id)
except Exception as e:
display.vvvv(f"Unmount failed (this is usually not critical): {e}", host=self._container_id)
self._connected = False
display.vvv("Connection closed", host=self._container_id)