Vendor Galaxy Roles and Collections

ansible_collections/community/docker/plugins/connection/docker.py

@@ -0,0 +1,623 @@
+# Based on the chroot connection plugin by Maykel Moya
+#
+# (c) 2014, Lorin Hochstein
+# (c) 2015, Leendert Brouwer (https://github.com/objectified)
+# (c) 2015, Toshio Kuratomi <tkuratomi@ansible.com>
+# Copyright (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import annotations
+
+DOCUMENTATION = r"""
+author:
+  - Lorin Hochestein (!UNKNOWN)
+  - Leendert Brouwer (!UNKNOWN)
+name: docker
+short_description: Run tasks in docker containers
+description:
+  - Run commands or put/fetch files to an existing docker container.
+  - Uses the Docker CLI to execute commands in the container. If you prefer to directly connect to the Docker daemon, use
+    the P(community.docker.docker_api#connection) connection plugin.
+options:
+  remote_addr:
+    description:
+      - The name of the container you want to access.
+    default: inventory_hostname
+    vars:
+      - name: inventory_hostname
+      - name: ansible_host
+      - name: ansible_docker_host
+  remote_user:
+    description:
+      - The user to execute as inside the container.
+      - If Docker is too old to allow this (< 1.7), the one set by Docker itself will be used.
+    vars:
+      - name: ansible_user
+      - name: ansible_docker_user
+    ini:
+      - section: defaults
+        key: remote_user
+    env:
+      - name: ANSIBLE_REMOTE_USER
+    cli:
+      - name: user
+    keyword:
+      - name: remote_user
+  docker_extra_args:
+    description:
+      - Extra arguments to pass to the docker command line.
+    default: ''
+    vars:
+      - name: ansible_docker_extra_args
+    ini:
+      - section: docker_connection
+        key: extra_cli_args
+  container_timeout:
+    default: 10
+    description:
+      - Controls how long we can wait to access reading output from the container once execution started.
+    env:
+      - name: ANSIBLE_TIMEOUT
+      - name: ANSIBLE_DOCKER_TIMEOUT
+        version_added: 2.2.0
+    ini:
+      - key: timeout
+        section: defaults
+      - key: timeout
+        section: docker_connection
+        version_added: 2.2.0
+    vars:
+      - name: ansible_docker_timeout
+        version_added: 2.2.0
+    cli:
+      - name: timeout
+    type: integer
+  extra_env:
+    description:
+      - Provide extra environment variables to set when running commands in the Docker container.
+      - This option can currently only be provided as Ansible variables due to limitations of ansible-core's configuration
+        manager.
+    vars:
+      - name: ansible_docker_extra_env
+    type: dict
+    version_added: 3.12.0
+  working_dir:
+    description:
+      - The directory inside the container to run commands in.
+      - Requires Docker CLI version 18.06 or later.
+    env:
+      - name: ANSIBLE_DOCKER_WORKING_DIR
+    ini:
+      - key: working_dir
+        section: docker_connection
+    vars:
+      - name: ansible_docker_working_dir
+    type: string
+    version_added: 3.12.0
+  privileged:
+    description:
+      - Whether commands should be run with extended privileges.
+      - B(Note) that this allows command to potentially break out of the container. Use with care!
+    env:
+      - name: ANSIBLE_DOCKER_PRIVILEGED
+    ini:
+      - key: privileged
+        section: docker_connection
+    vars:
+      - name: ansible_docker_privileged
+    type: boolean
+    default: false
+    version_added: 3.12.0
+"""
+
+import fcntl
+import os
+import os.path
+import re
+import selectors
+import subprocess
+import typing as t
+from shlex import quote
+
+from ansible.errors import AnsibleConnectionFailure, AnsibleError, AnsibleFileNotFound
+from ansible.module_utils.common.process import get_bin_path
+from ansible.module_utils.common.text.converters import to_bytes, to_text
+from ansible.plugins.connection import BUFSIZE, ConnectionBase
+from ansible.utils.display import Display
+
+from ansible_collections.community.docker.plugins.module_utils._version import (
+    LooseVersion,
+)
+
+display = Display()
+
+
+class Connection(ConnectionBase):
+    """Local docker based connections"""
+
+    transport = "community.docker.docker"
+    has_pipelining = True
+
+    def __init__(self, *args: t.Any, **kwargs: t.Any) -> None:
+        super().__init__(*args, **kwargs)
+
+        # Note: docker supports running as non-root in some configurations.
+        # (For instance, setting the UNIX socket file to be readable and
+        # writable by a specific UNIX group and then putting users into that
+        # group).  Therefore we do not check that the user is root when using
+        # this connection.  But if the user is getting a permission denied
+        # error it probably means that docker on their system is only
+        # configured to be connected to by root and they are not running as
+        # root.
+
+        self._docker_args: list[bytes | str] = []
+        self._container_user_cache: dict[str, str | None] = {}
+        self._version: str | None = None
+        self.remote_user: str | None = None
+        self.timeout: int | float | None = None
+
+        # Windows uses Powershell modules
+        if getattr(self._shell, "_IS_WINDOWS", False):
+            self.module_implementation_preferences = (".ps1", ".exe", "")
+
+        if "docker_command" in kwargs:
+            self.docker_cmd = kwargs["docker_command"]
+        else:
+            try:
+                self.docker_cmd = get_bin_path("docker")
+            except ValueError as exc:
+                raise AnsibleError("docker command not found in PATH") from exc
+
+    @staticmethod
+    def _sanitize_version(version: str) -> str:
+        version = re.sub("[^0-9a-zA-Z.]", "", version)
+        version = re.sub("^v", "", version)
+        return version
+
+    def _old_docker_version(self) -> tuple[list[str], str, bytes, int]:
+        cmd_args = self._docker_args
+
+        old_version_subcommand = ["version"]
+
+        old_docker_cmd = [self.docker_cmd] + cmd_args + old_version_subcommand
+        with subprocess.Popen(
+            old_docker_cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE
+        ) as p:
+            cmd_output, err = p.communicate()
+
+        return old_docker_cmd, to_text(cmd_output), err, p.returncode
+
+    def _new_docker_version(self) -> tuple[list[str], str, bytes, int]:
+        # no result yet, must be newer Docker version
+        cmd_args = self._docker_args
+
+        new_version_subcommand = ["version", "--format", "'{{.Server.Version}}'"]
+
+        new_docker_cmd = [self.docker_cmd] + cmd_args + new_version_subcommand
+        with subprocess.Popen(
+            new_docker_cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE
+        ) as p:
+            cmd_output, err = p.communicate()
+            return new_docker_cmd, to_text(cmd_output), err, p.returncode
+
+    def _get_docker_version(self) -> str:
+        cmd, cmd_output, err, returncode = self._old_docker_version()
+        if returncode == 0:
+            for line in to_text(cmd_output, errors="surrogate_or_strict").split("\n"):
+                if line.startswith("Server version:"):  # old docker versions
+                    return self._sanitize_version(line.split()[2])
+
+        cmd, cmd_output, err, returncode = self._new_docker_version()
+        if returncode:
+            raise AnsibleError(
+                f"Docker version check ({to_text(cmd)}) failed: {to_text(err)}"
+            )
+
+        return self._sanitize_version(to_text(cmd_output, errors="surrogate_or_strict"))
+
+    def _get_docker_remote_user(self) -> str | None:
+        """Get the default user configured in the docker container"""
+        container = self.get_option("remote_addr")
+        if container in self._container_user_cache:
+            return self._container_user_cache[container]
+        with subprocess.Popen(
+            [self.docker_cmd, "inspect", "--format", "{{.Config.User}}", container],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        ) as p:
+            out_b, err_b = p.communicate()
+            out = to_text(out_b, errors="surrogate_or_strict")
+
+            if p.returncode != 0:
+                display.warning(
+                    f"unable to retrieve default user from docker container: {out} {to_text(err_b)}"
+                )
+                self._container_user_cache[container] = None
+                return None
+
+        # The default exec user is root, unless it was changed in the Dockerfile with USER
+        user = out.strip() or "root"
+        self._container_user_cache[container] = user
+        return user
+
+    def _build_exec_cmd(self, cmd: list[bytes | str]) -> list[bytes | str]:
+        """Build the local docker exec command to run cmd on remote_host
+
+        If remote_user is available and is supported by the docker
+        version we are using, it will be provided to docker exec.
+        """
+
+        local_cmd = [self.docker_cmd]
+
+        if self._docker_args:
+            local_cmd += self._docker_args
+
+        local_cmd += [b"exec"]
+
+        if self.remote_user is not None:
+            local_cmd += [b"-u", self.remote_user]
+
+        if self.get_option("extra_env"):
+            for k, v in self.get_option("extra_env").items():
+                for val, what in ((k, "Key"), (v, "Value")):
+                    if not isinstance(val, str):
+                        raise AnsibleConnectionFailure(
+                            f"Non-string {what.lower()} found for extra_env option. Ambiguous env options must be "
+                            "wrapped in quotes to avoid them being interpreted when directly specified "
+                            "in YAML, or explicitly converted to strings when the option is templated. "
+                            f"{what}: {val!r}"
+                        )
+                local_cmd += [
+                    b"-e",
+                    b"%s=%s"
+                    % (
+                        to_bytes(k, errors="surrogate_or_strict"),
+                        to_bytes(v, errors="surrogate_or_strict"),
+                    ),
+                ]
+
+        if self.get_option("working_dir") is not None:
+            local_cmd += [
+                b"-w",
+                to_bytes(self.get_option("working_dir"), errors="surrogate_or_strict"),
+            ]
+            if self.docker_version != "dev" and LooseVersion(
+                self.docker_version
+            ) < LooseVersion("18.06"):
+                # https://github.com/docker/cli/pull/732, first appeared in release 18.06.0
+                raise AnsibleConnectionFailure(
+                    f"Providing the working directory requires Docker CLI version 18.06 or newer. You have Docker CLI version {self.docker_version}."
+                )
+
+        if self.get_option("privileged"):
+            local_cmd += [b"--privileged"]
+
+        # -i is needed to keep stdin open which allows pipelining to work
+        local_cmd += [b"-i", self.get_option("remote_addr")] + cmd
+
+        return local_cmd
+
+    def _set_docker_args(self) -> None:
+        # TODO: this is mostly for backwards compatibility, play_context is used as fallback for older versions
+        # docker arguments
+        del self._docker_args[:]
+        extra_args = self.get_option("docker_extra_args") or getattr(
+            self._play_context, "docker_extra_args", ""
+        )
+        if extra_args:
+            self._docker_args += extra_args.split(" ")
+
+    def _set_conn_data(self) -> None:
+        """initialize for the connection, cannot do only in init since all data is not ready at that point"""
+
+        self._set_docker_args()
+
+        self.remote_user = self.get_option("remote_user")
+        if self.remote_user is None and self._play_context.remote_user is not None:
+            self.remote_user = self._play_context.remote_user
+
+        # timeout, use unless default and pc is different, backwards compat
+        self.timeout = self.get_option("container_timeout")
+        if self.timeout == 10 and self.timeout != self._play_context.timeout:
+            self.timeout = self._play_context.timeout
+
+    @property
+    def docker_version(self) -> str:
+        if not self._version:
+            self._set_docker_args()
+
+            self._version = self._get_docker_version()
+            if self._version == "dev":
+                display.warning(
+                    'Docker version number is "dev". Will assume latest version.'
+                )
+            if self._version != "dev" and LooseVersion(self._version) < LooseVersion(
+                "1.3"
+            ):
+                raise AnsibleError(
+                    "docker connection type requires docker 1.3 or higher"
+                )
+        return self._version
+
+    def _get_actual_user(self) -> str | None:
+        if self.remote_user is not None:
+            # An explicit user is provided
+            if self.docker_version == "dev" or LooseVersion(
+                self.docker_version
+            ) >= LooseVersion("1.7"):
+                # Support for specifying the exec user was added in docker 1.7
+                return self.remote_user
+            self.remote_user = None
+            actual_user = self._get_docker_remote_user()
+            if actual_user != self.get_option("remote_user"):
+                display.warning(
+                    f"docker {self.docker_version} does not support remote_user, using container default: {actual_user or '?'}"
+                )
+            return actual_user
+        if self._display.verbosity > 2:
+            # Since we are not setting the actual_user, look it up so we have it for logging later
+            # Only do this if display verbosity is high enough that we'll need the value
+            # This saves overhead from calling into docker when we do not need to.
+            return self._get_docker_remote_user()
+        return None
+
+    def _connect(self) -> t.Self:
+        """Connect to the container. Nothing to do"""
+        super()._connect()  # type: ignore[safe-super]
+        if not self._connected:
+            self._set_conn_data()
+            actual_user = self._get_actual_user()
+            display.vvv(
+                f"ESTABLISH DOCKER CONNECTION FOR USER: {actual_user or '?'}",
+                host=self.get_option("remote_addr"),
+            )
+            self._connected = True
+        return self
+
+    def exec_command(
+        self, cmd: str, in_data: bytes | None = None, sudoable: bool = False
+    ) -> tuple[int, bytes, bytes]:
+        """Run a command on the docker host"""
+
+        self._set_conn_data()
+
+        super().exec_command(cmd, in_data=in_data, sudoable=sudoable)  # type: ignore[safe-super]
+
+        local_cmd = self._build_exec_cmd([self._play_context.executable, "-c", cmd])
+
+        display.vvv(f"EXEC {to_text(local_cmd)}", host=self.get_option("remote_addr"))
+        display.debug("opening command with Popen()")
+
+        local_cmd = [to_bytes(i, errors="surrogate_or_strict") for i in local_cmd]
+
+        with subprocess.Popen(
+            local_cmd,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        ) as p:
+            assert p.stdin is not None
+            assert p.stdout is not None
+            assert p.stderr is not None
+            display.debug("done running command with Popen()")
+
+            if self.become and self.become.expect_prompt() and sudoable:
+                fcntl.fcntl(
+                    p.stdout,
+                    fcntl.F_SETFL,
+                    fcntl.fcntl(p.stdout, fcntl.F_GETFL) | os.O_NONBLOCK,
+                )
+                fcntl.fcntl(
+                    p.stderr,
+                    fcntl.F_SETFL,
+                    fcntl.fcntl(p.stderr, fcntl.F_GETFL) | os.O_NONBLOCK,
+                )
+                selector = selectors.DefaultSelector()
+                selector.register(p.stdout, selectors.EVENT_READ)
+                selector.register(p.stderr, selectors.EVENT_READ)
+
+                become_output = b""
+                try:
+                    while not self.become.check_success(
+                        become_output
+                    ) and not self.become.check_password_prompt(become_output):
+                        events = selector.select(self.timeout)
+                        if not events:
+                            stdout, stderr = p.communicate()
+                            raise AnsibleError(
+                                "timeout waiting for privilege escalation password prompt:\n"
+                                + to_text(become_output)
+                            )
+
+                        chunks = b""
+                        for key, dummy_event in events:
+                            if key.fileobj == p.stdout:
+                                chunk = p.stdout.read()
+                                if chunk:
+                                    chunks += chunk
+                            elif key.fileobj == p.stderr:
+                                chunk = p.stderr.read()
+                                if chunk:
+                                    chunks += chunk
+
+                        if not chunks:
+                            stdout, stderr = p.communicate()
+                            raise AnsibleError(
+                                "privilege output closed while waiting for password prompt:\n"
+                                + to_text(become_output)
+                            )
+                        become_output += chunks
+                finally:
+                    selector.close()
+
+                if not self.become.check_success(become_output):
+                    become_pass = self.become.get_option(
+                        "become_pass", playcontext=self._play_context
+                    )
+                    p.stdin.write(
+                        to_bytes(become_pass, errors="surrogate_or_strict") + b"\n"
+                    )
+                fcntl.fcntl(
+                    p.stdout,
+                    fcntl.F_SETFL,
+                    fcntl.fcntl(p.stdout, fcntl.F_GETFL) & ~os.O_NONBLOCK,
+                )
+                fcntl.fcntl(
+                    p.stderr,
+                    fcntl.F_SETFL,
+                    fcntl.fcntl(p.stderr, fcntl.F_GETFL) & ~os.O_NONBLOCK,
+                )
+
+            display.debug("getting output with communicate()")
+            stdout, stderr = p.communicate(in_data)
+            display.debug("done communicating")
+
+            display.debug("done with docker.exec_command()")
+            return (p.returncode, stdout, stderr)
+
+    def _prefix_login_path(self, remote_path: str) -> str:
+        """Make sure that we put files into a standard path
+
+        If a path is relative, then we need to choose where to put it.
+        ssh chooses $HOME but we are not guaranteed that a home dir will
+        exist in any given chroot.  So for now we are choosing "/" instead.
+        This also happens to be the former default.
+
+        Can revisit using $HOME instead if it is a problem
+        """
+        if getattr(self._shell, "_IS_WINDOWS", False):
+            import ntpath
+
+            return ntpath.normpath(remote_path)
+        if not remote_path.startswith(os.path.sep):
+            remote_path = os.path.join(os.path.sep, remote_path)
+        return os.path.normpath(remote_path)
+
+    def put_file(self, in_path: str, out_path: str) -> None:
+        """Transfer a file from local to docker container"""
+        self._set_conn_data()
+        super().put_file(in_path, out_path)  # type: ignore[safe-super]
+        display.vvv(f"PUT {in_path} TO {out_path}", host=self.get_option("remote_addr"))
+
+        out_path = self._prefix_login_path(out_path)
+        if not os.path.exists(to_bytes(in_path, errors="surrogate_or_strict")):
+            raise AnsibleFileNotFound(
+                f"file or module does not exist: {to_text(in_path)}"
+            )
+
+        out_path = quote(out_path)
+        # Older docker does not have native support for copying files into
+        # running containers, so we use docker exec to implement this
+        # Although docker version 1.8 and later provide support, the
+        # owner and group of the files are always set to root
+        with open(to_bytes(in_path, errors="surrogate_or_strict"), "rb") as in_file:
+            if not os.fstat(in_file.fileno()).st_size:
+                count = " count=0"
+            else:
+                count = ""
+            args = self._build_exec_cmd(
+                [
+                    self._play_context.executable,
+                    "-c",
+                    f"dd of={out_path} bs={BUFSIZE}{count}",
+                ]
+            )
+            args = [to_bytes(i, errors="surrogate_or_strict") for i in args]
+            try:
+                # pylint: disable-next=consider-using-with
+                p = subprocess.Popen(
+                    args, stdin=in_file, stdout=subprocess.PIPE, stderr=subprocess.PIPE
+                )
+            except OSError as exc:
+                raise AnsibleError(
+                    "docker connection requires dd command in the container to put files"
+                ) from exc
+            stdout, stderr = p.communicate()
+
+            if p.returncode != 0:
+                raise AnsibleError(
+                    f"failed to transfer file {to_text(in_path)} to {to_text(out_path)}:\n{to_text(stdout)}\n{to_text(stderr)}"
+                )
+
+    def fetch_file(self, in_path: str, out_path: str) -> None:
+        """Fetch a file from container to local."""
+        self._set_conn_data()
+        super().fetch_file(in_path, out_path)  # type: ignore[safe-super]
+        display.vvv(
+            f"FETCH {in_path} TO {out_path}", host=self.get_option("remote_addr")
+        )
+
+        in_path = self._prefix_login_path(in_path)
+        # out_path is the final file path, but docker takes a directory, not a
+        # file path
+        out_dir = os.path.dirname(out_path)
+
+        args = [
+            self.docker_cmd,
+            "cp",
+            f"{self.get_option('remote_addr')}:{in_path}",
+            out_dir,
+        ]
+        args = [to_bytes(i, errors="surrogate_or_strict") for i in args]
+
+        with subprocess.Popen(
+            args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE
+        ) as p:
+            p.communicate()
+
+            if getattr(self._shell, "_IS_WINDOWS", False):
+                import ntpath
+
+                actual_out_path = ntpath.join(out_dir, ntpath.basename(in_path))
+            else:
+                actual_out_path = os.path.join(out_dir, os.path.basename(in_path))
+
+            if p.returncode != 0:
+                # Older docker does not have native support for fetching files command `cp`
+                # If `cp` fails, try to use `dd` instead
+                args = self._build_exec_cmd(
+                    [
+                        self._play_context.executable,
+                        "-c",
+                        f"dd if={in_path} bs={BUFSIZE}",
+                    ]
+                )
+                args = [to_bytes(i, errors="surrogate_or_strict") for i in args]
+                with open(
+                    to_bytes(actual_out_path, errors="surrogate_or_strict"), "wb"
+                ) as out_file:
+                    try:
+                        # pylint: disable-next=consider-using-with
+                        pp = subprocess.Popen(
+                            args,
+                            stdin=subprocess.PIPE,
+                            stdout=out_file,
+                            stderr=subprocess.PIPE,
+                        )
+                    except OSError as exc:
+                        raise AnsibleError(
+                            "docker connection requires dd command in the container to put files"
+                        ) from exc
+                    stdout, stderr = pp.communicate()
+
+                    if pp.returncode != 0:
+                        raise AnsibleError(
+                            f"failed to fetch file {in_path} to {out_path}:\n{stdout!r}\n{stderr!r}"
+                        )
+
+        # Rename if needed
+        if actual_out_path != out_path:
+            os.rename(
+                to_bytes(actual_out_path, errors="strict"),
+                to_bytes(out_path, errors="strict"),
+            )
+
+    def close(self) -> None:
+        """Terminate the connection. Nothing to do for Docker"""
+        super().close()  # type: ignore[safe-super]
+        self._connected = False
+
+    def reset(self) -> None:
+        # Clear container user cache
+        self._container_user_cache = {}

ansible_collections/community/docker/plugins/connection/docker_api.py

@@ -0,0 +1,479 @@
+# Copyright (c) 2019-2020, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import annotations
+
+DOCUMENTATION = r"""
+author:
+  - Felix Fontein (@felixfontein)
+name: docker_api
+short_description: Run tasks in docker containers
+version_added: 1.1.0
+description:
+  - Run commands or put/fetch files to an existing docker container.
+  - Uses the L(requests library,https://pypi.org/project/requests/) to interact directly with the Docker daemon instead of
+    using the Docker CLI. Use the P(community.docker.docker#connection) connection plugin if you want to use the Docker CLI.
+notes:
+  - Does B(not work with TCP TLS sockets)! This is caused by the inability to send C(close_notify) without closing the connection
+    with Python's C(SSLSocket)s. See U(https://github.com/ansible-collections/community.docker/issues/605) for more information.
+extends_documentation_fragment:
+  - community.docker._docker.api_documentation
+  - community.docker._docker.var_names
+options:
+  remote_user:
+    type: str
+    description:
+      - The user to execute as inside the container.
+    vars:
+      - name: ansible_user
+      - name: ansible_docker_user
+    ini:
+      - section: defaults
+        key: remote_user
+    env:
+      - name: ANSIBLE_REMOTE_USER
+    cli:
+      - name: user
+    keyword:
+      - name: remote_user
+  remote_addr:
+    type: str
+    description:
+      - The name of the container you want to access.
+    default: inventory_hostname
+    vars:
+      - name: inventory_hostname
+      - name: ansible_host
+      - name: ansible_docker_host
+  container_timeout:
+    default: 10
+    description:
+      - Controls how long we can wait to access reading output from the container once execution started.
+    env:
+      - name: ANSIBLE_TIMEOUT
+      - name: ANSIBLE_DOCKER_TIMEOUT
+        version_added: 2.2.0
+    ini:
+      - key: timeout
+        section: defaults
+      - key: timeout
+        section: docker_connection
+        version_added: 2.2.0
+    vars:
+      - name: ansible_docker_timeout
+        version_added: 2.2.0
+    cli:
+      - name: timeout
+    type: integer
+  extra_env:
+    description:
+      - Provide extra environment variables to set when running commands in the Docker container.
+      - This option can currently only be provided as Ansible variables due to limitations of ansible-core's configuration
+        manager.
+    vars:
+      - name: ansible_docker_extra_env
+    type: dict
+    version_added: 3.12.0
+  working_dir:
+    description:
+      - The directory inside the container to run commands in.
+      - Requires Docker API version 1.35 or later.
+    env:
+      - name: ANSIBLE_DOCKER_WORKING_DIR
+    ini:
+      - key: working_dir
+        section: docker_connection
+    vars:
+      - name: ansible_docker_working_dir
+    type: string
+    version_added: 3.12.0
+  privileged:
+    description:
+      - Whether commands should be run with extended privileges.
+      - B(Note) that this allows command to potentially break out of the container. Use with care!
+    env:
+      - name: ANSIBLE_DOCKER_PRIVILEGED
+    ini:
+      - key: privileged
+        section: docker_connection
+    vars:
+      - name: ansible_docker_privileged
+    type: boolean
+    default: false
+    version_added: 3.12.0
+"""
+
+import os
+import os.path
+import typing as t
+
+from ansible.errors import AnsibleConnectionFailure, AnsibleFileNotFound
+from ansible.module_utils.common.text.converters import to_bytes, to_text
+from ansible.plugins.connection import ConnectionBase
+from ansible.utils.display import Display
+
+from ansible_collections.community.docker.plugins.module_utils._api.errors import (
+    APIError,
+    DockerException,
+    NotFound,
+)
+from ansible_collections.community.docker.plugins.module_utils._common_api import (
+    RequestException,
+)
+from ansible_collections.community.docker.plugins.module_utils._copy import (
+    DockerFileCopyError,
+    DockerFileNotFound,
+    fetch_file,
+    put_file,
+)
+from ansible_collections.community.docker.plugins.module_utils._version import (
+    LooseVersion,
+)
+from ansible_collections.community.docker.plugins.plugin_utils._common_api import (
+    AnsibleDockerClient,
+)
+from ansible_collections.community.docker.plugins.plugin_utils._socket_handler import (
+    DockerSocketHandler,
+)
+
+if t.TYPE_CHECKING:
+    from collections.abc import Callable
+
+    _T = t.TypeVar("_T")
+
+
+MIN_DOCKER_API = None
+
+
+display = Display()
+
+
+class Connection(ConnectionBase):
+    """Local docker based connections"""
+
+    transport = "community.docker.docker_api"
+    has_pipelining = True
+
+    def _call_client(
+        self,
+        f: Callable[[AnsibleDockerClient], _T],
+        not_found_can_be_resource: bool = False,
+    ) -> _T:
+        if self.client is None:
+            raise AssertionError("Client must be present")
+        remote_addr = self.get_option("remote_addr")
+        try:
+            return f(self.client)
+        except NotFound as e:
+            if not_found_can_be_resource:
+                raise AnsibleConnectionFailure(
+                    f'Could not find container "{remote_addr}" or resource in it ({e})'
+                ) from e
+            raise AnsibleConnectionFailure(
+                f'Could not find container "{remote_addr}" ({e})'
+            ) from e
+        except APIError as e:
+            if e.response is not None and e.response.status_code == 409:
+                raise AnsibleConnectionFailure(
+                    f'The container "{remote_addr}" has been paused ({e})'
+                ) from e
+            self.client.fail(
+                f'An unexpected Docker error occurred for container "{remote_addr}": {e}'
+            )
+        except DockerException as e:
+            self.client.fail(
+                f'An unexpected Docker error occurred for container "{remote_addr}": {e}'
+            )
+        except RequestException as e:
+            self.client.fail(
+                f'An unexpected requests error occurred for container "{remote_addr}" when trying to talk to the Docker daemon: {e}'
+            )
+
+    def __init__(self, *args: t.Any, **kwargs: t.Any) -> None:
+        super().__init__(*args, **kwargs)
+
+        self.client: AnsibleDockerClient | None = None
+        self.ids: dict[str | None, tuple[int, int]] = {}
+
+        # Windows uses Powershell modules
+        if getattr(self._shell, "_IS_WINDOWS", False):
+            self.module_implementation_preferences = (".ps1", ".exe", "")
+
+        self.actual_user: str | None = None
+
+    def _connect(self) -> Connection:
+        """Connect to the container. Nothing to do"""
+        super()._connect()  # type: ignore[safe-super]
+        if not self._connected:
+            self.actual_user = self.get_option("remote_user")
+            display.vvv(
+                f"ESTABLISH DOCKER CONNECTION FOR USER: {self.actual_user or '?'}",
+                host=self.get_option("remote_addr"),
+            )
+            if self.client is None:
+                self.client = AnsibleDockerClient(
+                    self, min_docker_api_version=MIN_DOCKER_API
+                )
+            self._connected = True
+
+            if self.actual_user is None and display.verbosity > 2:
+                # Since we are not setting the actual_user, look it up so we have it for logging later
+                # Only do this if display verbosity is high enough that we'll need the value
+                # This saves overhead from calling into docker when we do not need to
+                display.vvv("Trying to determine actual user")
+                result = self._call_client(
+                    lambda client: client.get_json(
+                        "/containers/{0}/json", self.get_option("remote_addr")
+                    )
+                )
+                if result.get("Config"):
+                    self.actual_user = result["Config"].get("User")
+                    if self.actual_user is not None:
+                        display.vvv(f"Actual user is '{self.actual_user}'")
+
+        return self
+
+    def exec_command(
+        self, cmd: str, in_data: bytes | None = None, sudoable: bool = False
+    ) -> tuple[int, bytes, bytes]:
+        """Run a command on the docker host"""
+
+        super().exec_command(cmd, in_data=in_data, sudoable=sudoable)  # type: ignore[safe-super]
+
+        if self.client is None:
+            raise AssertionError("Client must be present")
+
+        command = [self._play_context.executable, "-c", cmd]
+
+        do_become = self.become and self.become.expect_prompt() and sudoable
+
+        stdin_part = (
+            f", with stdin ({len(in_data)} bytes)" if in_data is not None else ""
+        )
+        become_part = ", with become prompt" if do_become else ""
+        display.vvv(
+            f"EXEC {to_text(command)}{stdin_part}{become_part}",
+            host=self.get_option("remote_addr"),
+        )
+
+        need_stdin = bool((in_data is not None) or do_become)
+
+        data = {
+            "Container": self.get_option("remote_addr"),
+            "User": self.get_option("remote_user") or "",
+            "Privileged": self.get_option("privileged"),
+            "Tty": False,
+            "AttachStdin": need_stdin,
+            "AttachStdout": True,
+            "AttachStderr": True,
+            "Cmd": command,
+        }
+
+        if "detachKeys" in self.client._general_configs:
+            data["detachKeys"] = self.client._general_configs["detachKeys"]
+
+        if self.get_option("extra_env"):
+            data["Env"] = []
+            for k, v in self.get_option("extra_env").items():
+                for val, what in ((k, "Key"), (v, "Value")):
+                    if not isinstance(val, str):
+                        raise AnsibleConnectionFailure(
+                            f"Non-string {what.lower()} found for extra_env option. Ambiguous env options must be "
+                            "wrapped in quotes to avoid them being interpreted when directly specified "
+                            "in YAML, or explicitly converted to strings when the option is templated. "
+                            f"{what}: {val!r}"
+                        )
+                data["Env"].append(f"{k}={v}")
+
+        if self.get_option("working_dir") is not None:
+            data["WorkingDir"] = self.get_option("working_dir")
+            if self.client.docker_api_version < LooseVersion("1.35"):
+                raise AnsibleConnectionFailure(
+                    "Providing the working directory requires Docker API version 1.35 or newer."
+                    f" The Docker daemon the connection is using has API version {self.client.docker_api_version_str}."
+                )
+
+        exec_data = self._call_client(
+            lambda client: client.post_json_to_json(
+                "/containers/{0}/exec", self.get_option("remote_addr"), data=data
+            )
+        )
+        exec_id = exec_data["Id"]
+
+        data = {"Tty": False, "Detach": False}
+        if need_stdin:
+            exec_socket = self._call_client(
+                lambda client: client.post_json_to_stream_socket(
+                    "/exec/{0}/start", exec_id, data=data
+                )
+            )
+            try:
+                with DockerSocketHandler(
+                    display, exec_socket, container=self.get_option("remote_addr")
+                ) as exec_socket_handler:
+                    if do_become:
+                        assert self.become is not None
+
+                        become_output = [b""]
+
+                        def append_become_output(stream_id: int, data: bytes) -> None:
+                            become_output[0] += data
+
+                        exec_socket_handler.set_block_done_callback(
+                            append_become_output
+                        )
+
+                        while not self.become.check_success(
+                            become_output[0]
+                        ) and not self.become.check_password_prompt(become_output[0]):
+                            if not exec_socket_handler.select(
+                                self.get_option("container_timeout")
+                            ):
+                                stdout, stderr = exec_socket_handler.consume()
+                                raise AnsibleConnectionFailure(
+                                    "timeout waiting for privilege escalation password prompt:\n"
+                                    + to_text(become_output[0])
+                                )
+
+                            if exec_socket_handler.is_eof():
+                                raise AnsibleConnectionFailure(
+                                    "privilege output closed while waiting for password prompt:\n"
+                                    + to_text(become_output[0])
+                                )
+
+                        if not self.become.check_success(become_output[0]):
+                            become_pass = self.become.get_option(
+                                "become_pass", playcontext=self._play_context
+                            )
+                            exec_socket_handler.write(
+                                to_bytes(become_pass, errors="surrogate_or_strict")
+                                + b"\n"
+                            )
+
+                    if in_data is not None:
+                        exec_socket_handler.write(in_data)
+
+                    stdout, stderr = exec_socket_handler.consume()
+            finally:
+                exec_socket.close()
+        else:
+            stdout, stderr = self._call_client(
+                lambda client: client.post_json_to_stream(
+                    "/exec/{0}/start",
+                    exec_id,
+                    stream=False,
+                    demux=True,
+                    tty=False,
+                    data=data,
+                )
+            )
+
+        result = self._call_client(
+            lambda client: client.get_json("/exec/{0}/json", exec_id)
+        )
+
+        return result.get("ExitCode") or 0, stdout or b"", stderr or b""
+
+    def _prefix_login_path(self, remote_path: str) -> str:
+        """Make sure that we put files into a standard path
+
+        If a path is relative, then we need to choose where to put it.
+        ssh chooses $HOME but we are not guaranteed that a home dir will
+        exist in any given chroot.  So for now we are choosing "/" instead.
+        This also happens to be the former default.
+
+        Can revisit using $HOME instead if it is a problem
+        """
+        if getattr(self._shell, "_IS_WINDOWS", False):
+            import ntpath
+
+            return ntpath.normpath(remote_path)
+        if not remote_path.startswith(os.path.sep):
+            remote_path = os.path.join(os.path.sep, remote_path)
+        return os.path.normpath(remote_path)
+
+    def put_file(self, in_path: str, out_path: str) -> None:
+        """Transfer a file from local to docker container"""
+        super().put_file(in_path, out_path)  # type: ignore[safe-super]
+        display.vvv(f"PUT {in_path} TO {out_path}", host=self.get_option("remote_addr"))
+
+        if self.client is None:
+            raise AssertionError("Client must be present")
+
+        out_path = self._prefix_login_path(out_path)
+
+        if self.actual_user not in self.ids:
+            dummy, ids, dummy2 = self.exec_command("id -u && id -g")
+            remote_addr = self.get_option("remote_addr")
+            try:
+                b_user_id, b_group_id = ids.splitlines()
+                user_id, group_id = int(b_user_id), int(b_group_id)
+                self.ids[self.actual_user] = user_id, group_id
+                display.vvvv(
+                    f'PUT: Determined uid={user_id} and gid={group_id} for user "{self.actual_user}"',
+                    host=remote_addr,
+                )
+            except Exception as e:
+                raise AnsibleConnectionFailure(
+                    f'Error while determining user and group ID of current user in container "{remote_addr}": {e}\nGot value: {ids!r}'
+                ) from e
+
+        user_id, group_id = self.ids[self.actual_user]
+        try:
+            self._call_client(
+                lambda client: put_file(
+                    client,
+                    container=self.get_option("remote_addr"),
+                    in_path=in_path,
+                    out_path=out_path,
+                    user_id=user_id,
+                    group_id=group_id,
+                    user_name=self.actual_user,
+                    follow_links=True,
+                ),
+                not_found_can_be_resource=True,
+            )
+        except DockerFileNotFound as exc:
+            raise AnsibleFileNotFound(to_text(exc)) from exc
+        except DockerFileCopyError as exc:
+            raise AnsibleConnectionFailure(to_text(exc)) from exc
+
+    def fetch_file(self, in_path: str, out_path: str) -> None:
+        """Fetch a file from container to local."""
+        super().fetch_file(in_path, out_path)  # type: ignore[safe-super]
+        display.vvv(
+            f"FETCH {in_path} TO {out_path}", host=self.get_option("remote_addr")
+        )
+
+        if self.client is None:
+            raise AssertionError("Client must be present")
+
+        in_path = self._prefix_login_path(in_path)
+
+        try:
+            self._call_client(
+                lambda client: fetch_file(
+                    client,
+                    container=self.get_option("remote_addr"),
+                    in_path=in_path,
+                    out_path=out_path,
+                    follow_links=True,
+                    log=lambda msg: display.vvvv(
+                        msg, host=self.get_option("remote_addr")
+                    ),
+                ),
+                not_found_can_be_resource=True,
+            )
+        except DockerFileNotFound as exc:
+            raise AnsibleFileNotFound(to_text(exc)) from exc
+        except DockerFileCopyError as exc:
+            raise AnsibleConnectionFailure(to_text(exc)) from exc
+
+    def close(self) -> None:
+        """Terminate the connection. Nothing to do for Docker"""
+        super().close()  # type: ignore[safe-super]
+        self._connected = False
+
+    def reset(self) -> None:
+        self.ids.clear()

ansible_collections/community/docker/plugins/connection/nsenter.py

@@ -0,0 +1,286 @@
+# Copyright (c) 2021 Jeff Goldschrafe <jeff@holyhandgrenade.org>
+# Based on Ansible local connection plugin by:
+# Copyright (c) 2012 Michael DeHaan <michael.dehaan@gmail.com>
+# Copyright (c) 2015, 2017 Toshio Kuratomi <tkuratomi@ansible.com>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import annotations
+
+DOCUMENTATION = r"""
+name: nsenter
+short_description: execute on host running controller container
+version_added: 1.9.0
+description:
+  - This connection plugin allows Ansible, running in a privileged container, to execute tasks on the container host instead
+    of in the container itself.
+  - This is useful for running Ansible in a pull model, while still keeping the Ansible control node containerized.
+  - It relies on having privileged access to run C(nsenter) in the host's PID namespace, allowing it to enter the namespaces
+    of the provided PID (default PID 1, or init/systemd).
+author: Jeff Goldschrafe (@jgoldschrafe)
+options:
+  nsenter_pid:
+    description:
+      - PID to attach with using nsenter.
+      - The default should be fine unless you are attaching as a non-root user.
+    type: int
+    default: 1
+    vars:
+      - name: ansible_nsenter_pid
+    env:
+      - name: ANSIBLE_NSENTER_PID
+    ini:
+      - section: nsenter_connection
+        key: nsenter_pid
+notes:
+  - The remote user is ignored; this plugin always runs as root.
+  - "This plugin requires the Ansible controller container to be launched in the following way: (1) The container image contains
+    the C(nsenter) program; (2) The container is launched in privileged mode; (3) The container is launched in the host's
+    PID namespace (C(--pid host))."
+"""
+
+import fcntl
+import os
+import pty
+import selectors
+import shlex
+import subprocess
+import typing as t
+
+import ansible.constants as C
+from ansible.errors import AnsibleError
+from ansible.module_utils.common.text.converters import to_bytes, to_text
+from ansible.plugins.connection import ConnectionBase
+from ansible.utils.display import Display
+from ansible.utils.path import unfrackpath
+
+display = Display()
+
+
+class Connection(ConnectionBase):
+    """Connections to a container host using nsenter"""
+
+    transport = "community.docker.nsenter"
+    has_pipelining = False
+
+    def __init__(self, *args: t.Any, **kwargs: t.Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.cwd = None
+        self._nsenter_pid = None
+
+    def _connect(self) -> t.Self:
+        self._nsenter_pid = self.get_option("nsenter_pid")
+
+        # Because nsenter requires very high privileges, our remote user
+        # is always assumed to be root.
+        self._play_context.remote_user = "root"
+
+        if not self._connected:
+            display.vvv(
+                f"ESTABLISH NSENTER CONNECTION FOR USER: {self._play_context.remote_user}",
+                host=self._play_context.remote_addr,
+            )
+            self._connected = True
+        return self
+
+    def exec_command(
+        self, cmd: str, in_data: bytes | None = None, sudoable: bool = True
+    ) -> tuple[int, bytes, bytes]:
+        super().exec_command(cmd, in_data=in_data, sudoable=sudoable)  # type: ignore[safe-super]
+
+        display.debug("in nsenter.exec_command()")
+
+        # pylint: disable-next=no-member
+        def_executable: str | None = C.DEFAULT_EXECUTABLE  # type: ignore[attr-defined]
+        executable = def_executable.split()[0] if def_executable else None
+
+        if not os.path.exists(to_bytes(executable, errors="surrogate_or_strict")):
+            raise AnsibleError(
+                f"failed to find the executable specified {executable}."
+                " Please verify if the executable exists and re-try."
+            )
+
+        # Rewrite the provided command to prefix it with nsenter
+        nsenter_cmd_parts = [
+            "nsenter",
+            "--ipc",
+            "--mount",
+            "--net",
+            "--pid",
+            "--uts",
+            "--preserve-credentials",
+            f"--target={self._nsenter_pid}",
+            "--",
+        ]
+
+        cmd_parts = nsenter_cmd_parts + [cmd]
+        cmd_b = to_bytes(" ".join(cmd_parts))
+
+        display.vvv(f"EXEC {to_text(cmd_b)}", host=self._play_context.remote_addr)
+        display.debug("opening command with Popen()")
+
+        master = None
+        stdin = subprocess.PIPE
+
+        # This plugin does not support pipelining. This diverges from the behavior of
+        # the core "local" connection plugin that this one derives from.
+        if sudoable and self.become and self.become.expect_prompt():
+            # Create a pty if sudoable for privilege escalation that needs it.
+            # Falls back to using a standard pipe if this fails, which may
+            # cause the command to fail in certain situations where we are escalating
+            # privileges or the command otherwise needs a pty.
+            try:
+                master, stdin = pty.openpty()
+            except (IOError, OSError) as e:
+                display.debug(f"Unable to open pty: {e}")
+
+        with subprocess.Popen(
+            cmd_b,
+            shell=True,
+            executable=executable,
+            cwd=self.cwd,
+            stdin=stdin,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        ) as p:
+            assert p.stderr is not None
+            assert p.stdin is not None
+            assert p.stdout is not None
+            # if we created a master, we can close the other half of the pty now, otherwise master is stdin
+            if master is not None:
+                os.close(stdin)
+
+            display.debug("done running command with Popen()")
+
+            if self.become and self.become.expect_prompt() and sudoable:
+                fcntl.fcntl(
+                    p.stdout,
+                    fcntl.F_SETFL,
+                    fcntl.fcntl(p.stdout, fcntl.F_GETFL) | os.O_NONBLOCK,
+                )
+                fcntl.fcntl(
+                    p.stderr,
+                    fcntl.F_SETFL,
+                    fcntl.fcntl(p.stderr, fcntl.F_GETFL) | os.O_NONBLOCK,
+                )
+                selector = selectors.DefaultSelector()
+                selector.register(p.stdout, selectors.EVENT_READ)
+                selector.register(p.stderr, selectors.EVENT_READ)
+
+                become_output = b""
+                try:
+                    while not self.become.check_success(
+                        become_output
+                    ) and not self.become.check_password_prompt(become_output):
+                        events = selector.select(self._play_context.timeout)
+                        if not events:
+                            stdout, stderr = p.communicate()
+                            raise AnsibleError(
+                                "timeout waiting for privilege escalation password prompt:\n"
+                                + to_text(become_output)
+                            )
+
+                        chunks = b""
+                        for key, dummy_event in events:
+                            if key.fileobj == p.stdout:
+                                chunk = p.stdout.read()
+                                if chunk:
+                                    chunks += chunk
+                            elif key.fileobj == p.stderr:
+                                chunk = p.stderr.read()
+                                if chunk:
+                                    chunks += chunk
+
+                        if not chunks:
+                            stdout, stderr = p.communicate()
+                            raise AnsibleError(
+                                "privilege output closed while waiting for password prompt:\n"
+                                + to_text(become_output)
+                            )
+                        become_output += chunks
+                finally:
+                    selector.close()
+
+                if not self.become.check_success(become_output):
+                    become_pass = self.become.get_option(
+                        "become_pass", playcontext=self._play_context
+                    )
+                    if master is None:
+                        p.stdin.write(
+                            to_bytes(become_pass, errors="surrogate_or_strict") + b"\n"
+                        )
+                    else:
+                        os.write(
+                            master,
+                            to_bytes(become_pass, errors="surrogate_or_strict") + b"\n",
+                        )
+
+                fcntl.fcntl(
+                    p.stdout,
+                    fcntl.F_SETFL,
+                    fcntl.fcntl(p.stdout, fcntl.F_GETFL) & ~os.O_NONBLOCK,
+                )
+                fcntl.fcntl(
+                    p.stderr,
+                    fcntl.F_SETFL,
+                    fcntl.fcntl(p.stderr, fcntl.F_GETFL) & ~os.O_NONBLOCK,
+                )
+
+            display.debug("getting output with communicate()")
+            stdout, stderr = p.communicate(in_data)
+            display.debug("done communicating")
+
+            # finally, close the other half of the pty, if it was created
+            if master:
+                os.close(master)
+
+            display.debug("done with nsenter.exec_command()")
+            return (p.returncode, stdout, stderr)
+
+    def put_file(self, in_path: str, out_path: str) -> None:
+        super().put_file(in_path, out_path)  # type: ignore[safe-super]
+
+        in_path = unfrackpath(in_path, basedir=self.cwd)
+        out_path = unfrackpath(out_path, basedir=self.cwd)
+
+        display.vvv(f"PUT {in_path} to {out_path}", host=self._play_context.remote_addr)
+        try:
+            with open(to_bytes(in_path, errors="surrogate_or_strict"), "rb") as in_file:
+                in_data = in_file.read()
+            rc, dummy_out, err = self.exec_command(
+                cmd=f"tee {shlex.quote(out_path)}", in_data=in_data
+            )
+            if rc != 0:
+                raise AnsibleError(
+                    f"failed to transfer file to {out_path}: {to_text(err)}"
+                )
+        except IOError as e:
+            raise AnsibleError(f"failed to transfer file to {out_path}: {e}") from e
+
+    def fetch_file(self, in_path: str, out_path: str) -> None:
+        super().fetch_file(in_path, out_path)  # type: ignore[safe-super]
+
+        in_path = unfrackpath(in_path, basedir=self.cwd)
+        out_path = unfrackpath(out_path, basedir=self.cwd)
+
+        try:
+            rc, out, err = self.exec_command(cmd=f"cat {shlex.quote(in_path)}")
+            display.vvv(
+                f"FETCH {in_path} TO {out_path}", host=self._play_context.remote_addr
+            )
+            if rc != 0:
+                raise AnsibleError(
+                    f"failed to transfer file to {in_path}: {to_text(err)}"
+                )
+            with open(
+                to_bytes(out_path, errors="surrogate_or_strict"), "wb"
+            ) as out_file:
+                out_file.write(out)
+        except IOError as e:
+            raise AnsibleError(
+                f"failed to transfer file to {to_text(out_path)}: {e}"
+            ) from e
+
+    def close(self) -> None:
+        """terminate the connection; nothing to do here"""
+        self._connected = False