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

@@ -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)."

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

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']
 
 

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:<name|id>), C(<network_name>) 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}}\' <container_name>"',
-            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)

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']),

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