Add docker_image_build module. (#735)

README.md

@@ -62,6 +62,7 @@ If you use the Ansible package and do not update collections independently, use
     - community.docker.docker_container_info: retrieve information on Docker containers
     - community.docker.docker_host_info: retrieve information on the Docker daemon
     - community.docker.docker_image: manage Docker images
+    - community.docker.docker_image_build: build Docker images using Docker buildx
     - community.docker.docker_image_info: retrieve information on Docker images
     - community.docker.docker_image_load: load Docker images from archives
     - community.docker.docker_image_pull: pull Docker images from registries

meta/runtime.yml

@@ -14,6 +14,7 @@ action_groups:
     - docker_container_info
     - docker_host_info
     - docker_image
+    - docker_image_build
     - docker_image_info
     - docker_image_load
     - docker_image_pull

plugins/doc_fragments/docker.py

@@ -297,3 +297,100 @@ class ModuleDocFragment(object):
   - pyOpenSSL (when using TLS)
   - backports.ssl_match_hostname (when using TLS on Python 2)
 '''
+
+    # Docker doc fragment when using the Docker CLI
+    CLI_DOCUMENTATION = r'''
+options:
+    docker_cli:
+        description:
+            - Path to the Docker CLI. If not provided, will search for Docker CLI on the E(PATH).
+        type: path
+    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, V(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 E(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 E(DOCKER_TLS_HOSTNAME) will
+              be used instead. If the environment variable is not set, the default value will be used.
+            - Note that this option had a default value V(localhost) in older versions. It was removed in community.docker 3.0.0.
+        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 this collection and the docker daemon.
+            - If the value is not specified in the task, the value of environment variable E(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 E(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 E(DOCKER_CERT_PATH) is set,
+              the file C(ca.pem) from the directory specified in the environment variable E(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 E(DOCKER_CERT_PATH) is set,
+              the file C(cert.pem) from the directory specified in the environment variable E(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 E(DOCKER_CERT_PATH) is set,
+              the file C(key.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used.
+        type: path
+        aliases: [ tls_client_key, key_path ]
+    tls:
+        description:
+            - Secure the connection to the API by using TLS without verifying the authenticity of the Docker host
+              server. Note that if O(validate_certs) is set to V(true) as well, it will take precedence.
+            - If the value is not specified in the task, the value of environment variable E(DOCKER_TLS) will be used
+              instead. If the environment variable is not set, the default value will be used.
+        type: bool
+        default: false
+    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 E(DOCKER_TLS_VERIFY) will be
+              used instead. If the environment variable is not set, the default value will be used.
+        type: bool
+        default: false
+        aliases: [ tls_verify ]
+    debug:
+        description:
+            - Debug mode
+        type: bool
+        default: false
+    cli_context:
+        description:
+            - The Docker CLI context to use.
+        type: str
+
+notes:
+  - Connect to the Docker daemon by providing parameters with each task or by defining environment variables.
+    You can define E(DOCKER_HOST), E(DOCKER_TLS_HOSTNAME), E(DOCKER_API_VERSION), E(DOCKER_CERT_PATH),
+    E(DOCKER_TLS), E(DOCKER_TLS_VERIFY) and E(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.
+  - This module does B(not) use the L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) to
+    communicate with the Docker daemon. It directly calls the Docker CLI program.
+'''

plugins/module_utils/common.py

@@ -482,7 +482,7 @@ def find_image(self, name, tag):
                     images = self._image_lookup(lookup, tag)
 
         if len(images) > 1:
-            self.fail("Registry returned more than one result for %s:%s" % (name, tag))
+            self.fail("Daemon returned more than one result for %s:%s" % (name, tag))
 
         if len(images) == 1:
             try:

plugins/module_utils/common_api.py

@@ -396,7 +396,7 @@ def find_image(self, name, tag):
                     images = self._image_lookup(lookup, tag)
 
         if len(images) > 1:
-            self.fail("Registry returned more than one result for %s:%s" % (name, tag))
+            self.fail("Daemon returned more than one result for %s:%s" % (name, tag))
 
         if len(images) == 1:
             try: