diff --git a/changelogs/fragments/134-tls_hostname.yml b/changelogs/fragments/134-tls_hostname.yml new file mode 100644 index 00000000..2a64ea60 --- /dev/null +++ b/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)." diff --git a/plugins/doc_fragments/docker.py b/plugins/doc_fragments/docker.py index f3006e8e..d10bb78b 100644 --- a/plugins/doc_fragments/docker.py +++ b/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. diff --git a/plugins/module_utils/common.py b/plugins/module_utils/common.py index 02653d38..fd7cdeaf 100644 --- a/plugins/module_utils/common.py +++ b/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 diff --git a/plugins/plugin_utils/common.py b/plugins/plugin_utils/common.py index 4742367e..120bb791 100644 --- a/plugins/plugin_utils/common.py +++ b/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))