From 4070dab9a892a248922b3bd8e39702d74dd527d4 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 5 Oct 2021 17:39:42 +0200 Subject: [PATCH] Remove deprecated features, bump version to 2.0.0 (#210) * Remove docker_login's email option. * container_default_behavior now has default value no_defaults. * Disallow 'all' next to other ports. Deprecate 'all' in favor of publish_all_ports. * Change default for network_mode. * Add changelog fragment. * Fix tests. * Next expected release is 2.0.0. --- changelogs/fragments/210-deprecations.yml | 7 ++ galaxy.yml | 2 +- plugins/module_utils/common.py | 1 - plugins/modules/docker_container.py | 95 ++++++------------- plugins/modules/docker_login.py | 15 --- .../docker_container/tasks/tests/network.yml | 2 + 6 files changed, 40 insertions(+), 82 deletions(-) create mode 100644 changelogs/fragments/210-deprecations.yml diff --git a/changelogs/fragments/210-deprecations.yml b/changelogs/fragments/210-deprecations.yml new file mode 100644 index 000000000..6f8a97c0d --- /dev/null +++ b/changelogs/fragments/210-deprecations.yml @@ -0,0 +1,7 @@ +removed_features: + - "docker_container - the default value of ``container_default_behavior`` changed to ``no_defaults`` (https://github.com/ansible-collections/community.docker/pull/210)." + - "docker_container - the special value ``all`` can no longer be used in ``published_ports`` next to other values. Please use ``publish_all_ports=true`` instead (https://github.com/ansible-collections/community.docker/pull/210)." + - "docker_container - the default value of ``network_mode`` is now the name of the first network specified in ``networks`` if such are specified and ``networks_cli_compatible=true`` (https://github.com/ansible-collections/community.docker/pull/210)." + - "docker_login - removed the ``email`` option (https://github.com/ansible-collections/community.docker/pull/210)." +deprecated_features: + - "docker_container - using the special value ``all`` in ``published_ports`` has been deprecated. Use ``publish_all_ports=true`` instead (https://github.com/ansible-collections/community.docker/pull/210)." diff --git a/galaxy.yml b/galaxy.yml index f841b454d..e6815cfb8 100644 --- a/galaxy.yml +++ b/galaxy.yml @@ -2,7 +2,7 @@ namespace: community name: docker -version: 1.10.1 +version: 2.0.0 readme: README.md authors: - Ansible Docker Working Group diff --git a/plugins/module_utils/common.py b/plugins/module_utils/common.py index c9ab0a8e3..d03395e83 100644 --- a/plugins/module_utils/common.py +++ b/plugins/module_utils/common.py @@ -113,7 +113,6 @@ class RequestException(Exception): ] DEFAULT_DOCKER_REGISTRY = 'https://index.docker.io/v1/' -EMAIL_REGEX = r'[^@]+@[^@]+\.[^@]+' BYTE_SUFFIXES = ['B', 'KB', 'MB', 'GB', 'TB', 'PB'] diff --git a/plugins/modules/docker_container.py b/plugins/modules/docker_container.py index 82b8b429d..3b72c02db 100644 --- a/plugins/modules/docker_container.py +++ b/plugins/modules/docker_container.py @@ -25,18 +25,12 @@ - If the module needs to recreate the container, it will only use the options provided to the module to create the new container (except I(image)). Therefore, always specify *all* options relevant to the container. - When I(restart) is set to C(true), the module will only restart the container if no config changes are detected. - Please note that several options have default values; if the container to be restarted uses different values for - these options, it will be recreated instead. The options with default values which can cause this are I(auto_remove), - I(detach), I(init), I(interactive), I(memory), I(paused), I(privileged), I(read_only) and I(tty). This behavior - can be changed by setting I(container_default_behavior) to C(no_defaults), which will be the default value from - community.docker 2.0.0 on. options: auto_remove: description: - Enable auto-removal of the container on daemon side when the container's process exits. - - If I(container_default_behavior) is set to C(compatiblity) (the default value), this - option has a default of C(no). + - If I(container_default_behavior) is set to C(compatiblity), this option has a default of C(false). type: bool blkio_weight: description: @@ -91,19 +85,18 @@ type: dict container_default_behavior: description: - - Various module options used to have default values. This causes problems with - containers which use different values for these options. - - The default value is C(compatibility), which will ensure that the default values - are used when the values are not explicitly specified by the user. - - From community.docker 2.0.0 on, the default value will switch to C(no_defaults). To avoid - deprecation warnings, please set I(container_default_behavior) to an explicit - value. + - In older versions of this module, various module options used to have default values. + This caused problems with containers which use different values for these options. + - The default value is now C(no_defaults). To restore the old behavior, set it to + C(compatibility), which will ensure that the default values are used when the values + are not explicitly specified by the user. - This affects the I(auto_remove), I(detach), I(init), I(interactive), I(memory), I(paused), I(privileged), I(read_only) and I(tty) options. type: str choices: - compatibility - no_defaults + default: no_defaults command_handling: description: - The default behavior for I(command) (when provided as a list) and I(entrypoint) is to @@ -165,8 +158,7 @@ description: - Enable detached mode to leave the container running in background. - If disabled, the task will reflect the status of the container run (failed if the command failed). - - If I(container_default_behavior) is set to C(compatiblity) (the default value), this - option has a default of C(yes). + - If I(container_default_behavior) is set to C(compatiblity), this option has a default of C(true). type: bool devices: description: @@ -405,14 +397,12 @@ description: - Run an init inside the container that forwards signals and reaps processes. - This option requires Docker API >= 1.25. - - If I(container_default_behavior) is set to C(compatiblity) (the default value), this - option has a default of C(no). + - If I(container_default_behavior) is set to C(compatiblity), this option has a default of C(false). type: bool interactive: description: - Keep stdin open after a container is launched, even if not attached. - - If I(container_default_behavior) is set to C(compatiblity) (the default value), this - option has a default of C(no). + - If I(container_default_behavior) is set to C(compatiblity), this option has a default of C(false). type: bool ipc_mode: description: @@ -468,8 +458,7 @@ Unit can be C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte), C(T) (tebibyte), or C(P) (pebibyte)." - Omitting the unit defaults to bytes. - - If I(container_default_behavior) is set to C(compatiblity) (the default value), this - option has a default of C("0"). + - If I(container_default_behavior) is set to C(compatiblity), this option has a default of C("0"). type: str memory_reservation: description: @@ -582,8 +571,8 @@ network_mode: description: - Connect the container to a network. Choices are C(bridge), C(host), C(none), C(container:), C() or C(default). - - "*Note* that from community.docker 2.0.0 on, if I(networks_cli_compatible) is C(true) and I(networks) contains at least one network, - the default value for I(network_mode) will be the name of the first network in the I(networks) list. You can prevent this + - "Since community.docker 2.0.0, if I(networks_cli_compatible) is C(true) and I(networks) contains at least one network, + the default value for I(network_mode) is the name of the first network in the I(networks) list. You can prevent this by explicitly specifying a value for I(network_mode), like the default value C(default) which will be used by Docker if I(network_mode) is not specified." type: str @@ -637,13 +626,6 @@ but the default network not attached. This module with I(networks: {name: other}) will create a container with both C(default) and C(other) attached. If I(purge_networks) is set to C(yes), the C(default) network will be removed afterwards." - - "*Note* that docker CLI also sets I(network_mode) to the name of the first network - added if C(--network) is specified. For more compatibility with docker CLI, you - explicitly have to set I(network_mode) to the name of the first network you're - adding. This behavior will change for community.docker 2.0.0: then I(network_mode) will - automatically be set to the first network name in I(networks) if I(network_mode) - is not specified, I(networks) has at least one entry and I(networks_cli_compatible) - is C(true)." type: bool default: true oom_killer: @@ -664,8 +646,7 @@ paused: description: - Use with the started state to pause running processes inside the container. - - If I(container_default_behavior) is set to C(compatiblity) (the default value), this - option has a default of C(no). + - If I(container_default_behavior) is set to C(compatiblity), this option has a default of C(false). type: bool pid_mode: description: @@ -681,8 +662,7 @@ privileged: description: - Give extended privileges to the container. - - If I(container_default_behavior) is set to C(compatiblity) (the default value), this - option has a default of C(no). + - If I(container_default_behavior) is set to C(compatiblity), this option has a default of C(false). type: bool publish_all_ports: description: @@ -704,7 +684,8 @@ is different from the C(docker) command line utility. Use the L(dig lookup,../lookup/dig.html) to resolve hostnames." - A value of C(all) will publish all exposed container ports to random host ports, ignoring - any other mappings. Use I(publish_all_ports) instead as the use of C(all) will be deprecated in version 2.0.0. + any other mappings. This is deprecated since version 2.0.0 and will be disallowed in + community.docker 3.0.0. Use the I(publish_all_ports) option instead. - If I(networks) parameter is provided, will inspect each network to see if there exists a bridge network with optional parameter C(com.docker.network.bridge.host_binding_ipv4). If such a network is found, then published ports where no host IP address is specified @@ -732,8 +713,7 @@ read_only: description: - Mount the container's root file system as read-only. - - If I(container_default_behavior) is set to C(compatiblity) (the default value), this - option has a default of C(no). + - If I(container_default_behavior) is set to C(compatiblity), this option has a default of C(false). type: bool recreate: description: @@ -838,8 +818,7 @@ tty: description: - Allocate a pseudo-TTY. - - If I(container_default_behavior) is set to C(compatiblity) (the default value), this - option has a default of C(no). + - If I(container_default_behavior) is set to C(compatiblity), this option has a default of C(false). type: bool ulimits: description: @@ -1818,12 +1797,13 @@ def _parse_publish_ports(self): if 'all' in self.published_ports: if len(self.published_ports) > 1: - self.client.module.deprecate( - 'Specifying "all" in published_ports together with port mappings is not properly ' - 'supported by the module. The port mappings are currently ignored. Set publish_all_ports ' - 'to "true" to randomly assign port mappings for those not specified by published_ports. ' - 'The use of "all" in published_ports next to other values will be removed in version 2.0.0.', - collection_name='community.docker', version='2.0.0') + self.client.module.fail_json(msg='"all" can no longer be specified in published_ports next to ' + 'other values. Set publish_all_ports to "true" to randomly ' + 'assign port mappings for those not specified by published_ports.') + self.client.module.deprecate( + 'Specifying "all" in published_ports is deprecated. Set publish_all_ports to "true" instead ' + 'to randomly assign port mappings for those not specified by published_ports', + collection_name='community.docker', version='3.0.0') return 'all' default_ip = self.get_default_host_ip() @@ -3495,13 +3475,6 @@ def __init__(self, **kwargs): self._get_additional_minimal_versions() self._parse_comparisons() - if self.module.params['container_default_behavior'] is None: - self.module.params['container_default_behavior'] = 'compatibility' - self.module.deprecate( - 'The container_default_behavior option will change its default value from "compatibility" to ' - '"no_defaults" in community.docker 2.0.0. To remove this warning, please specify an explicit value for it now', - version='2.0.0', collection_name='community.docker' # was Ansible 2.14 / community.general 3.0.0 - ) if self.module.params['container_default_behavior'] == 'compatibility': old_default_values = dict( auto_remove=False, @@ -3529,7 +3502,7 @@ def main(): cleanup=dict(type='bool', default=False), command=dict(type='raw'), comparisons=dict(type='dict'), - container_default_behavior=dict(type='str', choices=['compatibility', 'no_defaults']), + container_default_behavior=dict(type='str', default='no_defaults', choices=['compatibility', 'no_defaults']), command_handling=dict(type='str', choices=['compatibility', 'correct']), cpu_period=dict(type='int'), cpu_quota=dict(type='int'), @@ -3671,17 +3644,9 @@ def main(): min_docker_api_version='1.20', ) if client.module.params['networks_cli_compatible'] is True and client.module.params['networks'] and client.module.params['network_mode'] is None: - client.module.deprecate( - 'Please note that the default value for `network_mode` will change from not specified ' - '(which is equal to `default`) to the name of the first network in `networks` if ' - '`networks` has at least one entry and `networks_cli_compatible` is `true`. You can ' - 'change the behavior now by explicitly setting `network_mode` to the name of the first ' - 'network in `networks`, and remove this warning by setting `network_mode` to `default`. ' - 'Please make sure that the value you set to `network_mode` equals the inspection result ' - 'for existing containers, otherwise the module will recreate them. You can find out the ' - 'correct value by running "docker inspect --format \'{{.HostConfig.NetworkMode}}\' "', - version='2.0.0', collection_name='community.docker', # was Ansible 2.14 / community.general 3.0.0 - ) + # Same behavior as Docker CLI: if networks are specified, use the name of the first network as the value for network_mode + # (assuming no explicit value is specified for network_mode) + client.module.params['network_mode'] = client.module.params['networks'][0]['name'] try: cm = ContainerManager(client) diff --git a/plugins/modules/docker_login.py b/plugins/modules/docker_login.py index 7cbcd0037..c4cccd2bc 100644 --- a/plugins/modules/docker_login.py +++ b/plugins/modules/docker_login.py @@ -40,11 +40,6 @@ - The plaintext password for the registry account. - Required when I(state) is C(present). type: str - email: - description: - - Does nothing, do not use. - - Will be removed in community.docker 2.0.0. - type: str reauthorize: description: - Refresh existing authentication found in the configuration file. @@ -147,7 +142,6 @@ HAS_DOCKER_PY, DEFAULT_DOCKER_REGISTRY, DockerBaseClass, - EMAIL_REGEX, RequestException, ) @@ -291,7 +285,6 @@ def __init__(self, client, results): self.registry_url = parameters.get('registry_url') self.username = parameters.get('username') self.password = parameters.get('password') - self.email = parameters.get('email') self.reauthorize = parameters.get('reauthorize') self.config_path = parameters.get('config_path') self.state = parameters.get('state') @@ -318,17 +311,12 @@ def login(self): :return: None ''' - if self.email and not re.match(EMAIL_REGEX, self.email): - self.fail("Parameter error: the email address appears to be incorrect. Expecting it to match " - "/%s/" % (EMAIL_REGEX)) - 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, - email=self.email, registry=self.registry_url, reauth=self.reauthorize, dockercfg_path=self.config_path @@ -346,7 +334,6 @@ def login(self): response = self.client.login( self.username, password=self.password, - email=self.email, registry=self.registry_url, reauth=True, dockercfg_path=self.config_path @@ -446,8 +433,6 @@ def main(): registry_url=dict(type='str', default=DEFAULT_DOCKER_REGISTRY, aliases=['registry', 'url']), username=dict(type='str'), password=dict(type='str', no_log=True), - # Was Ansible 2.14 / community.general 3.0.0: - email=dict(type='str', removed_in_version='2.0.0', removed_from_collection='community.docker'), 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']), diff --git a/tests/integration/targets/docker_container/tasks/tests/network.yml b/tests/integration/targets/docker_container/tasks/tests/network.yml index 9ef33643a..028fca3a8 100644 --- a/tests/integration/targets/docker_container/tasks/tests/network.yml +++ b/tests/integration/targets/docker_container/tasks/tests/network.yml @@ -465,6 +465,7 @@ - name: "{{ nname_2 }}" networks_cli_compatible: yes comparisons: + network_mode: ignore # otherwise we'd have to set network_mode to nname_1 networks: ignore register: networks_2 @@ -502,6 +503,7 @@ - name: "{{ nname_2 }}" networks_cli_compatible: yes comparisons: + network_mode: ignore # otherwise we'd have to set network_mode to nname_1 networks: allow_more_present force_kill: yes register: networks_5