Implements extra_hosts for docker_image module (#59540)

* Implements etc_hosts for docker_image module

Allows custom hosts on docker_image module.

The of this option made impossible to use docker_image module to build
images that required a custom hostname in /etc/hosts. For running
containers this option was already present.

While the python-docker API uses extra_hosts term, our existing module
already uses etc_hosts argument, so it sounds better to have some
consistency between docker_container and docker_image.

Fixes: #59233

* Update test/integration/targets/docker_image/files/EtcHostsDockerfile

Co-Authored-By: Felix Fontein <felix@fontein.de>

* Update lib/ansible/modules/cloud/docker/docker_image.py

Co-Authored-By: Felix Fontein <felix@fontein.de>

* Update changelogs/fragments/docker_image_etc_hosts.yml

Co-Authored-By: Felix Fontein <felix@fontein.de>

changelogs/fragments/docker_image_etc_hosts.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - docker_image - added ``extra_hosts`` argument (https://github.com/ansible/ansible/issues/59233)

lib/ansible/modules/cloud/docker/docker_image.py

@@ -92,6 +92,11 @@ options:
           - 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
+        version_added: "2.9"
       args:
         description:
           - Provide a dictionary of C(key:value) build arguments that map to Dockerfile ARG directive.
@@ -324,6 +329,7 @@ requirements:
 author:
   - Pavel Antonov (@softzilla)
   - Chris Houseknecht (@chouseknecht)
+  - Sorin Sbarnea (@ssbarnea)
 
 '''
 
@@ -424,6 +430,7 @@ import traceback
 from distutils.version import LooseVersion
 
 from ansible.module_utils.docker.common import (
+    clean_dict_booleans_for_docker_api,
     docker_version,
     AnsibleDockerClient,
     DockerBaseClass,
@@ -469,6 +476,7 @@ class ImageManager(DockerBaseClass):
         self.load_path = parameters.get('load_path')
         self.name = parameters.get('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')
@@ -738,6 +746,8 @@ class ImageManager(DockerBaseClass):
             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
@@ -813,6 +823,7 @@ def main():
             args=dict(type='dict'),
             use_config_proxy=dict(type='bool'),
             target=dict(type='str'),
+            etc_hosts=dict(type='dict'),
         )),
         archive_path=dict(type='path'),
         container_limits=dict(type='dict', options=dict(
@@ -859,11 +870,15 @@ def main():
     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'))
+
     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)
 
     client = AnsibleDockerClient(
         argument_spec=argument_spec,

test/integration/targets/docker_image/files/EtcHostsDockerfile

@@ -0,0 +1,3 @@
+FROM busybox
+# This should fail building if docker cannot resolve some-custom-host
+RUN ping -c1 some-custom-host

test/integration/targets/docker_image/tasks/tests/options.yml

@@ -316,3 +316,29 @@
     that:
     - dockerfile_2 is changed
     - dockerfile_2.image.Config.WorkingDir == '/first'
+
+####################################################################
+## build.etc_hosts #################################################
+####################################################################
+
+- name: Build image with custom etc_hosts
+  docker_image:
+    name: "{{ iname }}"
+    build:
+      path: "{{ role_path }}/files"
+      dockefile: "EtcHostsDockerfile"
+      pull: no
+      etc_hosts:
+        some-custom-host: "127.0.0.1"
+    source: build
+  register: path_1
+
+- name: cleanup
+  docker_image:
+    name: "{{ iname }}"
+    state: absent
+    force_absent: yes
+
+- assert:
+    that:
+      - path_1 is changed