Deprecate default for tls_hostname (#134)

* Start removing default.

* Add deprecate() function to AnsibleDockerClientBase.

* Deprecate default value for tls_hostname.

* Add changelog.

* Mention deprecation in documentation.

changelogs/fragments/134-tls_hostname.yml

@@ -0,0 +1,2 @@
+deprecated_features:
+- "docker_* modules and plugins, except ``docker_swarm`` connection plugin and ``docker_compose`` and ``docker_stack*` modules - the current default ``localhost`` for ``tls_hostname`` is deprecated. In community.docker 2.0.0 it will be computed from ``docker_host`` instead (https://github.com/ansible-collections/community.docker/pull/134)."

plugins/doc_fragments/docker.py

@@ -27,8 +27,10 @@ options:
             - 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
-        default: localhost
     api_version:
         description:
             - The version of the Docker API running on the Docker Host.

plugins/module_utils/common.py

@@ -77,13 +77,13 @@ except ImportError:
 DEFAULT_DOCKER_HOST = 'unix://var/run/docker.sock'
 DEFAULT_TLS = False
 DEFAULT_TLS_VERIFY = False
-DEFAULT_TLS_HOSTNAME = 'localhost'
+DEFAULT_TLS_HOSTNAME = 'localhost'  # deprecated
 MIN_DOCKER_VERSION = "1.8.0"
 DEFAULT_TIMEOUT_SECONDS = 60
 
 DOCKER_COMMON_ARGS = dict(
     docker_host=dict(type='str', default=DEFAULT_DOCKER_HOST, fallback=(env_fallback, ['DOCKER_HOST']), aliases=['docker_url']),
-    tls_hostname=dict(type='str', default=DEFAULT_TLS_HOSTNAME, fallback=(env_fallback, ['DOCKER_TLS_HOSTNAME'])),
+    tls_hostname=dict(type='str', fallback=(env_fallback, ['DOCKER_TLS_HOSTNAME'])),
     api_version=dict(type='str', default='auto', fallback=(env_fallback, ['DOCKER_API_VERSION']), aliases=['docker_api_version']),
     timeout=dict(type='int', default=DEFAULT_TIMEOUT_SECONDS, fallback=(env_fallback, ['DOCKER_TIMEOUT'])),
     ca_cert=dict(type='path', aliases=['tls_ca_cert', 'cacert_path']),
@@ -172,8 +172,18 @@ class DockerBaseClass(object):
         #         log_file.write(msg + u'\n')
 
 
-def update_tls_hostname(result):
+def update_tls_hostname(result, old_behavior=False, deprecate_function=None):
     if result['tls_hostname'] is None:
+        if old_behavior:
+            result['tls_hostname'] = DEFAULT_TLS_HOSTNAME
+            if deprecate_function is not None:
+                deprecate_function(
+                    'The default value "localhost" for tls_hostname is deprecated and will be removed in community.docker 2.0.0.'
+                    ' From then on, docker_host will be used to compute tls_hostname. If you want to keep using "localhost",'
+                    ' please set that value explicitly.',
+                    version='2.0.0', collection_name='community.docker')
+            return
+
         # get default machine name from the url
         parsed_url = urlparse(result['docker_host'])
         if ':' in parsed_url.netloc:
@@ -310,6 +320,9 @@ class AnsibleDockerClientBase(Client):
     def fail(self, msg, **kwargs):
         pass
 
+    def deprecate(self, msg, version=None, date=None, collection_name=None):
+        pass
+
     @staticmethod
     def _get_value(param_name, param_value, env_variable, default_value):
         if param_value is not None:
@@ -360,7 +373,7 @@ class AnsibleDockerClientBase(Client):
             docker_host=self._get_value('docker_host', params['docker_host'], 'DOCKER_HOST',
                                         DEFAULT_DOCKER_HOST),
             tls_hostname=self._get_value('tls_hostname', params['tls_hostname'],
-                                         'DOCKER_TLS_HOSTNAME', DEFAULT_TLS_HOSTNAME),
+                                         'DOCKER_TLS_HOSTNAME', None),
             api_version=self._get_value('api_version', params['api_version'], 'DOCKER_API_VERSION',
                                         'auto'),
             cacert_path=self._get_value('cacert_path', params['ca_cert'], 'DOCKER_CERT_PATH', None),
@@ -375,7 +388,10 @@ class AnsibleDockerClientBase(Client):
             use_ssh_client=self._get_value('use_ssh_client', params['use_ssh_client'], None, False),
         )
 
-        update_tls_hostname(result)
+        def depr(*args, **kwargs):
+            self.deprecate(*args, **kwargs)
+
+        update_tls_hostname(result, old_behavior=True, deprecate_function=depr)
 
         return result
 
@@ -657,6 +673,9 @@ class AnsibleDockerClient(AnsibleDockerClientBase):
         self.fail_results.update(kwargs)
         self.module.fail_json(msg=msg, **sanitize_result(self.fail_results))
 
+    def deprecate(self, msg, version=None, date=None, collection_name=None):
+        self.module.deprecate(msg, version=version, date=date, collection_name=collection_name)
+
     def _get_params(self):
         return self.module.params
 

plugins/plugin_utils/common.py

@@ -6,7 +6,7 @@ __metaclass__ = type
 
 
 from ansible.errors import AnsibleConnectionFailure
-
+from ansible.utils.display import Display
 
 from ansible_collections.community.docker.plugins.module_utils.common import (
     AnsibleDockerClientBase,
@@ -17,6 +17,7 @@ from ansible_collections.community.docker.plugins.module_utils.common import (
 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)
@@ -26,6 +27,9 @@ class AnsibleDockerClient(AnsibleDockerClientBase):
             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))