V1

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

@@ -0,0 +1,451 @@
+# 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 COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
+    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
+          R(community.docker.docker_api,ansible_collections.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
+'''
+
+import fcntl
+import os
+import os.path
+import subprocess
+import re
+
+from ansible.compat import selectors
+from ansible.errors import AnsibleError, AnsibleFileNotFound
+from ansible.module_utils.six.moves import shlex_quote
+from ansible.module_utils.common.process import get_bin_path
+from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
+from ansible.plugins.connection import ConnectionBase, BUFSIZE
+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, play_context, new_stdin, *args, **kwargs):
+        super(Connection, self).__init__(play_context, new_stdin, *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 don't 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 = []
+        self._container_user_cache = {}
+        self._version = 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:
+                raise AnsibleError("docker command not found in PATH")
+
+    @staticmethod
+    def _sanitize_version(version):
+        version = re.sub(u'[^0-9a-zA-Z.]', u'', version)
+        version = re.sub(u'^v', u'', version)
+        return version
+
+    def _old_docker_version(self):
+        cmd_args = self._docker_args
+
+        old_version_subcommand = ['version']
+
+        old_docker_cmd = [self.docker_cmd] + cmd_args + old_version_subcommand
+        p = subprocess.Popen(old_docker_cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+        cmd_output, err = p.communicate()
+
+        return old_docker_cmd, to_native(cmd_output), err, p.returncode
+
+    def _new_docker_version(self):
+        # 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
+        p = subprocess.Popen(new_docker_cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+        cmd_output, err = p.communicate()
+        return new_docker_cmd, to_native(cmd_output), err, p.returncode
+
+    def _get_docker_version(self):
+
+        cmd, cmd_output, err, returncode = self._old_docker_version()
+        if returncode == 0:
+            for line in to_text(cmd_output, errors='surrogate_or_strict').split(u'\n'):
+                if line.startswith(u'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('Docker version check (%s) failed: %s' % (to_native(cmd), to_native(err)))
+
+        return self._sanitize_version(to_text(cmd_output, errors='surrogate_or_strict'))
+
+    def _get_docker_remote_user(self):
+        """ 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]
+        p = subprocess.Popen([self.docker_cmd, 'inspect', '--format', '{{.Config.User}}', container],
+                             stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+
+        out, err = p.communicate()
+        out = to_text(out, errors='surrogate_or_strict')
+
+        if p.returncode != 0:
+            display.warning(u'unable to retrieve default user from docker container: %s %s' % (out, to_text(err)))
+            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 u'root'
+        self._container_user_cache[container] = user
+        return user
+
+    def _build_exec_cmd(self, cmd):
+        """ 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]
+
+        # -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):
+        # 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):
+
+        ''' 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):
+
+        if not self._version:
+            self._set_docker_args()
+
+            self._version = self._get_docker_version()
+            if self._version == u'dev':
+                display.warning(u'Docker version number is "dev". Will assume latest version.')
+            if self._version != u'dev' and LooseVersion(self._version) < LooseVersion(u'1.3'):
+                raise AnsibleError('docker connection type requires docker 1.3 or higher')
+        return self._version
+
+    def _get_actual_user(self):
+        if self.remote_user is not None:
+            # An explicit user is provided
+            if self.docker_version == u'dev' or LooseVersion(self.docker_version) >= LooseVersion(u'1.7'):
+                # Support for specifying the exec user was added in docker 1.7
+                return self.remote_user
+            else:
+                self.remote_user = None
+                actual_user = self._get_docker_remote_user()
+                if actual_user != self.get_option('remote_user'):
+                    display.warning(u'docker {0} does not support remote_user, using container default: {1}'
+                                    .format(self.docker_version, self.actual_user or u'?'))
+                return actual_user
+        elif self._display.verbosity > 2:
+            # Since we're 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 don't need to.
+            return self._get_docker_remote_user()
+        else:
+            return None
+
+    def _connect(self, port=None):
+        """ Connect to the container. Nothing to do """
+        super(Connection, self)._connect()
+        if not self._connected:
+            self._set_conn_data()
+            actual_user = self._get_actual_user()
+            display.vvv(u"ESTABLISH DOCKER CONNECTION FOR USER: {0}".format(
+                actual_user or u'?'), host=self.get_option('remote_addr')
+            )
+            self._connected = True
+
+    def exec_command(self, cmd, in_data=None, sudoable=False):
+        """ Run a command on the docker host """
+
+        self._set_conn_data()
+
+        super(Connection, self).exec_command(cmd, in_data=in_data, sudoable=sudoable)
+
+        local_cmd = self._build_exec_cmd([self._play_context.executable, '-c', cmd])
+
+        display.vvv(u"EXEC {0}".format(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]
+
+        p = subprocess.Popen(
+            local_cmd,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+        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_native(become_output))
+
+                    for key, event in events:
+                        if key.fileobj == p.stdout:
+                            chunk = p.stdout.read()
+                        elif key.fileobj == p.stderr:
+                            chunk = p.stderr.read()
+
+                    if not chunk:
+                        stdout, stderr = p.communicate()
+                        raise AnsibleError('privilege output closed while waiting for password prompt:\n' + to_native(become_output))
+                    become_output += chunk
+            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):
+        ''' 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 aren't guaranteed that a home dir will
+            exist in any given chroot.  So for now we're choosing "/" instead.
+            This also happens to be the former default.
+
+            Can revisit using $HOME instead if it's a problem
+        '''
+        if getattr(self._shell, "_IS_WINDOWS", False):
+            import ntpath
+            return ntpath.normpath(remote_path)
+        else:
+            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, out_path):
+        """ Transfer a file from local to docker container """
+        self._set_conn_data()
+        super(Connection, self).put_file(in_path, out_path)
+        display.vvv("PUT %s TO %s" % (in_path, 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(
+                "file or module does not exist: %s" % to_native(in_path))
+
+        out_path = shlex_quote(out_path)
+        # Older docker doesn't 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", "dd of=%s bs=%s%s" % (out_path, BUFSIZE, count)])
+            args = [to_bytes(i, errors='surrogate_or_strict') for i in args]
+            try:
+                p = subprocess.Popen(args, stdin=in_file, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+            except OSError:
+                raise AnsibleError("docker connection requires dd command in the container to put files")
+            stdout, stderr = p.communicate()
+
+            if p.returncode != 0:
+                raise AnsibleError("failed to transfer file %s to %s:\n%s\n%s" %
+                                   (to_native(in_path), to_native(out_path), to_native(stdout), to_native(stderr)))
+
+    def fetch_file(self, in_path, out_path):
+        """ Fetch a file from container to local. """
+        self._set_conn_data()
+        super(Connection, self).fetch_file(in_path, out_path)
+        display.vvv("FETCH %s TO %s" % (in_path, 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", "%s:%s" % (self.get_option('remote_addr'), in_path), out_dir]
+        args = [to_bytes(i, errors='surrogate_or_strict') for i in args]
+
+        p = subprocess.Popen(args, stdin=subprocess.PIPE,
+                             stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+        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 doesn't 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", "dd if=%s bs=%s" % (in_path, 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:
+                    p = subprocess.Popen(args, stdin=subprocess.PIPE,
+                                         stdout=out_file, stderr=subprocess.PIPE)
+                except OSError:
+                    raise AnsibleError("docker connection requires dd command in the container to put files")
+                stdout, stderr = p.communicate()
+
+                if p.returncode != 0:
+                    raise AnsibleError("failed to fetch file %s to %s:\n%s\n%s" % (in_path, out_path, stdout, stderr))
+
+        # 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):
+        """ Terminate the connection. Nothing to do for Docker"""
+        super(Connection, self).close()
+        self._connected = False
+
+    def reset(self):
+        # Clear container user cache
+        self._container_user_cache = {}

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

@@ -0,0 +1,388 @@
+# Copyright (c) 2019-2020, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
+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 Docker SDK for Python to interact directly with the Docker daemon instead of
+      using the Docker CLI. Use the
+      R(community.docker.docker,ansible_collections.community.docker.docker_connection)
+      connection plugin if you want to use the Docker CLI.
+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
+
+extends_documentation_fragment:
+    - community.docker.docker
+    - community.docker.docker.var_names
+    - community.docker.docker.docker_py_1_documentation
+'''
+
+import io
+import os
+import os.path
+import shutil
+import tarfile
+
+from ansible.errors import AnsibleFileNotFound, AnsibleConnectionFailure
+from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
+from ansible.plugins.connection import ConnectionBase
+from ansible.utils.display import Display
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    RequestException,
+)
+from ansible_collections.community.docker.plugins.plugin_utils.socket_handler import (
+    DockerSocketHandler,
+)
+from ansible_collections.community.docker.plugins.plugin_utils.common import (
+    AnsibleDockerClient,
+)
+
+try:
+    from docker.errors import DockerException, APIError, NotFound
+except Exception:
+    # missing Docker SDK for Python handled in ansible_collections.community.docker.plugins.module_utils.common
+    pass
+
+MIN_DOCKER_PY = '1.7.0'
+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, callable, not_found_can_be_resource=False):
+        try:
+            return callable()
+        except NotFound as e:
+            if not_found_can_be_resource:
+                raise AnsibleConnectionFailure('Could not find container "{1}" or resource in it ({0})'.format(e, self.get_option('remote_addr')))
+            else:
+                raise AnsibleConnectionFailure('Could not find container "{1}" ({0})'.format(e, self.get_option('remote_addr')))
+        except APIError as e:
+            if e.response and e.response.status_code == 409:
+                raise AnsibleConnectionFailure('The container "{1}" has been paused ({0})'.format(e, self.get_option('remote_addr')))
+            self.client.fail(
+                'An unexpected docker error occurred for container "{1}": {0}'.format(e, self.get_option('remote_addr'))
+            )
+        except DockerException as e:
+            self.client.fail(
+                'An unexpected docker error occurred for container "{1}": {0}'.format(e, self.get_option('remote_addr'))
+            )
+        except RequestException as e:
+            self.client.fail(
+                'An unexpected requests error occurred for container "{1}" when docker-py tried to talk to the docker daemon: {0}'
+                .format(e, self.get_option('remote_addr'))
+            )
+
+    def __init__(self, play_context, new_stdin, *args, **kwargs):
+        super(Connection, self).__init__(play_context, new_stdin, *args, **kwargs)
+
+        self.client = None
+        self.ids = dict()
+
+        # Windows uses Powershell modules
+        if getattr(self._shell, "_IS_WINDOWS", False):
+            self.module_implementation_preferences = ('.ps1', '.exe', '')
+
+        self.actual_user = None
+
+    def _connect(self, port=None):
+        """ Connect to the container. Nothing to do """
+        super(Connection, self)._connect()
+        if not self._connected:
+            self.actual_user = self.get_option('remote_user')
+            display.vvv(u"ESTABLISH DOCKER CONNECTION FOR USER: {0}".format(
+                self.actual_user or u'?'), host=self.get_option('remote_addr')
+            )
+            if self.client is None:
+                self.client = AnsibleDockerClient(self, min_docker_version=MIN_DOCKER_PY, min_docker_api_version=MIN_DOCKER_API)
+            self._connected = True
+
+            if self.actual_user is None and display.verbosity > 2:
+                # Since we're 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 don't need to
+                display.vvv(u"Trying to determine actual user")
+                result = self._call_client(lambda: self.client.inspect_container(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(u"Actual user is '{0}'".format(self.actual_user))
+
+    def exec_command(self, cmd, in_data=None, sudoable=False):
+        """ Run a command on the docker host """
+
+        super(Connection, self).exec_command(cmd, in_data=in_data, sudoable=sudoable)
+
+        command = [self._play_context.executable, '-c', to_text(cmd)]
+
+        do_become = self.become and self.become.expect_prompt() and sudoable
+
+        display.vvv(
+            u"EXEC {0}{1}{2}".format(
+                to_text(command),
+                ', with stdin ({0} bytes)'.format(len(in_data)) if in_data is not None else '',
+                ', with become prompt' if do_become else '',
+            ),
+            host=self.get_option('remote_addr')
+        )
+
+        need_stdin = True if (in_data is not None) or do_become else False
+
+        exec_data = self._call_client(lambda: self.client.exec_create(
+            self.get_option('remote_addr'),
+            command,
+            stdout=True,
+            stderr=True,
+            stdin=need_stdin,
+            user=self.get_option('remote_user') or '',
+            # workdir=None,  - only works for Docker SDK for Python 3.0.0 and later
+        ))
+        exec_id = exec_data['Id']
+
+        if need_stdin:
+            exec_socket = self._call_client(lambda: self.client.exec_start(
+                exec_id,
+                detach=False,
+                socket=True,
+            ))
+            try:
+                with DockerSocketHandler(display, exec_socket, container=self.get_option('remote_addr')) as exec_socket_handler:
+                    if do_become:
+                        become_output = [b'']
+
+                        def append_become_output(stream_id, data):
+                            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_native(become_output[0]))
+
+                            if exec_socket_handler.is_eof():
+                                raise AnsibleConnectionFailure('privilege output closed while waiting for password prompt:\n' + to_native(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: self.client.exec_start(
+                exec_id,
+                detach=False,
+                stream=False,
+                socket=False,
+                demux=True,
+            ))
+
+        result = self._call_client(lambda: self.client.exec_inspect(exec_id))
+
+        return result.get('ExitCode') or 0, stdout or b'', stderr or b''
+
+    def _prefix_login_path(self, remote_path):
+        ''' 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 aren't guaranteed that a home dir will
+            exist in any given chroot.  So for now we're choosing "/" instead.
+            This also happens to be the former default.
+
+            Can revisit using $HOME instead if it's a problem
+        '''
+        if getattr(self._shell, "_IS_WINDOWS", False):
+            import ntpath
+            return ntpath.normpath(remote_path)
+        else:
+            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, out_path):
+        """ Transfer a file from local to docker container """
+        super(Connection, self).put_file(in_path, out_path)
+        display.vvv("PUT %s TO %s" % (in_path, 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(
+                "file or module does not exist: %s" % to_native(in_path))
+
+        if self.actual_user not in self.ids:
+            dummy, ids, dummy = self.exec_command(b'id -u && id -g')
+            try:
+                user_id, group_id = ids.splitlines()
+                self.ids[self.actual_user] = int(user_id), int(group_id)
+                display.vvvv(
+                    'PUT: Determined uid={0} and gid={1} for user "{2}"'.format(user_id, group_id, self.actual_user),
+                    host=self.get_option('remote_addr')
+                )
+            except Exception as e:
+                raise AnsibleConnectionFailure(
+                    'Error while determining user and group ID of current user in container "{1}": {0}\nGot value: {2!r}'
+                    .format(e, self.get_option('remote_addr'), ids)
+                )
+
+        b_in_path = to_bytes(in_path, errors='surrogate_or_strict')
+
+        out_dir, out_file = os.path.split(out_path)
+
+        # TODO: stream tar file, instead of creating it in-memory into a BytesIO
+
+        bio = io.BytesIO()
+        with tarfile.open(fileobj=bio, mode='w|', dereference=True, encoding='utf-8') as tar:
+            # Note that without both name (bytes) and arcname (unicode), this either fails for
+            # Python 2.6/2.7, Python 3.5/3.6, or Python 3.7+. Only when passing both (in this
+            # form) it works with Python 2.6, 2.7, 3.5, 3.6, and 3.7 up to 3.9.
+            tarinfo = tar.gettarinfo(b_in_path, arcname=to_text(out_file))
+            user_id, group_id = self.ids[self.actual_user]
+            tarinfo.uid = user_id
+            tarinfo.uname = ''
+            if self.actual_user:
+                tarinfo.uname = self.actual_user
+            tarinfo.gid = group_id
+            tarinfo.gname = ''
+            tarinfo.mode &= 0o700
+            with open(b_in_path, 'rb') as f:
+                tar.addfile(tarinfo, fileobj=f)
+        data = bio.getvalue()
+
+        ok = self._call_client(lambda: self.client.put_archive(
+            self.get_option('remote_addr'),
+            out_dir,
+            data,  # can also be file object for streaming; this is only clear from the
+                   # implementation of put_archive(), which uses requests's put().
+                   # See https://2.python-requests.org/en/master/user/advanced/#streaming-uploads
+                   # WARNING: might not work with all transports!
+        ), not_found_can_be_resource=True)
+        if not ok:
+            raise AnsibleConnectionFailure(
+                'Unknown error while creating file "{0}" in container "{1}".'
+                .format(out_path, self.get_option('remote_addr'))
+            )
+
+    def fetch_file(self, in_path, out_path):
+        """ Fetch a file from container to local. """
+        super(Connection, self).fetch_file(in_path, out_path)
+        display.vvv("FETCH %s TO %s" % (in_path, out_path), host=self.get_option('remote_addr'))
+
+        in_path = self._prefix_login_path(in_path)
+        b_out_path = to_bytes(out_path, errors='surrogate_or_strict')
+
+        considered_in_paths = set()
+
+        while True:
+            if in_path in considered_in_paths:
+                raise AnsibleConnectionFailure('Found infinite symbolic link loop when trying to fetch "{0}"'.format(in_path))
+            considered_in_paths.add(in_path)
+
+            display.vvvv('FETCH: Fetching "%s"' % in_path, host=self.get_option('remote_addr'))
+            stream, stats = self._call_client(lambda: self.client.get_archive(
+                self.get_option('remote_addr'),
+                in_path,
+            ), not_found_can_be_resource=True)
+
+            # TODO: stream tar file instead of downloading it into a BytesIO
+
+            bio = io.BytesIO()
+            for chunk in stream:
+                bio.write(chunk)
+            bio.seek(0)
+
+            with tarfile.open(fileobj=bio, mode='r|') as tar:
+                symlink_member = None
+                first = True
+                for member in tar:
+                    if not first:
+                        raise AnsibleConnectionFailure('Received tarfile contains more than one file!')
+                    first = False
+                    if member.issym():
+                        symlink_member = member
+                        continue
+                    if not member.isfile():
+                        raise AnsibleConnectionFailure('Remote file "%s" is not a regular file or a symbolic link' % in_path)
+                    in_f = tar.extractfile(member)  # in Python 2, this *cannot* be used in `with`...
+                    with open(b_out_path, 'wb') as out_f:
+                        shutil.copyfileobj(in_f, out_f, member.size)
+                if first:
+                    raise AnsibleConnectionFailure('Received tarfile is empty!')
+                # If the only member was a file, it's already extracted. If it is a symlink, process it now.
+                if symlink_member is not None:
+                    in_path = os.path.join(os.path.split(in_path)[0], symlink_member.linkname)
+                    display.vvvv('FETCH: Following symbolic link to "%s"' % in_path, host=self.get_option('remote_addr'))
+                    continue
+                return
+
+    def close(self):
+        """ Terminate the connection. Nothing to do for Docker"""
+        super(Connection, self).close()
+        self._connected = False
+
+    def reset(self):
+        self.ids.clear()

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

@@ -0,0 +1,239 @@
+# (c) 2021 Jeff Goldschrafe <jeff@holyhandgrenade.org>
+# Based on Ansible local connection plugin by:
+# (c) 2012 Michael DeHaan <michael.dehaan@gmail.com>
+# (c) 2015, 2017 Toshio Kuratomi <tkuratomi@ansible.com>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
+    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 os
+import pty
+import shutil
+import subprocess
+import fcntl
+
+import ansible.constants as C
+from ansible.errors import AnsibleError, AnsibleFileNotFound
+from ansible.module_utils.compat import selectors
+from ansible.module_utils.six import binary_type, text_type
+from ansible.module_utils.common.text.converters import to_bytes, to_native, 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, **kwargs):
+        super(Connection, self).__init__(*args, **kwargs)
+        self.cwd = None
+
+    def _connect(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(
+                u"ESTABLISH NSENTER CONNECTION FOR USER: {0}".format(
+                    self._play_context.remote_user
+                ),
+                host=self._play_context.remote_addr,
+            )
+            self._connected = True
+        return self
+
+    def exec_command(self, cmd, in_data=None, sudoable=True):
+        super(Connection, self).exec_command(cmd, in_data=in_data, sudoable=sudoable)
+
+        display.debug("in nsenter.exec_command()")
+
+        executable = C.DEFAULT_EXECUTABLE.split()[0] if C.DEFAULT_EXECUTABLE else None
+
+        if not os.path.exists(to_bytes(executable, errors='surrogate_or_strict')):
+            raise AnsibleError("failed to find the executable specified %s."
+                               " Please verify if the executable exists and re-try." % executable)
+
+        # Rewrite the provided command to prefix it with nsenter
+        nsenter_cmd_parts = [
+            "nsenter",
+            "--ipc",
+            "--mount",
+            "--net",
+            "--pid",
+            "--uts",
+            "--preserve-credentials",
+            "--target={0}".format(self._nsenter_pid),
+            "--",
+        ]
+
+        if isinstance(cmd, (text_type, binary_type)):
+            cmd_parts = nsenter_cmd_parts + [cmd]
+            cmd = to_bytes(" ".join(cmd_parts))
+        else:
+            cmd_parts = nsenter_cmd_parts + cmd
+            cmd = [to_bytes(arg) for arg in cmd_parts]
+
+        display.vvv(u"EXEC {0}".format(to_text(cmd)), 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 privlege 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("Unable to open pty: %s" % to_native(e))
+
+        p = subprocess.Popen(
+            cmd,
+            shell=isinstance(cmd, (text_type, binary_type)),
+            executable=executable if isinstance(cmd, (text_type, binary_type)) else None,
+            cwd=self.cwd,
+            stdin=stdin,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+
+        # 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_native(become_output))
+
+                    for key, event in events:
+                        if key.fileobj == p.stdout:
+                            chunk = p.stdout.read()
+                        elif key.fileobj == p.stderr:
+                            chunk = p.stderr.read()
+
+                    if not chunk:
+                        stdout, stderr = p.communicate()
+                        raise AnsibleError('privilege output closed while waiting for password prompt:\n' + to_native(become_output))
+                    become_output += chunk
+            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, out_path):
+        super(Connection, self).put_file(in_path, out_path)
+
+        in_path = unfrackpath(in_path, basedir=self.cwd)
+        out_path = unfrackpath(out_path, basedir=self.cwd)
+
+        display.vvv(u"PUT {0} to {1}".format(in_path, 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, out, err = self.exec_command(cmd=["tee", out_path], in_data=in_data)
+            if rc != 0:
+                raise AnsibleError("failed to transfer file to {0}: {1}".format(out_path, err))
+        except IOError as e:
+            raise AnsibleError("failed to transfer file to {0}: {1}".format(out_path, to_native(e)))
+
+    def fetch_file(self, in_path, out_path):
+        super(Connection, self).fetch_file(in_path, out_path)
+
+        in_path = unfrackpath(in_path, basedir=self.cwd)
+        out_path = unfrackpath(out_path, basedir=self.cwd)
+
+        try:
+            rc, out, err = self.exec_command(cmd=["cat", in_path])
+            display.vvv(u"FETCH {0} TO {1}".format(in_path, out_path), host=self._play_context.remote_addr)
+            if rc != 0:
+                raise AnsibleError("failed to transfer file to {0}: {1}".format(in_path, 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("failed to transfer file to {0}: {1}".format(to_native(out_path), to_native(e)))
+
+    def close(self):
+        ''' terminate the connection; nothing to do here '''
+        self._connected = False

collections/ansible_collections/community/docker/plugins/doc_fragments/docker.py

@@ -0,0 +1,187 @@
+# -*- coding: utf-8 -*-
+
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+class ModuleDocFragment(object):
+
+    # Docker doc fragment
+    DOCUMENTATION = r'''
+
+options:
+    docker_host:
+        description:
+            - The URL or Unix socket path used to connect to the Docker API. To connect to a remote host, provide the
+              TCP connection string. For example, C(tcp://192.0.2.23:2376). If TLS is used to encrypt the connection,
+              the module will automatically replace C(tcp) in the connection URL with C(https).
+            - If the value is not specified in the task, the value of environment variable C(DOCKER_HOST) will be used
+              instead. If the environment variable is not set, the default value will be used.
+        type: str
+        default: unix://var/run/docker.sock
+        aliases: [ docker_url ]
+    tls_hostname:
+        description:
+            - When verifying the authenticity of the Docker Host server, provide the expected name of the server.
+            - If the value is not specified in the task, the value of environment variable C(DOCKER_TLS_HOSTNAME) will
+              be used instead. If the environment variable is not set, the default value will be used.
+            - The current default value is C(localhost). This default is deprecated and will change in community.docker
+              2.0.0 to be a value computed from I(docker_host). Explicitly specify C(localhost) to make sure this value
+              will still be used, and to disable the deprecation message which will be shown otherwise.
+        type: str
+    api_version:
+        description:
+            - The version of the Docker API running on the Docker Host.
+            - Defaults to the latest version of the API supported by Docker SDK for Python and the docker daemon.
+            - If the value is not specified in the task, the value of environment variable C(DOCKER_API_VERSION) will be
+              used instead. If the environment variable is not set, the default value will be used.
+        type: str
+        default: auto
+        aliases: [ docker_api_version ]
+    timeout:
+        description:
+            - The maximum amount of time in seconds to wait on a response from the API.
+            - If the value is not specified in the task, the value of environment variable C(DOCKER_TIMEOUT) will be used
+              instead. If the environment variable is not set, the default value will be used.
+        type: int
+        default: 60
+    ca_cert:
+        description:
+            - Use a CA certificate when performing server verification by providing the path to a CA certificate file.
+            - If the value is not specified in the task and the environment variable C(DOCKER_CERT_PATH) is set,
+              the file C(ca.pem) from the directory specified in the environment variable C(DOCKER_CERT_PATH) will be used.
+        type: path
+        aliases: [ tls_ca_cert, cacert_path ]
+    client_cert:
+        description:
+            - Path to the client's TLS certificate file.
+            - If the value is not specified in the task and the environment variable C(DOCKER_CERT_PATH) is set,
+              the file C(cert.pem) from the directory specified in the environment variable C(DOCKER_CERT_PATH) will be used.
+        type: path
+        aliases: [ tls_client_cert, cert_path ]
+    client_key:
+        description:
+            - Path to the client's TLS key file.
+            - If the value is not specified in the task and the environment variable C(DOCKER_CERT_PATH) is set,
+              the file C(key.pem) from the directory specified in the environment variable C(DOCKER_CERT_PATH) will be used.
+        type: path
+        aliases: [ tls_client_key, key_path ]
+    ssl_version:
+        description:
+            - Provide a valid SSL version number. Default value determined by ssl.py module.
+            - If the value is not specified in the task, the value of environment variable C(DOCKER_SSL_VERSION) will be
+              used instead.
+        type: str
+    tls:
+        description:
+            - Secure the connection to the API by using TLS without verifying the authenticity of the Docker host
+              server. Note that if I(validate_certs) is set to C(yes) as well, it will take precedence.
+            - If the value is not specified in the task, the value of environment variable C(DOCKER_TLS) will be used
+              instead. If the environment variable is not set, the default value will be used.
+        type: bool
+        default: no
+    use_ssh_client:
+        description:
+            - For SSH transports, use the C(ssh) CLI tool instead of paramiko.
+            - Requires Docker SDK for Python 4.4.0 or newer.
+        type: bool
+        default: no
+        version_added: 1.5.0
+    validate_certs:
+        description:
+            - Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server.
+            - If the value is not specified in the task, the value of environment variable C(DOCKER_TLS_VERIFY) will be
+              used instead. If the environment variable is not set, the default value will be used.
+        type: bool
+        default: no
+        aliases: [ tls_verify ]
+    debug:
+        description:
+            - Debug mode
+        type: bool
+        default: no
+
+notes:
+  - Connect to the Docker daemon by providing parameters with each task or by defining environment variables.
+    You can define C(DOCKER_HOST), C(DOCKER_TLS_HOSTNAME), C(DOCKER_API_VERSION), C(DOCKER_CERT_PATH), C(DOCKER_SSL_VERSION),
+    C(DOCKER_TLS), C(DOCKER_TLS_VERIFY) and C(DOCKER_TIMEOUT). If you are using docker machine, run the script shipped
+    with the product that sets up the environment. It will set these variables for you. See
+    U(https://docs.docker.com/machine/reference/env/) for more details.
+  - When connecting to Docker daemon with TLS, you might need to install additional Python packages.
+    For the Docker SDK for Python, version 2.4 or newer, this can be done by installing C(docker[tls]) with M(ansible.builtin.pip).
+  - Note that the Docker SDK for Python only allows to specify the path to the Docker configuration for very few functions.
+    In general, it will use C($HOME/.docker/config.json) if the C(DOCKER_CONFIG) environment variable is not specified,
+    and use C($DOCKER_CONFIG/config.json) otherwise.
+'''
+
+    # For plugins: allow to define common options with Ansible variables
+
+    VAR_NAMES = r'''
+options:
+    docker_host:
+        vars:
+            - name: ansible_docker_docker_host
+    tls_hostname:
+        vars:
+            - name: ansible_docker_tls_hostname
+    api_version:
+        vars:
+            - name: ansible_docker_api_version
+    timeout:
+        vars:
+            - name: ansible_docker_timeout
+    ca_cert:
+        vars:
+            - name: ansible_docker_ca_cert
+    client_cert:
+        vars:
+            - name: ansible_docker_client_cert
+    client_key:
+        vars:
+            - name: ansible_docker_client_key
+    ssl_version:
+        vars:
+            - name: ansible_docker_ssl_version
+    tls:
+        vars:
+            - name: ansible_docker_tls
+    validate_certs:
+        vars:
+            - name: ansible_docker_validate_certs
+'''
+
+    # Additional, more specific stuff for minimal Docker SDK for Python version < 2.0
+
+    DOCKER_PY_1_DOCUMENTATION = r'''
+options: {}
+notes:
+  - This module uses the L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) to
+    communicate with the Docker daemon.
+requirements:
+  - "Docker SDK for Python: Please note that the L(docker-py,https://pypi.org/project/docker-py/)
+     Python module has been superseded by L(docker,https://pypi.org/project/docker/)
+     (see L(here,https://github.com/docker/docker-py/issues/1310) for details).
+     For Python 2.6, C(docker-py) must be used. Otherwise, it is recommended to
+     install the C(docker) Python module. Note that both modules should *not*
+     be installed at the same time. Also note that when both modules are installed
+     and one of them is uninstalled, the other might no longer function and a
+     reinstall of it is required."
+'''
+
+    # Additional, more specific stuff for minimal Docker SDK for Python version >= 2.0.
+    # Note that Docker SDK for Python >= 2.0 requires Python 2.7 or newer.
+
+    DOCKER_PY_2_DOCUMENTATION = r'''
+options: {}
+notes:
+  - This module uses the L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) to
+    communicate with the Docker daemon.
+requirements:
+  - "Python >= 2.7"
+  - "Docker SDK for Python: Please note that the L(docker-py,https://pypi.org/project/docker-py/)
+     Python module has been superseded by L(docker,https://pypi.org/project/docker/)
+     (see L(here,https://github.com/docker/docker-py/issues/1310) for details).
+     This module does *not* work with docker-py."
+'''

collections/ansible_collections/community/docker/plugins/inventory/docker_containers.py

@@ -0,0 +1,346 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2020, Felix Fontein <felix@fontein.de>
+# For the parts taken from the docker inventory script:
+# Copyright (c) 2016, Paul Durivage <paul.durivage@gmail.com>
+# Copyright (c) 2016, Chris Houseknecht <house@redhat.com>
+# Copyright (c) 2016, James Tanner <jtanner@redhat.com>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+name: docker_containers
+short_description: Ansible dynamic inventory plugin for Docker containers.
+version_added: 1.1.0
+author:
+    - Felix Fontein (@felixfontein)
+requirements:
+    - L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 1.10.0
+extends_documentation_fragment:
+    - ansible.builtin.constructed
+    - community.docker.docker
+    - community.docker.docker.docker_py_1_documentation
+description:
+    - Reads inventories from the Docker API.
+    - Uses a YAML configuration file that ends with C(docker.[yml|yaml]).
+options:
+    plugin:
+        description:
+            - The name of this plugin, it should always be set to C(community.docker.docker_containers)
+              for this plugin to recognize it as it's own.
+        type: str
+        required: true
+        choices: [ community.docker.docker_containers ]
+
+    connection_type:
+        description:
+            - Which connection type to use the containers.
+            - One way to connect to containers is to use SSH (C(ssh)). For this, the options I(default_ip) and
+              I(private_ssh_port) are used. This requires that a SSH daemon is running inside the containers.
+            - Alternatively, C(docker-cli) selects the
+              R(docker connection plugin,ansible_collections.community.docker.docker_connection),
+              and C(docker-api) (default) selects the
+              R(docker_api connection plugin,ansible_collections.community.docker.docker_api_connection).
+            - When C(docker-api) is used, all Docker daemon configuration values are passed from the inventory plugin
+              to the connection plugin. This can be controlled with I(configure_docker_daemon).
+        type: str
+        default: docker-api
+        choices:
+            - ssh
+            - docker-cli
+            - docker-api
+
+    configure_docker_daemon:
+        description:
+            - Whether to pass all Docker daemon configuration from the inventory plugin to the connection plugin.
+            - Only used when I(connection_type=docker-api).
+        type: bool
+        default: true
+        version_added: 1.8.0
+
+    verbose_output:
+        description:
+            - Toggle to (not) include all available inspection metadata.
+            - Note that all top-level keys will be transformed to the format C(docker_xxx).
+              For example, C(HostConfig) is converted to C(docker_hostconfig).
+            - If this is C(false), these values can only be used during I(constructed), I(groups), and I(keyed_groups).
+            - The C(docker) inventory script always added these variables, so for compatibility set this to C(true).
+        type: bool
+        default: false
+
+    default_ip:
+        description:
+            - The IP address to assign to ansible_host when the container's SSH port is mapped to interface
+              '0.0.0.0'.
+            - Only used if I(connection_type) is C(ssh).
+        type: str
+        default: 127.0.0.1
+
+    private_ssh_port:
+        description:
+            - The port containers use for SSH.
+            - Only used if I(connection_type) is C(ssh).
+        type: int
+        default: 22
+
+    add_legacy_groups:
+        description:
+            - "Add the same groups as the C(docker) inventory script does. These are the following:"
+            - "C(<container id>): contains the container of this ID."
+            - "C(<container name>): contains the container that has this name."
+            - "C(<container short id>): contains the containers that have this short ID (first 13 letters of ID)."
+            - "C(image_<image name>): contains the containers that have the image C(<image name>)."
+            - "C(stack_<stack name>): contains the containers that belong to the stack C(<stack name>)."
+            - "C(service_<service name>): contains the containers that belong to the service C(<service name>)"
+            - "C(<docker_host>): contains the containers which belong to the Docker daemon I(docker_host).
+              Useful if you run this plugin against multiple Docker daemons."
+            - "C(running): contains all containers that are running."
+            - "C(stopped): contains all containers that are not running."
+            - If this is not set to C(true), you should use keyed groups to add the containers to groups.
+              See the examples for how to do that.
+        type: bool
+        default: false
+'''
+
+EXAMPLES = '''
+# Minimal example using local Docker daemon
+plugin: community.docker.docker_containers
+docker_host: unix://var/run/docker.sock
+
+# Minimal example using remote Docker daemon
+plugin: community.docker.docker_containers
+docker_host: tcp://my-docker-host:2375
+
+# Example using remote Docker daemon with unverified TLS
+plugin: community.docker.docker_containers
+docker_host: tcp://my-docker-host:2376
+tls: true
+
+# Example using remote Docker daemon with verified TLS and client certificate verification
+plugin: community.docker.docker_containers
+docker_host: tcp://my-docker-host:2376
+validate_certs: true
+ca_cert: /somewhere/ca.pem
+client_key: /somewhere/key.pem
+client_cert: /somewhere/cert.pem
+
+# Example using constructed features to create groups
+plugin: community.docker.docker_containers
+docker_host: tcp://my-docker-host:2375
+strict: false
+keyed_groups:
+  # Add containers with primary network foo to a network_foo group
+  - prefix: network
+    key: 'docker_hostconfig.NetworkMode'
+  # Add Linux hosts to an os_linux group
+  - prefix: os
+    key: docker_platform
+
+# Example using SSH connection with an explicit fallback for when port 22 has not been
+# exported: use container name as ansible_ssh_host and 22 as ansible_ssh_port
+plugin: community.docker.docker_containers
+connection_type: ssh
+compose:
+  ansible_ssh_host: ansible_ssh_host | default(docker_name[1:], true)
+  ansible_ssh_port: ansible_ssh_port | default(22, true)
+'''
+
+import re
+
+from ansible.errors import AnsibleError
+from ansible.module_utils.common.text.converters import to_native
+from ansible.plugins.inventory import BaseInventoryPlugin, Constructable
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    RequestException,
+    DOCKER_COMMON_ARGS_VARS,
+)
+from ansible_collections.community.docker.plugins.plugin_utils.common import (
+    AnsibleDockerClient,
+)
+
+try:
+    from docker.errors import DockerException, APIError
+except Exception:
+    # missing Docker SDK for Python handled in ansible_collections.community.docker.plugins.module_utils.common
+    pass
+
+MIN_DOCKER_PY = '1.7.0'
+MIN_DOCKER_API = None
+
+
+class InventoryModule(BaseInventoryPlugin, Constructable):
+    ''' Host inventory parser for ansible using Docker daemon as source. '''
+
+    NAME = 'community.docker.docker_containers'
+
+    def _slugify(self, value):
+        return 'docker_%s' % (re.sub(r'[^\w-]', '_', value).lower().lstrip('_'))
+
+    def _populate(self, client):
+        strict = self.get_option('strict')
+
+        ssh_port = self.get_option('private_ssh_port')
+        default_ip = self.get_option('default_ip')
+        hostname = self.get_option('docker_host')
+        verbose_output = self.get_option('verbose_output')
+        connection_type = self.get_option('connection_type')
+        add_legacy_groups = self.get_option('add_legacy_groups')
+
+        try:
+            containers = client.containers(all=True)
+        except APIError as exc:
+            raise AnsibleError("Error listing containers: %s" % to_native(exc))
+
+        if add_legacy_groups:
+            self.inventory.add_group('running')
+            self.inventory.add_group('stopped')
+
+        extra_facts = {}
+        if self.get_option('configure_docker_daemon'):
+            for option_name, var_name in DOCKER_COMMON_ARGS_VARS.items():
+                value = self.get_option(option_name)
+                if value is not None:
+                    extra_facts[var_name] = value
+
+        for container in containers:
+            id = container.get('Id')
+            short_id = id[:13]
+
+            try:
+                name = container.get('Names', list())[0].lstrip('/')
+                full_name = name
+            except IndexError:
+                name = short_id
+                full_name = id
+
+            self.inventory.add_host(name)
+            facts = dict(
+                docker_name=name,
+                docker_short_id=short_id
+            )
+            full_facts = dict()
+
+            try:
+                inspect = client.inspect_container(id)
+            except APIError as exc:
+                raise AnsibleError("Error inspecting container %s - %s" % (name, str(exc)))
+
+            state = inspect.get('State') or dict()
+            config = inspect.get('Config') or dict()
+            labels = config.get('Labels') or dict()
+
+            running = state.get('Running')
+
+            # Add container to groups
+            image_name = config.get('Image')
+            if image_name and add_legacy_groups:
+                self.inventory.add_group('image_{0}'.format(image_name))
+                self.inventory.add_host(name, group='image_{0}'.format(image_name))
+
+            stack_name = labels.get('com.docker.stack.namespace')
+            if stack_name:
+                full_facts['docker_stack'] = stack_name
+                if add_legacy_groups:
+                    self.inventory.add_group('stack_{0}'.format(stack_name))
+                    self.inventory.add_host(name, group='stack_{0}'.format(stack_name))
+
+            service_name = labels.get('com.docker.swarm.service.name')
+            if service_name:
+                full_facts['docker_service'] = service_name
+                if add_legacy_groups:
+                    self.inventory.add_group('service_{0}'.format(service_name))
+                    self.inventory.add_host(name, group='service_{0}'.format(service_name))
+
+            if connection_type == 'ssh':
+                # Figure out ssh IP and Port
+                try:
+                    # Lookup the public facing port Nat'ed to ssh port.
+                    port = client.port(container, ssh_port)[0]
+                except (IndexError, AttributeError, TypeError):
+                    port = dict()
+
+                try:
+                    ip = default_ip if port['HostIp'] == '0.0.0.0' else port['HostIp']
+                except KeyError:
+                    ip = ''
+
+                facts.update(dict(
+                    ansible_ssh_host=ip,
+                    ansible_ssh_port=port.get('HostPort', 0),
+                ))
+            elif connection_type == 'docker-cli':
+                facts.update(dict(
+                    ansible_host=full_name,
+                    ansible_connection='community.docker.docker',
+                ))
+            elif connection_type == 'docker-api':
+                facts.update(dict(
+                    ansible_host=full_name,
+                    ansible_connection='community.docker.docker_api',
+                ))
+                facts.update(extra_facts)
+
+            full_facts.update(facts)
+            for key, value in inspect.items():
+                fact_key = self._slugify(key)
+                full_facts[fact_key] = value
+
+            if verbose_output:
+                facts.update(full_facts)
+
+            for key, value in facts.items():
+                self.inventory.set_variable(name, key, value)
+
+            # Use constructed if applicable
+            # Composed variables
+            self._set_composite_vars(self.get_option('compose'), full_facts, name, strict=strict)
+            # Complex groups based on jinja2 conditionals, hosts that meet the conditional are added to group
+            self._add_host_to_composed_groups(self.get_option('groups'), full_facts, name, strict=strict)
+            # Create groups based on variable values and add the corresponding hosts to it
+            self._add_host_to_keyed_groups(self.get_option('keyed_groups'), full_facts, name, strict=strict)
+
+            # We need to do this last since we also add a group called `name`.
+            # When we do this before a set_variable() call, the variables are assigned
+            # to the group, and not to the host.
+            if add_legacy_groups:
+                self.inventory.add_group(id)
+                self.inventory.add_host(name, group=id)
+                self.inventory.add_group(name)
+                self.inventory.add_host(name, group=name)
+                self.inventory.add_group(short_id)
+                self.inventory.add_host(name, group=short_id)
+                self.inventory.add_group(hostname)
+                self.inventory.add_host(name, group=hostname)
+
+                if running is True:
+                    self.inventory.add_host(name, group='running')
+                else:
+                    self.inventory.add_host(name, group='stopped')
+
+    def verify_file(self, path):
+        """Return the possibly of a file being consumable by this plugin."""
+        return (
+            super(InventoryModule, self).verify_file(path) and
+            path.endswith(('docker.yaml', 'docker.yml')))
+
+    def _create_client(self):
+        return AnsibleDockerClient(self, min_docker_version=MIN_DOCKER_PY, min_docker_api_version=MIN_DOCKER_API)
+
+    def parse(self, inventory, loader, path, cache=True):
+        super(InventoryModule, self).parse(inventory, loader, path, cache)
+        self._read_config_data(path)
+        client = self._create_client()
+        try:
+            self._populate(client)
+        except DockerException as e:
+            raise AnsibleError(
+                'An unexpected docker error occurred: {0}'.format(e)
+            )
+        except RequestException as e:
+            raise AnsibleError(
+                'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(e)
+            )

collections/ansible_collections/community/docker/plugins/inventory/docker_machine.py

@@ -0,0 +1,274 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2019, Ximon Eighteen <ximon.eighteen@gmail.com>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
+    name: docker_machine
+    author: Ximon Eighteen (@ximon18)
+    short_description: Docker Machine inventory source
+    requirements:
+        - L(Docker Machine,https://docs.docker.com/machine/)
+    extends_documentation_fragment:
+        - constructed
+    description:
+        - Get inventory hosts from Docker Machine.
+        - Uses a YAML configuration file that ends with docker_machine.(yml|yaml).
+        - The plugin sets standard host variables C(ansible_host), C(ansible_port), C(ansible_user) and C(ansible_ssh_private_key).
+        - The plugin stores the Docker Machine 'env' output variables in I(dm_) prefixed host variables.
+
+    options:
+        plugin:
+            description: token that ensures this is a source file for the C(docker_machine) plugin.
+            required: yes
+            choices: ['docker_machine', 'community.docker.docker_machine']
+        daemon_env:
+            description:
+                - Whether docker daemon connection environment variables should be fetched, and how to behave if they cannot be fetched.
+                - With C(require) and C(require-silently), fetch them and skip any host for which they cannot be fetched.
+                  A warning will be issued for any skipped host if the choice is C(require).
+                - With C(optional) and C(optional-silently), fetch them and not skip hosts for which they cannot be fetched.
+                  A warning will be issued for hosts where they cannot be fetched if the choice is C(optional).
+                - With C(skip), do not attempt to fetch the docker daemon connection environment variables.
+                - If fetched successfully, the variables will be prefixed with I(dm_) and stored as host variables.
+            type: str
+            choices:
+                - require
+                - require-silently
+                - optional
+                - optional-silently
+                - skip
+            default: require
+        running_required:
+            description:
+                - When C(true), hosts which Docker Machine indicates are in a state other than C(running) will be skipped.
+            type: bool
+            default: yes
+        verbose_output:
+            description:
+                - When C(true), include all available nodes metadata (for exmaple C(Image), C(Region), C(Size)) as a JSON object
+                  named C(docker_machine_node_attributes).
+            type: bool
+            default: yes
+'''
+
+EXAMPLES = '''
+# Minimal example
+plugin: community.docker.docker_machine
+
+# Example using constructed features to create a group per Docker Machine driver
+# (https://docs.docker.com/machine/drivers/), for example:
+#   $ docker-machine create --driver digitalocean ... mymachine
+#   $ ansible-inventory -i ./path/to/docker-machine.yml --host=mymachine
+#   {
+#     ...
+#     "digitalocean": {
+#       "hosts": [
+#           "mymachine"
+#       ]
+#     ...
+#   }
+strict: no
+keyed_groups:
+  - separator: ''
+    key: docker_machine_node_attributes.DriverName
+
+# Example grouping hosts by Digital Machine tag
+strict: no
+keyed_groups:
+  - prefix: tag
+    key: 'dm_tags'
+
+# Example using compose to override the default SSH behaviour of asking the user to accept the remote host key
+compose:
+  ansible_ssh_common_args: '"-o StrictHostKeyChecking=accept-new"'
+'''
+
+from ansible.errors import AnsibleError
+from ansible.module_utils.common.text.converters import to_native
+from ansible.module_utils.common.text.converters import to_text
+from ansible.module_utils.common.process import get_bin_path
+from ansible.plugins.inventory import BaseInventoryPlugin, Constructable, Cacheable
+from ansible.utils.display import Display
+
+import json
+import re
+import subprocess
+
+display = Display()
+
+
+class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
+    ''' Host inventory parser for ansible using Docker machine as source. '''
+
+    NAME = 'community.docker.docker_machine'
+
+    DOCKER_MACHINE_PATH = None
+
+    def _run_command(self, args):
+        if not self.DOCKER_MACHINE_PATH:
+            try:
+                self.DOCKER_MACHINE_PATH = get_bin_path('docker-machine')
+            except ValueError as e:
+                raise AnsibleError(to_native(e))
+
+        command = [self.DOCKER_MACHINE_PATH]
+        command.extend(args)
+        display.debug('Executing command {0}'.format(command))
+        try:
+            result = subprocess.check_output(command)
+        except subprocess.CalledProcessError as e:
+            display.warning('Exception {0} caught while executing command {1}, this was the original exception: {2}'.format(type(e).__name__, command, e))
+            raise e
+
+        return to_text(result).strip()
+
+    def _get_docker_daemon_variables(self, machine_name):
+        '''
+        Capture settings from Docker Machine that would be needed to connect to the remote Docker daemon installed on
+        the Docker Machine remote host. Note: passing '--shell=sh' is a workaround for 'Error: Unknown shell'.
+        '''
+        try:
+            env_lines = self._run_command(['env', '--shell=sh', machine_name]).splitlines()
+        except subprocess.CalledProcessError:
+            # This can happen when the machine is created but provisioning is incomplete
+            return []
+
+        # example output of docker-machine env --shell=sh:
+        #   export DOCKER_TLS_VERIFY="1"
+        #   export DOCKER_HOST="tcp://134.209.204.160:2376"
+        #   export DOCKER_CERT_PATH="/root/.docker/machine/machines/routinator"
+        #   export DOCKER_MACHINE_NAME="routinator"
+        #   # Run this command to configure your shell:
+        #   # eval $(docker-machine env --shell=bash routinator)
+
+        # capture any of the DOCKER_xxx variables that were output and create Ansible host vars
+        # with the same name and value but with a dm_ name prefix.
+        vars = []
+        for line in env_lines:
+            match = re.search('(DOCKER_[^=]+)="([^"]+)"', line)
+            if match:
+                env_var_name = match.group(1)
+                env_var_value = match.group(2)
+                vars.append((env_var_name, env_var_value))
+
+        return vars
+
+    def _get_machine_names(self):
+        # Filter out machines that are not in the Running state as we probably can't do anything useful actions
+        # with them.
+        ls_command = ['ls', '-q']
+        if self.get_option('running_required'):
+            ls_command.extend(['--filter', 'state=Running'])
+
+        try:
+            ls_lines = self._run_command(ls_command)
+        except subprocess.CalledProcessError:
+            return []
+
+        return ls_lines.splitlines()
+
+    def _inspect_docker_machine_host(self, node):
+        try:
+            inspect_lines = self._run_command(['inspect', self.node])
+        except subprocess.CalledProcessError:
+            return None
+
+        return json.loads(inspect_lines)
+
+    def _ip_addr_docker_machine_host(self, node):
+        try:
+            ip_addr = self._run_command(['ip', self.node])
+        except subprocess.CalledProcessError:
+            return None
+
+        return ip_addr
+
+    def _should_skip_host(self, machine_name, env_var_tuples, daemon_env):
+        if not env_var_tuples:
+            warning_prefix = 'Unable to fetch Docker daemon env vars from Docker Machine for host {0}'.format(machine_name)
+            if daemon_env in ('require', 'require-silently'):
+                if daemon_env == 'require':
+                    display.warning('{0}: host will be skipped'.format(warning_prefix))
+                return True
+            else:  # 'optional', 'optional-silently'
+                if daemon_env == 'optional':
+                    display.warning('{0}: host will lack dm_DOCKER_xxx variables'.format(warning_prefix))
+        return False
+
+    def _populate(self):
+        daemon_env = self.get_option('daemon_env')
+        try:
+            for self.node in self._get_machine_names():
+                self.node_attrs = self._inspect_docker_machine_host(self.node)
+                if not self.node_attrs:
+                    continue
+
+                machine_name = self.node_attrs['Driver']['MachineName']
+
+                # query `docker-machine env` to obtain remote Docker daemon connection settings in the form of commands
+                # that could be used to set environment variables to influence a local Docker client:
+                if daemon_env == 'skip':
+                    env_var_tuples = []
+                else:
+                    env_var_tuples = self._get_docker_daemon_variables(machine_name)
+                    if self._should_skip_host(machine_name, env_var_tuples, daemon_env):
+                        continue
+
+                # add an entry in the inventory for this host
+                self.inventory.add_host(machine_name)
+
+                # check for valid ip address from inspect output, else explicitly use ip command to find host ip address
+                # this works around an issue seen with Google Compute Platform where the IP address was not available
+                # via the 'inspect' subcommand but was via the 'ip' subcomannd.
+                if self.node_attrs['Driver']['IPAddress']:
+                    ip_addr = self.node_attrs['Driver']['IPAddress']
+                else:
+                    ip_addr = self._ip_addr_docker_machine_host(self.node)
+
+                # set standard Ansible remote host connection settings to details captured from `docker-machine`
+                # see: https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html
+                self.inventory.set_variable(machine_name, 'ansible_host', ip_addr)
+                self.inventory.set_variable(machine_name, 'ansible_port', self.node_attrs['Driver']['SSHPort'])
+                self.inventory.set_variable(machine_name, 'ansible_user', self.node_attrs['Driver']['SSHUser'])
+                self.inventory.set_variable(machine_name, 'ansible_ssh_private_key_file', self.node_attrs['Driver']['SSHKeyPath'])
+
+                # set variables based on Docker Machine tags
+                tags = self.node_attrs['Driver'].get('Tags') or ''
+                self.inventory.set_variable(machine_name, 'dm_tags', tags)
+
+                # set variables based on Docker Machine env variables
+                for kv in env_var_tuples:
+                    self.inventory.set_variable(machine_name, 'dm_{0}'.format(kv[0]), kv[1])
+
+                if self.get_option('verbose_output'):
+                    self.inventory.set_variable(machine_name, 'docker_machine_node_attributes', self.node_attrs)
+
+                # Use constructed if applicable
+                strict = self.get_option('strict')
+
+                # Composed variables
+                self._set_composite_vars(self.get_option('compose'), self.node_attrs, machine_name, strict=strict)
+
+                # Complex groups based on jinja2 conditionals, hosts that meet the conditional are added to group
+                self._add_host_to_composed_groups(self.get_option('groups'), self.node_attrs, machine_name, strict=strict)
+
+                # Create groups based on variable values and add the corresponding hosts to it
+                self._add_host_to_keyed_groups(self.get_option('keyed_groups'), self.node_attrs, machine_name, strict=strict)
+
+        except Exception as e:
+            raise AnsibleError('Unable to fetch hosts from Docker Machine, this was the original exception: %s' %
+                               to_native(e), orig_exc=e)
+
+    def verify_file(self, path):
+        """Return the possibility of a file being consumable by this plugin."""
+        return (
+            super(InventoryModule, self).verify_file(path) and
+            path.endswith(('docker_machine.yaml', 'docker_machine.yml')))
+
+    def parse(self, inventory, loader, path, cache=True):
+        super(InventoryModule, self).parse(inventory, loader, path, cache)
+        self._read_config_data(path)
+        self._populate()

collections/ansible_collections/community/docker/plugins/inventory/docker_swarm.py

@@ -0,0 +1,262 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2018, Stefan Heitmueller <stefan.heitmueller@gmx.com>
+# Copyright (c) 2018 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+
+__metaclass__ = type
+
+DOCUMENTATION = '''
+    name: docker_swarm
+    author:
+      - Stefan Heitmüller (@morph027) <stefan.heitmueller@gmx.com>
+    short_description: Ansible dynamic inventory plugin for Docker swarm nodes.
+    requirements:
+        - python >= 2.7
+        - L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 1.10.0
+    extends_documentation_fragment:
+        - constructed
+    description:
+        - Reads inventories from the Docker swarm API.
+        - Uses a YAML configuration file docker_swarm.[yml|yaml].
+        - "The plugin returns following groups of swarm nodes:  I(all) - all hosts; I(workers) - all worker nodes;
+          I(managers) - all manager nodes; I(leader) - the swarm leader node;
+          I(nonleaders) - all nodes except the swarm leader."
+    options:
+        plugin:
+            description: The name of this plugin, it should always be set to C(community.docker.docker_swarm)
+                         for this plugin to recognize it as it's own.
+            type: str
+            required: true
+            choices: [ docker_swarm, community.docker.docker_swarm ]
+        docker_host:
+            description:
+                - Socket of a Docker swarm manager node (C(tcp), C(unix)).
+                - "Use C(unix://var/run/docker.sock) to connect via local socket."
+            type: str
+            required: true
+            aliases: [ docker_url ]
+        verbose_output:
+            description: Toggle to (not) include all available nodes metadata (for example C(Platform), C(Architecture), C(OS),
+                         C(EngineVersion))
+            type: bool
+            default: yes
+        tls:
+            description: Connect using TLS without verifying the authenticity of the Docker host server.
+            type: bool
+            default: no
+        validate_certs:
+            description: Toggle if connecting using TLS with or without verifying the authenticity of the Docker
+                         host server.
+            type: bool
+            default: no
+            aliases: [ tls_verify ]
+        client_key:
+            description: Path to the client's TLS key file.
+            type: path
+            aliases: [ tls_client_key, key_path ]
+        ca_cert:
+            description: Use a CA certificate when performing server verification by providing the path to a CA
+                         certificate file.
+            type: path
+            aliases: [ tls_ca_cert, cacert_path ]
+        client_cert:
+            description: Path to the client's TLS certificate file.
+            type: path
+            aliases: [ tls_client_cert, cert_path ]
+        tls_hostname:
+            description: When verifying the authenticity of the Docker host server, provide the expected name of
+                         the server.
+            type: str
+        ssl_version:
+            description: Provide a valid SSL version number. Default value determined by ssl.py module.
+            type: str
+        api_version:
+            description:
+                - The version of the Docker API running on the Docker Host.
+                - Defaults to the latest version of the API supported by docker-py.
+            type: str
+            aliases: [ docker_api_version ]
+        timeout:
+            description:
+                - The maximum amount of time in seconds to wait on a response from the API.
+                - If the value is not specified in the task, the value of environment variable C(DOCKER_TIMEOUT)
+                  will be used instead. If the environment variable is not set, the default value will be used.
+            type: int
+            default: 60
+            aliases: [ time_out ]
+        use_ssh_client:
+            description:
+                - For SSH transports, use the C(ssh) CLI tool instead of paramiko.
+                - Requires Docker SDK for Python 4.4.0 or newer.
+            type: bool
+            default: no
+            version_added: 1.5.0
+        include_host_uri:
+            description: Toggle to return the additional attribute C(ansible_host_uri) which contains the URI of the
+                         swarm leader in format of C(tcp://172.16.0.1:2376). This value may be used without additional
+                         modification as value of option I(docker_host) in Docker Swarm modules when connecting via API.
+                         The port always defaults to C(2376).
+            type: bool
+            default: no
+        include_host_uri_port:
+            description: Override the detected port number included in I(ansible_host_uri)
+            type: int
+'''
+
+EXAMPLES = '''
+# Minimal example using local docker
+plugin: community.docker.docker_swarm
+docker_host: unix://var/run/docker.sock
+
+# Minimal example using remote docker
+plugin: community.docker.docker_swarm
+docker_host: tcp://my-docker-host:2375
+
+# Example using remote docker with unverified TLS
+plugin: community.docker.docker_swarm
+docker_host: tcp://my-docker-host:2376
+tls: yes
+
+# Example using remote docker with verified TLS and client certificate verification
+plugin: community.docker.docker_swarm
+docker_host: tcp://my-docker-host:2376
+validate_certs: yes
+ca_cert: /somewhere/ca.pem
+client_key: /somewhere/key.pem
+client_cert: /somewhere/cert.pem
+
+# Example using constructed features to create groups and set ansible_host
+plugin: community.docker.docker_swarm
+docker_host: tcp://my-docker-host:2375
+strict: False
+keyed_groups:
+  # add for example x86_64 hosts to an arch_x86_64 group
+  - prefix: arch
+    key: 'Description.Platform.Architecture'
+  # add for example linux hosts to an os_linux group
+  - prefix: os
+    key: 'Description.Platform.OS'
+  # create a group per node label
+  # for exomple a node labeled w/ "production" ends up in group "label_production"
+  # hint: labels containing special characters will be converted to safe names
+  - key: 'Spec.Labels'
+    prefix: label
+'''
+
+from ansible.errors import AnsibleError
+from ansible.module_utils.common.text.converters import to_native
+from ansible_collections.community.docker.plugins.module_utils.common import update_tls_hostname, get_connect_params
+from ansible.plugins.inventory import BaseInventoryPlugin, Constructable
+from ansible.parsing.utils.addresses import parse_address
+
+try:
+    import docker
+    HAS_DOCKER = True
+except ImportError:
+    HAS_DOCKER = False
+
+
+class InventoryModule(BaseInventoryPlugin, Constructable):
+    ''' Host inventory parser for ansible using Docker swarm as source. '''
+
+    NAME = 'community.docker.docker_swarm'
+
+    def _fail(self, msg):
+        raise AnsibleError(msg)
+
+    def _populate(self):
+        raw_params = dict(
+            docker_host=self.get_option('docker_host'),
+            tls=self.get_option('tls'),
+            tls_verify=self.get_option('validate_certs'),
+            key_path=self.get_option('client_key'),
+            cacert_path=self.get_option('ca_cert'),
+            cert_path=self.get_option('client_cert'),
+            tls_hostname=self.get_option('tls_hostname'),
+            api_version=self.get_option('api_version'),
+            timeout=self.get_option('timeout'),
+            ssl_version=self.get_option('ssl_version'),
+            use_ssh_client=self.get_option('use_ssh_client'),
+            debug=None,
+        )
+        update_tls_hostname(raw_params)
+        connect_params = get_connect_params(raw_params, fail_function=self._fail)
+        self.client = docker.DockerClient(**connect_params)
+        self.inventory.add_group('all')
+        self.inventory.add_group('manager')
+        self.inventory.add_group('worker')
+        self.inventory.add_group('leader')
+        self.inventory.add_group('nonleaders')
+
+        if self.get_option('include_host_uri'):
+            if self.get_option('include_host_uri_port'):
+                host_uri_port = str(self.get_option('include_host_uri_port'))
+            elif self.get_option('tls') or self.get_option('validate_certs'):
+                host_uri_port = '2376'
+            else:
+                host_uri_port = '2375'
+
+        try:
+            self.nodes = self.client.nodes.list()
+            for self.node in self.nodes:
+                self.node_attrs = self.client.nodes.get(self.node.id).attrs
+                self.inventory.add_host(self.node_attrs['ID'])
+                self.inventory.add_host(self.node_attrs['ID'], group=self.node_attrs['Spec']['Role'])
+                self.inventory.set_variable(self.node_attrs['ID'], 'ansible_host',
+                                            self.node_attrs['Status']['Addr'])
+                if self.get_option('include_host_uri'):
+                    self.inventory.set_variable(self.node_attrs['ID'], 'ansible_host_uri',
+                                                'tcp://' + self.node_attrs['Status']['Addr'] + ':' + host_uri_port)
+                if self.get_option('verbose_output'):
+                    self.inventory.set_variable(self.node_attrs['ID'], 'docker_swarm_node_attributes', self.node_attrs)
+                if 'ManagerStatus' in self.node_attrs:
+                    if self.node_attrs['ManagerStatus'].get('Leader'):
+                        # This is workaround of bug in Docker when in some cases the Leader IP is 0.0.0.0
+                        # Check moby/moby#35437 for details
+                        swarm_leader_ip = parse_address(self.node_attrs['ManagerStatus']['Addr'])[0] or \
+                            self.node_attrs['Status']['Addr']
+                        if self.get_option('include_host_uri'):
+                            self.inventory.set_variable(self.node_attrs['ID'], 'ansible_host_uri',
+                                                        'tcp://' + swarm_leader_ip + ':' + host_uri_port)
+                        self.inventory.set_variable(self.node_attrs['ID'], 'ansible_host', swarm_leader_ip)
+                        self.inventory.add_host(self.node_attrs['ID'], group='leader')
+                    else:
+                        self.inventory.add_host(self.node_attrs['ID'], group='nonleaders')
+                else:
+                    self.inventory.add_host(self.node_attrs['ID'], group='nonleaders')
+                # Use constructed if applicable
+                strict = self.get_option('strict')
+                # Composed variables
+                self._set_composite_vars(self.get_option('compose'),
+                                         self.node_attrs,
+                                         self.node_attrs['ID'],
+                                         strict=strict)
+                # Complex groups based on jinja2 conditionals, hosts that meet the conditional are added to group
+                self._add_host_to_composed_groups(self.get_option('groups'),
+                                                  self.node_attrs,
+                                                  self.node_attrs['ID'],
+                                                  strict=strict)
+                # Create groups based on variable values and add the corresponding hosts to it
+                self._add_host_to_keyed_groups(self.get_option('keyed_groups'),
+                                               self.node_attrs,
+                                               self.node_attrs['ID'],
+                                               strict=strict)
+        except Exception as e:
+            raise AnsibleError('Unable to fetch hosts from Docker swarm API, this was the original exception: %s' %
+                               to_native(e))
+
+    def verify_file(self, path):
+        """Return the possibly of a file being consumable by this plugin."""
+        return (
+            super(InventoryModule, self).verify_file(path) and
+            path.endswith(('docker_swarm.yaml', 'docker_swarm.yml')))
+
+    def parse(self, inventory, loader, path, cache=True):
+        if not HAS_DOCKER:
+            raise AnsibleError('The Docker swarm dynamic inventory plugin requires the Docker SDK for Python: '
+                               'https://github.com/docker/docker-py.')
+        super(InventoryModule, self).parse(inventory, loader, path, cache)
+        self._read_config_data(path)
+        self._populate()

collections/ansible_collections/community/docker/plugins/module_utils/_version.py

@@ -0,0 +1,343 @@
+# Vendored copy of distutils/version.py from CPython 3.9.5
+#
+# Implements multiple version numbering conventions for the
+# Python Module Distribution Utilities.
+#
+# PSF License (see PSF-license.txt or https://opensource.org/licenses/Python-2.0)
+#
+
+"""Provides classes to represent module version numbers (one class for
+each style of version numbering).  There are currently two such classes
+implemented: StrictVersion and LooseVersion.
+
+Every version number class implements the following interface:
+  * the 'parse' method takes a string and parses it to some internal
+    representation; if the string is an invalid version number,
+    'parse' raises a ValueError exception
+  * the class constructor takes an optional string argument which,
+    if supplied, is passed to 'parse'
+  * __str__ reconstructs the string that was passed to 'parse' (or
+    an equivalent string -- ie. one that will generate an equivalent
+    version number instance)
+  * __repr__ generates Python code to recreate the version number instance
+  * _cmp compares the current instance with either another instance
+    of the same class or a string (which will be parsed to an instance
+    of the same class, thus must follow the same rules)
+"""
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import re
+
+try:
+    RE_FLAGS = re.VERBOSE | re.ASCII
+except AttributeError:
+    RE_FLAGS = re.VERBOSE
+
+
+class Version:
+    """Abstract base class for version numbering classes.  Just provides
+    constructor (__init__) and reproducer (__repr__), because those
+    seem to be the same for all version numbering classes; and route
+    rich comparisons to _cmp.
+    """
+
+    def __init__(self, vstring=None):
+        if vstring:
+            self.parse(vstring)
+
+    def __repr__(self):
+        return "%s ('%s')" % (self.__class__.__name__, str(self))
+
+    def __eq__(self, other):
+        c = self._cmp(other)
+        if c is NotImplemented:
+            return c
+        return c == 0
+
+    def __lt__(self, other):
+        c = self._cmp(other)
+        if c is NotImplemented:
+            return c
+        return c < 0
+
+    def __le__(self, other):
+        c = self._cmp(other)
+        if c is NotImplemented:
+            return c
+        return c <= 0
+
+    def __gt__(self, other):
+        c = self._cmp(other)
+        if c is NotImplemented:
+            return c
+        return c > 0
+
+    def __ge__(self, other):
+        c = self._cmp(other)
+        if c is NotImplemented:
+            return c
+        return c >= 0
+
+
+# Interface for version-number classes -- must be implemented
+# by the following classes (the concrete ones -- Version should
+# be treated as an abstract class).
+#    __init__ (string) - create and take same action as 'parse'
+#                        (string parameter is optional)
+#    parse (string)    - convert a string representation to whatever
+#                        internal representation is appropriate for
+#                        this style of version numbering
+#    __str__ (self)    - convert back to a string; should be very similar
+#                        (if not identical to) the string supplied to parse
+#    __repr__ (self)   - generate Python code to recreate
+#                        the instance
+#    _cmp (self, other) - compare two version numbers ('other' may
+#                        be an unparsed version string, or another
+#                        instance of your version class)
+
+
+class StrictVersion(Version):
+    """Version numbering for anal retentives and software idealists.
+    Implements the standard interface for version number classes as
+    described above.  A version number consists of two or three
+    dot-separated numeric components, with an optional "pre-release" tag
+    on the end.  The pre-release tag consists of the letter 'a' or 'b'
+    followed by a number.  If the numeric components of two version
+    numbers are equal, then one with a pre-release tag will always
+    be deemed earlier (lesser) than one without.
+
+    The following are valid version numbers (shown in the order that
+    would be obtained by sorting according to the supplied cmp function):
+
+        0.4       0.4.0  (these two are equivalent)
+        0.4.1
+        0.5a1
+        0.5b3
+        0.5
+        0.9.6
+        1.0
+        1.0.4a3
+        1.0.4b1
+        1.0.4
+
+    The following are examples of invalid version numbers:
+
+        1
+        2.7.2.2
+        1.3.a4
+        1.3pl1
+        1.3c4
+
+    The rationale for this version numbering system will be explained
+    in the distutils documentation.
+    """
+
+    version_re = re.compile(r'^(\d+) \. (\d+) (\. (\d+))? ([ab](\d+))?$',
+                            RE_FLAGS)
+
+    def parse(self, vstring):
+        match = self.version_re.match(vstring)
+        if not match:
+            raise ValueError("invalid version number '%s'" % vstring)
+
+        (major, minor, patch, prerelease, prerelease_num) = \
+            match.group(1, 2, 4, 5, 6)
+
+        if patch:
+            self.version = tuple(map(int, [major, minor, patch]))
+        else:
+            self.version = tuple(map(int, [major, minor])) + (0,)
+
+        if prerelease:
+            self.prerelease = (prerelease[0], int(prerelease_num))
+        else:
+            self.prerelease = None
+
+    def __str__(self):
+        if self.version[2] == 0:
+            vstring = '.'.join(map(str, self.version[0:2]))
+        else:
+            vstring = '.'.join(map(str, self.version))
+
+        if self.prerelease:
+            vstring = vstring + self.prerelease[0] + str(self.prerelease[1])
+
+        return vstring
+
+    def _cmp(self, other):
+        if isinstance(other, str):
+            other = StrictVersion(other)
+        elif not isinstance(other, StrictVersion):
+            return NotImplemented
+
+        if self.version != other.version:
+            # numeric versions don't match
+            # prerelease stuff doesn't matter
+            if self.version < other.version:
+                return -1
+            else:
+                return 1
+
+        # have to compare prerelease
+        # case 1: neither has prerelease; they're equal
+        # case 2: self has prerelease, other doesn't; other is greater
+        # case 3: self doesn't have prerelease, other does: self is greater
+        # case 4: both have prerelease: must compare them!
+
+        if (not self.prerelease and not other.prerelease):
+            return 0
+        elif (self.prerelease and not other.prerelease):
+            return -1
+        elif (not self.prerelease and other.prerelease):
+            return 1
+        elif (self.prerelease and other.prerelease):
+            if self.prerelease == other.prerelease:
+                return 0
+            elif self.prerelease < other.prerelease:
+                return -1
+            else:
+                return 1
+        else:
+            raise AssertionError("never get here")
+
+# end class StrictVersion
+
+# The rules according to Greg Stein:
+# 1) a version number has 1 or more numbers separated by a period or by
+#    sequences of letters. If only periods, then these are compared
+#    left-to-right to determine an ordering.
+# 2) sequences of letters are part of the tuple for comparison and are
+#    compared lexicographically
+# 3) recognize the numeric components may have leading zeroes
+#
+# The LooseVersion class below implements these rules: a version number
+# string is split up into a tuple of integer and string components, and
+# comparison is a simple tuple comparison.  This means that version
+# numbers behave in a predictable and obvious way, but a way that might
+# not necessarily be how people *want* version numbers to behave.  There
+# wouldn't be a problem if people could stick to purely numeric version
+# numbers: just split on period and compare the numbers as tuples.
+# However, people insist on putting letters into their version numbers;
+# the most common purpose seems to be:
+#   - indicating a "pre-release" version
+#     ('alpha', 'beta', 'a', 'b', 'pre', 'p')
+#   - indicating a post-release patch ('p', 'pl', 'patch')
+# but of course this can't cover all version number schemes, and there's
+# no way to know what a programmer means without asking him.
+#
+# The problem is what to do with letters (and other non-numeric
+# characters) in a version number.  The current implementation does the
+# obvious and predictable thing: keep them as strings and compare
+# lexically within a tuple comparison.  This has the desired effect if
+# an appended letter sequence implies something "post-release":
+# eg. "0.99" < "0.99pl14" < "1.0", and "5.001" < "5.001m" < "5.002".
+#
+# However, if letters in a version number imply a pre-release version,
+# the "obvious" thing isn't correct.  Eg. you would expect that
+# "1.5.1" < "1.5.2a2" < "1.5.2", but under the tuple/lexical comparison
+# implemented here, this just isn't so.
+#
+# Two possible solutions come to mind.  The first is to tie the
+# comparison algorithm to a particular set of semantic rules, as has
+# been done in the StrictVersion class above.  This works great as long
+# as everyone can go along with bondage and discipline.  Hopefully a
+# (large) subset of Python module programmers will agree that the
+# particular flavour of bondage and discipline provided by StrictVersion
+# provides enough benefit to be worth using, and will submit their
+# version numbering scheme to its domination.  The free-thinking
+# anarchists in the lot will never give in, though, and something needs
+# to be done to accommodate them.
+#
+# Perhaps a "moderately strict" version class could be implemented that
+# lets almost anything slide (syntactically), and makes some heuristic
+# assumptions about non-digits in version number strings.  This could
+# sink into special-case-hell, though; if I was as talented and
+# idiosyncratic as Larry Wall, I'd go ahead and implement a class that
+# somehow knows that "1.2.1" < "1.2.2a2" < "1.2.2" < "1.2.2pl3", and is
+# just as happy dealing with things like "2g6" and "1.13++".  I don't
+# think I'm smart enough to do it right though.
+#
+# In any case, I've coded the test suite for this module (see
+# ../test/test_version.py) specifically to fail on things like comparing
+# "1.2a2" and "1.2".  That's not because the *code* is doing anything
+# wrong, it's because the simple, obvious design doesn't match my
+# complicated, hairy expectations for real-world version numbers.  It
+# would be a snap to fix the test suite to say, "Yep, LooseVersion does
+# the Right Thing" (ie. the code matches the conception).  But I'd rather
+# have a conception that matches common notions about version numbers.
+
+
+class LooseVersion(Version):
+    """Version numbering for anarchists and software realists.
+    Implements the standard interface for version number classes as
+    described above.  A version number consists of a series of numbers,
+    separated by either periods or strings of letters.  When comparing
+    version numbers, the numeric components will be compared
+    numerically, and the alphabetic components lexically.  The following
+    are all valid version numbers, in no particular order:
+
+        1.5.1
+        1.5.2b2
+        161
+        3.10a
+        8.02
+        3.4j
+        1996.07.12
+        3.2.pl0
+        3.1.1.6
+        2g6
+        11g
+        0.960923
+        2.2beta29
+        1.13++
+        5.5.kw
+        2.0b1pl0
+
+    In fact, there is no such thing as an invalid version number under
+    this scheme; the rules for comparison are simple and predictable,
+    but may not always give the results you want (for some definition
+    of "want").
+    """
+
+    component_re = re.compile(r'(\d+ | [a-z]+ | \.)', re.VERBOSE)
+
+    def __init__(self, vstring=None):
+        if vstring:
+            self.parse(vstring)
+
+    def parse(self, vstring):
+        # I've given up on thinking I can reconstruct the version string
+        # from the parsed tuple -- so I just store the string here for
+        # use by __str__
+        self.vstring = vstring
+        components = [x for x in self.component_re.split(vstring) if x and x != '.']
+        for i, obj in enumerate(components):
+            try:
+                components[i] = int(obj)
+            except ValueError:
+                pass
+
+        self.version = components
+
+    def __str__(self):
+        return self.vstring
+
+    def __repr__(self):
+        return "LooseVersion ('%s')" % str(self)
+
+    def _cmp(self, other):
+        if isinstance(other, str):
+            other = LooseVersion(other)
+        elif not isinstance(other, LooseVersion):
+            return NotImplemented
+
+        if self.version == other.version:
+            return 0
+        if self.version < other.version:
+            return -1
+        if self.version > other.version:
+            return 1
+
+# end class LooseVersion

collections/ansible_collections/community/docker/plugins/module_utils/socket_handler.py

@@ -0,0 +1,232 @@
+# Copyright (c) 2019-2021, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+import os
+import os.path
+import socket as pysocket
+
+from ansible.module_utils.basic import missing_required_lib
+from ansible.module_utils.six import PY3
+
+try:
+    from docker.utils import socket as docker_socket
+    import struct
+except Exception:
+    # missing Docker SDK for Python handled in ansible_collections.community.docker.plugins.module_utils.common
+    pass
+
+from ansible_collections.community.docker.plugins.module_utils.socket_helper import (
+    make_unblocking,
+    shutdown_writing,
+    write_to_socket,
+)
+
+
+PARAMIKO_POLL_TIMEOUT = 0.01  # 10 milliseconds
+
+
+class DockerSocketHandlerBase(object):
+    def __init__(self, sock, selectors, log=None):
+        make_unblocking(sock)
+
+        self._selectors = selectors
+        if log is not None:
+            self._log = log
+        else:
+            self._log = lambda msg: True
+        self._paramiko_read_workaround = hasattr(sock, 'send_ready') and 'paramiko' in str(type(sock))
+
+        self._sock = sock
+        self._block_done_callback = None
+        self._block_buffer = []
+        self._eof = False
+        self._read_buffer = b''
+        self._write_buffer = b''
+        self._end_of_writing = False
+
+        self._current_stream = None
+        self._current_missing = 0
+        self._current_buffer = b''
+
+        self._selector = self._selectors.DefaultSelector()
+        self._selector.register(self._sock, self._selectors.EVENT_READ)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, type, value, tb):
+        self._selector.close()
+
+    def set_block_done_callback(self, block_done_callback):
+        self._block_done_callback = block_done_callback
+        if self._block_done_callback is not None:
+            while self._block_buffer:
+                elt = self._block_buffer.remove(0)
+                self._block_done_callback(*elt)
+
+    def _add_block(self, stream_id, data):
+        if self._block_done_callback is not None:
+            self._block_done_callback(stream_id, data)
+        else:
+            self._block_buffer.append((stream_id, data))
+
+    def _read(self):
+        if self._eof:
+            return
+        if hasattr(self._sock, 'recv'):
+            try:
+                data = self._sock.recv(262144)
+            except Exception as e:
+                # After calling self._sock.shutdown(), OpenSSL's/urllib3's
+                # WrappedSocket seems to eventually raise ZeroReturnError in
+                # case of EOF
+                if 'OpenSSL.SSL.ZeroReturnError' in str(type(e)):
+                    self._eof = True
+                    return
+                else:
+                    raise
+        elif PY3 and isinstance(self._sock, getattr(pysocket, 'SocketIO')):
+            data = self._sock.read()
+        else:
+            data = os.read(self._sock.fileno())
+        if data is None:
+            # no data available
+            return
+        self._log('read {0} bytes'.format(len(data)))
+        if len(data) == 0:
+            # Stream EOF
+            self._eof = True
+            return
+        self._read_buffer += data
+        while len(self._read_buffer) > 0:
+            if self._current_missing > 0:
+                n = min(len(self._read_buffer), self._current_missing)
+                self._current_buffer += self._read_buffer[:n]
+                self._read_buffer = self._read_buffer[n:]
+                self._current_missing -= n
+                if self._current_missing == 0:
+                    self._add_block(self._current_stream, self._current_buffer)
+                    self._current_buffer = b''
+            if len(self._read_buffer) < 8:
+                break
+            self._current_stream, self._current_missing = struct.unpack('>BxxxL', self._read_buffer[:8])
+            self._read_buffer = self._read_buffer[8:]
+            if self._current_missing < 0:
+                # Stream EOF (as reported by docker daemon)
+                self._eof = True
+                break
+
+    def _handle_end_of_writing(self):
+        if self._end_of_writing and len(self._write_buffer) == 0:
+            self._end_of_writing = False
+            self._log('Shutting socket down for writing')
+            shutdown_writing(self._sock, self._log)
+
+    def _write(self):
+        if len(self._write_buffer) > 0:
+            written = write_to_socket(self._sock, self._write_buffer)
+            self._write_buffer = self._write_buffer[written:]
+            self._log('wrote {0} bytes, {1} are left'.format(written, len(self._write_buffer)))
+            if len(self._write_buffer) > 0:
+                self._selector.modify(self._sock, self._selectors.EVENT_READ | self._selectors.EVENT_WRITE)
+            else:
+                self._selector.modify(self._sock, self._selectors.EVENT_READ)
+            self._handle_end_of_writing()
+
+    def select(self, timeout=None, _internal_recursion=False):
+        if not _internal_recursion and self._paramiko_read_workaround and len(self._write_buffer) > 0:
+            # When the SSH transport is used, docker-py internally uses Paramiko, whose
+            # Channel object supports select(), but only for reading
+            # (https://github.com/paramiko/paramiko/issues/695).
+            if self._sock.send_ready():
+                self._write()
+                return True
+            while timeout is None or timeout > PARAMIKO_POLL_TIMEOUT:
+                result = self.select(PARAMIKO_POLL_TIMEOUT, _internal_recursion=True)
+                if self._sock.send_ready():
+                    self._read()
+                    result += 1
+                if result > 0:
+                    return True
+                if timeout is not None:
+                    timeout -= PARAMIKO_POLL_TIMEOUT
+        self._log('select... ({0})'.format(timeout))
+        events = self._selector.select(timeout)
+        for key, event in events:
+            if key.fileobj == self._sock:
+                self._log(
+                    'select event read:{0} write:{1}'.format(
+                        event & self._selectors.EVENT_READ != 0,
+                        event & self._selectors.EVENT_WRITE != 0))
+                if event & self._selectors.EVENT_READ != 0:
+                    self._read()
+                if event & self._selectors.EVENT_WRITE != 0:
+                    self._write()
+        result = len(events)
+        if self._paramiko_read_workaround and len(self._write_buffer) > 0:
+            if self._sock.send_ready():
+                self._write()
+                result += 1
+        return result > 0
+
+    def is_eof(self):
+        return self._eof
+
+    def end_of_writing(self):
+        self._end_of_writing = True
+        self._handle_end_of_writing()
+
+    def consume(self):
+        stdout = []
+        stderr = []
+
+        def append_block(stream_id, data):
+            if stream_id == docker_socket.STDOUT:
+                stdout.append(data)
+            elif stream_id == docker_socket.STDERR:
+                stderr.append(data)
+            else:
+                raise ValueError('{0} is not a valid stream ID'.format(stream_id))
+
+        self.end_of_writing()
+
+        self.set_block_done_callback(append_block)
+        while not self._eof:
+            self.select()
+        return b''.join(stdout), b''.join(stderr)
+
+    def write(self, str):
+        self._write_buffer += str
+        if len(self._write_buffer) == len(str):
+            self._write()
+
+
+class DockerSocketHandlerModule(DockerSocketHandlerBase):
+    def __init__(self, sock, module, selectors):
+        super(DockerSocketHandlerModule, self).__init__(sock, selectors, module.debug)
+
+
+def find_selectors(module):
+    try:
+        # ansible-base 2.10+ has selectors a compat version of selectors, which a bundled fallback:
+        from ansible.module_utils.compat import selectors
+        return selectors
+    except ImportError:
+        pass
+    try:
+        # Python 3.4+
+        import selectors
+        return selectors
+    except ImportError:
+        pass
+    try:
+        # backport package installed in the system
+        import selectors2
+        return selectors2
+    except ImportError:
+        pass
+    module.fail_json(msg=missing_required_lib('selectors2', reason='for handling stdin'))

collections/ansible_collections/community/docker/plugins/module_utils/socket_helper.py

@@ -0,0 +1,53 @@
+# Copyright (c) 2019-2021, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+import fcntl
+import os
+import os.path
+import socket as pysocket
+
+from ansible.module_utils.six import PY3
+
+
+def make_unblocking(sock):
+    if hasattr(sock, '_sock'):
+        sock._sock.setblocking(0)
+    elif hasattr(sock, 'setblocking'):
+        sock.setblocking(0)
+    else:
+        fcntl.fcntl(sock.fileno(), fcntl.F_SETFL, fcntl.fcntl(sock.fileno(), fcntl.F_GETFL) | os.O_NONBLOCK)
+
+
+def _empty_writer(msg):
+    pass
+
+
+def shutdown_writing(sock, log=_empty_writer):
+    if hasattr(sock, 'shutdown_write'):
+        sock.shutdown_write()
+    elif hasattr(sock, 'shutdown'):
+        try:
+            sock.shutdown(pysocket.SHUT_WR)
+        except TypeError as e:
+            # probably: "TypeError: shutdown() takes 1 positional argument but 2 were given"
+            log('Shutting down for writing not possible; trying shutdown instead: {0}'.format(e))
+            sock.shutdown()
+    elif PY3 and isinstance(sock, getattr(pysocket, 'SocketIO')):
+        sock._sock.shutdown(pysocket.SHUT_WR)
+    else:
+        log('No idea how to signal end of writing')
+
+
+def write_to_socket(sock, data):
+    if hasattr(sock, '_send_until_done'):
+        # WrappedSocket (urllib3/contrib/pyopenssl) doesn't have `send`, but
+        # only `sendall`, which uses `_send_until_done` under the hood.
+        return sock._send_until_done(data)
+    elif hasattr(sock, 'send'):
+        return sock.send(data)
+    else:
+        return os.write(sock.fileno(), data)

collections/ansible_collections/community/docker/plugins/module_utils/swarm.py

@@ -0,0 +1,280 @@
+# (c) 2019 Piotr Wojciechowski (@wojciechowskipiotr) <piotr@it-playground.pl>
+# (c) Thierry Bouvet (@tbouvet)
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+import json
+from time import sleep
+
+try:
+    from docker.errors import APIError, NotFound
+except ImportError:
+    # missing Docker SDK for Python handled in ansible.module_utils.docker.common
+    pass
+
+from ansible.module_utils.common.text.converters import to_native
+
+from ansible_collections.community.docker.plugins.module_utils.version import LooseVersion
+
+from ansible_collections.community.docker.plugins.module_utils.common import AnsibleDockerClient
+
+
+class AnsibleDockerSwarmClient(AnsibleDockerClient):
+
+    def __init__(self, **kwargs):
+        super(AnsibleDockerSwarmClient, self).__init__(**kwargs)
+
+    def get_swarm_node_id(self):
+        """
+        Get the 'NodeID' of the Swarm node or 'None' if host is not in Swarm. It returns the NodeID
+        of Docker host the module is executed on
+        :return:
+            NodeID of host or 'None' if not part of Swarm
+        """
+
+        try:
+            info = self.info()
+        except APIError as exc:
+            self.fail("Failed to get node information for %s" % to_native(exc))
+
+        if info:
+            json_str = json.dumps(info, ensure_ascii=False)
+            swarm_info = json.loads(json_str)
+            if swarm_info['Swarm']['NodeID']:
+                return swarm_info['Swarm']['NodeID']
+        return None
+
+    def check_if_swarm_node(self, node_id=None):
+        """
+        Checking if host is part of Docker Swarm. If 'node_id' is not provided it reads the Docker host
+        system information looking if specific key in output exists. If 'node_id' is provided then it tries to
+        read node information assuming it is run on Swarm manager. The get_node_inspect() method handles exception if
+        it is not executed on Swarm manager
+
+        :param node_id: Node identifier
+        :return:
+            bool: True if node is part of Swarm, False otherwise
+        """
+
+        if node_id is None:
+            try:
+                info = self.info()
+            except APIError:
+                self.fail("Failed to get host information.")
+
+            if info:
+                json_str = json.dumps(info, ensure_ascii=False)
+                swarm_info = json.loads(json_str)
+                if swarm_info['Swarm']['NodeID']:
+                    return True
+                if swarm_info['Swarm']['LocalNodeState'] in ('active', 'pending', 'locked'):
+                    return True
+            return False
+        else:
+            try:
+                node_info = self.get_node_inspect(node_id=node_id)
+            except APIError:
+                return
+
+            if node_info['ID'] is not None:
+                return True
+            return False
+
+    def check_if_swarm_manager(self):
+        """
+        Checks if node role is set as Manager in Swarm. The node is the docker host on which module action
+        is performed. The inspect_swarm() will fail if node is not a manager
+
+        :return: True if node is Swarm Manager, False otherwise
+        """
+
+        try:
+            self.inspect_swarm()
+            return True
+        except APIError:
+            return False
+
+    def fail_task_if_not_swarm_manager(self):
+        """
+        If host is not a swarm manager then Ansible task on this host should end with 'failed' state
+        """
+        if not self.check_if_swarm_manager():
+            self.fail("Error running docker swarm module: must run on swarm manager node")
+
+    def check_if_swarm_worker(self):
+        """
+        Checks if node role is set as Worker in Swarm. The node is the docker host on which module action
+        is performed. Will fail if run on host that is not part of Swarm via check_if_swarm_node()
+
+        :return: True if node is Swarm Worker, False otherwise
+        """
+
+        if self.check_if_swarm_node() and not self.check_if_swarm_manager():
+            return True
+        return False
+
+    def check_if_swarm_node_is_down(self, node_id=None, repeat_check=1):
+        """
+        Checks if node status on Swarm manager is 'down'. If node_id is provided it query manager about
+        node specified in parameter, otherwise it query manager itself. If run on Swarm Worker node or
+        host that is not part of Swarm it will fail the playbook
+
+        :param repeat_check: number of check attempts with 5 seconds delay between them, by default check only once
+        :param node_id: node ID or name, if None then method will try to get node_id of host module run on
+        :return:
+            True if node is part of swarm but its state is down, False otherwise
+        """
+
+        if repeat_check < 1:
+            repeat_check = 1
+
+        if node_id is None:
+            node_id = self.get_swarm_node_id()
+
+        for retry in range(0, repeat_check):
+            if retry > 0:
+                sleep(5)
+            node_info = self.get_node_inspect(node_id=node_id)
+            if node_info['Status']['State'] == 'down':
+                return True
+        return False
+
+    def get_node_inspect(self, node_id=None, skip_missing=False):
+        """
+        Returns Swarm node info as in 'docker node inspect' command about single node
+
+        :param skip_missing: if True then function will return None instead of failing the task
+        :param node_id: node ID or name, if None then method will try to get node_id of host module run on
+        :return:
+            Single node information structure
+        """
+
+        if node_id is None:
+            node_id = self.get_swarm_node_id()
+
+        if node_id is None:
+            self.fail("Failed to get node information.")
+
+        try:
+            node_info = self.inspect_node(node_id=node_id)
+        except APIError as exc:
+            if exc.status_code == 503:
+                self.fail("Cannot inspect node: To inspect node execute module on Swarm Manager")
+            if exc.status_code == 404:
+                if skip_missing:
+                    return None
+            self.fail("Error while reading from Swarm manager: %s" % to_native(exc))
+        except Exception as exc:
+            self.fail("Error inspecting swarm node: %s" % exc)
+
+        json_str = json.dumps(node_info, ensure_ascii=False)
+        node_info = json.loads(json_str)
+
+        if 'ManagerStatus' in node_info:
+            if node_info['ManagerStatus'].get('Leader'):
+                # This is workaround of bug in Docker when in some cases the Leader IP is 0.0.0.0
+                # Check moby/moby#35437 for details
+                count_colons = node_info['ManagerStatus']['Addr'].count(":")
+                if count_colons == 1:
+                    swarm_leader_ip = node_info['ManagerStatus']['Addr'].split(":", 1)[0] or node_info['Status']['Addr']
+                else:
+                    swarm_leader_ip = node_info['Status']['Addr']
+                node_info['Status']['Addr'] = swarm_leader_ip
+        return node_info
+
+    def get_all_nodes_inspect(self):
+        """
+        Returns Swarm node info as in 'docker node inspect' command about all registered nodes
+
+        :return:
+            Structure with information about all nodes
+        """
+        try:
+            node_info = self.nodes()
+        except APIError as exc:
+            if exc.status_code == 503:
+                self.fail("Cannot inspect node: To inspect node execute module on Swarm Manager")
+            self.fail("Error while reading from Swarm manager: %s" % to_native(exc))
+        except Exception as exc:
+            self.fail("Error inspecting swarm node: %s" % exc)
+
+        json_str = json.dumps(node_info, ensure_ascii=False)
+        node_info = json.loads(json_str)
+        return node_info
+
+    def get_all_nodes_list(self, output='short'):
+        """
+        Returns list of nodes registered in Swarm
+
+        :param output: Defines format of returned data
+        :return:
+            If 'output' is 'short' then return data is list of nodes hostnames registered in Swarm,
+            if 'output' is 'long' then returns data is list of dict containing the attributes as in
+            output of command 'docker node ls'
+        """
+        nodes_list = []
+
+        nodes_inspect = self.get_all_nodes_inspect()
+        if nodes_inspect is None:
+            return None
+
+        if output == 'short':
+            for node in nodes_inspect:
+                nodes_list.append(node['Description']['Hostname'])
+        elif output == 'long':
+            for node in nodes_inspect:
+                node_property = {}
+
+                node_property.update({'ID': node['ID']})
+                node_property.update({'Hostname': node['Description']['Hostname']})
+                node_property.update({'Status': node['Status']['State']})
+                node_property.update({'Availability': node['Spec']['Availability']})
+                if 'ManagerStatus' in node:
+                    if node['ManagerStatus']['Leader'] is True:
+                        node_property.update({'Leader': True})
+                    node_property.update({'ManagerStatus': node['ManagerStatus']['Reachability']})
+                node_property.update({'EngineVersion': node['Description']['Engine']['EngineVersion']})
+
+                nodes_list.append(node_property)
+        else:
+            return None
+
+        return nodes_list
+
+    def get_node_name_by_id(self, nodeid):
+        return self.get_node_inspect(nodeid)['Description']['Hostname']
+
+    def get_unlock_key(self):
+        if self.docker_py_version < LooseVersion('2.7.0'):
+            return None
+        return super(AnsibleDockerSwarmClient, self).get_unlock_key()
+
+    def get_service_inspect(self, service_id, skip_missing=False):
+        """
+        Returns Swarm service info as in 'docker service inspect' command about single service
+
+        :param service_id: service ID or name
+        :param skip_missing: if True then function will return None instead of failing the task
+        :return:
+            Single service information structure
+        """
+        try:
+            service_info = self.inspect_service(service_id)
+        except NotFound as exc:
+            if skip_missing is False:
+                self.fail("Error while reading from Swarm manager: %s" % to_native(exc))
+            else:
+                return None
+        except APIError as exc:
+            if exc.status_code == 503:
+                self.fail("Cannot inspect service: To inspect service execute module on Swarm Manager")
+            self.fail("Error inspecting swarm service: %s" % exc)
+        except Exception as exc:
+            self.fail("Error inspecting swarm service: %s" % exc)
+
+        json_str = json.dumps(service_info, ensure_ascii=False)
+        service_info = json.loads(json_str)
+        return service_info

collections/ansible_collections/community/docker/plugins/module_utils/version.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2021, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+"""Provide version object to compare version numbers."""
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+# Once we drop support for Ansible 2.9, ansible-base 2.10, and ansible-core 2.11, we can
+# remove the _version.py file, and replace the following import by
+#
+#     from ansible.module_utils.compat.version import LooseVersion
+
+from ._version import LooseVersion

collections/ansible_collections/community/docker/plugins/modules/current_container_facts.py

@@ -0,0 +1,107 @@
+#!/usr/bin/python
+#
+# (c) 2020 Matt Clay <mclay@redhat.com>
+# (c) 2020 Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: current_container_facts
+short_description: Return facts about whether the module runs in a Docker container
+version_added: 1.1.0
+description:
+  - Return facts about whether the module runs in a Docker container.
+author:
+  - Felix Fontein (@felixfontein)
+'''
+
+EXAMPLES = '''
+- name: Get facts on current container
+  community.docker.current_container_facts:
+
+- name: Print information on current container when running in a container
+  ansible.builtin.debug:
+    msg: "Container ID is {{ ansible_module_container_id }}"
+  when: ansible_module_running_in_container
+'''
+
+RETURN = '''
+ansible_facts:
+    description: Ansible facts returned by the module
+    type: dict
+    returned: always
+    contains:
+        ansible_module_running_in_container:
+            description:
+              - Whether the module was able to detect that it runs in a container or not.
+            returned: always
+            type: bool
+        ansible_module_container_id:
+            description:
+              - The detected container ID.
+              - Contains an empty string if no container was detected.
+            returned: always
+            type: str
+        ansible_module_container_type:
+            description:
+              - The detected container environment.
+              - Contains an empty string if no container was detected.
+              - Otherwise, will be one of C(docker), C(azure_pipelines), or C(github_actions).
+              - C(github_actions) is supported since community.docker 2.4.0.
+            returned: always
+            type: str
+            choices:
+              - ''
+              - docker
+              - azure_pipelines
+              - github_actions
+'''
+
+import os
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+    module = AnsibleModule(dict(), supports_check_mode=True)
+
+    path = '/proc/self/cpuset'
+    container_id = ''
+    container_type = ''
+
+    if os.path.exists(path):
+        # File content varies based on the environment:
+        #   No Container: /
+        #   Docker: /docker/c86f3732b5ba3d28bb83b6e14af767ab96abbc52de31313dcb1176a62d91a507
+        #   Azure Pipelines (Docker): /azpl_job/0f2edfed602dd6ec9f2e42c867f4d5ee640ebf4c058e6d3196d4393bb8fd0891
+        #   Podman: /../../../../../..
+        with open(path, 'rb') as f:
+            contents = f.read().decode('utf-8')
+
+        cgroup_path, cgroup_name = os.path.split(contents.strip())
+
+        if cgroup_path == '/docker':
+            container_id = cgroup_name
+            container_type = 'docker'
+
+        if cgroup_path == '/azpl_job':
+            container_id = cgroup_name
+            container_type = 'azure_pipelines'
+
+        if cgroup_path == '/actions_job':
+            container_id = cgroup_name
+            container_type = 'github_actions'
+
+    module.exit_json(ansible_facts=dict(
+        ansible_module_running_in_container=container_id != '',
+        ansible_module_container_id=container_id,
+        ansible_module_container_type=container_type,
+    ))
+
+
+if __name__ == '__main__':
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_config.py

@@ -0,0 +1,424 @@
+#!/usr/bin/python
+#
+# Copyright 2016 Red Hat | Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: docker_config
+
+short_description: Manage docker configs.
+
+
+description:
+     - Create and remove Docker configs in a Swarm environment. Similar to C(docker config create) and C(docker config rm).
+     - Adds to the metadata of new configs 'ansible_key', an encrypted hash representation of the data, which is then used
+       in future runs to test if a config has changed. If 'ansible_key' is not present, then a config will not be updated
+       unless the I(force) option is set.
+     - Updates to configs are performed by removing the config and creating it again.
+options:
+  data:
+    description:
+      - The value of the config.
+      - Mutually exclusive with I(data_src). One of I(data) and I(data_src) is required if I(state=present).
+    type: str
+  data_is_b64:
+    description:
+      - If set to C(true), the data is assumed to be Base64 encoded and will be
+        decoded before being used.
+      - To use binary I(data), it is better to keep it Base64 encoded and let it
+        be decoded by this option.
+    type: bool
+    default: no
+  data_src:
+    description:
+      - The file on the target from which to read the config.
+      - Mutually exclusive with I(data). One of I(data) and I(data_src) is required if I(state=present).
+    type: path
+    version_added: 1.10.0
+  labels:
+    description:
+      - "A map of key:value meta data, where both the I(key) and I(value) are expected to be a string."
+      - If new meta data is provided, or existing meta data is modified, the config will be updated by removing it and creating it again.
+    type: dict
+  force:
+    description:
+      - Use with state C(present) to always remove and recreate an existing config.
+      - If C(true), an existing config will be replaced, even if it has not been changed.
+    type: bool
+    default: no
+  rolling_versions:
+    description:
+      - If set to C(true), configs are created with an increasing version number appended to their name.
+      - Adds a label containing the version number to the managed configs with the name C(ansible_version).
+    type: bool
+    default: false
+    version_added: 2.2.0
+  versions_to_keep:
+    description:
+      - When using I(rolling_versions), the number of old versions of the config to keep.
+      - Extraneous old configs are deleted after the new one is created.
+      - Set to C(-1) to keep everything or to C(0) or C(1) to keep only the current one.
+    type: int
+    default: 5
+    version_added: 2.2.0
+  name:
+    description:
+      - The name of the config.
+    type: str
+    required: yes
+  state:
+    description:
+      - Set to C(present), if the config should exist, and C(absent), if it should not.
+    type: str
+    default: present
+    choices:
+      - absent
+      - present
+  template_driver:
+    description:
+      - Set to C(golang) to use a Go template in I(data) or a Go template file in I(data_src).
+    type: str
+    choices:
+      - golang
+    version_added: 2.5.0
+
+extends_documentation_fragment:
+- community.docker.docker
+- community.docker.docker.docker_py_2_documentation
+
+
+requirements:
+  - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 2.6.0"
+  - "Docker API >= 1.30"
+
+author:
+  - Chris Houseknecht (@chouseknecht)
+  - John Hu (@ushuz)
+'''
+
+EXAMPLES = '''
+
+- name: Create config foo (from a file on the control machine)
+  community.docker.docker_config:
+    name: foo
+    # If the file is JSON or binary, Ansible might modify it (because
+    # it is first decoded and later re-encoded). Base64-encoding the
+    # file directly after reading it prevents this to happen.
+    data: "{{ lookup('file', '/path/to/config/file') | b64encode }}"
+    data_is_b64: true
+    state: present
+
+- name: Create config foo (from a file on the target machine)
+  community.docker.docker_config:
+    name: foo
+    data_src: /path/to/config/file
+    state: present
+
+- name: Change the config data
+  community.docker.docker_config:
+    name: foo
+    data: Goodnight everyone!
+    labels:
+      bar: baz
+      one: '1'
+    state: present
+
+- name: Add a new label
+  community.docker.docker_config:
+    name: foo
+    data: Goodnight everyone!
+    labels:
+      bar: baz
+      one: '1'
+      # Adding a new label will cause a remove/create of the config
+      two: '2'
+    state: present
+
+- name: No change
+  community.docker.docker_config:
+    name: foo
+    data: Goodnight everyone!
+    labels:
+      bar: baz
+      one: '1'
+      # Even though 'two' is missing, there is no change to the existing config
+    state: present
+
+- name: Update an existing label
+  community.docker.docker_config:
+    name: foo
+    data: Goodnight everyone!
+    labels:
+      bar: monkey   # Changing a label will cause a remove/create of the config
+      one: '1'
+    state: present
+
+- name: Force the (re-)creation of the config
+  community.docker.docker_config:
+    name: foo
+    data: Goodnight everyone!
+    force: yes
+    state: present
+
+- name: Remove config foo
+  community.docker.docker_config:
+    name: foo
+    state: absent
+'''
+
+RETURN = '''
+config_id:
+  description:
+    - The ID assigned by Docker to the config object.
+  returned: success and I(state) is C(present)
+  type: str
+  sample: 'hzehrmyjigmcp2gb6nlhmjqcv'
+config_name:
+  description:
+    - The name of the created config object.
+  returned: success and I(state) is C(present)
+  type: str
+  sample: 'awesome_config'
+  version_added: 2.2.0
+'''
+
+import base64
+import hashlib
+import traceback
+
+try:
+    from docker.errors import DockerException, APIError
+except ImportError:
+    # missing Docker SDK for Python handled in ansible.module_utils.docker.common
+    pass
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    AnsibleDockerClient,
+    DockerBaseClass,
+    compare_generic,
+    RequestException,
+)
+from ansible.module_utils.common.text.converters import to_native, to_bytes
+
+
+class ConfigManager(DockerBaseClass):
+
+    def __init__(self, client, results):
+
+        super(ConfigManager, self).__init__()
+
+        self.client = client
+        self.results = results
+        self.check_mode = self.client.check_mode
+
+        parameters = self.client.module.params
+        self.name = parameters.get('name')
+        self.state = parameters.get('state')
+        self.data = parameters.get('data')
+        if self.data is not None:
+            if parameters.get('data_is_b64'):
+                self.data = base64.b64decode(self.data)
+            else:
+                self.data = to_bytes(self.data)
+        data_src = parameters.get('data_src')
+        if data_src is not None:
+            try:
+                with open(data_src, 'rb') as f:
+                    self.data = f.read()
+            except Exception as exc:
+                self.client.fail('Error while reading {src}: {error}'.format(src=data_src, error=to_native(exc)))
+        self.labels = parameters.get('labels')
+        self.force = parameters.get('force')
+        self.rolling_versions = parameters.get('rolling_versions')
+        self.versions_to_keep = parameters.get('versions_to_keep')
+        self.template_driver = parameters.get('template_driver')
+
+        if self.rolling_versions:
+            self.version = 0
+        self.data_key = None
+        self.configs = []
+
+    def __call__(self):
+        self.get_config()
+        if self.state == 'present':
+            self.data_key = hashlib.sha224(self.data).hexdigest()
+            self.present()
+            self.remove_old_versions()
+        elif self.state == 'absent':
+            self.absent()
+
+    def get_version(self, config):
+        try:
+            return int(config.get('Spec', {}).get('Labels', {}).get('ansible_version', 0))
+        except ValueError:
+            return 0
+
+    def remove_old_versions(self):
+        if not self.rolling_versions or self.versions_to_keep < 0:
+            return
+        if not self.check_mode:
+            while len(self.configs) > max(self.versions_to_keep, 1):
+                self.remove_config(self.configs.pop(0))
+
+    def get_config(self):
+        ''' Find an existing config. '''
+        try:
+            configs = self.client.configs(filters={'name': self.name})
+        except APIError as exc:
+            self.client.fail("Error accessing config %s: %s" % (self.name, to_native(exc)))
+
+        if self.rolling_versions:
+            self.configs = [
+                config
+                for config in configs
+                if config['Spec']['Name'].startswith('{name}_v'.format(name=self.name))
+            ]
+            self.configs.sort(key=self.get_version)
+        else:
+            self.configs = [
+                config for config in configs if config['Spec']['Name'] == self.name
+            ]
+
+    def create_config(self):
+        ''' Create a new config '''
+        config_id = None
+        # We can't see the data after creation, so adding a label we can use for idempotency check
+        labels = {
+            'ansible_key': self.data_key
+        }
+        if self.rolling_versions:
+            self.version += 1
+            labels['ansible_version'] = str(self.version)
+            self.name = '{name}_v{version}'.format(name=self.name, version=self.version)
+        if self.labels:
+            labels.update(self.labels)
+
+        try:
+            if not self.check_mode:
+                # only use templating argument when self.template_driver is defined
+                kwargs = {}
+                if self.template_driver:
+                    kwargs['templating'] = {
+                        'name': self.template_driver
+                    }
+                config_id = self.client.create_config(self.name, self.data, labels=labels, **kwargs)
+                self.configs += self.client.configs(filters={'id': config_id})
+        except APIError as exc:
+            self.client.fail("Error creating config: %s" % to_native(exc))
+
+        if isinstance(config_id, dict):
+            config_id = config_id['ID']
+
+        return config_id
+
+    def remove_config(self, config):
+        try:
+            if not self.check_mode:
+                self.client.remove_config(config['ID'])
+        except APIError as exc:
+            self.client.fail("Error removing config %s: %s" % (config['Spec']['Name'], to_native(exc)))
+
+    def present(self):
+        ''' Handles state == 'present', creating or updating the config '''
+        if self.configs:
+            config = self.configs[-1]
+            self.results['config_id'] = config['ID']
+            self.results['config_name'] = config['Spec']['Name']
+            data_changed = False
+            template_driver_changed = False
+            attrs = config.get('Spec', {})
+            if attrs.get('Labels', {}).get('ansible_key'):
+                if attrs['Labels']['ansible_key'] != self.data_key:
+                    data_changed = True
+            else:
+                if not self.force:
+                    self.client.module.warn("'ansible_key' label not found. Config will not be changed unless the force parameter is set to 'yes'")
+            # template_driver has changed if it was set in the previous config
+            # and now it differs, or if it wasn't set but now it is.
+            if attrs.get('Templating', {}).get('Name'):
+                if attrs['Templating']['Name'] != self.template_driver:
+                    template_driver_changed = True
+            elif self.template_driver:
+                template_driver_changed = True
+            labels_changed = not compare_generic(self.labels, attrs.get('Labels'), 'allow_more_present', 'dict')
+            if self.rolling_versions:
+                self.version = self.get_version(config)
+            if data_changed or template_driver_changed or labels_changed or self.force:
+                # if something changed or force, delete and re-create the config
+                if not self.rolling_versions:
+                    self.absent()
+                config_id = self.create_config()
+                self.results['changed'] = True
+                self.results['config_id'] = config_id
+                self.results['config_name'] = self.name
+        else:
+            self.results['changed'] = True
+            self.results['config_id'] = self.create_config()
+            self.results['config_name'] = self.name
+
+    def absent(self):
+        ''' Handles state == 'absent', removing the config '''
+        if self.configs:
+            for config in self.configs:
+                self.remove_config(config)
+            self.results['changed'] = True
+
+
+def main():
+    argument_spec = dict(
+        name=dict(type='str', required=True),
+        state=dict(type='str', default='present', choices=['absent', 'present']),
+        data=dict(type='str'),
+        data_is_b64=dict(type='bool', default=False),
+        data_src=dict(type='path'),
+        labels=dict(type='dict'),
+        force=dict(type='bool', default=False),
+        rolling_versions=dict(type='bool', default=False),
+        versions_to_keep=dict(type='int', default=5),
+        template_driver=dict(type='str', choices=['golang']),
+    )
+
+    required_if = [
+        ('state', 'present', ['data', 'data_src'], True),
+    ]
+
+    mutually_exclusive = [
+        ('data', 'data_src'),
+    ]
+
+    option_minimal_versions = dict(
+        template_driver=dict(docker_py_version='5.0.3', docker_api_version='1.37'),
+    )
+
+    client = AnsibleDockerClient(
+        argument_spec=argument_spec,
+        supports_check_mode=True,
+        required_if=required_if,
+        mutually_exclusive=mutually_exclusive,
+        min_docker_version='2.6.0',
+        min_docker_api_version='1.30',
+        option_minimal_versions=option_minimal_versions,
+    )
+
+    try:
+        results = dict(
+            changed=False,
+        )
+
+        ConfigManager(client, results)()
+        client.module.exit_json(**results)
+    except DockerException as e:
+        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except RequestException as e:
+        client.fail(
+            'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(to_native(e)),
+            exception=traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_container_exec.py

@@ -0,0 +1,314 @@
+#!/usr/bin/python
+#
+# Copyright (c) 2021, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: docker_container_exec
+
+short_description: Execute command in a docker container
+
+version_added: 1.5.0
+
+description:
+  - Executes a command in a Docker container.
+
+options:
+  container:
+    type: str
+    required: true
+    description:
+      - The name of the container to execute the command in.
+  argv:
+    type: list
+    elements: str
+    description:
+      - The command to execute.
+      - Since this is a list of arguments, no quoting is needed.
+      - Exactly one of I(argv) and I(command) must be specified.
+  command:
+    type: str
+    description:
+      - The command to execute.
+      - Exactly one of I(argv) and I(command) must be specified.
+  chdir:
+    type: str
+    description:
+      - The directory to run the command in.
+  detach:
+    description:
+      - Whether to run the command synchronously (I(detach=false), default) or asynchronously (I(detach=true)).
+      - If set to C(true), I(stdin) cannot be provided, and the return values C(stdout), C(stderr) and
+        C(rc) are not returned.
+    type: bool
+    default: false
+    version_added: 2.1.0
+  user:
+    type: str
+    description:
+      - If specified, the user to execute this command with.
+  stdin:
+    type: str
+    description:
+      - Set the stdin of the command directly to the specified value.
+      - Can only be used if I(detach=false).
+  stdin_add_newline:
+    type: bool
+    default: true
+    description:
+      - If set to C(true), appends a newline to I(stdin).
+  strip_empty_ends:
+    type: bool
+    default: true
+    description:
+      - Strip empty lines from the end of stdout/stderr in result.
+  tty:
+    type: bool
+    default: false
+    description:
+      - Whether to allocate a TTY.
+  env:
+    description:
+      - Dictionary of environment variables with their respective values to be passed to the command ran inside the container.
+      - Values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (for example C("true")) in order to avoid data loss.
+      - Please note that if you are passing values in with Jinja2 templates, like C("{{ value }}"), you need to add C(| string) to prevent Ansible to
+        convert strings such as C("true") back to booleans. The correct way is to use C("{{ value | string }}").
+    type: dict
+    version_added: 2.1.0
+
+extends_documentation_fragment:
+  - community.docker.docker
+  - community.docker.docker.docker_py_1_documentation
+notes:
+  - Does not support C(check_mode).
+author:
+  - "Felix Fontein (@felixfontein)"
+
+requirements:
+  - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 1.8.0 (use L(docker-py,https://pypi.org/project/docker-py/) for Python 2.6)"
+  - "Docker API >= 1.20"
+'''
+
+EXAMPLES = '''
+- name: Run a simple command (command)
+  community.docker.docker_container_exec:
+    container: foo
+    command: /bin/bash -c "ls -lah"
+    chdir: /root
+  register: result
+
+- name: Print stdout
+  debug:
+    var: result.stdout
+
+- name: Run a simple command (argv)
+  community.docker.docker_container_exec:
+    container: foo
+    argv:
+      - /bin/bash
+      - "-c"
+      - "ls -lah > /dev/stderr"
+    chdir: /root
+  register: result
+
+- name: Print stderr lines
+  debug:
+    var: result.stderr_lines
+'''
+
+RETURN = '''
+stdout:
+    type: str
+    returned: success and I(detach=false)
+    description:
+      - The standard output of the container command.
+stderr:
+    type: str
+    returned: success and I(detach=false)
+    description:
+      - The standard error output of the container command.
+rc:
+    type: int
+    returned: success and I(detach=false)
+    sample: 0
+    description:
+      - The exit code of the command.
+exec_id:
+    type: str
+    returned: success and I(detach=true)
+    sample: 249d9e3075655baf705ed8f40488c5e9434049cf3431976f1bfdb73741c574c5
+    description:
+      - The execution ID of the command.
+    version_added: 2.1.0
+'''
+
+import shlex
+import traceback
+
+from ansible.module_utils.common.text.converters import to_text, to_bytes, to_native
+from ansible.module_utils.six import string_types
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    AnsibleDockerClient,
+    RequestException,
+)
+
+from ansible_collections.community.docker.plugins.module_utils.socket_helper import (
+    shutdown_writing,
+    write_to_socket,
+)
+
+from ansible_collections.community.docker.plugins.module_utils.socket_handler import (
+    find_selectors,
+    DockerSocketHandlerModule,
+)
+
+try:
+    from docker.errors import DockerException, APIError, NotFound
+except Exception:
+    # missing Docker SDK for Python handled in ansible.module_utils.docker.common
+    pass
+
+
+def main():
+    argument_spec = dict(
+        container=dict(type='str', required=True),
+        argv=dict(type='list', elements='str'),
+        command=dict(type='str'),
+        chdir=dict(type='str'),
+        detach=dict(type='bool', default=False),
+        user=dict(type='str'),
+        stdin=dict(type='str'),
+        stdin_add_newline=dict(type='bool', default=True),
+        strip_empty_ends=dict(type='bool', default=True),
+        tty=dict(type='bool', default=False),
+        env=dict(type='dict'),
+    )
+
+    option_minimal_versions = dict(
+        chdir=dict(docker_py_version='3.0.0', docker_api_version='1.35'),
+        env=dict(docker_py_version='2.3.0', docker_api_version='1.25'),
+    )
+
+    client = AnsibleDockerClient(
+        argument_spec=argument_spec,
+        option_minimal_versions=option_minimal_versions,
+        min_docker_api_version='1.20',
+        mutually_exclusive=[('argv', 'command')],
+        required_one_of=[('argv', 'command')],
+    )
+
+    container = client.module.params['container']
+    argv = client.module.params['argv']
+    command = client.module.params['command']
+    chdir = client.module.params['chdir']
+    detach = client.module.params['detach']
+    user = client.module.params['user']
+    stdin = client.module.params['stdin']
+    strip_empty_ends = client.module.params['strip_empty_ends']
+    tty = client.module.params['tty']
+    env = client.module.params['env']
+
+    if env is not None:
+        for name, value in list(env.items()):
+            if not isinstance(value, string_types):
+                client.module.fail_json(
+                    msg="Non-string value found for env option. Ambiguous env options must be "
+                        "wrapped in quotes to avoid them being interpreted. Key: %s" % (name, ))
+            env[name] = to_text(value, errors='surrogate_or_strict')
+
+    if command is not None:
+        argv = shlex.split(command)
+
+    if detach and stdin is not None:
+        client.module.fail_json(msg='If detach=true, stdin cannot be provided.')
+
+    if stdin is not None and client.module.params['stdin_add_newline']:
+        stdin += '\n'
+
+    selectors = None
+    if stdin and not detach:
+        selectors = find_selectors(client.module)
+
+    try:
+        kwargs = {}
+        if chdir is not None:
+            kwargs['workdir'] = chdir
+        if env is not None:
+            kwargs['environment'] = env
+        exec_data = client.exec_create(
+            container,
+            argv,
+            stdout=True,
+            stderr=True,
+            stdin=bool(stdin),
+            user=user or '',
+            **kwargs
+        )
+        exec_id = exec_data['Id']
+
+        if detach:
+            client.exec_start(exec_id, tty=tty, detach=True)
+            client.module.exit_json(changed=True, exec_id=exec_id)
+
+        else:
+            if selectors:
+                exec_socket = client.exec_start(
+                    exec_id,
+                    tty=tty,
+                    detach=False,
+                    socket=True,
+                )
+                try:
+                    with DockerSocketHandlerModule(exec_socket, client.module, selectors) as exec_socket_handler:
+                        if stdin:
+                            exec_socket_handler.write(to_bytes(stdin))
+
+                        stdout, stderr = exec_socket_handler.consume()
+                finally:
+                    exec_socket.close()
+            else:
+                stdout, stderr = client.exec_start(
+                    exec_id,
+                    tty=tty,
+                    detach=False,
+                    stream=False,
+                    socket=False,
+                    demux=True,
+                )
+
+            result = client.exec_inspect(exec_id)
+
+            stdout = to_text(stdout or b'')
+            stderr = to_text(stderr or b'')
+            if strip_empty_ends:
+                stdout = stdout.rstrip('\r\n')
+                stderr = stderr.rstrip('\r\n')
+
+            client.module.exit_json(
+                changed=True,
+                stdout=stdout,
+                stderr=stderr,
+                rc=result.get('ExitCode') or 0,
+            )
+    except NotFound:
+        client.fail('Could not find container "{0}"'.format(container))
+    except APIError as e:
+        if e.response and e.response.status_code == 409:
+            client.fail('The container "{0}" has been paused ({1})'.format(container, to_native(e)))
+        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except DockerException as e:
+        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except RequestException as e:
+        client.fail(
+            'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(to_native(e)),
+            exception=traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_container_info.py

@@ -0,0 +1,149 @@
+#!/usr/bin/python
+#
+# Copyright 2016 Red Hat | Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: docker_container_info
+
+short_description: Retrieves facts about docker container
+
+description:
+  - Retrieves facts about a docker container.
+  - Essentially returns the output of C(docker inspect <name>), similar to what M(community.docker.docker_container)
+    returns for a non-absent container.
+
+
+options:
+  name:
+    description:
+      - The name of the container to inspect.
+      - When identifying an existing container name may be a name or a long or short container ID.
+    type: str
+    required: yes
+extends_documentation_fragment:
+- community.docker.docker
+- community.docker.docker.docker_py_1_documentation
+
+
+author:
+  - "Felix Fontein (@felixfontein)"
+
+requirements:
+  - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 1.8.0 (use L(docker-py,https://pypi.org/project/docker-py/) for Python 2.6)"
+  - "Docker API >= 1.20"
+'''
+
+EXAMPLES = '''
+- name: Get infos on container
+  community.docker.docker_container_info:
+    name: mydata
+  register: result
+
+- name: Does container exist?
+  ansible.builtin.debug:
+    msg: "The container {{ 'exists' if result.exists else 'does not exist' }}"
+
+- name: Print information about container
+  ansible.builtin.debug:
+    var: result.container
+  when: result.exists
+'''
+
+RETURN = '''
+exists:
+    description:
+      - Returns whether the container exists.
+    type: bool
+    returned: always
+    sample: true
+container:
+    description:
+      - Facts representing the current state of the container. Matches the docker inspection output.
+      - Will be C(none) if container does not exist.
+    returned: always
+    type: dict
+    sample: '{
+        "AppArmorProfile": "",
+        "Args": [],
+        "Config": {
+            "AttachStderr": false,
+            "AttachStdin": false,
+            "AttachStdout": false,
+            "Cmd": [
+                "/usr/bin/supervisord"
+            ],
+            "Domainname": "",
+            "Entrypoint": null,
+            "Env": [
+                "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+            ],
+            "ExposedPorts": {
+                "443/tcp": {},
+                "80/tcp": {}
+            },
+            "Hostname": "8e47bf643eb9",
+            "Image": "lnmp_nginx:v1",
+            "Labels": {},
+            "OnBuild": null,
+            "OpenStdin": false,
+            "StdinOnce": false,
+            "Tty": false,
+            "User": "",
+            "Volumes": {
+                "/tmp/lnmp/nginx-sites/logs/": {}
+            },
+            ...
+    }'
+'''
+
+import traceback
+
+from ansible.module_utils.common.text.converters import to_native
+
+try:
+    from docker.errors import DockerException
+except ImportError:
+    # missing Docker SDK for Python handled in ansible.module_utils.docker.common
+    pass
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    AnsibleDockerClient,
+    RequestException,
+)
+
+
+def main():
+    argument_spec = dict(
+        name=dict(type='str', required=True),
+    )
+
+    client = AnsibleDockerClient(
+        argument_spec=argument_spec,
+        supports_check_mode=True,
+        min_docker_api_version='1.20',
+    )
+
+    try:
+        container = client.get_container(client.module.params['name'])
+
+        client.module.exit_json(
+            changed=False,
+            exists=(True if container else False),
+            container=container,
+        )
+    except DockerException as e:
+        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except RequestException as e:
+        client.fail(
+            'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(to_native(e)),
+            exception=traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_host_info.py

@@ -0,0 +1,362 @@
+#!/usr/bin/python
+#
+# (c) 2019 Piotr Wojciechowski <piotr@it-playground.pl>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: docker_host_info
+
+short_description: Retrieves facts about docker host and lists of objects of the services.
+
+description:
+  - Retrieves facts about a docker host.
+  - Essentially returns the output of C(docker system info).
+  - The module also allows to list object names for containers, images, networks and volumes.
+    It also allows to query information on disk usage.
+  - The output differs depending on API version of the docker daemon.
+  - If the docker daemon cannot be contacted or does not meet the API version requirements,
+    the module will fail.
+
+
+options:
+  containers:
+    description:
+      - Whether to list containers.
+    type: bool
+    default: no
+  containers_filters:
+    description:
+      - A dictionary of filter values used for selecting containers to list.
+      - "For example, C(until: 24h)."
+      - C(label) is a special case of filter which can be a string C(<key>) matching when a label is present, a string
+        C(<key>=<value>) matching when a label has a particular value, or a list of strings C(<key>)/C(<key>=<value).
+      - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/container_prune/#filtering)
+        for more information on possible filters.
+    type: dict
+  images:
+    description:
+      - Whether to list images.
+    type: bool
+    default: no
+  images_filters:
+    description:
+      - A dictionary of filter values used for selecting images to list.
+      - "For example, C(dangling: true)."
+      - C(label) is a special case of filter which can be a string C(<key>) matching when a label is present, a string
+        C(<key>=<value>) matching when a label has a particular value, or a list of strings C(<key>)/C(<key>=<value).
+      - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/image_prune/#filtering)
+        for more information on possible filters.
+    type: dict
+  networks:
+    description:
+      - Whether to list networks.
+    type: bool
+    default: no
+  networks_filters:
+    description:
+      - A dictionary of filter values used for selecting networks to list.
+      - C(label) is a special case of filter which can be a string C(<key>) matching when a label is present, a string
+        C(<key>=<value>) matching when a label has a particular value, or a list of strings C(<key>)/C(<key>=<value).
+      - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/network_prune/#filtering)
+        for more information on possible filters.
+    type: dict
+  volumes:
+    description:
+      - Whether to list volumes.
+    type: bool
+    default: no
+  volumes_filters:
+    description:
+      - A dictionary of filter values used for selecting volumes to list.
+      - C(label) is a special case of filter which can be a string C(<key>) matching when a label is present, a string
+        C(<key>=<value>) matching when a label has a particular value, or a list of strings C(<key>)/C(<key>=<value).
+      - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/volume_prune/#filtering)
+        for more information on possible filters.
+    type: dict
+  disk_usage:
+    description:
+      - Summary information on used disk space by all Docker layers.
+      - The output is a sum of images, volumes, containers and build cache.
+    type: bool
+    default: no
+  verbose_output:
+    description:
+      - When set to C(yes) and I(networks), I(volumes), I(images), I(containers) or I(disk_usage) is set to C(yes)
+        then output will contain verbose information about objects matching the full output of API method.
+        For details see the documentation of your version of Docker API at U(https://docs.docker.com/engine/api/).
+      - The verbose output in this module contains only subset of information returned by I(_info) module
+        for each type of the objects.
+    type: bool
+    default: no
+extends_documentation_fragment:
+- community.docker.docker
+- community.docker.docker.docker_py_1_documentation
+
+
+author:
+  - Piotr Wojciechowski (@WojciechowskiPiotr)
+
+requirements:
+  - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 1.10.0 (use L(docker-py,https://pypi.org/project/docker-py/) for Python 2.6)"
+  - "Docker API >= 1.21"
+'''
+
+EXAMPLES = '''
+- name: Get info on docker host
+  community.docker.docker_host_info:
+  register: result
+
+- name: Get info on docker host and list images
+  community.docker.docker_host_info:
+    images: yes
+  register: result
+
+- name: Get info on docker host and list images matching the filter
+  community.docker.docker_host_info:
+    images: yes
+    images_filters:
+      label: "mylabel"
+  register: result
+
+- name: Get info on docker host and verbose list images
+  community.docker.docker_host_info:
+    images: yes
+    verbose_output: yes
+  register: result
+
+- name: Get info on docker host and used disk space
+  community.docker.docker_host_info:
+    disk_usage: yes
+  register: result
+
+- name: Get info on docker host and list containers matching the filter
+  community.docker.docker_host_info:
+    containers: yes
+    containers_filters:
+      label:
+        - key1=value1
+        - key2=value2
+  register: result
+
+- ansible.builtin.debug:
+    var: result.host_info
+
+'''
+
+RETURN = '''
+can_talk_to_docker:
+    description:
+      - Will be C(true) if the module can talk to the docker daemon.
+    returned: both on success and on error
+    type: bool
+
+host_info:
+    description:
+      - Facts representing the basic state of the docker host. Matches the C(docker system info) output.
+    returned: always
+    type: dict
+volumes:
+    description:
+      - List of dict objects containing the basic information about each volume.
+        Keys matches the C(docker volume ls) output unless I(verbose_output=yes).
+        See description for I(verbose_output).
+    returned: When I(volumes) is C(yes)
+    type: list
+    elements: dict
+networks:
+    description:
+      - List of dict objects containing the basic information about each network.
+        Keys matches the C(docker network ls) output unless I(verbose_output=yes).
+        See description for I(verbose_output).
+    returned: When I(networks) is C(yes)
+    type: list
+    elements: dict
+containers:
+    description:
+      - List of dict objects containing the basic information about each container.
+        Keys matches the C(docker container ls) output unless I(verbose_output=yes).
+        See description for I(verbose_output).
+    returned: When I(containers) is C(yes)
+    type: list
+    elements: dict
+images:
+    description:
+      - List of dict objects containing the basic information about each image.
+        Keys matches the C(docker image ls) output unless I(verbose_output=yes).
+        See description for I(verbose_output).
+    returned: When I(images) is C(yes)
+    type: list
+    elements: dict
+disk_usage:
+    description:
+      - Information on summary disk usage by images, containers and volumes on docker host
+        unless I(verbose_output=yes). See description for I(verbose_output).
+    returned: When I(disk_usage) is C(yes)
+    type: dict
+
+'''
+
+import traceback
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    AnsibleDockerClient,
+    DockerBaseClass,
+    RequestException,
+)
+from ansible.module_utils.common.text.converters import to_native
+
+try:
+    from docker.errors import DockerException, APIError
+except ImportError:
+    # Missing Docker SDK for Python handled in ansible.module_utils.docker.common
+    pass
+
+from ansible_collections.community.docker.plugins.module_utils.common import clean_dict_booleans_for_docker_api
+
+
+class DockerHostManager(DockerBaseClass):
+
+    def __init__(self, client, results):
+
+        super(DockerHostManager, self).__init__()
+
+        self.client = client
+        self.results = results
+        self.verbose_output = self.client.module.params['verbose_output']
+
+        listed_objects = ['volumes', 'networks', 'containers', 'images']
+
+        self.results['host_info'] = self.get_docker_host_info()
+
+        if self.client.module.params['disk_usage']:
+            self.results['disk_usage'] = self.get_docker_disk_usage_facts()
+
+        for docker_object in listed_objects:
+            if self.client.module.params[docker_object]:
+                returned_name = docker_object
+                filter_name = docker_object + "_filters"
+                filters = clean_dict_booleans_for_docker_api(client.module.params.get(filter_name), True)
+                self.results[returned_name] = self.get_docker_items_list(docker_object, filters)
+
+    def get_docker_host_info(self):
+        try:
+            return self.client.info()
+        except APIError as exc:
+            self.client.fail("Error inspecting docker host: %s" % to_native(exc))
+
+    def get_docker_disk_usage_facts(self):
+        try:
+            if self.verbose_output:
+                return self.client.df()
+            else:
+                return dict(LayersSize=self.client.df()['LayersSize'])
+        except APIError as exc:
+            self.client.fail("Error inspecting docker host: %s" % to_native(exc))
+
+    def get_docker_items_list(self, docker_object=None, filters=None, verbose=False):
+        items = None
+        items_list = []
+
+        header_containers = ['Id', 'Image', 'Command', 'Created', 'Status', 'Ports', 'Names']
+        header_volumes = ['Driver', 'Name']
+        header_images = ['Id', 'RepoTags', 'Created', 'Size']
+        header_networks = ['Id', 'Driver', 'Name', 'Scope']
+
+        filter_arg = dict()
+        if filters:
+            filter_arg['filters'] = filters
+        try:
+            if docker_object == 'containers':
+                items = self.client.containers(**filter_arg)
+            elif docker_object == 'networks':
+                items = self.client.networks(**filter_arg)
+            elif docker_object == 'images':
+                items = self.client.images(**filter_arg)
+            elif docker_object == 'volumes':
+                items = self.client.volumes(**filter_arg)
+        except APIError as exc:
+            self.client.fail("Error inspecting docker host for object '%s': %s" %
+                             (docker_object, to_native(exc)))
+
+        if self.verbose_output:
+            if docker_object != 'volumes':
+                return items
+            else:
+                return items['Volumes']
+
+        if docker_object == 'volumes':
+            items = items['Volumes']
+
+        for item in items:
+            item_record = dict()
+
+            if docker_object == 'containers':
+                for key in header_containers:
+                    item_record[key] = item.get(key)
+            elif docker_object == 'networks':
+                for key in header_networks:
+                    item_record[key] = item.get(key)
+            elif docker_object == 'images':
+                for key in header_images:
+                    item_record[key] = item.get(key)
+            elif docker_object == 'volumes':
+                for key in header_volumes:
+                    item_record[key] = item.get(key)
+            items_list.append(item_record)
+
+        return items_list
+
+
+def main():
+    argument_spec = dict(
+        containers=dict(type='bool', default=False),
+        containers_filters=dict(type='dict'),
+        images=dict(type='bool', default=False),
+        images_filters=dict(type='dict'),
+        networks=dict(type='bool', default=False),
+        networks_filters=dict(type='dict'),
+        volumes=dict(type='bool', default=False),
+        volumes_filters=dict(type='dict'),
+        disk_usage=dict(type='bool', default=False),
+        verbose_output=dict(type='bool', default=False),
+    )
+
+    option_minimal_versions = dict(
+        network_filters=dict(docker_py_version='2.0.2'),
+        disk_usage=dict(docker_py_version='2.2.0'),
+    )
+
+    client = AnsibleDockerClient(
+        argument_spec=argument_spec,
+        supports_check_mode=True,
+        min_docker_version='1.10.0',
+        min_docker_api_version='1.21',
+        option_minimal_versions=option_minimal_versions,
+        fail_results=dict(
+            can_talk_to_docker=False,
+        ),
+    )
+    client.fail_results['can_talk_to_docker'] = True
+
+    try:
+        results = dict(
+            changed=False,
+        )
+
+        DockerHostManager(client, results)
+        client.module.exit_json(**results)
+    except DockerException as e:
+        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except RequestException as e:
+        client.fail(
+            'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(to_native(e)),
+            exception=traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_image.py

@@ -0,0 +1,923 @@
+#!/usr/bin/python
+#
+# Copyright 2016 Red Hat | Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: docker_image
+
+short_description: Manage docker images
+
+
+description:
+  - Build, load or pull an image, making the image available for creating containers. Also supports tagging
+    an image, pushing an image, and archiving an image to a C(.tar) file.
+
+options:
+  source:
+    description:
+      - "Determines where the module will try to retrieve the image from."
+      - "Use C(build) to build the image from a C(Dockerfile). I(build.path) must
+         be specified when this value is used."
+      - "Use C(load) to load the image from a C(.tar) file. I(load_path) must
+         be specified when this value is used."
+      - "Use C(pull) to pull the image from a registry."
+      - "Use C(local) to make sure that the image is already available on the local
+         docker daemon. This means that the module does not try to build, pull or load the image."
+    type: str
+    choices:
+    - build
+    - load
+    - pull
+    - local
+  build:
+    description:
+      - "Specifies options used for building images."
+    type: dict
+    suboptions:
+      cache_from:
+        description:
+          - List of image names to consider as cache source.
+        type: list
+        elements: str
+      dockerfile:
+        description:
+          - Use with state C(present) and source C(build) to provide an alternate name for the Dockerfile to use when building an image.
+          - This can also include a relative path (relative to I(path)).
+        type: str
+      http_timeout:
+        description:
+          - Timeout for HTTP requests during the image build operation. Provide a positive integer value for the number of
+            seconds.
+        type: int
+      path:
+        description:
+          - Use with state 'present' to build an image. Will be the path to a directory containing the context and
+            Dockerfile for building an image.
+        type: path
+        required: yes
+      pull:
+        description:
+          - When building an image downloads any updates to the FROM image in Dockerfile.
+        type: bool
+        default: no
+      rm:
+        description:
+          - Remove intermediate containers after build.
+        type: bool
+        default: yes
+      network:
+        description:
+          - The network to use for C(RUN) build instructions.
+        type: str
+      nocache:
+        description:
+          - Do not use cache when building an image.
+        type: bool
+        default: no
+      etc_hosts:
+        description:
+          - Extra hosts to add to C(/etc/hosts) in building containers, as a mapping of hostname to IP address.
+        type: dict
+      args:
+        description:
+          - Provide a dictionary of C(key:value) build arguments that map to Dockerfile ARG directive.
+          - Docker expects the value to be a string. For convenience any non-string values will be converted to strings.
+          - Requires Docker API >= 1.21.
+        type: dict
+      container_limits:
+        description:
+          - A dictionary of limits applied to each container created by the build process.
+        type: dict
+        suboptions:
+          memory:
+            description:
+              - Set memory limit for build.
+            type: int
+          memswap:
+            description:
+              - Total memory (memory + swap).
+              - Use C(-1) to disable swap.
+            type: int
+          cpushares:
+            description:
+              - CPU shares (relative weight).
+            type: int
+          cpusetcpus:
+            description:
+              - CPUs in which to allow execution.
+              - For example, C(0-3) or C(0,1).
+            type: str
+      use_config_proxy:
+        description:
+          - If set to C(yes) and a proxy configuration is specified in the docker client configuration
+            (by default C($HOME/.docker/config.json)), the corresponding environment variables will
+            be set in the container being built.
+          - Needs Docker SDK for Python >= 3.7.0.
+        type: bool
+      target:
+        description:
+          - When building an image specifies an intermediate build stage by
+            name as a final stage for the resulting image.
+        type: str
+      platform:
+        description:
+          - Platform in the format C(os[/arch[/variant]]).
+        type: str
+        version_added: 1.1.0
+  archive_path:
+    description:
+      - Use with state C(present) to archive an image to a .tar file.
+    type: path
+  load_path:
+    description:
+      - Use with state C(present) to load an image from a .tar file.
+      - Set I(source) to C(load) if you want to load the image.
+    type: path
+  force_source:
+    description:
+      - Use with state C(present) to build, load or pull an image (depending on the
+        value of the I(source) option) when the image already exists.
+    type: bool
+    default: false
+  force_absent:
+    description:
+      - Use with state I(absent) to un-tag and remove all images matching the specified name.
+    type: bool
+    default: false
+  force_tag:
+    description:
+      - Use with state C(present) to force tagging an image.
+    type: bool
+    default: false
+  name:
+    description:
+      - "Image name. Name format will be one of: C(name), C(repository/name), C(registry_server:port/name).
+        When pushing or pulling an image the name can optionally include the tag by appending C(:tag_name)."
+      - Note that image IDs (hashes) are only supported for I(state=absent), for I(state=present) with I(source=load),
+        and for I(state=present) with I(source=local).
+    type: str
+    required: yes
+  pull:
+    description:
+      - "Specifies options used for pulling images."
+    type: dict
+    version_added: 1.3.0
+    suboptions:
+      platform:
+        description:
+          - When pulling an image, ask for this specific platform.
+          - Note that this value is not used to determine whether the image needs to be pulled. This might change
+            in the future in a minor release, though.
+        type: str
+  push:
+    description:
+      - Push the image to the registry. Specify the registry as part of the I(name) or I(repository) parameter.
+    type: bool
+    default: no
+  repository:
+    description:
+      - Use with state C(present) to tag the image.
+      - Expects format C(repository:tag). If no tag is provided, will use the value of the I(tag) parameter or C(latest).
+      - If I(push=true), I(repository) must either include a registry, or will be assumed to belong to the default
+        registry (Docker Hub).
+    type: str
+  state:
+    description:
+      - Make assertions about the state of an image.
+      - When C(absent) an image will be removed. Use the force option to un-tag and remove all images
+        matching the provided name.
+      - When C(present) check if an image exists using the provided name and tag. If the image is not found or the
+        force option is used, the image will either be pulled, built or loaded, depending on the I(source) option.
+    type: str
+    default: present
+    choices:
+      - absent
+      - present
+  tag:
+    description:
+      - Used to select an image when pulling. Will be added to the image when pushing, tagging or building. Defaults to
+        I(latest).
+      - If I(name) parameter format is I(name:tag), then tag value from I(name) will take precedence.
+    type: str
+    default: latest
+
+extends_documentation_fragment:
+- community.docker.docker
+- community.docker.docker.docker_py_1_documentation
+
+
+requirements:
+  - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 1.8.0 (use L(docker-py,https://pypi.org/project/docker-py/) for Python 2.6)"
+  - "Docker API >= 1.20"
+
+author:
+  - Pavel Antonov (@softzilla)
+  - Chris Houseknecht (@chouseknecht)
+  - Sorin Sbarnea (@ssbarnea)
+
+'''
+
+EXAMPLES = '''
+
+- name: Pull an image
+  community.docker.docker_image:
+    name: pacur/centos-7
+    source: pull
+    # Select platform for pulling. If not specified, will pull whatever docker prefers.
+    pull:
+      platform: amd64
+
+- name: Tag and push to docker hub
+  community.docker.docker_image:
+    name: pacur/centos-7:56
+    repository: dcoppenhagan/myimage:7.56
+    push: yes
+    source: local
+
+- name: Tag and push to local registry
+  community.docker.docker_image:
+    # Image will be centos:7
+    name: centos
+    # Will be pushed to localhost:5000/centos:7
+    repository: localhost:5000/centos
+    tag: 7
+    push: yes
+    source: local
+
+- name: Add tag latest to image
+  community.docker.docker_image:
+    name: myimage:7.1.2
+    repository: myimage:latest
+    # As 'latest' usually already is present, we need to enable overwriting of existing tags:
+    force_tag: yes
+    source: local
+
+- name: Remove image
+  community.docker.docker_image:
+    state: absent
+    name: registry.ansible.com/chouseknecht/sinatra
+    tag: v1
+
+- name: Build an image and push it to a private repo
+  community.docker.docker_image:
+    build:
+      path: ./sinatra
+    name: registry.ansible.com/chouseknecht/sinatra
+    tag: v1
+    push: yes
+    source: build
+
+- name: Archive image
+  community.docker.docker_image:
+    name: registry.ansible.com/chouseknecht/sinatra
+    tag: v1
+    archive_path: my_sinatra.tar
+    source: local
+
+- name: Load image from archive and push to a private registry
+  community.docker.docker_image:
+    name: localhost:5000/myimages/sinatra
+    tag: v1
+    push: yes
+    load_path: my_sinatra.tar
+    source: load
+
+- name: Build image and with build args
+  community.docker.docker_image:
+    name: myimage
+    build:
+      path: /path/to/build/dir
+      args:
+        log_volume: /var/log/myapp
+        listen_port: 8080
+    source: build
+
+- name: Build image using cache source
+  community.docker.docker_image:
+    name: myimage:latest
+    build:
+      path: /path/to/build/dir
+      # Use as cache source for building myimage
+      cache_from:
+        - nginx:latest
+        - alpine:3.8
+    source: build
+'''
+
+RETURN = '''
+image:
+    description: Image inspection results for the affected image.
+    returned: success
+    type: dict
+    sample: {}
+stdout:
+    description: Docker build output when building an image.
+    returned: success
+    type: str
+    sample: ""
+    version_added: 1.0.0
+'''
+
+import errno
+import os
+import traceback
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    clean_dict_booleans_for_docker_api,
+    docker_version,
+    AnsibleDockerClient,
+    DockerBaseClass,
+    is_image_name_id,
+    is_valid_tag,
+    RequestException,
+)
+from ansible.module_utils.common.text.converters import to_native
+
+from ansible_collections.community.docker.plugins.module_utils.version import LooseVersion
+
+if docker_version is not None:
+    try:
+        if LooseVersion(docker_version) >= LooseVersion('2.0.0'):
+            from docker.auth import resolve_repository_name
+        else:
+            from docker.auth.auth import resolve_repository_name
+        from docker.utils.utils import parse_repository_tag
+        from docker.errors import DockerException, NotFound
+    except ImportError:
+        # missing Docker SDK for Python handled in module_utils.docker.common
+        pass
+
+
+class ImageManager(DockerBaseClass):
+
+    def __init__(self, client, results):
+
+        super(ImageManager, self).__init__()
+
+        self.client = client
+        self.results = results
+        parameters = self.client.module.params
+        self.check_mode = self.client.check_mode
+
+        self.source = parameters['source']
+        build = parameters['build'] or dict()
+        pull = parameters['pull'] or dict()
+        self.archive_path = parameters['archive_path']
+        self.cache_from = build.get('cache_from')
+        self.container_limits = build.get('container_limits')
+        self.dockerfile = build.get('dockerfile')
+        self.force_source = parameters['force_source']
+        self.force_absent = parameters['force_absent']
+        self.force_tag = parameters['force_tag']
+        self.load_path = parameters['load_path']
+        self.name = parameters['name']
+        self.network = build.get('network')
+        self.extra_hosts = clean_dict_booleans_for_docker_api(build.get('etc_hosts'))
+        self.nocache = build.get('nocache', False)
+        self.build_path = build.get('path')
+        self.pull = build.get('pull')
+        self.target = build.get('target')
+        self.repository = parameters['repository']
+        self.rm = build.get('rm', True)
+        self.state = parameters['state']
+        self.tag = parameters['tag']
+        self.http_timeout = build.get('http_timeout')
+        self.pull_platform = pull.get('platform')
+        self.push = parameters['push']
+        self.buildargs = build.get('args')
+        self.build_platform = build.get('platform')
+        self.use_config_proxy = build.get('use_config_proxy')
+
+        # If name contains a tag, it takes precedence over tag parameter.
+        if not is_image_name_id(self.name):
+            repo, repo_tag = parse_repository_tag(self.name)
+            if repo_tag:
+                self.name = repo
+                self.tag = repo_tag
+
+        # Sanity check: fail early when we know that something will fail later
+        if self.repository and is_image_name_id(self.repository):
+            self.fail("`repository` must not be an image ID; got: %s" % self.repository)
+        if not self.repository and self.push and is_image_name_id(self.name):
+            self.fail("Cannot push an image by ID; specify `repository` to tag and push the image with ID %s instead" % self.name)
+
+        if self.state == 'present':
+            self.present()
+        elif self.state == 'absent':
+            self.absent()
+
+    def fail(self, msg):
+        self.client.fail(msg)
+
+    def present(self):
+        '''
+        Handles state = 'present', which includes building, loading or pulling an image,
+        depending on user provided parameters.
+
+        :returns None
+        '''
+        if is_image_name_id(self.name):
+            image = self.client.find_image_by_id(self.name, accept_missing_image=True)
+        else:
+            image = self.client.find_image(name=self.name, tag=self.tag)
+
+        if not image or self.force_source:
+            if self.source == 'build':
+                if is_image_name_id(self.name):
+                    self.fail("Image name must not be an image ID for source=build; got: %s" % self.name)
+
+                # Build the image
+                if not os.path.isdir(self.build_path):
+                    self.fail("Requested build path %s could not be found or you do not have access." % self.build_path)
+                image_name = self.name
+                if self.tag:
+                    image_name = "%s:%s" % (self.name, self.tag)
+                self.log("Building image %s" % image_name)
+                self.results['actions'].append("Built image %s from %s" % (image_name, self.build_path))
+                self.results['changed'] = True
+                if not self.check_mode:
+                    self.results.update(self.build_image())
+
+            elif self.source == 'load':
+                # Load the image from an archive
+                if not os.path.isfile(self.load_path):
+                    self.fail("Error loading image %s. Specified path %s does not exist." % (self.name,
+                                                                                             self.load_path))
+                image_name = self.name
+                if self.tag and not is_image_name_id(image_name):
+                    image_name = "%s:%s" % (self.name, self.tag)
+                self.results['actions'].append("Loaded image %s from %s" % (image_name, self.load_path))
+                self.results['changed'] = True
+                if not self.check_mode:
+                    self.results['image'] = self.load_image()
+            elif self.source == 'pull':
+                if is_image_name_id(self.name):
+                    self.fail("Image name must not be an image ID for source=pull; got: %s" % self.name)
+
+                # pull the image
+                self.results['actions'].append('Pulled image %s:%s' % (self.name, self.tag))
+                self.results['changed'] = True
+                if not self.check_mode:
+                    self.results['image'], dummy = self.client.pull_image(self.name, tag=self.tag, platform=self.pull_platform)
+            elif self.source == 'local':
+                if image is None:
+                    name = self.name
+                    if self.tag and not is_image_name_id(name):
+                        name = "%s:%s" % (self.name, self.tag)
+                    self.client.fail('Cannot find the image %s locally.' % name)
+            if not self.check_mode and image and image['Id'] == self.results['image']['Id']:
+                self.results['changed'] = False
+        else:
+            self.results['image'] = image
+
+        if self.archive_path:
+            self.archive_image(self.name, self.tag)
+
+        if self.push and not self.repository:
+            self.push_image(self.name, self.tag)
+        elif self.repository:
+            self.tag_image(self.name, self.tag, self.repository, push=self.push)
+
+    def absent(self):
+        '''
+        Handles state = 'absent', which removes an image.
+
+        :return None
+        '''
+        name = self.name
+        if is_image_name_id(name):
+            image = self.client.find_image_by_id(name, accept_missing_image=True)
+        else:
+            image = self.client.find_image(name, self.tag)
+            if self.tag:
+                name = "%s:%s" % (self.name, self.tag)
+        if image:
+            if not self.check_mode:
+                try:
+                    self.client.remove_image(name, force=self.force_absent)
+                except NotFound:
+                    # If the image vanished while we were trying to remove it, don't fail
+                    pass
+                except Exception as exc:
+                    self.fail("Error removing image %s - %s" % (name, to_native(exc)))
+
+            self.results['changed'] = True
+            self.results['actions'].append("Removed image %s" % (name))
+            self.results['image']['state'] = 'Deleted'
+
+    def archive_image(self, name, tag):
+        '''
+        Archive an image to a .tar file. Called when archive_path is passed.
+
+        :param name - name of the image. Type: str
+        :return None
+        '''
+
+        if not tag:
+            tag = "latest"
+
+        if is_image_name_id(name):
+            image = self.client.find_image_by_id(name, accept_missing_image=True)
+            image_name = name
+        else:
+            image = self.client.find_image(name=name, tag=tag)
+            image_name = "%s:%s" % (name, tag)
+
+        if not image:
+            self.log("archive image: image %s not found" % image_name)
+            return
+
+        self.results['actions'].append('Archived image %s to %s' % (image_name, self.archive_path))
+        self.results['changed'] = True
+        if not self.check_mode:
+            self.log("Getting archive of image %s" % image_name)
+            try:
+                saved_image = self.client.get_image(image_name)
+            except Exception as exc:
+                self.fail("Error getting image %s - %s" % (image_name, to_native(exc)))
+
+            try:
+                with open(self.archive_path, 'wb') as fd:
+                    if self.client.docker_py_version >= LooseVersion('3.0.0'):
+                        for chunk in saved_image:
+                            fd.write(chunk)
+                    else:
+                        for chunk in saved_image.stream(2048, decode_content=False):
+                            fd.write(chunk)
+            except Exception as exc:
+                self.fail("Error writing image archive %s - %s" % (self.archive_path, to_native(exc)))
+
+        if image:
+            self.results['image'] = image
+
+    def push_image(self, name, tag=None):
+        '''
+        If the name of the image contains a repository path, then push the image.
+
+        :param name Name of the image to push.
+        :param tag Use a specific tag.
+        :return: None
+        '''
+
+        if is_image_name_id(name):
+            self.fail("Cannot push an image ID: %s" % name)
+
+        repository = name
+        if not tag:
+            repository, tag = parse_repository_tag(name)
+        registry, repo_name = resolve_repository_name(repository)
+
+        self.log("push %s to %s/%s:%s" % (self.name, registry, repo_name, tag))
+
+        if registry:
+            self.results['actions'].append("Pushed image %s to %s/%s:%s" % (self.name, registry, repo_name, tag))
+            self.results['changed'] = True
+            if not self.check_mode:
+                status = None
+                try:
+                    changed = False
+                    for line in self.client.push(repository, tag=tag, stream=True, decode=True):
+                        self.log(line, pretty_print=True)
+                        if line.get('errorDetail'):
+                            raise Exception(line['errorDetail']['message'])
+                        status = line.get('status')
+                        if status == 'Pushing':
+                            changed = True
+                    self.results['changed'] = changed
+                except Exception as exc:
+                    if 'unauthorized' in str(exc):
+                        if 'authentication required' in str(exc):
+                            self.fail("Error pushing image %s/%s:%s - %s. Try logging into %s first." %
+                                      (registry, repo_name, tag, to_native(exc), registry))
+                        else:
+                            self.fail("Error pushing image %s/%s:%s - %s. Does the repository exist?" %
+                                      (registry, repo_name, tag, str(exc)))
+                    self.fail("Error pushing image %s: %s" % (repository, to_native(exc)))
+                self.results['image'] = self.client.find_image(name=repository, tag=tag)
+                if not self.results['image']:
+                    self.results['image'] = dict()
+                self.results['image']['push_status'] = status
+
+    def tag_image(self, name, tag, repository, push=False):
+        '''
+        Tag an image into a repository.
+
+        :param name: name of the image. required.
+        :param tag: image tag.
+        :param repository: path to the repository. required.
+        :param push: bool. push the image once it's tagged.
+        :return: None
+        '''
+        repo, repo_tag = parse_repository_tag(repository)
+        if not repo_tag:
+            repo_tag = "latest"
+            if tag:
+                repo_tag = tag
+        image = self.client.find_image(name=repo, tag=repo_tag)
+        found = 'found' if image else 'not found'
+        self.log("image %s was %s" % (repo, found))
+
+        if not image or self.force_tag:
+            image_name = name
+            if not is_image_name_id(name) and tag and not name.endswith(':' + tag):
+                image_name = "%s:%s" % (name, tag)
+            self.log("tagging %s to %s:%s" % (image_name, repo, repo_tag))
+            self.results['changed'] = True
+            self.results['actions'].append("Tagged image %s to %s:%s" % (image_name, repo, repo_tag))
+            if not self.check_mode:
+                try:
+                    # Finding the image does not always work, especially running a localhost registry. In those
+                    # cases, if we don't set force=True, it errors.
+                    tag_status = self.client.tag(image_name, repo, tag=repo_tag, force=True)
+                    if not tag_status:
+                        raise Exception("Tag operation failed.")
+                except Exception as exc:
+                    self.fail("Error: failed to tag image - %s" % to_native(exc))
+                self.results['image'] = self.client.find_image(name=repo, tag=repo_tag)
+                if image and image['Id'] == self.results['image']['Id']:
+                    self.results['changed'] = False
+
+        if push:
+            self.push_image(repo, repo_tag)
+
+    @staticmethod
+    def _extract_output_line(line, output):
+        '''
+        Extract text line from stream output and, if found, adds it to output.
+        '''
+        if 'stream' in line or 'status' in line:
+            # Make sure we have a string (assuming that line['stream'] and
+            # line['status'] are either not defined, falsish, or a string)
+            text_line = line.get('stream') or line.get('status') or ''
+            output.extend(text_line.splitlines())
+
+    def build_image(self):
+        '''
+        Build an image
+
+        :return: image dict
+        '''
+        params = dict(
+            path=self.build_path,
+            tag=self.name,
+            rm=self.rm,
+            nocache=self.nocache,
+            timeout=self.http_timeout,
+            pull=self.pull,
+            forcerm=self.rm,
+            dockerfile=self.dockerfile,
+            decode=True,
+        )
+        if self.client.docker_py_version < LooseVersion('3.0.0'):
+            params['stream'] = True
+
+        if self.tag:
+            params['tag'] = "%s:%s" % (self.name, self.tag)
+        if self.container_limits:
+            params['container_limits'] = self.container_limits
+        if self.buildargs:
+            for key, value in self.buildargs.items():
+                self.buildargs[key] = to_native(value)
+            params['buildargs'] = self.buildargs
+        if self.cache_from:
+            params['cache_from'] = self.cache_from
+        if self.network:
+            params['network_mode'] = self.network
+        if self.extra_hosts:
+            params['extra_hosts'] = self.extra_hosts
+        if self.use_config_proxy:
+            params['use_config_proxy'] = self.use_config_proxy
+            # Due to a bug in docker-py, it will crash if
+            # use_config_proxy is True and buildargs is None
+            if 'buildargs' not in params:
+                params['buildargs'] = {}
+        if self.target:
+            params['target'] = self.target
+        if self.build_platform is not None:
+            params['platform'] = self.build_platform
+
+        build_output = []
+        for line in self.client.build(**params):
+            # line = json.loads(line)
+            self.log(line, pretty_print=True)
+            self._extract_output_line(line, build_output)
+
+            if line.get('error'):
+                if line.get('errorDetail'):
+                    errorDetail = line.get('errorDetail')
+                    self.fail(
+                        "Error building %s - code: %s, message: %s, logs: %s" % (
+                            self.name,
+                            errorDetail.get('code'),
+                            errorDetail.get('message'),
+                            build_output))
+                else:
+                    self.fail("Error building %s - message: %s, logs: %s" % (
+                        self.name, line.get('error'), build_output))
+
+        return {"stdout": "\n".join(build_output),
+                "image": self.client.find_image(name=self.name, tag=self.tag)}
+
+    def load_image(self):
+        '''
+        Load an image from a .tar archive
+
+        :return: image dict
+        '''
+        # Load image(s) from file
+        load_output = []
+        has_output = False
+        try:
+            self.log("Opening image %s" % self.load_path)
+            with open(self.load_path, 'rb') as image_tar:
+                self.log("Loading image from %s" % self.load_path)
+                output = self.client.load_image(image_tar)
+                if output is not None:
+                    # Old versions of Docker SDK of Python (before version 2.5.0) do not return anything.
+                    # (See https://github.com/docker/docker-py/commit/7139e2d8f1ea82340417add02090bfaf7794f159)
+                    # Note that before that commit, something else than None was returned, but that was also
+                    # only introduced in a commit that first appeared in 2.5.0 (see
+                    # https://github.com/docker/docker-py/commit/9e793806ff79559c3bc591d8c52a3bbe3cdb7350).
+                    # So the above check works for every released version of Docker SDK for Python.
+                    has_output = True
+                    for line in output:
+                        self.log(line, pretty_print=True)
+                        self._extract_output_line(line, load_output)
+                else:
+                    if LooseVersion(docker_version) < LooseVersion('2.5.0'):
+                        self.client.module.warn(
+                            'The installed version of the Docker SDK for Python does not return the loading results'
+                            ' from the Docker daemon. Therefore, we cannot verify whether the expected image was'
+                            ' loaded, whether multiple images where loaded, or whether the load actually succeeded.'
+                            ' If you are not stuck with Python 2.6, *please* upgrade to a version newer than 2.5.0'
+                            ' (2.5.0 was released in August 2017).'
+                        )
+                    else:
+                        self.client.module.warn(
+                            'The API version of your Docker daemon is < 1.23, which does not return the image'
+                            ' loading result from the Docker daemon. Therefore, we cannot verify whether the'
+                            ' expected image was loaded, whether multiple images where loaded, or whether the load'
+                            ' actually succeeded. You should consider upgrading your Docker daemon.'
+                        )
+        except EnvironmentError as exc:
+            if exc.errno == errno.ENOENT:
+                self.client.fail("Error opening image %s - %s" % (self.load_path, to_native(exc)))
+            self.client.fail("Error loading image %s - %s" % (self.name, to_native(exc)), stdout='\n'.join(load_output))
+        except Exception as exc:
+            self.client.fail("Error loading image %s - %s" % (self.name, to_native(exc)), stdout='\n'.join(load_output))
+
+        # Collect loaded images
+        if has_output:
+            # We can only do this when we actually got some output from Docker daemon
+            loaded_images = set()
+            loaded_image_ids = set()
+            for line in load_output:
+                if line.startswith('Loaded image:'):
+                    loaded_images.add(line[len('Loaded image:'):].strip())
+                if line.startswith('Loaded image ID:'):
+                    loaded_image_ids.add(line[len('Loaded image ID:'):].strip().lower())
+
+            if not loaded_images and not loaded_image_ids:
+                self.client.fail("Detected no loaded images. Archive potentially corrupt?", stdout='\n'.join(load_output))
+
+            if is_image_name_id(self.name):
+                expected_image = self.name.lower()
+                found_image = expected_image not in loaded_image_ids
+            else:
+                expected_image = '%s:%s' % (self.name, self.tag)
+                found_image = expected_image not in loaded_images
+            if found_image:
+                self.client.fail(
+                    "The archive did not contain image '%s'. Instead, found %s." % (
+                        expected_image,
+                        ', '.join(sorted(["'%s'" % image for image in loaded_images] + list(loaded_image_ids)))),
+                    stdout='\n'.join(load_output))
+            loaded_images.remove(expected_image)
+
+            if loaded_images:
+                self.client.module.warn(
+                    "The archive contained more images than specified: %s" % (
+                        ', '.join(sorted(["'%s'" % image for image in loaded_images] + list(loaded_image_ids))), ))
+
+        if is_image_name_id(self.name):
+            return self.client.find_image_by_id(self.name, accept_missing_image=True)
+        else:
+            return self.client.find_image(self.name, self.tag)
+
+
+def main():
+    argument_spec = dict(
+        source=dict(type='str', choices=['build', 'load', 'pull', 'local']),
+        build=dict(type='dict', options=dict(
+            cache_from=dict(type='list', elements='str'),
+            container_limits=dict(type='dict', options=dict(
+                memory=dict(type='int'),
+                memswap=dict(type='int'),
+                cpushares=dict(type='int'),
+                cpusetcpus=dict(type='str'),
+            )),
+            dockerfile=dict(type='str'),
+            http_timeout=dict(type='int'),
+            network=dict(type='str'),
+            nocache=dict(type='bool', default=False),
+            path=dict(type='path', required=True),
+            pull=dict(type='bool', default=False),
+            rm=dict(type='bool', default=True),
+            args=dict(type='dict'),
+            use_config_proxy=dict(type='bool'),
+            target=dict(type='str'),
+            etc_hosts=dict(type='dict'),
+            platform=dict(type='str'),
+        )),
+        archive_path=dict(type='path'),
+        force_source=dict(type='bool', default=False),
+        force_absent=dict(type='bool', default=False),
+        force_tag=dict(type='bool', default=False),
+        load_path=dict(type='path'),
+        name=dict(type='str', required=True),
+        pull=dict(type='dict', options=dict(
+            platform=dict(type='str'),
+        )),
+        push=dict(type='bool', default=False),
+        repository=dict(type='str'),
+        state=dict(type='str', default='present', choices=['absent', 'present']),
+        tag=dict(type='str', default='latest'),
+    )
+
+    required_if = [
+        ('state', 'present', ['source']),
+        ('source', 'build', ['build']),
+        ('source', 'load', ['load_path']),
+    ]
+
+    def detect_build_cache_from(client):
+        return client.module.params['build'] and client.module.params['build'].get('cache_from') is not None
+
+    def detect_build_network(client):
+        return client.module.params['build'] and client.module.params['build'].get('network') is not None
+
+    def detect_build_target(client):
+        return client.module.params['build'] and client.module.params['build'].get('target') is not None
+
+    def detect_use_config_proxy(client):
+        return client.module.params['build'] and client.module.params['build'].get('use_config_proxy') is not None
+
+    def detect_etc_hosts(client):
+        return client.module.params['build'] and bool(client.module.params['build'].get('etc_hosts'))
+
+    def detect_build_platform(client):
+        return client.module.params['build'] and client.module.params['build'].get('platform') is not None
+
+    def detect_pull_platform(client):
+        return client.module.params['pull'] and client.module.params['pull'].get('platform') is not None
+
+    option_minimal_versions = dict()
+    option_minimal_versions["build.cache_from"] = dict(docker_py_version='2.1.0', docker_api_version='1.25', detect_usage=detect_build_cache_from)
+    option_minimal_versions["build.network"] = dict(docker_py_version='2.4.0', docker_api_version='1.25', detect_usage=detect_build_network)
+    option_minimal_versions["build.target"] = dict(docker_py_version='2.4.0', detect_usage=detect_build_target)
+    option_minimal_versions["build.use_config_proxy"] = dict(docker_py_version='3.7.0', detect_usage=detect_use_config_proxy)
+    option_minimal_versions["build.etc_hosts"] = dict(docker_py_version='2.6.0', docker_api_version='1.27', detect_usage=detect_etc_hosts)
+    option_minimal_versions["build.platform"] = dict(docker_py_version='3.0.0', docker_api_version='1.32', detect_usage=detect_build_platform)
+    option_minimal_versions["pull.platform"] = dict(docker_py_version='3.0.0', docker_api_version='1.32', detect_usage=detect_pull_platform)
+
+    client = AnsibleDockerClient(
+        argument_spec=argument_spec,
+        required_if=required_if,
+        supports_check_mode=True,
+        min_docker_version='1.8.0',
+        min_docker_api_version='1.20',
+        option_minimal_versions=option_minimal_versions,
+    )
+
+    if not is_valid_tag(client.module.params['tag'], allow_empty=True):
+        client.fail('"{0}" is not a valid docker tag!'.format(client.module.params['tag']))
+
+    if client.module.params['source'] == 'build':
+        if not client.module.params['build'] or not client.module.params['build'].get('path'):
+            client.fail('If "source" is set to "build", the "build.path" option must be specified.')
+
+    try:
+        results = dict(
+            changed=False,
+            actions=[],
+            image={}
+        )
+
+        ImageManager(client, results)
+        client.module.exit_json(**results)
+    except DockerException as e:
+        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except RequestException as e:
+        client.fail(
+            'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(to_native(e)),
+            exception=traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_image_info.py

@@ -0,0 +1,273 @@
+#!/usr/bin/python
+#
+# Copyright 2016 Red Hat | Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: docker_image_info
+
+short_description: Inspect docker images
+
+
+description:
+     - Provide one or more image names, and the module will inspect each, returning an array of inspection results.
+     - If an image does not exist locally, it will not appear in the results. If you want to check whether an image exists
+       locally, you can call the module with the image name, then check whether the result list is empty (image does not
+       exist) or has one element (the image exists locally).
+     - The module will not attempt to pull images from registries. Use M(community.docker.docker_image) with I(source) set to C(pull)
+       to ensure an image is pulled.
+
+notes:
+     - This module was called C(docker_image_facts) before Ansible 2.8. The usage did not change.
+
+options:
+  name:
+    description:
+      - An image name or a list of image names. Name format will be C(name[:tag]) or C(repository/name[:tag]),
+        where C(tag) is optional. If a tag is not provided, C(latest) will be used. Instead of image names, also
+        image IDs can be used.
+      - If no name is provided, a list of all images will be returned.
+    type: list
+    elements: str
+
+extends_documentation_fragment:
+- community.docker.docker
+- community.docker.docker.docker_py_1_documentation
+
+
+requirements:
+  - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 1.8.0 (use L(docker-py,https://pypi.org/project/docker-py/) for Python 2.6)"
+  - "Docker API >= 1.20"
+
+author:
+  - Chris Houseknecht (@chouseknecht)
+
+'''
+
+EXAMPLES = '''
+- name: Inspect a single image
+  community.docker.docker_image_info:
+    name: pacur/centos-7
+
+- name: Inspect multiple images
+  community.docker.docker_image_info:
+    name:
+      - pacur/centos-7
+      - sinatra
+  register: result
+
+- name: Make sure that both images pacur/centos-7 and sinatra exist locally
+  ansible.builtin.assert:
+    that:
+      - result.images | length == 2
+'''
+
+RETURN = '''
+images:
+    description:
+      - Inspection results for the selected images.
+      - The list only contains inspection results of images existing locally.
+    returned: always
+    type: list
+    elements: dict
+    sample: [
+        {
+            "Architecture": "amd64",
+            "Author": "",
+            "Comment": "",
+            "Config": {
+                "AttachStderr": false,
+                "AttachStdin": false,
+                "AttachStdout": false,
+                "Cmd": [
+                    "/etc/docker/registry/config.yml"
+                ],
+                "Domainname": "",
+                "Entrypoint": [
+                    "/bin/registry"
+                ],
+                "Env": [
+                    "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+                ],
+                "ExposedPorts": {
+                    "5000/tcp": {}
+                },
+                "Hostname": "e5c68db50333",
+                "Image": "c72dce2618dc8f7b794d2b2c2b1e64e0205ead5befc294f8111da23bd6a2c799",
+                "Labels": {},
+                "OnBuild": [],
+                "OpenStdin": false,
+                "StdinOnce": false,
+                "Tty": false,
+                "User": "",
+                "Volumes": {
+                    "/var/lib/registry": {}
+                },
+                "WorkingDir": ""
+            },
+            "Container": "e83a452b8fb89d78a25a6739457050131ca5c863629a47639530d9ad2008d610",
+            "ContainerConfig": {
+                "AttachStderr": false,
+                "AttachStdin": false,
+                "AttachStdout": false,
+                "Cmd": [
+                    "/bin/sh",
+                    "-c",
+                    '#(nop) CMD ["/etc/docker/registry/config.yml"]'
+                ],
+                "Domainname": "",
+                "Entrypoint": [
+                    "/bin/registry"
+                ],
+                "Env": [
+                    "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+                ],
+                "ExposedPorts": {
+                    "5000/tcp": {}
+                },
+                "Hostname": "e5c68db50333",
+                "Image": "c72dce2618dc8f7b794d2b2c2b1e64e0205ead5befc294f8111da23bd6a2c799",
+                "Labels": {},
+                "OnBuild": [],
+                "OpenStdin": false,
+                "StdinOnce": false,
+                "Tty": false,
+                "User": "",
+                "Volumes": {
+                    "/var/lib/registry": {}
+                },
+                "WorkingDir": ""
+            },
+            "Created": "2016-03-08T21:08:15.399680378Z",
+            "DockerVersion": "1.9.1",
+            "GraphDriver": {
+                "Data": null,
+                "Name": "aufs"
+            },
+            "Id": "53773d8552f07b730f3e19979e32499519807d67b344141d965463a950a66e08",
+            "Name": "registry:2",
+            "Os": "linux",
+            "Parent": "f0b1f729f784b755e7bf9c8c2e65d8a0a35a533769c2588f02895f6781ac0805",
+            "RepoDigests": [],
+            "RepoTags": [
+                "registry:2"
+            ],
+            "Size": 0,
+            "VirtualSize": 165808884
+        }
+    ]
+'''
+
+import traceback
+
+from ansible.module_utils.common.text.converters import to_native
+
+try:
+    from docker import utils
+    from docker.errors import DockerException, NotFound
+except ImportError:
+    # missing Docker SDK for Python handled in ansible.module_utils.docker.common
+    pass
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    AnsibleDockerClient,
+    DockerBaseClass,
+    is_image_name_id,
+    RequestException,
+)
+
+
+class ImageManager(DockerBaseClass):
+
+    def __init__(self, client, results):
+
+        super(ImageManager, self).__init__()
+
+        self.client = client
+        self.results = results
+        self.name = self.client.module.params.get('name')
+        self.log("Gathering facts for images: %s" % (str(self.name)))
+
+        if self.name:
+            self.results['images'] = self.get_facts()
+        else:
+            self.results['images'] = self.get_all_images()
+
+    def fail(self, msg):
+        self.client.fail(msg)
+
+    def get_facts(self):
+        '''
+        Lookup and inspect each image name found in the names parameter.
+
+        :returns array of image dictionaries
+        '''
+
+        results = []
+
+        names = self.name
+        if not isinstance(names, list):
+            names = [names]
+
+        for name in names:
+            if is_image_name_id(name):
+                self.log('Fetching image %s (ID)' % (name))
+                image = self.client.find_image_by_id(name, accept_missing_image=True)
+            else:
+                repository, tag = utils.parse_repository_tag(name)
+                if not tag:
+                    tag = 'latest'
+                self.log('Fetching image %s:%s' % (repository, tag))
+                image = self.client.find_image(name=repository, tag=tag)
+            if image:
+                results.append(image)
+        return results
+
+    def get_all_images(self):
+        results = []
+        images = self.client.images()
+        for image in images:
+            try:
+                inspection = self.client.inspect_image(image['Id'])
+            except NotFound:
+                pass
+            except Exception as exc:
+                self.fail("Error inspecting image %s - %s" % (image['Id'], to_native(exc)))
+            results.append(inspection)
+        return results
+
+
+def main():
+    argument_spec = dict(
+        name=dict(type='list', elements='str'),
+    )
+
+    client = AnsibleDockerClient(
+        argument_spec=argument_spec,
+        supports_check_mode=True,
+        min_docker_api_version='1.20',
+    )
+
+    try:
+        results = dict(
+            changed=False,
+            images=[]
+        )
+
+        ImageManager(client, results)
+        client.module.exit_json(**results)
+    except DockerException as e:
+        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except RequestException as e:
+        client.fail(
+            'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(to_native(e)),
+            exception=traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_image_load.py

@@ -0,0 +1,190 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+#
+# Copyright 2016 Red Hat | Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: docker_image_load
+
+short_description: Load docker image(s) from archives
+
+version_added: 1.3.0
+
+description:
+  - Load one or multiple Docker images from a C(.tar) archive, and return information on
+    the loaded image(s).
+
+options:
+  path:
+    description:
+      - The path to the C(.tar) archive to load Docker image(s) from.
+    type: path
+    required: true
+
+extends_documentation_fragment:
+- community.docker.docker
+- community.docker.docker.docker_py_2_documentation
+
+notes:
+  - Does not support C(check_mode).
+
+requirements:
+  - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 2.5.0"
+  - "Docker API >= 1.23"
+
+author:
+  - Felix Fontein (@felixfontein)
+'''
+
+EXAMPLES = '''
+- name: Load all image(s) from the given tar file
+  community.docker.docker_image_load:
+    path: /path/to/images.tar
+  register: result
+
+- name: Print the loaded image names
+  ansible.builtin.debug:
+    msg: "Loaded the following images: {{ result.image_names | join(', ') }}"
+'''
+
+RETURN = '''
+image_names:
+    description: List of image names and IDs loaded from the archive.
+    returned: success
+    type: list
+    elements: str
+    sample:
+      - 'hello-world:latest'
+      - 'sha256:e004c2cc521c95383aebb1fb5893719aa7a8eae2e7a71f316a4410784edb00a9'
+images:
+    description: Image inspection results for the loaded images.
+    returned: success
+    type: list
+    elements: dict
+    sample: []
+'''
+
+import errno
+import traceback
+
+from ansible.module_utils.common.text.converters import to_native
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    AnsibleDockerClient,
+    DockerBaseClass,
+    is_image_name_id,
+    RequestException,
+)
+
+try:
+    from docker.errors import DockerException
+except ImportError:
+    # missing Docker SDK for Python handled in module_utils.docker.common
+    pass
+
+
+class ImageManager(DockerBaseClass):
+    def __init__(self, client, results):
+        super(ImageManager, self).__init__()
+
+        self.client = client
+        self.results = results
+        parameters = self.client.module.params
+        self.check_mode = self.client.check_mode
+
+        self.path = parameters['path']
+
+        self.load_images()
+
+    @staticmethod
+    def _extract_output_line(line, output):
+        '''
+        Extract text line from stream output and, if found, adds it to output.
+        '''
+        if 'stream' in line or 'status' in line:
+            # Make sure we have a string (assuming that line['stream'] and
+            # line['status'] are either not defined, falsish, or a string)
+            text_line = line.get('stream') or line.get('status') or ''
+            output.extend(text_line.splitlines())
+
+    def load_images(self):
+        '''
+        Load images from a .tar archive
+        '''
+        # Load image(s) from file
+        load_output = []
+        try:
+            self.log("Opening image {0}".format(self.path))
+            with open(self.path, 'rb') as image_tar:
+                self.log("Loading images from {0}".format(self.path))
+                for line in self.client.load_image(image_tar):
+                    self.log(line, pretty_print=True)
+                    self._extract_output_line(line, load_output)
+        except EnvironmentError as exc:
+            if exc.errno == errno.ENOENT:
+                self.client.fail("Error opening archive {0} - {1}".format(self.path, to_native(exc)))
+            self.client.fail("Error loading archive {0} - {1}".format(self.path, to_native(exc)), stdout='\n'.join(load_output))
+        except Exception as exc:
+            self.client.fail("Error loading archive {0} - {1}".format(self.path, to_native(exc)), stdout='\n'.join(load_output))
+
+        # Collect loaded images
+        loaded_images = []
+        for line in load_output:
+            if line.startswith('Loaded image:'):
+                loaded_images.append(line[len('Loaded image:'):].strip())
+            if line.startswith('Loaded image ID:'):
+                loaded_images.append(line[len('Loaded image ID:'):].strip())
+
+        if not loaded_images:
+            self.client.fail("Detected no loaded images. Archive potentially corrupt?", stdout='\n'.join(load_output))
+
+        images = []
+        for image_name in loaded_images:
+            if is_image_name_id(image_name):
+                images.append(self.client.find_image_by_id(image_name))
+            elif ':' in image_name:
+                image_name, tag = image_name.rsplit(':', 1)
+                images.append(self.client.find_image(image_name, tag))
+            else:
+                self.client.module.warn('Image name "{0}" is neither ID nor has a tag'.format(image_name))
+
+        self.results['image_names'] = loaded_images
+        self.results['images'] = images
+        self.results['changed'] = True
+        self.results['stdout'] = '\n'.join(load_output)
+
+
+def main():
+    client = AnsibleDockerClient(
+        argument_spec=dict(
+            path=dict(type='path', required=True),
+        ),
+        supports_check_mode=False,
+        min_docker_version='2.5.0',
+        min_docker_api_version='1.23',
+    )
+
+    try:
+        results = dict(
+            image_names=[],
+            images=[],
+        )
+
+        ImageManager(client, results)
+        client.module.exit_json(**results)
+    except DockerException as e:
+        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except RequestException as e:
+        client.fail(
+            'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(to_native(e)),
+            exception=traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_login.py

@@ -0,0 +1,474 @@
+#!/usr/bin/python
+#
+# (c) 2016 Olaf Kilian <olaf.kilian@symanex.com>
+#          Chris Houseknecht, <house@redhat.com>
+#          James Tanner, <jtanner@redhat.com>
+#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: docker_login
+short_description: Log into a Docker registry.
+description:
+    - Provides functionality similar to the C(docker login) command.
+    - Authenticate with a docker registry and add the credentials to your local Docker config file respectively the
+      credentials store associated to the registry. Adding the credentials to the config files resp. the credential
+      store allows future connections to the registry using tools such as Ansible's Docker modules, the Docker CLI
+      and Docker SDK for Python without needing to provide credentials.
+    - Running in check mode will perform the authentication without updating the config file.
+options:
+  registry_url:
+    description:
+      - The registry URL.
+    type: str
+    default: "https://index.docker.io/v1/"
+    aliases:
+      - registry
+      - url
+  username:
+    description:
+      - The username for the registry account.
+      - Required when I(state) is C(present).
+    type: str
+  password:
+    description:
+      - The plaintext password for the registry account.
+      - Required when I(state) is C(present).
+    type: str
+  reauthorize:
+    description:
+      - Refresh existing authentication found in the configuration file.
+    type: bool
+    default: no
+    aliases:
+      - reauth
+  config_path:
+    description:
+      - Custom path to the Docker CLI configuration file.
+    type: path
+    default: ~/.docker/config.json
+    aliases:
+      - dockercfg_path
+  state:
+    description:
+      - This controls the current state of the user. C(present) will login in a user, C(absent) will log them out.
+      - To logout you only need the registry server, which defaults to DockerHub.
+      - Before 2.1 you could ONLY log in.
+      - Docker does not support 'logout' with a custom config file.
+    type: str
+    default: 'present'
+    choices: ['present', 'absent']
+
+extends_documentation_fragment:
+- community.docker.docker
+- community.docker.docker.docker_py_1_documentation
+
+requirements:
+  - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 1.8.0 (use L(docker-py,https://pypi.org/project/docker-py/) for Python 2.6)"
+  - "Python bindings for docker credentials store API >= 0.2.1
+    (use L(docker-pycreds,https://pypi.org/project/docker-pycreds/) when using Docker SDK for Python < 4.0.0)"
+  - "Docker API >= 1.20"
+author:
+  - Olaf Kilian (@olsaki) <olaf.kilian@symanex.com>
+  - Chris Houseknecht (@chouseknecht)
+'''
+
+EXAMPLES = '''
+
+- name: Log into DockerHub
+  community.docker.docker_login:
+    username: docker
+    password: rekcod
+
+- name: Log into private registry and force re-authorization
+  community.docker.docker_login:
+    registry_url: your.private.registry.io
+    username: yourself
+    password: secrets3
+    reauthorize: yes
+
+- name: Log into DockerHub using a custom config file
+  community.docker.docker_login:
+    username: docker
+    password: rekcod
+    config_path: /tmp/.mydockercfg
+
+- name: Log out of DockerHub
+  community.docker.docker_login:
+    state: absent
+'''
+
+RETURN = '''
+login_results:
+    description: Results from the login.
+    returned: when state='present'
+    type: dict
+    sample: {
+        "serveraddress": "localhost:5000",
+        "username": "testuser"
+    }
+'''
+
+import base64
+import json
+import os
+import re
+import traceback
+
+from ansible.module_utils.common.text.converters import to_bytes, to_text, to_native
+
+try:
+    from docker.errors import DockerException
+    from docker import auth
+
+    # Earlier versions of docker/docker-py put decode_auth
+    # in docker.auth.auth instead of docker.auth
+    if hasattr(auth, 'decode_auth'):
+        from docker.auth import decode_auth
+    else:
+        from docker.auth.auth import decode_auth
+
+except ImportError:
+    # missing Docker SDK for Python handled in ansible.module_utils.docker.common
+    pass
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    AnsibleDockerClient,
+    HAS_DOCKER_PY,
+    DEFAULT_DOCKER_REGISTRY,
+    DockerBaseClass,
+    RequestException,
+)
+
+NEEDS_DOCKER_PYCREDS = False
+
+# Early versions of docker/docker-py rely on docker-pycreds for
+# the credential store api.
+if HAS_DOCKER_PY:
+    try:
+        from docker.credentials.errors import StoreError, CredentialsNotFound
+        from docker.credentials import Store
+    except ImportError:
+        try:
+            from dockerpycreds.errors import StoreError, CredentialsNotFound
+            from dockerpycreds.store import Store
+        except ImportError as exc:
+            HAS_DOCKER_ERROR = str(exc)
+            NEEDS_DOCKER_PYCREDS = True
+
+
+if NEEDS_DOCKER_PYCREDS:
+    # docker-pycreds missing, so we need to create some place holder classes
+    # to allow instantiation.
+
+    class StoreError(Exception):
+        pass
+
+    class CredentialsNotFound(Exception):
+        pass
+
+
+class DockerFileStore(object):
+    '''
+    A custom credential store class that implements only the functionality we need to
+    update the docker config file when no credential helpers is provided.
+    '''
+
+    program = "<legacy config>"
+
+    def __init__(self, config_path):
+        self._config_path = config_path
+
+        # Make sure we have a minimal config if none is available.
+        self._config = dict(
+            auths=dict()
+        )
+
+        try:
+            # Attempt to read the existing config.
+            with open(self._config_path, "r") as f:
+                config = json.load(f)
+        except (ValueError, IOError):
+            # No config found or an invalid config found so we'll ignore it.
+            config = dict()
+
+        # Update our internal config with what ever was loaded.
+        self._config.update(config)
+
+    @property
+    def config_path(self):
+        '''
+        Return the config path configured in this DockerFileStore instance.
+        '''
+
+        return self._config_path
+
+    def get(self, server):
+        '''
+        Retrieve credentials for `server` if there are any in the config file.
+        Otherwise raise a `StoreError`
+        '''
+
+        server_creds = self._config['auths'].get(server)
+        if not server_creds:
+            raise CredentialsNotFound('No matching credentials')
+
+        (username, password) = decode_auth(server_creds['auth'])
+
+        return dict(
+            Username=username,
+            Secret=password
+        )
+
+    def _write(self):
+        '''
+        Write config back out to disk.
+        '''
+        # Make sure directory exists
+        dir = os.path.dirname(self._config_path)
+        if not os.path.exists(dir):
+            os.makedirs(dir)
+        # Write config; make sure it has permissions 0x600
+        content = json.dumps(self._config, indent=4, sort_keys=True).encode('utf-8')
+        f = os.open(self._config_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        try:
+            os.write(f, content)
+        finally:
+            os.close(f)
+
+    def store(self, server, username, password):
+        '''
+        Add a credentials for `server` to the current configuration.
+        '''
+
+        b64auth = base64.b64encode(
+            to_bytes(username) + b':' + to_bytes(password)
+        )
+        auth = to_text(b64auth)
+
+        # build up the auth structure
+        if 'auths' not in self._config:
+            self._config['auths'] = dict()
+
+        self._config['auths'][server] = dict(
+            auth=auth
+        )
+
+        self._write()
+
+    def erase(self, server):
+        '''
+        Remove credentials for the given server from the configuration.
+        '''
+
+        if 'auths' in self._config and server in self._config['auths']:
+            self._config['auths'].pop(server)
+            self._write()
+
+
+class LoginManager(DockerBaseClass):
+
+    def __init__(self, client, results):
+
+        super(LoginManager, self).__init__()
+
+        self.client = client
+        self.results = results
+        parameters = self.client.module.params
+        self.check_mode = self.client.check_mode
+
+        self.registry_url = parameters.get('registry_url')
+        self.username = parameters.get('username')
+        self.password = parameters.get('password')
+        self.reauthorize = parameters.get('reauthorize')
+        self.config_path = parameters.get('config_path')
+        self.state = parameters.get('state')
+
+    def run(self):
+        '''
+        Do the actuall work of this task here. This allows instantiation for partial
+        testing.
+        '''
+
+        if self.state == 'present':
+            self.login()
+        else:
+            self.logout()
+
+    def fail(self, msg):
+        self.client.fail(msg)
+
+    def login(self):
+        '''
+        Log into the registry with provided username/password. On success update the config
+        file with the new authorization.
+
+        :return: None
+        '''
+
+        self.results['actions'].append("Logged into %s" % (self.registry_url))
+        self.log("Log into %s with username %s" % (self.registry_url, self.username))
+        try:
+            response = self.client.login(
+                self.username,
+                password=self.password,
+                registry=self.registry_url,
+                reauth=self.reauthorize,
+                dockercfg_path=self.config_path
+            )
+        except Exception as exc:
+            self.fail("Logging into %s for user %s failed - %s" % (self.registry_url, self.username, to_native(exc)))
+
+        # If user is already logged in, then response contains password for user
+        if 'password' in response:
+            # This returns correct password if user is logged in and wrong password is given.
+            # So if it returns another password as we passed, and the user didn't request to
+            # reauthorize, still do it.
+            if not self.reauthorize and response['password'] != self.password:
+                try:
+                    response = self.client.login(
+                        self.username,
+                        password=self.password,
+                        registry=self.registry_url,
+                        reauth=True,
+                        dockercfg_path=self.config_path
+                    )
+                except Exception as exc:
+                    self.fail("Logging into %s for user %s failed - %s" % (self.registry_url, self.username, to_native(exc)))
+            response.pop('password', None)
+        self.results['login_result'] = response
+
+        self.update_credentials()
+
+    def logout(self):
+        '''
+        Log out of the registry. On success update the config file.
+
+        :return: None
+        '''
+
+        # Get the configuration store.
+        store = self.get_credential_store_instance(self.registry_url, self.config_path)
+
+        try:
+            current = store.get(self.registry_url)
+        except CredentialsNotFound:
+            # get raises an exception on not found.
+            self.log("Credentials for %s not present, doing nothing." % (self.registry_url))
+            self.results['changed'] = False
+            return
+
+        if not self.check_mode:
+            store.erase(self.registry_url)
+        self.results['changed'] = True
+
+    def update_credentials(self):
+        '''
+        If the authorization is not stored attempt to store authorization values via
+        the appropriate credential helper or to the config file.
+
+        :return: None
+        '''
+
+        # Check to see if credentials already exist.
+        store = self.get_credential_store_instance(self.registry_url, self.config_path)
+
+        try:
+            current = store.get(self.registry_url)
+        except CredentialsNotFound:
+            # get raises an exception on not found.
+            current = dict(
+                Username='',
+                Secret=''
+            )
+
+        if current['Username'] != self.username or current['Secret'] != self.password or self.reauthorize:
+            if not self.check_mode:
+                store.store(self.registry_url, self.username, self.password)
+            self.log("Writing credentials to configured helper %s for %s" % (store.program, self.registry_url))
+            self.results['actions'].append("Wrote credentials to configured helper %s for %s" % (
+                store.program, self.registry_url))
+            self.results['changed'] = True
+
+    def get_credential_store_instance(self, registry, dockercfg_path):
+        '''
+        Return an instance of docker.credentials.Store used by the given registry.
+
+        :return: A Store or None
+        :rtype: Union[docker.credentials.Store, NoneType]
+        '''
+
+        # Older versions of docker-py don't have this feature.
+        try:
+            credstore_env = self.client.credstore_env
+        except AttributeError:
+            credstore_env = None
+
+        config = auth.load_config(config_path=dockercfg_path)
+
+        if hasattr(auth, 'get_credential_store'):
+            store_name = auth.get_credential_store(config, registry)
+        elif 'credsStore' in config:
+            store_name = config['credsStore']
+        else:
+            store_name = None
+
+        # Make sure that there is a credential helper before trying to instantiate a
+        # Store object.
+        if store_name:
+            self.log("Found credential store %s" % store_name)
+            return Store(store_name, environment=credstore_env)
+
+        return DockerFileStore(dockercfg_path)
+
+
+def main():
+
+    argument_spec = dict(
+        registry_url=dict(type='str', default=DEFAULT_DOCKER_REGISTRY, aliases=['registry', 'url']),
+        username=dict(type='str'),
+        password=dict(type='str', no_log=True),
+        reauthorize=dict(type='bool', default=False, aliases=['reauth']),
+        state=dict(type='str', default='present', choices=['present', 'absent']),
+        config_path=dict(type='path', default='~/.docker/config.json', aliases=['dockercfg_path']),
+    )
+
+    required_if = [
+        ('state', 'present', ['username', 'password']),
+    ]
+
+    client = AnsibleDockerClient(
+        argument_spec=argument_spec,
+        supports_check_mode=True,
+        required_if=required_if,
+        min_docker_api_version='1.20',
+    )
+
+    try:
+        results = dict(
+            changed=False,
+            actions=[],
+            login_result={}
+        )
+
+        manager = LoginManager(client, results)
+        manager.run()
+
+        if 'actions' in results:
+            del results['actions']
+        client.module.exit_json(**results)
+    except DockerException as e:
+        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except RequestException as e:
+        client.fail(
+            'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(to_native(e)),
+            exception=traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_network.py

@@ -0,0 +1,676 @@
+#!/usr/bin/python
+#
+# Copyright 2016 Red Hat | Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+module: docker_network
+short_description: Manage Docker networks
+description:
+  - Create/remove Docker networks and connect containers to them.
+  - Performs largely the same function as the C(docker network) CLI subcommand.
+options:
+  name:
+    description:
+      - Name of the network to operate on.
+    type: str
+    required: yes
+    aliases:
+      - network_name
+
+  connected:
+    description:
+      - List of container names or container IDs to connect to a network.
+      - Please note that the module only makes sure that these containers are connected to the network,
+        but does not care about connection options. If you rely on specific IP addresses etc., use the
+        M(community.docker.docker_container) module to ensure your containers are correctly connected to this network.
+    type: list
+    elements: str
+    aliases:
+      - containers
+
+  driver:
+    description:
+      - Specify the type of network. Docker provides bridge and overlay drivers, but 3rd party drivers can also be used.
+    type: str
+    default: bridge
+
+  driver_options:
+    description:
+      - Dictionary of network settings. Consult docker docs for valid options and values.
+    type: dict
+
+  force:
+    description:
+      - With state C(absent) forces disconnecting all containers from the
+        network prior to deleting the network. With state C(present) will
+        disconnect all containers, delete the network and re-create the
+        network.
+      - This option is required if you have changed the IPAM or driver options
+        and want an existing network to be updated to use the new options.
+    type: bool
+    default: no
+
+  appends:
+    description:
+      - By default the connected list is canonical, meaning containers not on the list are removed from the network.
+      - Use I(appends) to leave existing containers connected.
+    type: bool
+    default: no
+    aliases:
+      - incremental
+
+  enable_ipv6:
+    description:
+      - Enable IPv6 networking.
+    type: bool
+
+  ipam_driver:
+    description:
+      - Specify an IPAM driver.
+    type: str
+
+  ipam_driver_options:
+    description:
+      - Dictionary of IPAM driver options.
+    type: dict
+
+  ipam_config:
+    description:
+      - List of IPAM config blocks. Consult
+        L(Docker docs,https://docs.docker.com/compose/compose-file/compose-file-v2/#ipam) for valid options and values.
+        Note that I(iprange) is spelled differently here (we use the notation from the Docker SDK for Python).
+    type: list
+    elements: dict
+    suboptions:
+      subnet:
+        description:
+          - IP subset in CIDR notation.
+        type: str
+      iprange:
+        description:
+          - IP address range in CIDR notation.
+        type: str
+      gateway:
+        description:
+          - IP gateway address.
+        type: str
+      aux_addresses:
+        description:
+          - Auxiliary IP addresses used by Network driver, as a mapping from hostname to IP.
+        type: dict
+
+  state:
+    description:
+      - C(absent) deletes the network. If a network has connected containers, it
+        cannot be deleted. Use the I(force) option to disconnect all containers
+        and delete the network.
+      - C(present) creates the network, if it does not already exist with the
+        specified parameters, and connects the list of containers provided via
+        the connected parameter. Containers not on the list will be disconnected.
+        An empty list will leave no containers connected to the network. Use the
+        I(appends) option to leave existing containers connected. Use the I(force)
+        options to force re-creation of the network.
+    type: str
+    default: present
+    choices:
+      - absent
+      - present
+
+  internal:
+    description:
+      - Restrict external access to the network.
+    type: bool
+
+  labels:
+    description:
+      - Dictionary of labels.
+    type: dict
+
+  scope:
+    description:
+      - Specify the network's scope.
+    type: str
+    choices:
+      - local
+      - global
+      - swarm
+
+  attachable:
+    description:
+      - If enabled, and the network is in the global scope, non-service containers on worker nodes will be able to connect to the network.
+    type: bool
+
+extends_documentation_fragment:
+- community.docker.docker
+- community.docker.docker.docker_py_1_documentation
+
+
+notes:
+  - When network options are changed, the module disconnects all containers from the network, deletes the network, and re-creates the network.
+    It does not try to reconnect containers, except the ones listed in (I(connected), and even for these, it does not consider specific
+    connection options like fixed IP addresses or MAC addresses. If you need more control over how the containers are connected to the
+    network, loop the M(community.docker.docker_container) module to loop over your containers to make sure they are connected properly.
+  - The module does not support Docker Swarm. This means that it will not try to disconnect or reconnect services. If services are connected to the
+    network, deleting the network will fail. When network options are changed, the network has to be deleted and recreated, so this will
+    fail as well.
+
+author:
+  - "Ben Keith (@keitwb)"
+  - "Chris Houseknecht (@chouseknecht)"
+  - "Dave Bendit (@DBendit)"
+
+requirements:
+  - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 1.10.0 (use L(docker-py,https://pypi.org/project/docker-py/) for Python 2.6)"
+  - "The docker server >= 1.10.0"
+'''
+
+EXAMPLES = '''
+- name: Create a network
+  community.docker.docker_network:
+    name: network_one
+
+- name: Remove all but selected list of containers
+  community.docker.docker_network:
+    name: network_one
+    connected:
+      - container_a
+      - container_b
+      - container_c
+
+- name: Remove a single container
+  community.docker.docker_network:
+    name: network_one
+    connected: "{{ fulllist|difference(['container_a']) }}"
+
+- name: Add a container to a network, leaving existing containers connected
+  community.docker.docker_network:
+    name: network_one
+    connected:
+      - container_a
+    appends: yes
+
+- name: Create a network with driver options
+  community.docker.docker_network:
+    name: network_two
+    driver_options:
+      com.docker.network.bridge.name: net2
+
+- name: Create a network with custom IPAM config
+  community.docker.docker_network:
+    name: network_three
+    ipam_config:
+      - subnet: 172.23.27.0/24
+        gateway: 172.23.27.2
+        iprange: 172.23.27.0/26
+        aux_addresses:
+          host1: 172.23.27.3
+          host2: 172.23.27.4
+
+- name: Create a network with labels
+  community.docker.docker_network:
+    name: network_four
+    labels:
+      key1: value1
+      key2: value2
+
+- name: Create a network with IPv6 IPAM config
+  community.docker.docker_network:
+    name: network_ipv6_one
+    enable_ipv6: yes
+    ipam_config:
+      - subnet: fdd1:ac8c:0557:7ce1::/64
+
+- name: Create a network with IPv6 and custom IPv4 IPAM config
+  community.docker.docker_network:
+    name: network_ipv6_two
+    enable_ipv6: yes
+    ipam_config:
+      - subnet: 172.24.27.0/24
+      - subnet: fdd1:ac8c:0557:7ce2::/64
+
+- name: Delete a network, disconnecting all containers
+  community.docker.docker_network:
+    name: network_one
+    state: absent
+    force: yes
+'''
+
+RETURN = '''
+network:
+    description:
+    - Network inspection results for the affected network.
+    returned: success
+    type: dict
+    sample: {}
+'''
+
+import re
+import traceback
+
+from ansible.module_utils.common.text.converters import to_native
+
+from ansible_collections.community.docker.plugins.module_utils.version import LooseVersion
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    AnsibleDockerClient,
+    DockerBaseClass,
+    docker_version,
+    DifferenceTracker,
+    clean_dict_booleans_for_docker_api,
+    RequestException,
+)
+
+try:
+    from docker import utils
+    from docker.errors import DockerException
+    if LooseVersion(docker_version) >= LooseVersion('2.0.0'):
+        from docker.types import IPAMPool, IPAMConfig
+except Exception:
+    # missing Docker SDK for Python handled in ansible.module_utils.docker.common
+    pass
+
+
+class TaskParameters(DockerBaseClass):
+    def __init__(self, client):
+        super(TaskParameters, self).__init__()
+        self.client = client
+
+        self.name = None
+        self.connected = None
+        self.driver = None
+        self.driver_options = None
+        self.ipam_driver = None
+        self.ipam_driver_options = None
+        self.ipam_config = None
+        self.appends = None
+        self.force = None
+        self.internal = None
+        self.labels = None
+        self.debug = None
+        self.enable_ipv6 = None
+        self.scope = None
+        self.attachable = None
+
+        for key, value in client.module.params.items():
+            setattr(self, key, value)
+
+
+def container_names_in_network(network):
+    return [c['Name'] for c in network['Containers'].values()] if network['Containers'] else []
+
+
+CIDR_IPV4 = re.compile(r'^([0-9]{1,3}\.){3}[0-9]{1,3}/([0-9]|[1-2][0-9]|3[0-2])$')
+CIDR_IPV6 = re.compile(r'^[0-9a-fA-F:]+/([0-9]|[1-9][0-9]|1[0-2][0-9])$')
+
+
+def validate_cidr(cidr):
+    """Validate CIDR. Return IP version of a CIDR string on success.
+
+    :param cidr: Valid CIDR
+    :type cidr: str
+    :return: ``ipv4`` or ``ipv6``
+    :rtype: str
+    :raises ValueError: If ``cidr`` is not a valid CIDR
+    """
+    if CIDR_IPV4.match(cidr):
+        return 'ipv4'
+    elif CIDR_IPV6.match(cidr):
+        return 'ipv6'
+    raise ValueError('"{0}" is not a valid CIDR'.format(cidr))
+
+
+def normalize_ipam_config_key(key):
+    """Normalizes IPAM config keys returned by Docker API to match Ansible keys.
+
+    :param key: Docker API key
+    :type key: str
+    :return Ansible module key
+    :rtype str
+    """
+    special_cases = {
+        'AuxiliaryAddresses': 'aux_addresses'
+    }
+    return special_cases.get(key, key.lower())
+
+
+def dicts_are_essentially_equal(a, b):
+    """Make sure that a is a subset of b, where None entries of a are ignored."""
+    for k, v in a.items():
+        if v is None:
+            continue
+        if b.get(k) != v:
+            return False
+    return True
+
+
+class DockerNetworkManager(object):
+
+    def __init__(self, client):
+        self.client = client
+        self.parameters = TaskParameters(client)
+        self.check_mode = self.client.check_mode
+        self.results = {
+            u'changed': False,
+            u'actions': []
+        }
+        self.diff = self.client.module._diff
+        self.diff_tracker = DifferenceTracker()
+        self.diff_result = dict()
+
+        self.existing_network = self.get_existing_network()
+
+        if not self.parameters.connected and self.existing_network:
+            self.parameters.connected = container_names_in_network(self.existing_network)
+
+        if self.parameters.ipam_config:
+            try:
+                for ipam_config in self.parameters.ipam_config:
+                    validate_cidr(ipam_config['subnet'])
+            except ValueError as e:
+                self.client.fail(to_native(e))
+
+        if self.parameters.driver_options:
+            self.parameters.driver_options = clean_dict_booleans_for_docker_api(self.parameters.driver_options)
+
+        state = self.parameters.state
+        if state == 'present':
+            self.present()
+        elif state == 'absent':
+            self.absent()
+
+        if self.diff or self.check_mode or self.parameters.debug:
+            if self.diff:
+                self.diff_result['before'], self.diff_result['after'] = self.diff_tracker.get_before_after()
+            self.results['diff'] = self.diff_result
+
+    def get_existing_network(self):
+        return self.client.get_network(name=self.parameters.name)
+
+    def has_different_config(self, net):
+        '''
+        Evaluates an existing network and returns a tuple containing a boolean
+        indicating if the configuration is different and a list of differences.
+
+        :param net: the inspection output for an existing network
+        :return: (bool, list)
+        '''
+        differences = DifferenceTracker()
+        if self.parameters.driver and self.parameters.driver != net['Driver']:
+            differences.add('driver',
+                            parameter=self.parameters.driver,
+                            active=net['Driver'])
+        if self.parameters.driver_options:
+            if not net.get('Options'):
+                differences.add('driver_options',
+                                parameter=self.parameters.driver_options,
+                                active=net.get('Options'))
+            else:
+                for key, value in self.parameters.driver_options.items():
+                    if not (key in net['Options']) or value != net['Options'][key]:
+                        differences.add('driver_options.%s' % key,
+                                        parameter=value,
+                                        active=net['Options'].get(key))
+
+        if self.parameters.ipam_driver:
+            if not net.get('IPAM') or net['IPAM']['Driver'] != self.parameters.ipam_driver:
+                differences.add('ipam_driver',
+                                parameter=self.parameters.ipam_driver,
+                                active=net.get('IPAM'))
+
+        if self.parameters.ipam_driver_options is not None:
+            ipam_driver_options = net['IPAM'].get('Options') or {}
+            if ipam_driver_options != self.parameters.ipam_driver_options:
+                differences.add('ipam_driver_options',
+                                parameter=self.parameters.ipam_driver_options,
+                                active=ipam_driver_options)
+
+        if self.parameters.ipam_config is not None and self.parameters.ipam_config:
+            if not net.get('IPAM') or not net['IPAM']['Config']:
+                differences.add('ipam_config',
+                                parameter=self.parameters.ipam_config,
+                                active=net.get('IPAM', {}).get('Config'))
+            else:
+                # Put network's IPAM config into the same format as module's IPAM config
+                net_ipam_configs = []
+                for net_ipam_config in net['IPAM']['Config']:
+                    config = dict()
+                    for k, v in net_ipam_config.items():
+                        config[normalize_ipam_config_key(k)] = v
+                    net_ipam_configs.append(config)
+                # Compare lists of dicts as sets of dicts
+                for idx, ipam_config in enumerate(self.parameters.ipam_config):
+                    net_config = dict()
+                    for net_ipam_config in net_ipam_configs:
+                        if dicts_are_essentially_equal(ipam_config, net_ipam_config):
+                            net_config = net_ipam_config
+                            break
+                    for key, value in ipam_config.items():
+                        if value is None:
+                            # due to recursive argument_spec, all keys are always present
+                            # (but have default value None if not specified)
+                            continue
+                        if value != net_config.get(key):
+                            differences.add('ipam_config[%s].%s' % (idx, key),
+                                            parameter=value,
+                                            active=net_config.get(key))
+
+        if self.parameters.enable_ipv6 is not None and self.parameters.enable_ipv6 != net.get('EnableIPv6', False):
+            differences.add('enable_ipv6',
+                            parameter=self.parameters.enable_ipv6,
+                            active=net.get('EnableIPv6', False))
+
+        if self.parameters.internal is not None and self.parameters.internal != net.get('Internal', False):
+            differences.add('internal',
+                            parameter=self.parameters.internal,
+                            active=net.get('Internal'))
+
+        if self.parameters.scope is not None and self.parameters.scope != net.get('Scope'):
+            differences.add('scope',
+                            parameter=self.parameters.scope,
+                            active=net.get('Scope'))
+
+        if self.parameters.attachable is not None and self.parameters.attachable != net.get('Attachable', False):
+            differences.add('attachable',
+                            parameter=self.parameters.attachable,
+                            active=net.get('Attachable'))
+        if self.parameters.labels:
+            if not net.get('Labels'):
+                differences.add('labels',
+                                parameter=self.parameters.labels,
+                                active=net.get('Labels'))
+            else:
+                for key, value in self.parameters.labels.items():
+                    if not (key in net['Labels']) or value != net['Labels'][key]:
+                        differences.add('labels.%s' % key,
+                                        parameter=value,
+                                        active=net['Labels'].get(key))
+
+        return not differences.empty, differences
+
+    def create_network(self):
+        if not self.existing_network:
+            params = dict(
+                driver=self.parameters.driver,
+                options=self.parameters.driver_options,
+            )
+
+            ipam_pools = []
+            if self.parameters.ipam_config:
+                for ipam_pool in self.parameters.ipam_config:
+                    if LooseVersion(docker_version) >= LooseVersion('2.0.0'):
+                        ipam_pools.append(IPAMPool(**ipam_pool))
+                    else:
+                        ipam_pools.append(utils.create_ipam_pool(**ipam_pool))
+
+            if self.parameters.ipam_driver or self.parameters.ipam_driver_options or ipam_pools:
+                # Only add ipam parameter if a driver was specified or if IPAM parameters
+                # were specified. Leaving this parameter away can significantly speed up
+                # creation; on my machine creation with this option needs ~15 seconds,
+                # and without just a few seconds.
+                if LooseVersion(docker_version) >= LooseVersion('2.0.0'):
+                    params['ipam'] = IPAMConfig(driver=self.parameters.ipam_driver,
+                                                pool_configs=ipam_pools,
+                                                options=self.parameters.ipam_driver_options)
+                else:
+                    params['ipam'] = utils.create_ipam_config(driver=self.parameters.ipam_driver,
+                                                              pool_configs=ipam_pools)
+
+            if self.parameters.enable_ipv6 is not None:
+                params['enable_ipv6'] = self.parameters.enable_ipv6
+            if self.parameters.internal is not None:
+                params['internal'] = self.parameters.internal
+            if self.parameters.scope is not None:
+                params['scope'] = self.parameters.scope
+            if self.parameters.attachable is not None:
+                params['attachable'] = self.parameters.attachable
+            if self.parameters.labels:
+                params['labels'] = self.parameters.labels
+
+            if not self.check_mode:
+                resp = self.client.create_network(self.parameters.name, **params)
+                self.client.report_warnings(resp, ['Warning'])
+                self.existing_network = self.client.get_network(network_id=resp['Id'])
+            self.results['actions'].append("Created network %s with driver %s" % (self.parameters.name, self.parameters.driver))
+            self.results['changed'] = True
+
+    def remove_network(self):
+        if self.existing_network:
+            self.disconnect_all_containers()
+            if not self.check_mode:
+                self.client.remove_network(self.parameters.name)
+            self.results['actions'].append("Removed network %s" % (self.parameters.name,))
+            self.results['changed'] = True
+
+    def is_container_connected(self, container_name):
+        if not self.existing_network:
+            return False
+        return container_name in container_names_in_network(self.existing_network)
+
+    def connect_containers(self):
+        for name in self.parameters.connected:
+            if not self.is_container_connected(name):
+                if not self.check_mode:
+                    self.client.connect_container_to_network(name, self.parameters.name)
+                self.results['actions'].append("Connected container %s" % (name,))
+                self.results['changed'] = True
+                self.diff_tracker.add('connected.{0}'.format(name),
+                                      parameter=True,
+                                      active=False)
+
+    def disconnect_missing(self):
+        if not self.existing_network:
+            return
+        containers = self.existing_network['Containers']
+        if not containers:
+            return
+        for c in containers.values():
+            name = c['Name']
+            if name not in self.parameters.connected:
+                self.disconnect_container(name)
+
+    def disconnect_all_containers(self):
+        containers = self.client.get_network(name=self.parameters.name)['Containers']
+        if not containers:
+            return
+        for cont in containers.values():
+            self.disconnect_container(cont['Name'])
+
+    def disconnect_container(self, container_name):
+        if not self.check_mode:
+            self.client.disconnect_container_from_network(container_name, self.parameters.name)
+        self.results['actions'].append("Disconnected container %s" % (container_name,))
+        self.results['changed'] = True
+        self.diff_tracker.add('connected.{0}'.format(container_name),
+                              parameter=False,
+                              active=True)
+
+    def present(self):
+        different = False
+        differences = DifferenceTracker()
+        if self.existing_network:
+            different, differences = self.has_different_config(self.existing_network)
+
+        self.diff_tracker.add('exists', parameter=True, active=self.existing_network is not None)
+        if self.parameters.force or different:
+            self.remove_network()
+            self.existing_network = None
+
+        self.create_network()
+        self.connect_containers()
+        if not self.parameters.appends:
+            self.disconnect_missing()
+
+        if self.diff or self.check_mode or self.parameters.debug:
+            self.diff_result['differences'] = differences.get_legacy_docker_diffs()
+            self.diff_tracker.merge(differences)
+
+        if not self.check_mode and not self.parameters.debug:
+            self.results.pop('actions')
+
+        network_facts = self.get_existing_network()
+        self.results['network'] = network_facts
+
+    def absent(self):
+        self.diff_tracker.add('exists', parameter=False, active=self.existing_network is not None)
+        self.remove_network()
+
+
+def main():
+    argument_spec = dict(
+        name=dict(type='str', required=True, aliases=['network_name']),
+        connected=dict(type='list', default=[], elements='str', aliases=['containers']),
+        state=dict(type='str', default='present', choices=['present', 'absent']),
+        driver=dict(type='str', default='bridge'),
+        driver_options=dict(type='dict', default={}),
+        force=dict(type='bool', default=False),
+        appends=dict(type='bool', default=False, aliases=['incremental']),
+        ipam_driver=dict(type='str'),
+        ipam_driver_options=dict(type='dict'),
+        ipam_config=dict(type='list', elements='dict', options=dict(
+            subnet=dict(type='str'),
+            iprange=dict(type='str'),
+            gateway=dict(type='str'),
+            aux_addresses=dict(type='dict'),
+        )),
+        enable_ipv6=dict(type='bool'),
+        internal=dict(type='bool'),
+        labels=dict(type='dict', default={}),
+        debug=dict(type='bool', default=False),
+        scope=dict(type='str', choices=['local', 'global', 'swarm']),
+        attachable=dict(type='bool'),
+    )
+
+    option_minimal_versions = dict(
+        scope=dict(docker_py_version='2.6.0', docker_api_version='1.30'),
+        attachable=dict(docker_py_version='2.0.0', docker_api_version='1.26'),
+        labels=dict(docker_api_version='1.23'),
+        ipam_driver_options=dict(docker_py_version='2.0.0'),
+    )
+
+    client = AnsibleDockerClient(
+        argument_spec=argument_spec,
+        supports_check_mode=True,
+        min_docker_version='1.10.0',
+        min_docker_api_version='1.22',
+        # "The docker server >= 1.10.0"
+        option_minimal_versions=option_minimal_versions,
+    )
+
+    try:
+        cm = DockerNetworkManager(client)
+        client.module.exit_json(**cm.results)
+    except DockerException as e:
+        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except RequestException as e:
+        client.fail(
+            'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(to_native(e)),
+            exception=traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_network_info.py

@@ -0,0 +1,145 @@
+#!/usr/bin/python
+#
+# Copyright 2016 Red Hat | Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: docker_network_info
+
+short_description: Retrieves facts about docker network
+
+description:
+  - Retrieves facts about a docker network.
+  - Essentially returns the output of C(docker network inspect <name>), similar to what M(community.docker.docker_network)
+    returns for a non-absent network.
+
+
+options:
+  name:
+    description:
+      - The name of the network to inspect.
+      - When identifying an existing network name may be a name or a long or short network ID.
+    type: str
+    required: yes
+extends_documentation_fragment:
+- community.docker.docker
+- community.docker.docker.docker_py_1_documentation
+
+
+author:
+  - "Dave Bendit (@DBendit)"
+
+requirements:
+  - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 1.8.0 (use L(docker-py,https://pypi.org/project/docker-py/) for Python 2.6)"
+  - "Docker API >= 1.21"
+'''
+
+EXAMPLES = '''
+- name: Get infos on network
+  community.docker.docker_network_info:
+    name: mydata
+  register: result
+
+- name: Does network exist?
+  ansible.builtin.debug:
+    msg: "The network {{ 'exists' if result.exists else 'does not exist' }}"
+
+- name: Print information about network
+  ansible.builtin.debug:
+    var: result.network
+  when: result.exists
+'''
+
+RETURN = '''
+exists:
+    description:
+      - Returns whether the network exists.
+    type: bool
+    returned: always
+    sample: true
+network:
+    description:
+      - Facts representing the current state of the network. Matches the docker inspection output.
+      - Will be C(none) if network does not exist.
+    returned: always
+    type: dict
+    sample: '{
+        "Attachable": false,
+        "ConfigFrom": {
+            "Network": ""
+        },
+        "ConfigOnly": false,
+        "Containers": {},
+        "Created": "2018-12-07T01:47:51.250835114-06:00",
+        "Driver": "bridge",
+        "EnableIPv6": false,
+        "IPAM": {
+            "Config": [
+                {
+                    "Gateway": "192.168.96.1",
+                    "Subnet": "192.168.96.0/20"
+                }
+            ],
+            "Driver": "default",
+            "Options": null
+        },
+        "Id": "0856968545f22026c41c2c7c3d448319d3b4a6a03a40b148b3ac4031696d1c0a",
+        "Ingress": false,
+        "Internal": false,
+        "Labels": {},
+        "Name": "ansible-test-f2700bba",
+        "Options": {},
+        "Scope": "local"
+    }'
+'''
+
+import traceback
+
+from ansible.module_utils.common.text.converters import to_native
+
+try:
+    from docker.errors import DockerException
+except ImportError:
+    # missing Docker SDK for Python handled in ansible.module_utils.docker.common
+    pass
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    AnsibleDockerClient,
+    RequestException,
+)
+
+
+def main():
+    argument_spec = dict(
+        name=dict(type='str', required=True),
+    )
+
+    client = AnsibleDockerClient(
+        argument_spec=argument_spec,
+        supports_check_mode=True,
+        min_docker_api_version='1.21',
+    )
+
+    try:
+        network = client.get_network(client.module.params['name'])
+
+        client.module.exit_json(
+            changed=False,
+            exists=(True if network else False),
+            network=network,
+        )
+    except DockerException as e:
+        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except RequestException as e:
+        client.fail(
+            'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(to_native(e)),
+            exception=traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_node.py

@@ -0,0 +1,296 @@
+#!/usr/bin/python
+#
+# (c) 2019 Piotr Wojciechowski <piotr@it-playground.pl>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+DOCUMENTATION = '''
+---
+module: docker_node
+short_description: Manage Docker Swarm node
+description:
+    - Manages the Docker nodes via Swarm Manager.
+    - This module allows to change the node's role, its availability, and to modify, add or remove node labels.
+options:
+    hostname:
+        description:
+            - The hostname or ID of node as registered in Swarm.
+            - If more than one node is registered using the same hostname the ID must be used,
+              otherwise module will fail.
+        type: str
+        required: yes
+    labels:
+        description:
+            - User-defined key/value metadata that will be assigned as node attribute.
+            - Label operations in this module apply to the docker swarm node specified by I(hostname).
+              Use M(community.docker.docker_swarm) module to add/modify/remove swarm cluster labels.
+            - The actual state of labels assigned to the node when module completes its work depends on
+              I(labels_state) and I(labels_to_remove) parameters values. See description below.
+        type: dict
+    labels_state:
+        description:
+            - It defines the operation on the labels assigned to node and labels specified in I(labels) option.
+            - Set to C(merge) to combine labels provided in I(labels) with those already assigned to the node.
+              If no labels are assigned then it will add listed labels. For labels that are already assigned
+              to the node, it will update their values. The labels not specified in I(labels) will remain unchanged.
+              If I(labels) is empty then no changes will be made.
+            - Set to C(replace) to replace all assigned labels with provided ones. If I(labels) is empty then
+              all labels assigned to the node will be removed.
+        type: str
+        default: 'merge'
+        choices:
+          - merge
+          - replace
+    labels_to_remove:
+        description:
+            - List of labels that will be removed from the node configuration. The list has to contain only label
+              names, not their values.
+            - If the label provided on the list is not assigned to the node, the entry is ignored.
+            - If the label is both on the I(labels_to_remove) and I(labels), then value provided in I(labels) remains
+              assigned to the node.
+            - If I(labels_state) is C(replace) and I(labels) is not provided or empty then all labels assigned to
+              node are removed and I(labels_to_remove) is ignored.
+        type: list
+        elements: str
+    availability:
+        description: Node availability to assign. If not provided then node availability remains unchanged.
+        choices:
+          - active
+          - pause
+          - drain
+        type: str
+    role:
+        description: Node role to assign. If not provided then node role remains unchanged.
+        choices:
+          - manager
+          - worker
+        type: str
+extends_documentation_fragment:
+- community.docker.docker
+- community.docker.docker.docker_py_1_documentation
+
+requirements:
+  - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 2.4.0"
+  - Docker API >= 1.25
+author:
+  - Piotr Wojciechowski (@WojciechowskiPiotr)
+  - Thierry Bouvet (@tbouvet)
+
+'''
+
+EXAMPLES = '''
+- name: Set node role
+  community.docker.docker_node:
+    hostname: mynode
+    role: manager
+
+- name: Set node availability
+  community.docker.docker_node:
+    hostname: mynode
+    availability: drain
+
+- name: Replace node labels with new labels
+  community.docker.docker_node:
+    hostname: mynode
+    labels:
+      key: value
+    labels_state: replace
+
+- name: Merge node labels and new labels
+  community.docker.docker_node:
+    hostname: mynode
+    labels:
+      key: value
+
+- name: Remove all labels assigned to node
+  community.docker.docker_node:
+    hostname: mynode
+    labels_state: replace
+
+- name: Remove selected labels from the node
+  community.docker.docker_node:
+    hostname: mynode
+    labels_to_remove:
+      - key1
+      - key2
+'''
+
+RETURN = '''
+node:
+  description: Information about node after 'update' operation
+  returned: success
+  type: dict
+
+'''
+
+import traceback
+
+try:
+    from docker.errors import DockerException, APIError
+except ImportError:
+    # missing Docker SDK for Python handled in ansible.module_utils.docker.common
+    pass
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    DockerBaseClass,
+    RequestException,
+)
+
+from ansible.module_utils.common.text.converters import to_native
+
+from ansible_collections.community.docker.plugins.module_utils.swarm import AnsibleDockerSwarmClient
+
+
+class TaskParameters(DockerBaseClass):
+    def __init__(self, client):
+        super(TaskParameters, self).__init__()
+
+        # Spec
+        self.name = None
+        self.labels = None
+        self.labels_state = None
+        self.labels_to_remove = None
+
+        # Node
+        self.availability = None
+        self.role = None
+
+        for key, value in client.module.params.items():
+            setattr(self, key, value)
+
+
+class SwarmNodeManager(DockerBaseClass):
+
+    def __init__(self, client, results):
+
+        super(SwarmNodeManager, self).__init__()
+
+        self.client = client
+        self.results = results
+        self.check_mode = self.client.check_mode
+
+        self.client.fail_task_if_not_swarm_manager()
+
+        self.parameters = TaskParameters(client)
+
+        self.node_update()
+
+    def node_update(self):
+        if not (self.client.check_if_swarm_node(node_id=self.parameters.hostname)):
+            self.client.fail("This node is not part of a swarm.")
+            return
+
+        if self.client.check_if_swarm_node_is_down():
+            self.client.fail("Can not update the node. The node is down.")
+
+        try:
+            node_info = self.client.inspect_node(node_id=self.parameters.hostname)
+        except APIError as exc:
+            self.client.fail("Failed to get node information for %s" % to_native(exc))
+
+        changed = False
+        node_spec = dict(
+            Availability=self.parameters.availability,
+            Role=self.parameters.role,
+            Labels=self.parameters.labels,
+        )
+
+        if self.parameters.role is None:
+            node_spec['Role'] = node_info['Spec']['Role']
+        else:
+            if not node_info['Spec']['Role'] == self.parameters.role:
+                node_spec['Role'] = self.parameters.role
+                changed = True
+
+        if self.parameters.availability is None:
+            node_spec['Availability'] = node_info['Spec']['Availability']
+        else:
+            if not node_info['Spec']['Availability'] == self.parameters.availability:
+                node_info['Spec']['Availability'] = self.parameters.availability
+                changed = True
+
+        if self.parameters.labels_state == 'replace':
+            if self.parameters.labels is None:
+                node_spec['Labels'] = {}
+                if node_info['Spec']['Labels']:
+                    changed = True
+            else:
+                if (node_info['Spec']['Labels'] or {}) != self.parameters.labels:
+                    node_spec['Labels'] = self.parameters.labels
+                    changed = True
+        elif self.parameters.labels_state == 'merge':
+            node_spec['Labels'] = dict(node_info['Spec']['Labels'] or {})
+            if self.parameters.labels is not None:
+                for key, value in self.parameters.labels.items():
+                    if node_spec['Labels'].get(key) != value:
+                        node_spec['Labels'][key] = value
+                        changed = True
+
+            if self.parameters.labels_to_remove is not None:
+                for key in self.parameters.labels_to_remove:
+                    if self.parameters.labels is not None:
+                        if not self.parameters.labels.get(key):
+                            if node_spec['Labels'].get(key):
+                                node_spec['Labels'].pop(key)
+                                changed = True
+                        else:
+                            self.client.module.warn(
+                                "Label '%s' listed both in 'labels' and 'labels_to_remove'. "
+                                "Keeping the assigned label value."
+                                % to_native(key))
+                    else:
+                        if node_spec['Labels'].get(key):
+                            node_spec['Labels'].pop(key)
+                            changed = True
+
+        if changed is True:
+            if not self.check_mode:
+                try:
+                    self.client.update_node(node_id=node_info['ID'], version=node_info['Version']['Index'],
+                                            node_spec=node_spec)
+                except APIError as exc:
+                    self.client.fail("Failed to update node : %s" % to_native(exc))
+            self.results['node'] = self.client.get_node_inspect(node_id=node_info['ID'])
+            self.results['changed'] = changed
+        else:
+            self.results['node'] = node_info
+            self.results['changed'] = changed
+
+
+def main():
+    argument_spec = dict(
+        hostname=dict(type='str', required=True),
+        labels=dict(type='dict'),
+        labels_state=dict(type='str', default='merge', choices=['merge', 'replace']),
+        labels_to_remove=dict(type='list', elements='str'),
+        availability=dict(type='str', choices=['active', 'pause', 'drain']),
+        role=dict(type='str', choices=['worker', 'manager']),
+    )
+
+    client = AnsibleDockerSwarmClient(
+        argument_spec=argument_spec,
+        supports_check_mode=True,
+        min_docker_version='2.4.0',
+        min_docker_api_version='1.25',
+    )
+
+    try:
+        results = dict(
+            changed=False,
+        )
+
+        SwarmNodeManager(client, results)
+        client.module.exit_json(**results)
+    except DockerException as e:
+        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except RequestException as e:
+        client.fail(
+            'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(to_native(e)),
+            exception=traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_node_info.py

@@ -0,0 +1,160 @@
+#!/usr/bin/python
+#
+# (c) 2019 Piotr Wojciechowski <piotr@it-playground.pl>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: docker_node_info
+
+short_description: Retrieves facts about docker swarm node from Swarm Manager
+
+description:
+  - Retrieves facts about a docker node.
+  - Essentially returns the output of C(docker node inspect <name>).
+  - Must be executed on a host running as Swarm Manager, otherwise the module will fail.
+
+
+options:
+  name:
+    description:
+      - The name of the node to inspect.
+      - The list of nodes names to inspect.
+      - If empty then return information of all nodes in Swarm cluster.
+      - When identifying the node use either the hostname of the node (as registered in Swarm) or node ID.
+      - If I(self) is C(true) then this parameter is ignored.
+    type: list
+    elements: str
+  self:
+    description:
+      - If C(true), queries the node (that is, the docker daemon) the module communicates with.
+      - If C(true) then I(name) is ignored.
+      - If C(false) then query depends on I(name) presence and value.
+    type: bool
+    default: no
+extends_documentation_fragment:
+- community.docker.docker
+- community.docker.docker.docker_py_1_documentation
+
+
+author:
+  - Piotr Wojciechowski (@WojciechowskiPiotr)
+
+requirements:
+  - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 2.4.0"
+  - "Docker API >= 1.24"
+'''
+
+EXAMPLES = '''
+- name: Get info on all nodes
+  community.docker.docker_node_info:
+  register: result
+
+- name: Get info on node
+  community.docker.docker_node_info:
+    name: mynode
+  register: result
+
+- name: Get info on list of nodes
+  community.docker.docker_node_info:
+    name:
+      - mynode1
+      - mynode2
+  register: result
+
+- name: Get info on host if it is Swarm Manager
+  community.docker.docker_node_info:
+    self: true
+  register: result
+'''
+
+RETURN = '''
+nodes:
+    description:
+      - Facts representing the current state of the nodes. Matches the C(docker node inspect) output.
+      - Can contain multiple entries if more than one node provided in I(name), or I(name) is not provided.
+      - If I(name) contains a list of nodes, the output will provide information on all nodes registered
+        at the swarm, including nodes that left the swarm but have not been removed from the cluster on swarm
+        managers and nodes that are unreachable.
+    returned: always
+    type: list
+    elements: dict
+'''
+
+import traceback
+
+from ansible.module_utils.common.text.converters import to_native
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    RequestException,
+)
+from ansible_collections.community.docker.plugins.module_utils.swarm import AnsibleDockerSwarmClient
+
+try:
+    from docker.errors import DockerException
+except ImportError:
+    # missing Docker SDK for Python handled in ansible.module_utils.docker.common
+    pass
+
+
+def get_node_facts(client):
+
+    results = []
+
+    if client.module.params['self'] is True:
+        self_node_id = client.get_swarm_node_id()
+        node_info = client.get_node_inspect(node_id=self_node_id)
+        results.append(node_info)
+        return results
+
+    if client.module.params['name'] is None:
+        node_info = client.get_all_nodes_inspect()
+        return node_info
+
+    nodes = client.module.params['name']
+    if not isinstance(nodes, list):
+        nodes = [nodes]
+
+    for next_node_name in nodes:
+        next_node_info = client.get_node_inspect(node_id=next_node_name, skip_missing=True)
+        if next_node_info:
+            results.append(next_node_info)
+    return results
+
+
+def main():
+    argument_spec = dict(
+        name=dict(type='list', elements='str'),
+        self=dict(type='bool', default=False),
+    )
+
+    client = AnsibleDockerSwarmClient(
+        argument_spec=argument_spec,
+        supports_check_mode=True,
+        min_docker_version='2.4.0',
+        min_docker_api_version='1.24',
+    )
+
+    client.fail_task_if_not_swarm_manager()
+
+    try:
+        nodes = get_node_facts(client)
+
+        client.module.exit_json(
+            changed=False,
+            nodes=nodes,
+        )
+    except DockerException as e:
+        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except RequestException as e:
+        client.fail(
+            'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(to_native(e)),
+            exception=traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_plugin.py

@@ -0,0 +1,371 @@
+#!/usr/bin/python
+# coding: utf-8
+#
+# Copyright: (c) 2021 Red Hat | Ansible Sakar Mehra<@sakarmehra100@gmail.com | @sakar97>
+# Copyright: (c) 2019, Vladimir Porshkevich (@porshkevich) <neosonic@mail.ru>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+module: docker_plugin
+short_description: Manage Docker plugins
+version_added: 1.3.0
+description:
+  - This module allows to install, delete, enable and disable Docker plugins.
+  - Performs largely the same function as the C(docker plugin) CLI subcommand.
+options:
+  plugin_name:
+    description:
+      - Name of the plugin to operate on.
+    required: true
+    type: str
+
+  state:
+    description:
+      - C(absent) remove the plugin.
+      - C(present) install the plugin, if it does not already exist.
+      - C(enable) enable the plugin.
+      - C(disable) disable the plugin.
+    default: present
+    choices:
+      - absent
+      - present
+      - enable
+      - disable
+    type: str
+
+  alias:
+    description:
+     - Local name for plugin.
+    type: str
+    version_added: 1.8.0
+
+  plugin_options:
+    description:
+      - Dictionary of plugin settings.
+    type: dict
+
+  force_remove:
+    description:
+      - Remove even if the plugin is enabled.
+    default: False
+    type: bool
+
+  enable_timeout:
+    description:
+      - Timeout in seconds.
+    type: int
+    default: 0
+
+extends_documentation_fragment:
+  - community.docker.docker
+  - community.docker.docker.docker_py_2_documentation
+
+author:
+  - Sakar Mehra (@sakar97)
+  - Vladimir Porshkevich (@porshkevich)
+
+requirements:
+  - "python >= 2.7"
+  - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 2.6.0"
+  - "Docker API >= 1.25"
+'''
+
+EXAMPLES = '''
+- name: Install a plugin
+  community.docker.docker_plugin:
+    plugin_name: plugin_one
+    state: present
+
+- name: Remove a plugin
+  community.docker.docker_plugin:
+    plugin_name: plugin_one
+    state: absent
+
+- name: Enable the plugin
+  community.docker.docker_plugin:
+    plugin_name: plugin_one
+    state: enable
+
+- name: Disable the plugin
+  community.docker.docker_plugin:
+    plugin_name: plugin_one
+    state: disable
+
+- name: Install a plugin with options
+  community.docker.docker_plugin:
+    plugin_name: weaveworks/net-plugin:latest_release
+    plugin_options:
+      IPALLOC_RANGE: "10.32.0.0/12"
+      WEAVE_PASSWORD: "PASSWORD"
+'''
+
+RETURN = '''
+plugin:
+    description:
+      - Plugin inspection results for the affected plugin.
+    returned: success
+    type: dict
+    sample: {}
+actions:
+    description:
+      - List of actions performed during task execution.
+    returned: when I(state!=absent)
+    type: list
+'''
+
+import traceback
+
+from ansible.module_utils.common.text.converters import to_native
+
+try:
+    from docker.errors import APIError, NotFound, DockerException
+    from docker import DockerClient
+except ImportError:
+    # missing docker-py handled in ansible.module_utils.docker_common
+    pass
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    DockerBaseClass,
+    AnsibleDockerClient,
+    DifferenceTracker,
+    RequestException
+)
+
+
+class TaskParameters(DockerBaseClass):
+    def __init__(self, client):
+        super(TaskParameters, self).__init__()
+        self.client = client
+        self.plugin_name = None
+        self.alias = None
+        self.plugin_options = None
+        self.debug = None
+        self.force_remove = None
+        self.enable_timeout = None
+
+        for key, value in client.module.params.items():
+            setattr(self, key, value)
+
+
+def prepare_options(options):
+    return ['%s=%s' % (k, v if v is not None else "") for k, v in options.items()] if options else []
+
+
+def parse_options(options_list):
+    return dict(x.split('=', 1) for x in options_list) if options_list else {}
+
+
+class DockerPluginManager(object):
+
+    def __init__(self, client):
+        self.client = client
+
+        self.dclient = DockerClient(**self.client._connect_params)
+        self.dclient.api = client
+
+        self.parameters = TaskParameters(client)
+        self.preferred_name = self.parameters.alias or self.parameters.plugin_name
+        self.check_mode = self.client.check_mode
+        self.diff = self.client.module._diff
+        self.diff_tracker = DifferenceTracker()
+        self.diff_result = dict()
+
+        self.actions = []
+        self.changed = False
+
+        self.existing_plugin = self.get_existing_plugin()
+
+        state = self.parameters.state
+        if state == 'present':
+            self.present()
+        elif state == 'absent':
+            self.absent()
+        elif state == 'enable':
+            self.enable()
+        elif state == 'disable':
+            self.disable()
+
+        if self.diff or self.check_mode or self.parameters.debug:
+            if self.diff:
+                self.diff_result['before'], self.diff_result['after'] = self.diff_tracker.get_before_after()
+            self.diff = self.diff_result
+
+    def get_existing_plugin(self):
+        try:
+            plugin = self.dclient.plugins.get(self.preferred_name)
+        except NotFound:
+            return None
+        except APIError as e:
+            self.client.fail(to_native(e))
+
+        if plugin is None:
+            return None
+        else:
+            return plugin
+
+    def has_different_config(self):
+        """
+        Return the list of differences between the current parameters and the existing plugin.
+
+        :return: list of options that differ
+        """
+        differences = DifferenceTracker()
+        if self.parameters.plugin_options:
+            if not self.existing_plugin.settings:
+                differences.add('plugin_options', parameters=self.parameters.plugin_options, active=self.existing_plugin.settings['Env'])
+            else:
+                existing_options_list = self.existing_plugin.settings['Env']
+                existing_options = parse_options(existing_options_list)
+
+                for key, value in self.parameters.plugin_options.items():
+                    options_count = 0
+                    if ((not existing_options.get(key) and value) or
+                            not value or
+                            value != existing_options[key]):
+                        differences.add('plugin_options.%s' % key,
+                                        parameter=value,
+                                        active=self.existing_plugin.settings['Env'][options_count])
+
+        return differences
+
+    def install_plugin(self):
+        if not self.existing_plugin:
+            if not self.check_mode:
+                try:
+                    self.existing_plugin = self.dclient.plugins.install(
+                        self.parameters.plugin_name, self.parameters.alias
+                    )
+                    if self.parameters.plugin_options:
+                        self.existing_plugin.configure(prepare_options(self.parameters.plugin_options))
+                except APIError as e:
+                    self.client.fail(to_native(e))
+
+            self.actions.append("Installed plugin %s" % self.preferred_name)
+            self.changed = True
+
+    def remove_plugin(self):
+        force = self.parameters.force_remove
+        if self.existing_plugin:
+            if not self.check_mode:
+                try:
+                    self.existing_plugin.remove(force)
+                except APIError as e:
+                    self.client.fail(to_native(e))
+
+            self.actions.append("Removed plugin %s" % self.preferred_name)
+            self.changed = True
+
+    def update_plugin(self):
+        if self.existing_plugin:
+            differences = self.has_different_config()
+            if not differences.empty:
+                if not self.check_mode:
+                    try:
+                        self.existing_plugin.configure(prepare_options(self.parameters.plugin_options))
+                    except APIError as e:
+                        self.client.fail(to_native(e))
+                self.actions.append("Updated plugin %s settings" % self.preferred_name)
+                self.changed = True
+        else:
+            self.client.fail("Cannot update the plugin: Plugin does not exist")
+
+    def present(self):
+        differences = DifferenceTracker()
+        if self.existing_plugin:
+            differences = self.has_different_config()
+
+        self.diff_tracker.add('exists', parameter=True, active=self.existing_plugin is not None)
+
+        if self.existing_plugin:
+            self.update_plugin()
+        else:
+            self.install_plugin()
+
+        if self.diff or self.check_mode or self.parameters.debug:
+            self.diff_tracker.merge(differences)
+
+        if not self.check_mode and not self.parameters.debug:
+            self.actions = None
+
+    def absent(self):
+        self.remove_plugin()
+
+    def enable(self):
+        timeout = self.parameters.enable_timeout
+        if self.existing_plugin:
+            if not self.existing_plugin.enabled:
+                if not self.check_mode:
+                    try:
+                        self.existing_plugin.enable(timeout)
+                    except APIError as e:
+                        self.client.fail(to_native(e))
+                self.actions.append("Enabled plugin %s" % self.preferred_name)
+                self.changed = True
+        else:
+            self.install_plugin()
+            if not self.check_mode:
+                try:
+                    self.existing_plugin.enable(timeout)
+                except APIError as e:
+                    self.client.fail(to_native(e))
+            self.actions.append("Enabled plugin %s" % self.preferred_name)
+            self.changed = True
+
+    def disable(self):
+        if self.existing_plugin:
+            if self.existing_plugin.enabled:
+                if not self.check_mode:
+                    try:
+                        self.existing_plugin.disable()
+                    except APIError as e:
+                        self.client.fail(to_native(e))
+                self.actions.append("Disable plugin %s" % self.preferred_name)
+                self.changed = True
+        else:
+            self.client.fail("Plugin not found: Plugin does not exist.")
+
+    @property
+    def result(self):
+        result = {
+            'actions': self.actions,
+            'changed': self.changed,
+            'diff': self.diff,
+            'plugin': self.client.inspect_plugin(self.preferred_name) if self.parameters.state != 'absent' else {}
+        }
+        return dict((k, v) for k, v in result.items() if v is not None)
+
+
+def main():
+    argument_spec = dict(
+        alias=dict(type='str'),
+        plugin_name=dict(type='str', required=True),
+        state=dict(type='str', default='present', choices=['present', 'absent', 'enable', 'disable']),
+        plugin_options=dict(type='dict', default={}),
+        debug=dict(type='bool', default=False),
+        force_remove=dict(type='bool', default=False),
+        enable_timeout=dict(type='int', default=0),
+    )
+    client = AnsibleDockerClient(
+        argument_spec=argument_spec,
+        supports_check_mode=True,
+        min_docker_version='2.6.0',
+        min_docker_api_version='1.25',
+    )
+
+    try:
+        cm = DockerPluginManager(client)
+        client.module.exit_json(**cm.result)
+    except DockerException as e:
+        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except RequestException as e:
+        client.fail(
+            'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(to_native(e)),
+            exception=traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_prune.py

@@ -0,0 +1,269 @@
+#!/usr/bin/python
+#
+# Copyright 2016 Red Hat | Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: docker_prune
+
+short_description: Allows to prune various docker objects
+
+description:
+  - Allows to run C(docker container prune), C(docker image prune), C(docker network prune)
+    and C(docker volume prune) via the Docker API.
+
+
+options:
+  containers:
+    description:
+      - Whether to prune containers.
+    type: bool
+    default: no
+  containers_filters:
+    description:
+      - A dictionary of filter values used for selecting containers to delete.
+      - "For example, C(until: 24h)."
+      - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/container_prune/#filtering)
+        for more information on possible filters.
+    type: dict
+  images:
+    description:
+      - Whether to prune images.
+    type: bool
+    default: no
+  images_filters:
+    description:
+      - A dictionary of filter values used for selecting images to delete.
+      - "For example, C(dangling: true)."
+      - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/image_prune/#filtering)
+        for more information on possible filters.
+    type: dict
+  networks:
+    description:
+      - Whether to prune networks.
+    type: bool
+    default: no
+  networks_filters:
+    description:
+      - A dictionary of filter values used for selecting networks to delete.
+      - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/network_prune/#filtering)
+        for more information on possible filters.
+    type: dict
+  volumes:
+    description:
+      - Whether to prune volumes.
+    type: bool
+    default: no
+  volumes_filters:
+    description:
+      - A dictionary of filter values used for selecting volumes to delete.
+      - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/volume_prune/#filtering)
+        for more information on possible filters.
+    type: dict
+  builder_cache:
+    description:
+      - Whether to prune the builder cache.
+      - Requires version 3.3.0 of the Docker SDK for Python or newer.
+    type: bool
+    default: no
+
+extends_documentation_fragment:
+- community.docker.docker
+- community.docker.docker.docker_py_2_documentation
+
+
+author:
+  - "Felix Fontein (@felixfontein)"
+
+requirements:
+  - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 2.1.0"
+  - "Docker API >= 1.25"
+'''
+
+EXAMPLES = '''
+- name: Prune containers older than 24h
+  community.docker.docker_prune:
+    containers: yes
+    containers_filters:
+      # only consider containers created more than 24 hours ago
+      until: 24h
+
+- name: Prune everything
+  community.docker.docker_prune:
+    containers: yes
+    images: yes
+    networks: yes
+    volumes: yes
+    builder_cache: yes
+
+- name: Prune everything (including non-dangling images)
+  community.docker.docker_prune:
+    containers: yes
+    images: yes
+    images_filters:
+      dangling: false
+    networks: yes
+    volumes: yes
+    builder_cache: yes
+'''
+
+RETURN = '''
+# containers
+containers:
+    description:
+      - List of IDs of deleted containers.
+    returned: I(containers) is C(true)
+    type: list
+    elements: str
+    sample: '[]'
+containers_space_reclaimed:
+    description:
+      - Amount of reclaimed disk space from container pruning in bytes.
+    returned: I(containers) is C(true)
+    type: int
+    sample: '0'
+
+# images
+images:
+    description:
+      - List of IDs of deleted images.
+    returned: I(images) is C(true)
+    type: list
+    elements: str
+    sample: '[]'
+images_space_reclaimed:
+    description:
+      - Amount of reclaimed disk space from image pruning in bytes.
+    returned: I(images) is C(true)
+    type: int
+    sample: '0'
+
+# networks
+networks:
+    description:
+      - List of IDs of deleted networks.
+    returned: I(networks) is C(true)
+    type: list
+    elements: str
+    sample: '[]'
+
+# volumes
+volumes:
+    description:
+      - List of IDs of deleted volumes.
+    returned: I(volumes) is C(true)
+    type: list
+    elements: str
+    sample: '[]'
+volumes_space_reclaimed:
+    description:
+      - Amount of reclaimed disk space from volumes pruning in bytes.
+    returned: I(volumes) is C(true)
+    type: int
+    sample: '0'
+
+# builder_cache
+builder_cache_space_reclaimed:
+    description:
+      - Amount of reclaimed disk space from builder cache pruning in bytes.
+    returned: I(builder_cache) is C(true)
+    type: int
+    sample: '0'
+'''
+
+import traceback
+
+from ansible.module_utils.common.text.converters import to_native
+
+try:
+    from docker.errors import DockerException
+except ImportError:
+    # missing Docker SDK for Python handled in ansible.module_utils.docker.common
+    pass
+
+from ansible_collections.community.docker.plugins.module_utils.version import LooseVersion
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    AnsibleDockerClient,
+    RequestException,
+)
+
+try:
+    from ansible_collections.community.docker.plugins.module_utils.common import docker_version, clean_dict_booleans_for_docker_api
+except Exception as dummy:
+    # missing Docker SDK for Python handled in ansible.module_utils.docker.common
+    pass
+
+
+def main():
+    argument_spec = dict(
+        containers=dict(type='bool', default=False),
+        containers_filters=dict(type='dict'),
+        images=dict(type='bool', default=False),
+        images_filters=dict(type='dict'),
+        networks=dict(type='bool', default=False),
+        networks_filters=dict(type='dict'),
+        volumes=dict(type='bool', default=False),
+        volumes_filters=dict(type='dict'),
+        builder_cache=dict(type='bool', default=False),
+    )
+
+    client = AnsibleDockerClient(
+        argument_spec=argument_spec,
+        # supports_check_mode=True,
+        min_docker_api_version='1.25',
+        min_docker_version='2.1.0',
+    )
+
+    # Version checks
+    cache_min_version = '3.3.0'
+    if client.module.params['builder_cache'] and client.docker_py_version < LooseVersion(cache_min_version):
+        msg = "Error: Docker SDK for Python's version is %s. Minimum version required for builds option is %s. Use `pip install --upgrade docker` to upgrade."
+        client.fail(msg % (docker_version, cache_min_version))
+
+    try:
+        result = dict()
+
+        if client.module.params['containers']:
+            filters = clean_dict_booleans_for_docker_api(client.module.params.get('containers_filters'))
+            res = client.prune_containers(filters=filters)
+            result['containers'] = res.get('ContainersDeleted') or []
+            result['containers_space_reclaimed'] = res['SpaceReclaimed']
+
+        if client.module.params['images']:
+            filters = clean_dict_booleans_for_docker_api(client.module.params.get('images_filters'))
+            res = client.prune_images(filters=filters)
+            result['images'] = res.get('ImagesDeleted') or []
+            result['images_space_reclaimed'] = res['SpaceReclaimed']
+
+        if client.module.params['networks']:
+            filters = clean_dict_booleans_for_docker_api(client.module.params.get('networks_filters'))
+            res = client.prune_networks(filters=filters)
+            result['networks'] = res.get('NetworksDeleted') or []
+
+        if client.module.params['volumes']:
+            filters = clean_dict_booleans_for_docker_api(client.module.params.get('volumes_filters'))
+            res = client.prune_volumes(filters=filters)
+            result['volumes'] = res.get('VolumesDeleted') or []
+            result['volumes_space_reclaimed'] = res['SpaceReclaimed']
+
+        if client.module.params['builder_cache']:
+            res = client.prune_builds()
+            result['builder_cache_space_reclaimed'] = res['SpaceReclaimed']
+
+        client.module.exit_json(**result)
+    except DockerException as e:
+        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except RequestException as e:
+        client.fail(
+            'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(to_native(e)),
+            exception=traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_secret.py

@@ -0,0 +1,397 @@
+#!/usr/bin/python
+#
+# Copyright 2016 Red Hat | Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: docker_secret
+
+short_description: Manage docker secrets.
+
+
+description:
+     - Create and remove Docker secrets in a Swarm environment. Similar to C(docker secret create) and C(docker secret rm).
+     - Adds to the metadata of new secrets C(ansible_key), an encrypted hash representation of the data, which is then used
+       in future runs to test if a secret has changed. If C(ansible_key) is not present, then a secret will not be updated
+       unless the I(force) option is set.
+     - Updates to secrets are performed by removing the secret and creating it again.
+options:
+  data:
+    description:
+      - The value of the secret.
+      - Mutually exclusive with I(data_src). One of I(data) and I(data_src) is required if I(state=present).
+    type: str
+  data_is_b64:
+    description:
+      - If set to C(true), the data is assumed to be Base64 encoded and will be
+        decoded before being used.
+      - To use binary I(data), it is better to keep it Base64 encoded and let it
+        be decoded by this option.
+    type: bool
+    default: no
+  data_src:
+    description:
+      - The file on the target from which to read the secret.
+      - Mutually exclusive with I(data). One of I(data) and I(data_src) is required if I(state=present).
+    type: path
+    version_added: 1.10.0
+  labels:
+    description:
+      - "A map of key:value meta data, where both key and value are expected to be strings."
+      - If new meta data is provided, or existing meta data is modified, the secret will be updated by removing it and creating it again.
+    type: dict
+  force:
+    description:
+      - Use with state C(present) to always remove and recreate an existing secret.
+      - If C(true), an existing secret will be replaced, even if it has not changed.
+    type: bool
+    default: no
+  rolling_versions:
+    description:
+      - If set to C(true), secrets are created with an increasing version number appended to their name.
+      - Adds a label containing the version number to the managed secrets with the name C(ansible_version).
+    type: bool
+    default: false
+    version_added: 2.2.0
+  versions_to_keep:
+    description:
+      - When using I(rolling_versions), the number of old versions of the secret to keep.
+      - Extraneous old secrets are deleted after the new one is created.
+      - Set to C(-1) to keep everything or to C(0) or C(1) to keep only the current one.
+    type: int
+    default: 5
+    version_added: 2.2.0
+  name:
+    description:
+      - The name of the secret.
+    type: str
+    required: yes
+  state:
+    description:
+      - Set to C(present), if the secret should exist, and C(absent), if it should not.
+    type: str
+    default: present
+    choices:
+      - absent
+      - present
+
+extends_documentation_fragment:
+- community.docker.docker
+- community.docker.docker.docker_py_2_documentation
+
+
+requirements:
+  - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 2.1.0"
+  - "Docker API >= 1.25"
+
+author:
+  - Chris Houseknecht (@chouseknecht)
+'''
+
+EXAMPLES = '''
+
+- name: Create secret foo (from a file on the control machine)
+  community.docker.docker_secret:
+    name: foo
+    # If the file is JSON or binary, Ansible might modify it (because
+    # it is first decoded and later re-encoded). Base64-encoding the
+    # file directly after reading it prevents this to happen.
+    data: "{{ lookup('file', '/path/to/secret/file') | b64encode }}"
+    data_is_b64: true
+    state: present
+
+- name: Create secret foo (from a file on the target machine)
+  community.docker.docker_secret:
+    name: foo
+    data_src: /path/to/secret/file
+    state: present
+
+- name: Change the secret data
+  community.docker.docker_secret:
+    name: foo
+    data: Goodnight everyone!
+    labels:
+      bar: baz
+      one: '1'
+    state: present
+
+- name: Add a new label
+  community.docker.docker_secret:
+    name: foo
+    data: Goodnight everyone!
+    labels:
+      bar: baz
+      one: '1'
+      # Adding a new label will cause a remove/create of the secret
+      two: '2'
+    state: present
+
+- name: No change
+  community.docker.docker_secret:
+    name: foo
+    data: Goodnight everyone!
+    labels:
+      bar: baz
+      one: '1'
+      # Even though 'two' is missing, there is no change to the existing secret
+    state: present
+
+- name: Update an existing label
+  community.docker.docker_secret:
+    name: foo
+    data: Goodnight everyone!
+    labels:
+      bar: monkey   # Changing a label will cause a remove/create of the secret
+      one: '1'
+    state: present
+
+- name: Force the removal/creation of the secret
+  community.docker.docker_secret:
+    name: foo
+    data: Goodnight everyone!
+    force: yes
+    state: present
+
+- name: Remove secret foo
+  community.docker.docker_secret:
+    name: foo
+    state: absent
+'''
+
+RETURN = '''
+secret_id:
+  description:
+    - The ID assigned by Docker to the secret object.
+  returned: success and I(state) is C(present)
+  type: str
+  sample: 'hzehrmyjigmcp2gb6nlhmjqcv'
+secret_name:
+  description:
+    - The name of the created secret object.
+  returned: success and I(state) is C(present)
+  type: str
+  sample: 'awesome_secret'
+  version_added: 2.2.0
+'''
+
+import base64
+import hashlib
+import traceback
+
+try:
+    from docker.errors import DockerException, APIError
+except ImportError:
+    # missing Docker SDK for Python handled in ansible.module_utils.docker.common
+    pass
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    AnsibleDockerClient,
+    DockerBaseClass,
+    compare_generic,
+    RequestException,
+)
+from ansible.module_utils.common.text.converters import to_native, to_bytes
+
+
+class SecretManager(DockerBaseClass):
+
+    def __init__(self, client, results):
+
+        super(SecretManager, self).__init__()
+
+        self.client = client
+        self.results = results
+        self.check_mode = self.client.check_mode
+
+        parameters = self.client.module.params
+        self.name = parameters.get('name')
+        self.state = parameters.get('state')
+        self.data = parameters.get('data')
+        if self.data is not None:
+            if parameters.get('data_is_b64'):
+                self.data = base64.b64decode(self.data)
+            else:
+                self.data = to_bytes(self.data)
+        data_src = parameters.get('data_src')
+        if data_src is not None:
+            try:
+                with open(data_src, 'rb') as f:
+                    self.data = f.read()
+            except Exception as exc:
+                self.client.fail('Error while reading {src}: {error}'.format(src=data_src, error=to_native(exc)))
+        self.labels = parameters.get('labels')
+        self.force = parameters.get('force')
+        self.rolling_versions = parameters.get('rolling_versions')
+        self.versions_to_keep = parameters.get('versions_to_keep')
+
+        if self.rolling_versions:
+            self.version = 0
+        self.data_key = None
+        self.secrets = []
+
+    def __call__(self):
+        self.get_secret()
+        if self.state == 'present':
+            self.data_key = hashlib.sha224(self.data).hexdigest()
+            self.present()
+            self.remove_old_versions()
+        elif self.state == 'absent':
+            self.absent()
+
+    def get_version(self, secret):
+        try:
+            return int(secret.get('Spec', {}).get('Labels', {}).get('ansible_version', 0))
+        except ValueError:
+            return 0
+
+    def remove_old_versions(self):
+        if not self.rolling_versions or self.versions_to_keep < 0:
+            return
+        if not self.check_mode:
+            while len(self.secrets) > max(self.versions_to_keep, 1):
+                self.remove_secret(self.secrets.pop(0))
+
+    def get_secret(self):
+        ''' Find an existing secret. '''
+        try:
+            secrets = self.client.secrets(filters={'name': self.name})
+        except APIError as exc:
+            self.client.fail("Error accessing secret %s: %s" % (self.name, to_native(exc)))
+
+        if self.rolling_versions:
+            self.secrets = [
+                secret
+                for secret in secrets
+                if secret['Spec']['Name'].startswith('{name}_v'.format(name=self.name))
+            ]
+            self.secrets.sort(key=self.get_version)
+        else:
+            self.secrets = [
+                secret for secret in secrets if secret['Spec']['Name'] == self.name
+            ]
+
+    def create_secret(self):
+        ''' Create a new secret '''
+        secret_id = None
+        # We can't see the data after creation, so adding a label we can use for idempotency check
+        labels = {
+            'ansible_key': self.data_key
+        }
+        if self.rolling_versions:
+            self.version += 1
+            labels['ansible_version'] = str(self.version)
+            self.name = '{name}_v{version}'.format(name=self.name, version=self.version)
+        if self.labels:
+            labels.update(self.labels)
+
+        try:
+            if not self.check_mode:
+                secret_id = self.client.create_secret(self.name, self.data, labels=labels)
+                self.secrets += self.client.secrets(filters={'id': secret_id})
+        except APIError as exc:
+            self.client.fail("Error creating secret: %s" % to_native(exc))
+
+        if isinstance(secret_id, dict):
+            secret_id = secret_id['ID']
+
+        return secret_id
+
+    def remove_secret(self, secret):
+        try:
+            if not self.check_mode:
+                self.client.remove_secret(secret['ID'])
+        except APIError as exc:
+            self.client.fail("Error removing secret %s: %s" % (secret['Spec']['Name'], to_native(exc)))
+
+    def present(self):
+        ''' Handles state == 'present', creating or updating the secret '''
+        if self.secrets:
+            secret = self.secrets[-1]
+            self.results['secret_id'] = secret['ID']
+            self.results['secret_name'] = secret['Spec']['Name']
+            data_changed = False
+            attrs = secret.get('Spec', {})
+            if attrs.get('Labels', {}).get('ansible_key'):
+                if attrs['Labels']['ansible_key'] != self.data_key:
+                    data_changed = True
+            else:
+                if not self.force:
+                    self.client.module.warn("'ansible_key' label not found. Secret will not be changed unless the force parameter is set to 'yes'")
+            labels_changed = not compare_generic(self.labels, attrs.get('Labels'), 'allow_more_present', 'dict')
+            if self.rolling_versions:
+                self.version = self.get_version(secret)
+            if data_changed or labels_changed or self.force:
+                # if something changed or force, delete and re-create the secret
+                if not self.rolling_versions:
+                    self.absent()
+                secret_id = self.create_secret()
+                self.results['changed'] = True
+                self.results['secret_id'] = secret_id
+                self.results['secret_name'] = self.name
+        else:
+            self.results['changed'] = True
+            self.results['secret_id'] = self.create_secret()
+            self.results['secret_name'] = self.name
+
+    def absent(self):
+        ''' Handles state == 'absent', removing the secret '''
+        if self.secrets:
+            for secret in self.secrets:
+                self.remove_secret(secret)
+            self.results['changed'] = True
+
+
+def main():
+    argument_spec = dict(
+        name=dict(type='str', required=True),
+        state=dict(type='str', default='present', choices=['absent', 'present']),
+        data=dict(type='str', no_log=True),
+        data_is_b64=dict(type='bool', default=False),
+        data_src=dict(type='path'),
+        labels=dict(type='dict'),
+        force=dict(type='bool', default=False),
+        rolling_versions=dict(type='bool', default=False),
+        versions_to_keep=dict(type='int', default=5),
+    )
+
+    required_if = [
+        ('state', 'present', ['data', 'data_src'], True),
+    ]
+
+    mutually_exclusive = [
+        ('data', 'data_src'),
+    ]
+
+    client = AnsibleDockerClient(
+        argument_spec=argument_spec,
+        supports_check_mode=True,
+        required_if=required_if,
+        mutually_exclusive=mutually_exclusive,
+        min_docker_version='2.1.0',
+        min_docker_api_version='1.25',
+    )
+
+    try:
+        results = dict(
+            changed=False,
+            secret_id='',
+            secret_name=''
+        )
+
+        SecretManager(client, results)()
+        client.module.exit_json(**results)
+    except DockerException as e:
+        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except RequestException as e:
+        client.fail(
+            'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(to_native(e)),
+            exception=traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_stack.py

@@ -0,0 +1,308 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2018 Dario Zanzico (git@dariozanzico.com)
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: docker_stack
+author: "Dario Zanzico (@dariko)"
+short_description: docker stack module
+description:
+  - Manage docker stacks using the C(docker stack) command
+    on the target node (see examples).
+options:
+  name:
+    description:
+      - Stack name
+    type: str
+    required: yes
+  state:
+    description:
+      - Service state.
+    type: str
+    default: "present"
+    choices:
+      - present
+      - absent
+  compose:
+    description:
+      - List of compose definitions. Any element may be a string
+        referring to the path of the compose file on the target host
+        or the YAML contents of a compose file nested as dictionary.
+    type: list
+    elements: raw
+    default: []
+  prune:
+    description:
+      - If true will add the C(--prune) option to the C(docker stack deploy) command.
+        This will have docker remove the services not present in the
+        current stack definition.
+    type: bool
+    default: no
+  with_registry_auth:
+    description:
+      - If true will add the C(--with-registry-auth) option to the C(docker stack deploy) command.
+        This will have docker send registry authentication details to Swarm agents.
+    type: bool
+    default: no
+  resolve_image:
+    description:
+      - If set will add the C(--resolve-image) option to the C(docker stack deploy) command.
+        This will have docker query the registry to resolve image digest and
+        supported platforms. If not set, docker use "always" by default.
+    type: str
+    choices: ["always", "changed", "never"]
+  absent_retries:
+    description:
+      - If C(>0) and I(state) is C(absent) the module will retry up to
+        I(absent_retries) times to delete the stack until all the
+        resources have been effectively deleted.
+        If the last try still reports the stack as not completely
+        removed the module will fail.
+    type: int
+    default: 0
+  absent_retries_interval:
+    description:
+      - Interval in seconds between consecutive I(absent_retries).
+    type: int
+    default: 1
+
+requirements:
+  - jsondiff
+  - pyyaml
+
+notes:
+  - Return values I(out) and I(err) have been deprecated and will be removed in community.docker 3.0.0. Use I(stdout) and I(stderr) instead.
+'''
+
+RETURN = '''
+stack_spec_diff:
+    description: |
+        dictionary containing the differences between the 'Spec' field
+        of the stack services before and after applying the new stack
+        definition.
+    sample: >
+        "stack_spec_diff":
+        {'test_stack_test_service': {u'TaskTemplate': {u'ContainerSpec': {delete: [u'Env']}}}}
+    returned: on change
+    type: dict
+'''
+
+EXAMPLES = '''
+  - name: Deploy stack from a compose file
+    community.docker.docker_stack:
+      state: present
+      name: mystack
+      compose:
+        - /opt/docker-compose.yml
+
+  - name: Deploy stack from base compose file and override the web service
+    community.docker.docker_stack:
+      state: present
+      name: mystack
+      compose:
+        - /opt/docker-compose.yml
+        - version: '3'
+          services:
+            web:
+              image: nginx:latest
+              environment:
+                ENVVAR: envvar
+
+  - name: Remove stack
+    community.docker.docker_stack:
+      name: mystack
+      state: absent
+'''
+
+
+import json
+import tempfile
+from ansible.module_utils.six import string_types
+from time import sleep
+
+try:
+    from jsondiff import diff as json_diff
+    HAS_JSONDIFF = True
+except ImportError:
+    HAS_JSONDIFF = False
+
+try:
+    from yaml import dump as yaml_dump
+    HAS_YAML = True
+except ImportError:
+    HAS_YAML = False
+
+from ansible.module_utils.basic import AnsibleModule, os
+
+
+def docker_stack_services(module, stack_name):
+    docker_bin = module.get_bin_path('docker', required=True)
+    rc, out, err = module.run_command([docker_bin,
+                                       "stack",
+                                       "services",
+                                       stack_name,
+                                       "--format",
+                                       "{{.Name}}"])
+    if err == "Nothing found in stack: %s\n" % stack_name:
+        return []
+    return out.strip().split('\n')
+
+
+def docker_service_inspect(module, service_name):
+    docker_bin = module.get_bin_path('docker', required=True)
+    rc, out, err = module.run_command([docker_bin,
+                                       "service",
+                                       "inspect",
+                                       service_name])
+    if rc != 0:
+        return None
+    else:
+        ret = json.loads(out)[0]['Spec']
+        return ret
+
+
+def docker_stack_deploy(module, stack_name, compose_files):
+    docker_bin = module.get_bin_path('docker', required=True)
+    command = [docker_bin, "stack", "deploy"]
+    if module.params["prune"]:
+        command += ["--prune"]
+    if module.params["with_registry_auth"]:
+        command += ["--with-registry-auth"]
+    if module.params["resolve_image"]:
+        command += ["--resolve-image",
+                    module.params["resolve_image"]]
+    for compose_file in compose_files:
+        command += ["--compose-file",
+                    compose_file]
+    command += [stack_name]
+    return module.run_command(command)
+
+
+def docker_stack_inspect(module, stack_name):
+    ret = {}
+    for service_name in docker_stack_services(module, stack_name):
+        ret[service_name] = docker_service_inspect(module, service_name)
+    return ret
+
+
+def docker_stack_rm(module, stack_name, retries, interval):
+    docker_bin = module.get_bin_path('docker', required=True)
+    command = [docker_bin, "stack", "rm", stack_name]
+
+    rc, out, err = module.run_command(command)
+
+    while err != "Nothing found in stack: %s\n" % stack_name and retries > 0:
+        sleep(interval)
+        retries = retries - 1
+        rc, out, err = module.run_command(command)
+    return rc, out, err
+
+
+def main():
+    module = AnsibleModule(
+        argument_spec={
+            'name': dict(type='str', required=True),
+            'compose': dict(type='list', elements='raw', default=[]),
+            'prune': dict(type='bool', default=False),
+            'with_registry_auth': dict(type='bool', default=False),
+            'resolve_image': dict(type='str', choices=['always', 'changed', 'never']),
+            'state': dict(type='str', default='present', choices=['present', 'absent']),
+            'absent_retries': dict(type='int', default=0),
+            'absent_retries_interval': dict(type='int', default=1)
+        },
+        supports_check_mode=False
+    )
+
+    if not HAS_JSONDIFF:
+        return module.fail_json(msg="jsondiff is not installed, try 'pip install jsondiff'")
+
+    if not HAS_YAML:
+        return module.fail_json(msg="yaml is not installed, try 'pip install pyyaml'")
+
+    state = module.params['state']
+    compose = module.params['compose']
+    name = module.params['name']
+    absent_retries = module.params['absent_retries']
+    absent_retries_interval = module.params['absent_retries_interval']
+
+    if state == 'present':
+        if not compose:
+            module.fail_json(msg=("compose parameter must be a list "
+                                  "containing at least one element"))
+
+        compose_files = []
+        for i, compose_def in enumerate(compose):
+            if isinstance(compose_def, dict):
+                compose_file_fd, compose_file = tempfile.mkstemp()
+                module.add_cleanup_file(compose_file)
+                with os.fdopen(compose_file_fd, 'w') as stack_file:
+                    compose_files.append(compose_file)
+                    stack_file.write(yaml_dump(compose_def))
+            elif isinstance(compose_def, string_types):
+                compose_files.append(compose_def)
+            else:
+                module.fail_json(msg="compose element '%s' must be a " +
+                                 "string or a dictionary" % compose_def)
+
+        before_stack_services = docker_stack_inspect(module, name)
+
+        rc, out, err = docker_stack_deploy(module, name, compose_files)
+
+        after_stack_services = docker_stack_inspect(module, name)
+
+        if rc != 0:
+            module.fail_json(msg="docker stack up deploy command failed",
+                             rc=rc,
+                             out=out, err=err,  # Deprecated
+                             stdout=out, stderr=err)
+
+        before_after_differences = json_diff(before_stack_services,
+                                             after_stack_services)
+        for k in before_after_differences.keys():
+            if isinstance(before_after_differences[k], dict):
+                before_after_differences[k].pop('UpdatedAt', None)
+                before_after_differences[k].pop('Version', None)
+                if not list(before_after_differences[k].keys()):
+                    before_after_differences.pop(k)
+
+        if not before_after_differences:
+            module.exit_json(
+                changed=False,
+                rc=rc,
+                stdout=out,
+                stderr=err)
+        else:
+            module.exit_json(
+                changed=True,
+                rc=rc,
+                stdout=out,
+                stderr=err,
+                stack_spec_diff=json_diff(before_stack_services,
+                                          after_stack_services,
+                                          dump=True))
+
+    else:
+        if docker_stack_services(module, name):
+            rc, out, err = docker_stack_rm(module, name, absent_retries, absent_retries_interval)
+            if rc != 0:
+                module.fail_json(msg="'docker stack down' command failed",
+                                 rc=rc,
+                                 out=out, err=err,  # Deprecated
+                                 stdout=out, stderr=err)
+            else:
+                module.exit_json(changed=True,
+                                 msg=out, rc=rc,
+                                 err=err,  # Deprecated
+                                 stdout=out, stderr=err)
+        module.exit_json(changed=False)
+
+
+if __name__ == "__main__":
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_stack_info.py

@@ -0,0 +1,83 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2020 Jose Angel Munoz (@imjoseangel)
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+
+__metaclass__ = type
+
+DOCUMENTATION = '''
+---
+module: docker_stack_info
+author: "Jose Angel Munoz (@imjoseangel)"
+short_description: Return information on a docker stack
+description:
+  - Retrieve information on docker stacks using the C(docker stack) command
+    on the target node (see examples).
+'''
+
+RETURN = '''
+results:
+    description: |
+        List of dictionaries containing the list of stacks or tasks associated
+        to a stack name.
+    sample: >
+        "results": [{"name":"grafana","namespace":"default","orchestrator":"Kubernetes","services":"2"}]
+    returned: always
+    type: list
+'''
+
+EXAMPLES = '''
+  - name: Shows stack info
+    community.docker.docker_stack_info:
+    register: result
+
+  - name: Show results
+    ansible.builtin.debug:
+      var: result.results
+'''
+
+import json
+from ansible.module_utils.basic import AnsibleModule
+
+
+def docker_stack_list(module):
+    docker_bin = module.get_bin_path('docker', required=True)
+    rc, out, err = module.run_command(
+        [docker_bin, "stack", "ls", "--format={{json .}}"])
+
+    return rc, out.strip(), err.strip()
+
+
+def main():
+    module = AnsibleModule(
+        argument_spec={
+        },
+        supports_check_mode=True
+    )
+
+    rc, out, err = docker_stack_list(module)
+
+    if rc != 0:
+        module.fail_json(msg="Error running docker stack. {0}".format(err),
+                         rc=rc, stdout=out, stderr=err)
+    else:
+        if out:
+            ret = list(
+                json.loads(outitem)
+                for outitem in out.splitlines())
+
+        else:
+            ret = []
+
+        module.exit_json(changed=False,
+                         rc=rc,
+                         stdout=out,
+                         stderr=err,
+                         results=ret)
+
+
+if __name__ == "__main__":
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_stack_task_info.py

@@ -0,0 +1,94 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2020 Jose Angel Munoz (@imjoseangel)
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+
+__metaclass__ = type
+
+DOCUMENTATION = '''
+---
+module: docker_stack_task_info
+author: "Jose Angel Munoz (@imjoseangel)"
+short_description: Return information of the tasks on a docker stack
+description:
+  - Retrieve information on docker stacks tasks using the C(docker stack) command
+    on the target node (see examples).
+options:
+  name:
+    description:
+      - Stack name.
+    type: str
+    required: yes
+'''
+
+RETURN = '''
+results:
+    description: |
+        List of dictionaries containing the list of tasks associated
+        to a stack name.
+    sample: >
+        [{"CurrentState":"Running","DesiredState":"Running","Error":"","ID":"7wqv6m02ugkw","Image":"busybox","Name":"test_stack.1","Node":"swarm","Ports":""}]
+    returned: always
+    type: list
+    elements: dict
+'''
+
+EXAMPLES = '''
+  - name: Shows stack info
+    community.docker.docker_stack_task_info:
+      name: test_stack
+    register: result
+
+  - name: Show results
+    ansible.builtin.debug:
+      var: result.results
+'''
+
+import json
+from ansible.module_utils.basic import AnsibleModule
+
+
+def docker_stack_task(module, stack_name):
+    docker_bin = module.get_bin_path('docker', required=True)
+    rc, out, err = module.run_command(
+        [docker_bin, "stack", "ps", stack_name, "--format={{json .}}"])
+
+    return rc, out.strip(), err.strip()
+
+
+def main():
+    module = AnsibleModule(
+        argument_spec={
+            'name': dict(type='str', required=True)
+        },
+        supports_check_mode=True
+    )
+
+    name = module.params['name']
+
+    rc, out, err = docker_stack_task(module, name)
+
+    if rc != 0:
+        module.fail_json(msg="Error running docker stack. {0}".format(err),
+                         rc=rc, stdout=out, stderr=err)
+    else:
+        if out:
+            ret = list(
+                json.loads(outitem)
+                for outitem in out.splitlines())
+
+        else:
+            ret = []
+
+        module.exit_json(changed=False,
+                         rc=rc,
+                         stdout=out,
+                         stderr=err,
+                         results=ret)
+
+
+if __name__ == "__main__":
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_swarm.py

@@ -0,0 +1,694 @@
+#!/usr/bin/python
+
+# Copyright 2016 Red Hat | Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+DOCUMENTATION = '''
+---
+module: docker_swarm
+short_description: Manage Swarm cluster
+description:
+  - Create a new Swarm cluster.
+  - Add/Remove nodes or managers to an existing cluster.
+options:
+  advertise_addr:
+    description:
+      - Externally reachable address advertised to other nodes.
+      - This can either be an address/port combination
+          in the form C(192.168.1.1:4567), or an interface followed by a
+          port number, like C(eth0:4567).
+      - If the port number is omitted,
+          the port number from the listen address is used.
+      - If I(advertise_addr) is not specified, it will be automatically
+          detected when possible.
+      - Only used when swarm is initialised or joined. Because of this it's not
+        considered for idempotency checking.
+    type: str
+  default_addr_pool:
+    description:
+      - Default address pool in CIDR format.
+      - Only used when swarm is initialised. Because of this it's not considered
+        for idempotency checking.
+      - Requires API version >= 1.39.
+    type: list
+    elements: str
+  subnet_size:
+    description:
+      - Default address pool subnet mask length.
+      - Only used when swarm is initialised. Because of this it's not considered
+        for idempotency checking.
+      - Requires API version >= 1.39.
+    type: int
+  listen_addr:
+    description:
+      - Listen address used for inter-manager communication.
+      - This can either be an address/port combination in the form
+          C(192.168.1.1:4567), or an interface followed by a port number,
+          like C(eth0:4567).
+      - If the port number is omitted, the default swarm listening port
+          is used.
+      - Only used when swarm is initialised or joined. Because of this it's not
+        considered for idempotency checking.
+    type: str
+    default: 0.0.0.0:2377
+  force:
+    description:
+      - Use with state C(present) to force creating a new Swarm, even if already part of one.
+      - Use with state C(absent) to Leave the swarm even if this node is a manager.
+    type: bool
+    default: no
+  state:
+    description:
+      - Set to C(present), to create/update a new cluster.
+      - Set to C(join), to join an existing cluster.
+      - Set to C(absent), to leave an existing cluster.
+      - Set to C(remove), to remove an absent node from the cluster.
+        Note that removing requires Docker SDK for Python >= 2.4.0.
+    type: str
+    default: present
+    choices:
+      - present
+      - join
+      - absent
+      - remove
+  node_id:
+    description:
+      - Swarm id of the node to remove.
+      - Used with I(state=remove).
+    type: str
+  join_token:
+    description:
+      - Swarm token used to join a swarm cluster.
+      - Used with I(state=join).
+      - If this value is specified, the corresponding value in the return values will be censored by Ansible.
+        This is a side-effect of this value not being logged.
+    type: str
+  remote_addrs:
+    description:
+      - Remote address of one or more manager nodes of an existing Swarm to connect to.
+      - Used with I(state=join).
+    type: list
+    elements: str
+  task_history_retention_limit:
+    description:
+      - Maximum number of tasks history stored.
+      - Docker default value is C(5).
+    type: int
+  snapshot_interval:
+    description:
+      - Number of logs entries between snapshot.
+      - Docker default value is C(10000).
+    type: int
+  keep_old_snapshots:
+    description:
+      - Number of snapshots to keep beyond the current snapshot.
+      - Docker default value is C(0).
+    type: int
+  log_entries_for_slow_followers:
+    description:
+      - Number of log entries to keep around to sync up slow followers after a snapshot is created.
+    type: int
+  heartbeat_tick:
+    description:
+      - Amount of ticks (in seconds) between each heartbeat.
+      - Docker default value is C(1s).
+    type: int
+  election_tick:
+    description:
+      - Amount of ticks (in seconds) needed without a leader to trigger a new election.
+      - Docker default value is C(10s).
+    type: int
+  dispatcher_heartbeat_period:
+    description:
+      - The delay for an agent to send a heartbeat to the dispatcher.
+      - Docker default value is C(5s).
+    type: int
+  node_cert_expiry:
+    description:
+      - Automatic expiry for nodes certificates.
+      - Docker default value is C(3months).
+    type: int
+  name:
+    description:
+      - The name of the swarm.
+    type: str
+  labels:
+    description:
+      - User-defined key/value metadata.
+      - Label operations in this module apply to the docker swarm cluster.
+        Use M(community.docker.docker_node) module to add/modify/remove swarm node labels.
+      - Requires API version >= 1.32.
+    type: dict
+  signing_ca_cert:
+    description:
+      - The desired signing CA certificate for all swarm node TLS leaf certificates, in PEM format.
+      - This must not be a path to a certificate, but the contents of the certificate.
+      - Requires API version >= 1.30.
+    type: str
+  signing_ca_key:
+    description:
+      - The desired signing CA key for all swarm node TLS leaf certificates, in PEM format.
+      - This must not be a path to a key, but the contents of the key.
+      - Requires API version >= 1.30.
+    type: str
+  ca_force_rotate:
+    description:
+      - An integer whose purpose is to force swarm to generate a new signing CA certificate and key,
+          if none have been specified.
+      - Docker default value is C(0).
+      - Requires API version >= 1.30.
+    type: int
+  autolock_managers:
+    description:
+      - If set, generate a key and use it to lock data stored on the managers.
+      - Docker default value is C(no).
+      - M(community.docker.docker_swarm_info) can be used to retrieve the unlock key.
+    type: bool
+  rotate_worker_token:
+    description: Rotate the worker join token.
+    type: bool
+    default: no
+  rotate_manager_token:
+    description: Rotate the manager join token.
+    type: bool
+    default: no
+  data_path_addr:
+    description:
+      - Address or interface to use for data path traffic.
+      - This can either be an address in the form C(192.168.1.1), or an interface,
+          like C(eth0).
+      - Only used when swarm is initialised or joined. Because of this it is not
+        considered for idempotency checking.
+    type: str
+    version_added: 2.5.0
+extends_documentation_fragment:
+- community.docker.docker
+- community.docker.docker.docker_py_1_documentation
+
+requirements:
+  - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 1.10.0 (use L(docker-py,https://pypi.org/project/docker-py/) for Python 2.6)"
+  - Docker API >= 1.25
+author:
+  - Thierry Bouvet (@tbouvet)
+  - Piotr Wojciechowski (@WojciechowskiPiotr)
+'''
+
+EXAMPLES = '''
+
+- name: Init a new swarm with default parameters
+  community.docker.docker_swarm:
+    state: present
+
+- name: Update swarm configuration
+  community.docker.docker_swarm:
+    state: present
+    election_tick: 5
+
+- name: Add nodes
+  community.docker.docker_swarm:
+    state: join
+    advertise_addr: 192.168.1.2
+    join_token: SWMTKN-1--xxxxx
+    remote_addrs: [ '192.168.1.1:2377' ]
+
+- name: Leave swarm for a node
+  community.docker.docker_swarm:
+    state: absent
+
+- name: Remove a swarm manager
+  community.docker.docker_swarm:
+    state: absent
+    force: true
+
+- name: Remove node from swarm
+  community.docker.docker_swarm:
+    state: remove
+    node_id: mynode
+
+- name: Init a new swarm with different data path interface
+  community.docker.docker_swarm:
+    state: present
+    advertise_addr: eth0
+    data_path_addr: ens10
+'''
+
+RETURN = '''
+swarm_facts:
+  description: Informations about swarm.
+  returned: success
+  type: dict
+  contains:
+      JoinTokens:
+          description: Tokens to connect to the Swarm.
+          returned: success
+          type: dict
+          contains:
+              Worker:
+                  description:
+                    - Token to join the cluster as a new *worker* node.
+                    - "B(Note:) if this value has been specified as I(join_token), the value here will not
+                       be the token, but C(VALUE_SPECIFIED_IN_NO_LOG_PARAMETER). If you pass I(join_token),
+                       make sure your playbook/role does not depend on this return value!"
+                  returned: success
+                  type: str
+                  example: SWMTKN-1--xxxxx
+              Manager:
+                  description:
+                    - Token to join the cluster as a new *manager* node.
+                    - "B(Note:) if this value has been specified as I(join_token), the value here will not
+                       be the token, but C(VALUE_SPECIFIED_IN_NO_LOG_PARAMETER). If you pass I(join_token),
+                       make sure your playbook/role does not depend on this return value!"
+                  returned: success
+                  type: str
+                  example: SWMTKN-1--xxxxx
+      UnlockKey:
+          description: The swarm unlock-key if I(autolock_managers) is C(true).
+          returned: on success if I(autolock_managers) is C(true)
+            and swarm is initialised, or if I(autolock_managers) has changed.
+          type: str
+          example: SWMKEY-1-xxx
+
+actions:
+  description: Provides the actions done on the swarm.
+  returned: when action failed.
+  type: list
+  elements: str
+  example: "['This cluster is already a swarm cluster']"
+
+'''
+
+import json
+import traceback
+
+try:
+    from docker.errors import DockerException, APIError
+except ImportError:
+    # missing Docker SDK for Python handled in ansible.module_utils.docker.common
+    pass
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    DockerBaseClass,
+    DifferenceTracker,
+    RequestException,
+)
+
+from ansible_collections.community.docker.plugins.module_utils.swarm import AnsibleDockerSwarmClient
+
+from ansible.module_utils.common.text.converters import to_native
+
+
+class TaskParameters(DockerBaseClass):
+    def __init__(self):
+        super(TaskParameters, self).__init__()
+
+        self.advertise_addr = None
+        self.listen_addr = None
+        self.remote_addrs = None
+        self.join_token = None
+        self.data_path_addr = None
+
+        # Spec
+        self.snapshot_interval = None
+        self.task_history_retention_limit = None
+        self.keep_old_snapshots = None
+        self.log_entries_for_slow_followers = None
+        self.heartbeat_tick = None
+        self.election_tick = None
+        self.dispatcher_heartbeat_period = None
+        self.node_cert_expiry = None
+        self.name = None
+        self.labels = None
+        self.log_driver = None
+        self.signing_ca_cert = None
+        self.signing_ca_key = None
+        self.ca_force_rotate = None
+        self.autolock_managers = None
+        self.rotate_worker_token = None
+        self.rotate_manager_token = None
+        self.default_addr_pool = None
+        self.subnet_size = None
+
+    @staticmethod
+    def from_ansible_params(client):
+        result = TaskParameters()
+        for key, value in client.module.params.items():
+            if key in result.__dict__:
+                setattr(result, key, value)
+
+        result.update_parameters(client)
+        return result
+
+    def update_from_swarm_info(self, swarm_info):
+        spec = swarm_info['Spec']
+
+        ca_config = spec.get('CAConfig') or dict()
+        if self.node_cert_expiry is None:
+            self.node_cert_expiry = ca_config.get('NodeCertExpiry')
+        if self.ca_force_rotate is None:
+            self.ca_force_rotate = ca_config.get('ForceRotate')
+
+        dispatcher = spec.get('Dispatcher') or dict()
+        if self.dispatcher_heartbeat_period is None:
+            self.dispatcher_heartbeat_period = dispatcher.get('HeartbeatPeriod')
+
+        raft = spec.get('Raft') or dict()
+        if self.snapshot_interval is None:
+            self.snapshot_interval = raft.get('SnapshotInterval')
+        if self.keep_old_snapshots is None:
+            self.keep_old_snapshots = raft.get('KeepOldSnapshots')
+        if self.heartbeat_tick is None:
+            self.heartbeat_tick = raft.get('HeartbeatTick')
+        if self.log_entries_for_slow_followers is None:
+            self.log_entries_for_slow_followers = raft.get('LogEntriesForSlowFollowers')
+        if self.election_tick is None:
+            self.election_tick = raft.get('ElectionTick')
+
+        orchestration = spec.get('Orchestration') or dict()
+        if self.task_history_retention_limit is None:
+            self.task_history_retention_limit = orchestration.get('TaskHistoryRetentionLimit')
+
+        encryption_config = spec.get('EncryptionConfig') or dict()
+        if self.autolock_managers is None:
+            self.autolock_managers = encryption_config.get('AutoLockManagers')
+
+        if self.name is None:
+            self.name = spec['Name']
+
+        if self.labels is None:
+            self.labels = spec.get('Labels') or {}
+
+        if 'LogDriver' in spec['TaskDefaults']:
+            self.log_driver = spec['TaskDefaults']['LogDriver']
+
+    def update_parameters(self, client):
+        assign = dict(
+            snapshot_interval='snapshot_interval',
+            task_history_retention_limit='task_history_retention_limit',
+            keep_old_snapshots='keep_old_snapshots',
+            log_entries_for_slow_followers='log_entries_for_slow_followers',
+            heartbeat_tick='heartbeat_tick',
+            election_tick='election_tick',
+            dispatcher_heartbeat_period='dispatcher_heartbeat_period',
+            node_cert_expiry='node_cert_expiry',
+            name='name',
+            labels='labels',
+            signing_ca_cert='signing_ca_cert',
+            signing_ca_key='signing_ca_key',
+            ca_force_rotate='ca_force_rotate',
+            autolock_managers='autolock_managers',
+            log_driver='log_driver',
+        )
+        params = dict()
+        for dest, source in assign.items():
+            if not client.option_minimal_versions[source]['supported']:
+                continue
+            value = getattr(self, source)
+            if value is not None:
+                params[dest] = value
+        self.spec = client.create_swarm_spec(**params)
+
+    def compare_to_active(self, other, client, differences):
+        for k in self.__dict__:
+            if k in ('advertise_addr', 'listen_addr', 'remote_addrs', 'join_token',
+                     'rotate_worker_token', 'rotate_manager_token', 'spec',
+                     'default_addr_pool', 'subnet_size', 'data_path_addr'):
+                continue
+            if not client.option_minimal_versions[k]['supported']:
+                continue
+            value = getattr(self, k)
+            if value is None:
+                continue
+            other_value = getattr(other, k)
+            if value != other_value:
+                differences.add(k, parameter=value, active=other_value)
+        if self.rotate_worker_token:
+            differences.add('rotate_worker_token', parameter=True, active=False)
+        if self.rotate_manager_token:
+            differences.add('rotate_manager_token', parameter=True, active=False)
+        return differences
+
+
+class SwarmManager(DockerBaseClass):
+
+    def __init__(self, client, results):
+
+        super(SwarmManager, self).__init__()
+
+        self.client = client
+        self.results = results
+        self.check_mode = self.client.check_mode
+        self.swarm_info = {}
+
+        self.state = client.module.params['state']
+        self.force = client.module.params['force']
+        self.node_id = client.module.params['node_id']
+
+        self.differences = DifferenceTracker()
+        self.parameters = TaskParameters.from_ansible_params(client)
+
+        self.created = False
+
+    def __call__(self):
+        choice_map = {
+            "present": self.init_swarm,
+            "join": self.join,
+            "absent": self.leave,
+            "remove": self.remove,
+        }
+
+        choice_map.get(self.state)()
+
+        if self.client.module._diff or self.parameters.debug:
+            diff = dict()
+            diff['before'], diff['after'] = self.differences.get_before_after()
+            self.results['diff'] = diff
+
+    def inspect_swarm(self):
+        try:
+            data = self.client.inspect_swarm()
+            json_str = json.dumps(data, ensure_ascii=False)
+            self.swarm_info = json.loads(json_str)
+
+            self.results['changed'] = False
+            self.results['swarm_facts'] = self.swarm_info
+
+            unlock_key = self.get_unlock_key()
+            self.swarm_info.update(unlock_key)
+        except APIError:
+            return
+
+    def get_unlock_key(self):
+        default = {'UnlockKey': None}
+        if not self.has_swarm_lock_changed():
+            return default
+        try:
+            return self.client.get_unlock_key() or default
+        except APIError:
+            return default
+
+    def has_swarm_lock_changed(self):
+        return self.parameters.autolock_managers and (
+            self.created or self.differences.has_difference_for('autolock_managers')
+        )
+
+    def init_swarm(self):
+        if not self.force and self.client.check_if_swarm_manager():
+            self.__update_swarm()
+            return
+
+        if not self.check_mode:
+            init_arguments = {
+                'advertise_addr': self.parameters.advertise_addr,
+                'listen_addr': self.parameters.listen_addr,
+                'data_path_addr': self.parameters.data_path_addr,
+                'force_new_cluster': self.force,
+                'swarm_spec': self.parameters.spec,
+            }
+            if self.parameters.default_addr_pool is not None:
+                init_arguments['default_addr_pool'] = self.parameters.default_addr_pool
+            if self.parameters.subnet_size is not None:
+                init_arguments['subnet_size'] = self.parameters.subnet_size
+            try:
+                self.client.init_swarm(**init_arguments)
+            except APIError as exc:
+                self.client.fail("Can not create a new Swarm Cluster: %s" % to_native(exc))
+
+        if not self.client.check_if_swarm_manager():
+            if not self.check_mode:
+                self.client.fail("Swarm not created or other error!")
+
+        self.created = True
+        self.inspect_swarm()
+        self.results['actions'].append("New Swarm cluster created: %s" % (self.swarm_info.get('ID')))
+        self.differences.add('state', parameter='present', active='absent')
+        self.results['changed'] = True
+        self.results['swarm_facts'] = {
+            'JoinTokens': self.swarm_info.get('JoinTokens'),
+            'UnlockKey': self.swarm_info.get('UnlockKey')
+        }
+
+    def __update_swarm(self):
+        try:
+            self.inspect_swarm()
+            version = self.swarm_info['Version']['Index']
+            self.parameters.update_from_swarm_info(self.swarm_info)
+            old_parameters = TaskParameters()
+            old_parameters.update_from_swarm_info(self.swarm_info)
+            self.parameters.compare_to_active(old_parameters, self.client, self.differences)
+            if self.differences.empty:
+                self.results['actions'].append("No modification")
+                self.results['changed'] = False
+                return
+            update_parameters = TaskParameters.from_ansible_params(self.client)
+            update_parameters.update_parameters(self.client)
+            if not self.check_mode:
+                self.client.update_swarm(
+                    version=version, swarm_spec=update_parameters.spec,
+                    rotate_worker_token=self.parameters.rotate_worker_token,
+                    rotate_manager_token=self.parameters.rotate_manager_token)
+        except APIError as exc:
+            self.client.fail("Can not update a Swarm Cluster: %s" % to_native(exc))
+            return
+
+        self.inspect_swarm()
+        self.results['actions'].append("Swarm cluster updated")
+        self.results['changed'] = True
+
+    def join(self):
+        if self.client.check_if_swarm_node():
+            self.results['actions'].append("This node is already part of a swarm.")
+            return
+        if not self.check_mode:
+            try:
+                self.client.join_swarm(
+                    remote_addrs=self.parameters.remote_addrs, join_token=self.parameters.join_token,
+                    listen_addr=self.parameters.listen_addr, advertise_addr=self.parameters.advertise_addr,
+                    data_path_addr=self.parameters.data_path_addr)
+            except APIError as exc:
+                self.client.fail("Can not join the Swarm Cluster: %s" % to_native(exc))
+        self.results['actions'].append("New node is added to swarm cluster")
+        self.differences.add('joined', parameter=True, active=False)
+        self.results['changed'] = True
+
+    def leave(self):
+        if not self.client.check_if_swarm_node():
+            self.results['actions'].append("This node is not part of a swarm.")
+            return
+        if not self.check_mode:
+            try:
+                self.client.leave_swarm(force=self.force)
+            except APIError as exc:
+                self.client.fail("This node can not leave the Swarm Cluster: %s" % to_native(exc))
+        self.results['actions'].append("Node has left the swarm cluster")
+        self.differences.add('joined', parameter='absent', active='present')
+        self.results['changed'] = True
+
+    def remove(self):
+        if not self.client.check_if_swarm_manager():
+            self.client.fail("This node is not a manager.")
+
+        try:
+            status_down = self.client.check_if_swarm_node_is_down(node_id=self.node_id, repeat_check=5)
+        except APIError:
+            return
+
+        if not status_down:
+            self.client.fail("Can not remove the node. The status node is ready and not down.")
+
+        if not self.check_mode:
+            try:
+                self.client.remove_node(node_id=self.node_id, force=self.force)
+            except APIError as exc:
+                self.client.fail("Can not remove the node from the Swarm Cluster: %s" % to_native(exc))
+        self.results['actions'].append("Node is removed from swarm cluster.")
+        self.differences.add('joined', parameter=False, active=True)
+        self.results['changed'] = True
+
+
+def _detect_remove_operation(client):
+    return client.module.params['state'] == 'remove'
+
+
+def main():
+    argument_spec = dict(
+        advertise_addr=dict(type='str'),
+        data_path_addr=dict(type='str'),
+        state=dict(type='str', default='present', choices=['present', 'join', 'absent', 'remove']),
+        force=dict(type='bool', default=False),
+        listen_addr=dict(type='str', default='0.0.0.0:2377'),
+        remote_addrs=dict(type='list', elements='str'),
+        join_token=dict(type='str', no_log=True),
+        snapshot_interval=dict(type='int'),
+        task_history_retention_limit=dict(type='int'),
+        keep_old_snapshots=dict(type='int'),
+        log_entries_for_slow_followers=dict(type='int'),
+        heartbeat_tick=dict(type='int'),
+        election_tick=dict(type='int'),
+        dispatcher_heartbeat_period=dict(type='int'),
+        node_cert_expiry=dict(type='int'),
+        name=dict(type='str'),
+        labels=dict(type='dict'),
+        signing_ca_cert=dict(type='str'),
+        signing_ca_key=dict(type='str', no_log=True),
+        ca_force_rotate=dict(type='int'),
+        autolock_managers=dict(type='bool'),
+        node_id=dict(type='str'),
+        rotate_worker_token=dict(type='bool', default=False),
+        rotate_manager_token=dict(type='bool', default=False),
+        default_addr_pool=dict(type='list', elements='str'),
+        subnet_size=dict(type='int'),
+    )
+
+    required_if = [
+        ('state', 'join', ['remote_addrs', 'join_token']),
+        ('state', 'remove', ['node_id'])
+    ]
+
+    option_minimal_versions = dict(
+        labels=dict(docker_py_version='2.6.0', docker_api_version='1.32'),
+        signing_ca_cert=dict(docker_py_version='2.6.0', docker_api_version='1.30'),
+        signing_ca_key=dict(docker_py_version='2.6.0', docker_api_version='1.30'),
+        ca_force_rotate=dict(docker_py_version='2.6.0', docker_api_version='1.30'),
+        autolock_managers=dict(docker_py_version='2.6.0'),
+        log_driver=dict(docker_py_version='2.6.0'),
+        remove_operation=dict(
+            docker_py_version='2.4.0',
+            detect_usage=_detect_remove_operation,
+            usage_msg='remove swarm nodes'
+        ),
+        default_addr_pool=dict(docker_py_version='4.0.0', docker_api_version='1.39'),
+        subnet_size=dict(docker_py_version='4.0.0', docker_api_version='1.39'),
+        data_path_addr=dict(docker_py_version='4.0.0', docker_api_version='1.30'),
+    )
+
+    client = AnsibleDockerSwarmClient(
+        argument_spec=argument_spec,
+        supports_check_mode=True,
+        required_if=required_if,
+        min_docker_version='1.10.0',
+        min_docker_api_version='1.25',
+        option_minimal_versions=option_minimal_versions,
+    )
+
+    try:
+        results = dict(
+            changed=False,
+            result='',
+            actions=[]
+        )
+
+        SwarmManager(client, results)()
+        client.module.exit_json(**results)
+    except DockerException as e:
+        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except RequestException as e:
+        client.fail(
+            'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(to_native(e)),
+            exception=traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_swarm_info.py

@@ -0,0 +1,386 @@
+#!/usr/bin/python
+#
+# (c) 2019 Piotr Wojciechowski <piotr@it-playground.pl>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+DOCUMENTATION = '''
+---
+module: docker_swarm_info
+
+short_description: Retrieves facts about Docker Swarm cluster.
+
+description:
+  - Retrieves facts about a Docker Swarm.
+  - Returns lists of swarm objects names for the services - nodes, services, tasks.
+  - The output differs depending on API version available on docker host.
+  - Must be run on Swarm Manager node; otherwise module fails with error message.
+    It does return boolean flags in on both error and success which indicate whether
+    the docker daemon can be communicated with, whether it is in Swarm mode, and
+    whether it is a Swarm Manager node.
+
+
+author:
+    - Piotr Wojciechowski (@WojciechowskiPiotr)
+
+options:
+  nodes:
+    description:
+      - Whether to list swarm nodes.
+    type: bool
+    default: no
+  nodes_filters:
+    description:
+      - A dictionary of filter values used for selecting nodes to list.
+      - "For example, C(name: mynode)."
+      - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/node_ls/#filtering)
+        for more information on possible filters.
+    type: dict
+  services:
+    description:
+      - Whether to list swarm services.
+    type: bool
+    default: no
+  services_filters:
+    description:
+      - A dictionary of filter values used for selecting services to list.
+      - "For example, C(name: myservice)."
+      - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/service_ls/#filtering)
+        for more information on possible filters.
+    type: dict
+  tasks:
+    description:
+      - Whether to list containers.
+    type: bool
+    default: no
+  tasks_filters:
+    description:
+      - A dictionary of filter values used for selecting tasks to list.
+      - "For example, C(node: mynode-1)."
+      - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/service_ps/#filtering)
+        for more information on possible filters.
+    type: dict
+  unlock_key:
+    description:
+      - Whether to retrieve the swarm unlock key.
+    type: bool
+    default: no
+  verbose_output:
+    description:
+      - When set to C(yes) and I(nodes), I(services) or I(tasks) is set to C(yes), then the module output will
+        contain verbose information about objects matching the full output of API method.
+      - For details see the documentation of your version of Docker API at U(https://docs.docker.com/engine/api/).
+      - The verbose output in this module contains only subset of information returned by I(_info) module
+        for each type of the objects.
+    type: bool
+    default: no
+extends_documentation_fragment:
+- community.docker.docker
+- community.docker.docker.docker_py_1_documentation
+
+
+requirements:
+    - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 1.10.0 (use L(docker-py,https://pypi.org/project/docker-py/) for Python 2.6)"
+    - "Docker API >= 1.24"
+'''
+
+EXAMPLES = '''
+- name: Get info on Docker Swarm
+  community.docker.docker_swarm_info:
+  ignore_errors: yes
+  register: result
+
+- name: Inform about basic flags
+  ansible.builtin.debug:
+    msg: |
+      Was able to talk to docker daemon: {{ result.can_talk_to_docker }}
+      Docker in Swarm mode: {{ result.docker_swarm_active }}
+      This is a Manager node: {{ result.docker_swarm_manager }}
+
+- block:
+
+- name: Get info on Docker Swarm and list of registered nodes
+  community.docker.docker_swarm_info:
+    nodes: yes
+  register: result
+
+- name: Get info on Docker Swarm and extended list of registered nodes
+  community.docker.docker_swarm_info:
+    nodes: yes
+    verbose_output: yes
+  register: result
+
+- name: Get info on Docker Swarm and filtered list of registered nodes
+  community.docker.docker_swarm_info:
+    nodes: yes
+    nodes_filters:
+      name: mynode
+  register: result
+
+- ansible.builtin.debug:
+    var: result.swarm_facts
+
+- name: Get the swarm unlock key
+  community.docker.docker_swarm_info:
+    unlock_key: yes
+  register: result
+
+- ansible.builtin.debug:
+    var: result.swarm_unlock_key
+
+'''
+
+RETURN = '''
+can_talk_to_docker:
+    description:
+      - Will be C(true) if the module can talk to the docker daemon.
+    returned: both on success and on error
+    type: bool
+docker_swarm_active:
+    description:
+      - Will be C(true) if the module can talk to the docker daemon,
+        and the docker daemon is in Swarm mode.
+    returned: both on success and on error
+    type: bool
+docker_swarm_manager:
+    description:
+      - Will be C(true) if the module can talk to the docker daemon,
+        the docker daemon is in Swarm mode, and the current node is
+        a manager node.
+      - Only if this one is C(true), the module will not fail.
+    returned: both on success and on error
+    type: bool
+swarm_facts:
+    description:
+      - Facts representing the basic state of the docker Swarm cluster.
+      - Contains tokens to connect to the Swarm
+    returned: always
+    type: dict
+swarm_unlock_key:
+    description:
+      - Contains the key needed to unlock the swarm.
+    returned: When I(unlock_key) is C(true).
+    type: str
+nodes:
+    description:
+      - List of dict objects containing the basic information about each volume.
+        Keys matches the C(docker node ls) output unless I(verbose_output=yes).
+        See description for I(verbose_output).
+    returned: When I(nodes) is C(yes)
+    type: list
+    elements: dict
+services:
+    description:
+      - List of dict objects containing the basic information about each volume.
+        Keys matches the C(docker service ls) output unless I(verbose_output=yes).
+        See description for I(verbose_output).
+    returned: When I(services) is C(yes)
+    type: list
+    elements: dict
+tasks:
+    description:
+      - List of dict objects containing the basic information about each volume.
+        Keys matches the C(docker service ps) output unless I(verbose_output=yes).
+        See description for I(verbose_output).
+    returned: When I(tasks) is C(yes)
+    type: list
+    elements: dict
+
+'''
+
+import traceback
+
+try:
+    from docker.errors import DockerException, APIError
+except ImportError:
+    # missing Docker SDK for Python handled in ansible.module_utils.docker_common
+    pass
+
+from ansible.module_utils.common.text.converters import to_native
+
+from ansible_collections.community.docker.plugins.module_utils.swarm import AnsibleDockerSwarmClient
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    DockerBaseClass,
+    clean_dict_booleans_for_docker_api,
+    RequestException,
+)
+
+
+class DockerSwarmManager(DockerBaseClass):
+
+    def __init__(self, client, results):
+
+        super(DockerSwarmManager, self).__init__()
+
+        self.client = client
+        self.results = results
+        self.verbose_output = self.client.module.params['verbose_output']
+
+        listed_objects = ['tasks', 'services', 'nodes']
+
+        self.client.fail_task_if_not_swarm_manager()
+
+        self.results['swarm_facts'] = self.get_docker_swarm_facts()
+
+        for docker_object in listed_objects:
+            if self.client.module.params[docker_object]:
+                returned_name = docker_object
+                filter_name = docker_object + "_filters"
+                filters = clean_dict_booleans_for_docker_api(client.module.params.get(filter_name))
+                self.results[returned_name] = self.get_docker_items_list(docker_object, filters)
+        if self.client.module.params['unlock_key']:
+            self.results['swarm_unlock_key'] = self.get_docker_swarm_unlock_key()
+
+    def get_docker_swarm_facts(self):
+        try:
+            return self.client.inspect_swarm()
+        except APIError as exc:
+            self.client.fail("Error inspecting docker swarm: %s" % to_native(exc))
+
+    def get_docker_items_list(self, docker_object=None, filters=None):
+        items = None
+        items_list = []
+
+        try:
+            if docker_object == 'nodes':
+                items = self.client.nodes(filters=filters)
+            elif docker_object == 'tasks':
+                items = self.client.tasks(filters=filters)
+            elif docker_object == 'services':
+                items = self.client.services(filters=filters)
+        except APIError as exc:
+            self.client.fail("Error inspecting docker swarm for object '%s': %s" %
+                             (docker_object, to_native(exc)))
+
+        if self.verbose_output:
+            return items
+
+        for item in items:
+            item_record = dict()
+
+            if docker_object == 'nodes':
+                item_record = self.get_essential_facts_nodes(item)
+            elif docker_object == 'tasks':
+                item_record = self.get_essential_facts_tasks(item)
+            elif docker_object == 'services':
+                item_record = self.get_essential_facts_services(item)
+                if item_record['Mode'] == 'Global':
+                    item_record['Replicas'] = len(items)
+            items_list.append(item_record)
+
+        return items_list
+
+    @staticmethod
+    def get_essential_facts_nodes(item):
+        object_essentials = dict()
+
+        object_essentials['ID'] = item.get('ID')
+        object_essentials['Hostname'] = item['Description']['Hostname']
+        object_essentials['Status'] = item['Status']['State']
+        object_essentials['Availability'] = item['Spec']['Availability']
+        if 'ManagerStatus' in item:
+            object_essentials['ManagerStatus'] = item['ManagerStatus']['Reachability']
+            if 'Leader' in item['ManagerStatus'] and item['ManagerStatus']['Leader'] is True:
+                object_essentials['ManagerStatus'] = "Leader"
+        else:
+            object_essentials['ManagerStatus'] = None
+        object_essentials['EngineVersion'] = item['Description']['Engine']['EngineVersion']
+
+        return object_essentials
+
+    def get_essential_facts_tasks(self, item):
+        object_essentials = dict()
+
+        object_essentials['ID'] = item['ID']
+        # Returning container ID to not trigger another connection to host
+        # Container ID is sufficient to get extended info in other tasks
+        object_essentials['ContainerID'] = item['Status']['ContainerStatus']['ContainerID']
+        object_essentials['Image'] = item['Spec']['ContainerSpec']['Image']
+        object_essentials['Node'] = self.client.get_node_name_by_id(item['NodeID'])
+        object_essentials['DesiredState'] = item['DesiredState']
+        object_essentials['CurrentState'] = item['Status']['State']
+        if 'Err' in item['Status']:
+            object_essentials['Error'] = item['Status']['Err']
+        else:
+            object_essentials['Error'] = None
+
+        return object_essentials
+
+    @staticmethod
+    def get_essential_facts_services(item):
+        object_essentials = dict()
+
+        object_essentials['ID'] = item['ID']
+        object_essentials['Name'] = item['Spec']['Name']
+        if 'Replicated' in item['Spec']['Mode']:
+            object_essentials['Mode'] = "Replicated"
+            object_essentials['Replicas'] = item['Spec']['Mode']['Replicated']['Replicas']
+        elif 'Global' in item['Spec']['Mode']:
+            object_essentials['Mode'] = "Global"
+            # Number of replicas have to be updated in calling method or may be left as None
+            object_essentials['Replicas'] = None
+        object_essentials['Image'] = item['Spec']['TaskTemplate']['ContainerSpec']['Image']
+        if 'Ports' in item['Spec']['EndpointSpec']:
+            object_essentials['Ports'] = item['Spec']['EndpointSpec']['Ports']
+        else:
+            object_essentials['Ports'] = []
+
+        return object_essentials
+
+    def get_docker_swarm_unlock_key(self):
+        unlock_key = self.client.get_unlock_key() or {}
+        return unlock_key.get('UnlockKey') or None
+
+
+def main():
+    argument_spec = dict(
+        nodes=dict(type='bool', default=False),
+        nodes_filters=dict(type='dict'),
+        tasks=dict(type='bool', default=False),
+        tasks_filters=dict(type='dict'),
+        services=dict(type='bool', default=False),
+        services_filters=dict(type='dict'),
+        unlock_key=dict(type='bool', default=False),
+        verbose_output=dict(type='bool', default=False),
+    )
+    option_minimal_versions = dict(
+        unlock_key=dict(docker_py_version='2.7.0', docker_api_version='1.25'),
+    )
+
+    client = AnsibleDockerSwarmClient(
+        argument_spec=argument_spec,
+        supports_check_mode=True,
+        min_docker_version='1.10.0',
+        min_docker_api_version='1.24',
+        option_minimal_versions=option_minimal_versions,
+        fail_results=dict(
+            can_talk_to_docker=False,
+            docker_swarm_active=False,
+            docker_swarm_manager=False,
+        ),
+    )
+    client.fail_results['can_talk_to_docker'] = True
+    client.fail_results['docker_swarm_active'] = client.check_if_swarm_node()
+    client.fail_results['docker_swarm_manager'] = client.check_if_swarm_manager()
+
+    try:
+        results = dict(
+            changed=False,
+        )
+
+        DockerSwarmManager(client, results)
+        results.update(client.fail_results)
+        client.module.exit_json(**results)
+    except DockerException as e:
+        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except RequestException as e:
+        client.fail(
+            'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(to_native(e)),
+            exception=traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_swarm_service_info.py

@@ -0,0 +1,119 @@
+#!/usr/bin/python
+#
+# (c) 2019 Hannes Ljungberg <hannes.ljungberg@gmail.com>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: docker_swarm_service_info
+
+short_description: Retrieves information about docker services from a Swarm Manager
+
+description:
+  - Retrieves information about a docker service.
+  - Essentially returns the output of C(docker service inspect <name>).
+  - Must be executed on a host running as Swarm Manager, otherwise the module will fail.
+
+
+options:
+  name:
+    description:
+      - The name of the service to inspect.
+    type: str
+    required: yes
+extends_documentation_fragment:
+- community.docker.docker
+- community.docker.docker.docker_py_1_documentation
+
+
+author:
+  - Hannes Ljungberg (@hannseman)
+
+requirements:
+  - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 2.0.0"
+  - "Docker API >= 1.24"
+'''
+
+EXAMPLES = '''
+- name: Get info from a service
+  community.docker.docker_swarm_service_info:
+    name: myservice
+  register: result
+'''
+
+RETURN = '''
+exists:
+    description:
+      - Returns whether the service exists.
+    type: bool
+    returned: always
+    sample: true
+service:
+    description:
+      - A dictionary representing the current state of the service. Matches the C(docker service inspect) output.
+      - Will be C(none) if service does not exist.
+    returned: always
+    type: dict
+'''
+
+import traceback
+
+from ansible.module_utils.common.text.converters import to_native
+
+try:
+    from docker.errors import DockerException
+except ImportError:
+    # missing Docker SDK for Python handled in ansible.module_utils.docker.common
+    pass
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    RequestException,
+)
+
+from ansible_collections.community.docker.plugins.module_utils.swarm import AnsibleDockerSwarmClient
+
+
+def get_service_info(client):
+    service = client.module.params['name']
+    return client.get_service_inspect(
+        service_id=service,
+        skip_missing=True
+    )
+
+
+def main():
+    argument_spec = dict(
+        name=dict(type='str', required=True),
+    )
+
+    client = AnsibleDockerSwarmClient(
+        argument_spec=argument_spec,
+        supports_check_mode=True,
+        min_docker_version='2.0.0',
+        min_docker_api_version='1.24',
+    )
+
+    client.fail_task_if_not_swarm_manager()
+
+    try:
+        service = get_service_info(client)
+
+        client.module.exit_json(
+            changed=False,
+            service=service,
+            exists=bool(service)
+        )
+    except DockerException as e:
+        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except RequestException as e:
+        client.fail(
+            'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(to_native(e)),
+            exception=traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_volume.py

@@ -0,0 +1,312 @@
+#!/usr/bin/python
+# coding: utf-8
+#
+# Copyright 2017 Red Hat | Ansible, Alex Grönholm <alex.gronholm@nextday.fi>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+module: docker_volume
+short_description: Manage Docker volumes
+description:
+  - Create/remove Docker volumes.
+  - Performs largely the same function as the C(docker volume) CLI subcommand.
+options:
+  volume_name:
+    description:
+      - Name of the volume to operate on.
+    type: str
+    required: yes
+    aliases:
+      - name
+
+  driver:
+    description:
+      - Specify the type of volume. Docker provides the C(local) driver, but 3rd party drivers can also be used.
+    type: str
+    default: local
+
+  driver_options:
+    description:
+      - "Dictionary of volume settings. Consult docker docs for valid options and values:
+        U(https://docs.docker.com/engine/reference/commandline/volume_create/#driver-specific-options)."
+    type: dict
+
+  labels:
+    description:
+      - Dictionary of label key/values to set for the volume
+    type: dict
+
+  recreate:
+    description:
+      - Controls when a volume will be recreated when I(state) is C(present). Please
+        note that recreating an existing volume will cause B(any data in the existing volume
+        to be lost!) The volume will be deleted and a new volume with the same name will be
+        created.
+      - The value C(always) forces the volume to be always recreated.
+      - The value C(never) makes sure the volume will not be recreated.
+      - The value C(options-changed) makes sure the volume will be recreated if the volume
+        already exist and the driver, driver options or labels differ.
+    type: str
+    default: never
+    choices:
+    - always
+    - never
+    - options-changed
+
+  state:
+    description:
+      - C(absent) deletes the volume.
+      - C(present) creates the volume, if it does not already exist.
+    type: str
+    default: present
+    choices:
+      - absent
+      - present
+
+extends_documentation_fragment:
+- community.docker.docker
+- community.docker.docker.docker_py_1_documentation
+
+
+author:
+  - Alex Grönholm (@agronholm)
+
+requirements:
+  - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 1.10.0 (use L(docker-py,https://pypi.org/project/docker-py/) for Python 2.6)"
+  - "The docker server >= 1.9.0"
+'''
+
+EXAMPLES = '''
+- name: Create a volume
+  community.docker.docker_volume:
+    name: volume_one
+
+- name: Remove a volume
+  community.docker.docker_volume:
+    name: volume_one
+    state: absent
+
+- name: Create a volume with options
+  community.docker.docker_volume:
+    name: volume_two
+    driver_options:
+      type: btrfs
+      device: /dev/sda2
+'''
+
+RETURN = '''
+volume:
+    description:
+    - Volume inspection results for the affected volume.
+    returned: success
+    type: dict
+    sample: {}
+'''
+
+import traceback
+
+from ansible.module_utils.common.text.converters import to_native
+
+try:
+    from docker.errors import DockerException, APIError
+except ImportError:
+    # missing Docker SDK for Python handled in ansible.module_utils.docker.common
+    pass
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    DockerBaseClass,
+    AnsibleDockerClient,
+    DifferenceTracker,
+    RequestException,
+)
+from ansible.module_utils.six import iteritems, text_type
+
+
+class TaskParameters(DockerBaseClass):
+    def __init__(self, client):
+        super(TaskParameters, self).__init__()
+        self.client = client
+
+        self.volume_name = None
+        self.driver = None
+        self.driver_options = None
+        self.labels = None
+        self.recreate = None
+        self.debug = None
+
+        for key, value in iteritems(client.module.params):
+            setattr(self, key, value)
+
+
+class DockerVolumeManager(object):
+
+    def __init__(self, client):
+        self.client = client
+        self.parameters = TaskParameters(client)
+        self.check_mode = self.client.check_mode
+        self.results = {
+            u'changed': False,
+            u'actions': []
+        }
+        self.diff = self.client.module._diff
+        self.diff_tracker = DifferenceTracker()
+        self.diff_result = dict()
+
+        self.existing_volume = self.get_existing_volume()
+
+        state = self.parameters.state
+        if state == 'present':
+            self.present()
+        elif state == 'absent':
+            self.absent()
+
+        if self.diff or self.check_mode or self.parameters.debug:
+            if self.diff:
+                self.diff_result['before'], self.diff_result['after'] = self.diff_tracker.get_before_after()
+            self.results['diff'] = self.diff_result
+
+    def get_existing_volume(self):
+        try:
+            volumes = self.client.volumes()
+        except APIError as e:
+            self.client.fail(to_native(e))
+
+        if volumes[u'Volumes'] is None:
+            return None
+
+        for volume in volumes[u'Volumes']:
+            if volume['Name'] == self.parameters.volume_name:
+                return volume
+
+        return None
+
+    def has_different_config(self):
+        """
+        Return the list of differences between the current parameters and the existing volume.
+
+        :return: list of options that differ
+        """
+        differences = DifferenceTracker()
+        if self.parameters.driver and self.parameters.driver != self.existing_volume['Driver']:
+            differences.add('driver', parameter=self.parameters.driver, active=self.existing_volume['Driver'])
+        if self.parameters.driver_options:
+            if not self.existing_volume.get('Options'):
+                differences.add('driver_options',
+                                parameter=self.parameters.driver_options,
+                                active=self.existing_volume.get('Options'))
+            else:
+                for key, value in iteritems(self.parameters.driver_options):
+                    if (not self.existing_volume['Options'].get(key) or
+                            value != self.existing_volume['Options'][key]):
+                        differences.add('driver_options.%s' % key,
+                                        parameter=value,
+                                        active=self.existing_volume['Options'].get(key))
+        if self.parameters.labels:
+            existing_labels = self.existing_volume.get('Labels', {})
+            for label in self.parameters.labels:
+                if existing_labels.get(label) != self.parameters.labels.get(label):
+                    differences.add('labels.%s' % label,
+                                    parameter=self.parameters.labels.get(label),
+                                    active=existing_labels.get(label))
+
+        return differences
+
+    def create_volume(self):
+        if not self.existing_volume:
+            if not self.check_mode:
+                try:
+                    params = dict(
+                        driver=self.parameters.driver,
+                        driver_opts=self.parameters.driver_options,
+                    )
+
+                    if self.parameters.labels is not None:
+                        params['labels'] = self.parameters.labels
+
+                    resp = self.client.create_volume(self.parameters.volume_name, **params)
+                    self.existing_volume = self.client.inspect_volume(resp['Name'])
+                except APIError as e:
+                    self.client.fail(to_native(e))
+
+            self.results['actions'].append("Created volume %s with driver %s" % (self.parameters.volume_name, self.parameters.driver))
+            self.results['changed'] = True
+
+    def remove_volume(self):
+        if self.existing_volume:
+            if not self.check_mode:
+                try:
+                    self.client.remove_volume(self.parameters.volume_name)
+                except APIError as e:
+                    self.client.fail(to_native(e))
+
+            self.results['actions'].append("Removed volume %s" % self.parameters.volume_name)
+            self.results['changed'] = True
+
+    def present(self):
+        differences = DifferenceTracker()
+        if self.existing_volume:
+            differences = self.has_different_config()
+
+        self.diff_tracker.add('exists', parameter=True, active=self.existing_volume is not None)
+        if (not differences.empty and self.parameters.recreate == 'options-changed') or self.parameters.recreate == 'always':
+            self.remove_volume()
+            self.existing_volume = None
+
+        self.create_volume()
+
+        if self.diff or self.check_mode or self.parameters.debug:
+            self.diff_result['differences'] = differences.get_legacy_docker_diffs()
+            self.diff_tracker.merge(differences)
+
+        if not self.check_mode and not self.parameters.debug:
+            self.results.pop('actions')
+
+        volume_facts = self.get_existing_volume()
+        self.results['volume'] = volume_facts
+
+    def absent(self):
+        self.diff_tracker.add('exists', parameter=False, active=self.existing_volume is not None)
+        self.remove_volume()
+
+
+def main():
+    argument_spec = dict(
+        volume_name=dict(type='str', required=True, aliases=['name']),
+        state=dict(type='str', default='present', choices=['present', 'absent']),
+        driver=dict(type='str', default='local'),
+        driver_options=dict(type='dict', default={}),
+        labels=dict(type='dict'),
+        recreate=dict(type='str', default='never', choices=['always', 'never', 'options-changed']),
+        debug=dict(type='bool', default=False)
+    )
+
+    option_minimal_versions = dict(
+        labels=dict(docker_py_version='1.10.0', docker_api_version='1.23'),
+    )
+
+    client = AnsibleDockerClient(
+        argument_spec=argument_spec,
+        supports_check_mode=True,
+        min_docker_version='1.10.0',
+        min_docker_api_version='1.21',
+        # "The docker server >= 1.9.0"
+        option_minimal_versions=option_minimal_versions,
+    )
+
+    try:
+        cm = DockerVolumeManager(client)
+        client.module.exit_json(**cm.results)
+    except DockerException as e:
+        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except RequestException as e:
+        client.fail(
+            'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(to_native(e)),
+            exception=traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

collections/ansible_collections/community/docker/plugins/modules/docker_volume_info.py

@@ -0,0 +1,132 @@
+#!/usr/bin/python
+# coding: utf-8
+#
+# Copyright 2017 Red Hat | Ansible, Alex Grönholm <alex.gronholm@nextday.fi>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+module: docker_volume_info
+short_description: Retrieve facts about Docker volumes
+description:
+  - Performs largely the same function as the C(docker volume inspect) CLI subcommand.
+options:
+  name:
+    description:
+      - Name of the volume to inspect.
+    type: str
+    required: yes
+    aliases:
+      - volume_name
+
+extends_documentation_fragment:
+- community.docker.docker
+- community.docker.docker.docker_py_1_documentation
+
+
+author:
+  - Felix Fontein (@felixfontein)
+
+requirements:
+  - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 1.8.0 (use L(docker-py,https://pypi.org/project/docker-py/) for Python 2.6)"
+  - "Docker API >= 1.21"
+'''
+
+EXAMPLES = '''
+- name: Get infos on volume
+  community.docker.docker_volume_info:
+    name: mydata
+  register: result
+
+- name: Does volume exist?
+  ansible.builtin.debug:
+    msg: "The volume {{ 'exists' if result.exists else 'does not exist' }}"
+
+- name: Print information about volume
+  ansible.builtin.debug:
+    var: result.volume
+  when: result.exists
+'''
+
+RETURN = '''
+exists:
+    description:
+      - Returns whether the volume exists.
+    type: bool
+    returned: always
+    sample: true
+volume:
+    description:
+      - Volume inspection results for the affected volume.
+      - Will be C(none) if volume does not exist.
+    returned: success
+    type: dict
+    sample: '{
+            "CreatedAt": "2018-12-09T17:43:44+01:00",
+            "Driver": "local",
+            "Labels": null,
+            "Mountpoint": "/var/lib/docker/volumes/ansible-test-bd3f6172/_data",
+            "Name": "ansible-test-bd3f6172",
+            "Options": {},
+            "Scope": "local"
+        }'
+'''
+
+import traceback
+
+from ansible.module_utils.common.text.converters import to_native
+
+try:
+    from docker.errors import DockerException, NotFound
+except ImportError:
+    # missing Docker SDK for Python handled in ansible.module_utils.docker.common
+    pass
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    AnsibleDockerClient,
+    RequestException,
+)
+
+
+def get_existing_volume(client, volume_name):
+    try:
+        return client.inspect_volume(volume_name)
+    except NotFound as dummy:
+        return None
+    except Exception as exc:
+        client.fail("Error inspecting volume: %s" % to_native(exc))
+
+
+def main():
+    argument_spec = dict(
+        name=dict(type='str', required=True, aliases=['volume_name']),
+    )
+
+    client = AnsibleDockerClient(
+        argument_spec=argument_spec,
+        supports_check_mode=True,
+        min_docker_version='1.8.0',
+        min_docker_api_version='1.21',
+    )
+
+    try:
+        volume = get_existing_volume(client, client.module.params['name'])
+
+        client.module.exit_json(
+            changed=False,
+            exists=(True if volume else False),
+            volume=volume,
+        )
+    except DockerException as e:
+        client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except RequestException as e:
+        client.fail(
+            'An unexpected requests error occurred when docker-py tried to talk to the docker daemon: {0}'.format(to_native(e)),
+            exception=traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

collections/ansible_collections/community/docker/plugins/plugin_utils/common.py

@@ -0,0 +1,37 @@
+# Copyright (c) 2019-2020, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+from ansible.errors import AnsibleConnectionFailure
+from ansible.utils.display import Display
+
+from ansible_collections.community.docker.plugins.module_utils.common import (
+    AnsibleDockerClientBase,
+    DOCKER_COMMON_ARGS,
+)
+
+
+class AnsibleDockerClient(AnsibleDockerClientBase):
+    def __init__(self, plugin, min_docker_version=None, min_docker_api_version=None):
+        self.plugin = plugin
+        self.display = Display()
+        super(AnsibleDockerClient, self).__init__(
+            min_docker_version=min_docker_version,
+            min_docker_api_version=min_docker_api_version)
+
+    def fail(self, msg, **kwargs):
+        if kwargs:
+            msg += '\nContext:\n' + '\n'.join('  {0} = {1!r}'.format(k, v) for (k, v) in kwargs.items())
+        raise AnsibleConnectionFailure(msg)
+
+    def deprecate(self, msg, version=None, date=None, collection_name=None):
+        self.display.deprecated(msg, version=version, date=date, collection_name=collection_name)
+
+    def _get_params(self):
+        return dict([
+            (option, self.plugin.get_option(option))
+            for option in DOCKER_COMMON_ARGS
+        ])

collections/ansible_collections/community/docker/plugins/plugin_utils/socket_handler.py

@@ -0,0 +1,17 @@
+# Copyright (c) 2019-2020, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+from ansible.compat import selectors
+
+from ansible_collections.community.docker.plugins.module_utils.socket_handler import (
+    DockerSocketHandlerBase,
+)
+
+
+class DockerSocketHandler(DockerSocketHandlerBase):
+    def __init__(self, display, sock, log=None, container=None):
+        super(DockerSocketHandler, self).__init__(sock, selectors, log=lambda msg: display.vvvv(msg, host=container))