docker_container: deprecate ignore_image and purge_networks (#487)

* Deprecate ignore_image and purge_networks.

* Fix YAML.

* Simple replacement doesn't work in this case.

changelogs/fragments/487-docker_container-deprecate.yml

@@ -0,0 +1,3 @@
+deprecated_features:
+  - "docker_container - the ``ignore_image`` option is deprecated and will be removed in community.docker 4.0.0. Use ``image: ignore`` in ``comparisons`` instead (https://github.com/ansible-collections/community.docker/pull/487)."
+  - "docker_container - the ``purge_networks`` option is deprecated and will be removed in community.docker 4.0.0. Use ``networks: strict`` in ``comparisons`` instead, and make sure to provide ``networks``, with value ``[]`` if all networks should be removed (https://github.com/ansible-collections/community.docker/pull/487)."

plugins/module_utils/module_container/module.py

@@ -75,7 +75,6 @@ def __init__(self, module, engine_driver, client, active_options):
         self.param_output_logs = self.module.params['output_logs']
         self.param_paused = self.module.params['paused']
         self.param_pull = self.module.params['pull']
-        self.param_purge_networks = self.module.params['purge_networks']
         self.param_recreate = self.module.params['recreate']
         self.param_removal_wait_timeout = self.module.params['removal_wait_timeout']
         self.param_restart = self.module.params['restart']
@@ -128,7 +127,7 @@ def _parse_comparisons(self):
         # Process legacy ignore options
         if self.module.params['ignore_image']:
             self.all_options['image'].comparison = 'ignore'
-        if self.param_purge_networks:
+        if self.module.params['purge_networks']:
             self.all_options['networks'].comparison = 'strict'
         # Process comparsions specified by user
         if self.module.params.get('comparisons'):
@@ -177,7 +176,7 @@ def _parse_comparisons(self):
         # Check legacy values
         if self.module.params['ignore_image'] and self.all_options['image'].comparison != 'ignore':
             self.module.warn('The ignore_image option has been overridden by the comparisons option!')
-        if self.param_purge_networks and self.all_options['networks'].comparison != 'strict':
+        if self.module.params['purge_networks'] and self.all_options['networks'].comparison != 'strict':
             self.module.warn('The purge_networks option has been overridden by the comparisons option!')
 
     def _update_params(self):
@@ -630,7 +629,15 @@ def update_networks(self, container, container_created):
                 self.results['changed'] = True
                 updated_container = self._add_networks(container, network_differences)
 
-        if (self.all_options['networks'].comparison == 'strict' and self.module.params['networks'] is not None) or self.param_purge_networks:
+        purge_networks = self.all_options['networks'].comparison == 'strict' and self.module.params['networks'] is not None
+        if not purge_networks and self.module.params['purge_networks']:
+            purge_networks = True
+            self.module.deprecate(
+                'The purge_networks option is used while networks is not specified. In this case purge_networks=true cannot'
+                ' be replaced by `networks: strict` in comparisons, which is necessary once purge_networks is removed.'
+                ' Please modify the docker_container invocation by adding `networks: []`',
+                version='4.0.0', collection_name='community.docker')
+        if purge_networks:
             has_extra_networks, extra_networks = self.has_extra_networks(container)
             if has_extra_networks:
                 if self.diff.get('differences'):
@@ -799,7 +806,7 @@ def run_module(engine_driver):
             command_handling=dict(type='str', choices=['compatibility', 'correct'], default='correct'),
             default_host_ip=dict(type='str'),
             force_kill=dict(type='bool', default=False, aliases=['forcekill']),
-            ignore_image=dict(type='bool', default=False),
+            ignore_image=dict(type='bool', default=False, removed_in_version='4.0.0', removed_from_collection='community.docker'),
             image=dict(type='str'),
             image_comparison=dict(type='str', choices=['desired-image', 'current-image'], default='desired-image'),
             image_label_mismatch=dict(type='str', choices=['ignore', 'fail'], default='ignore'),
@@ -810,7 +817,7 @@ def run_module(engine_driver):
             output_logs=dict(type='bool', default=False),
             paused=dict(type='bool'),
             pull=dict(type='bool', default=False),
-            purge_networks=dict(type='bool', default=False),
+            purge_networks=dict(type='bool', default=False, removed_in_version='4.0.0', removed_from_collection='community.docker'),
             recreate=dict(type='bool', default=False),
             removal_wait_timeout=dict(type='float'),
             restart=dict(type='bool', default=False),

plugins/modules/docker_container.py

@@ -396,6 +396,8 @@
         stop this behavior by setting I(ignore_image) to C(true).
       - "B(Warning:) This option is ignored if C(image: ignore) or C(*: ignore) is specified in the
         I(comparisons) option."
+      - "This option is deprecated since community.docker 3.2.0 and will be removed in community.docker 4.0.0.
+        Use C(image: ignore) in I(comparisons) instead of I(ignore_image=true)."
     type: bool
     default: false
   image:
@@ -626,10 +628,10 @@
     description:
       - List of networks the container belongs to.
       - For examples of the data structure and usage see EXAMPLES below.
-      - To remove a container from one or more networks, use the I(purge_networks) option.
-      - If I(networks_cli_compatible) is set to C(false), this will not remove the default network if I(networks) is specified.
-        This is different from the behavior of C(docker run ...). You need to explicitly use I(purge_networks) to enforce
-        the removal of the default network (and all other networks not explicitly mentioned in I(networks)) in that case.
+      - "To remove a container from one or more networks, use C(networks: strict) in the I(comparisons) option."
+      - "If I(networks_cli_compatible) is set to C(false), this will not remove the default network if I(networks) is specified.
+        This is different from the behavior of C(docker run ...). You need to explicitly use C(networks: strict) in I(comparisons)
+        to enforce the removal of the default network (and all other networks not explicitly mentioned in I(networks)) in that case."
     type: list
     elements: dict
     suboptions:
@@ -666,8 +668,8 @@
          via the I(networks) option, the module behaves differently than C(docker run --network):
          C(docker run --network other) will create a container with network C(other) attached,
          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(true), the C(default) network will be removed afterwards."
+         create a container with both C(default) and C(other) attached. If C(networks: strict)
+         or C(*: strict) is set in I(comparisons), the C(default) network will be removed afterwards."
     type: bool
     default: true
   oom_killer:
@@ -745,16 +747,19 @@
       - ports
   pull:
     description:
-       - If true, always pull the latest version of an image. Otherwise, will only pull an image
-         when missing.
-       - "B(Note:) images are only pulled when specified by name. If the image is specified
-         as a image ID (hash), it cannot be pulled."
+      - If true, always pull the latest version of an image. Otherwise, will only pull an image
+        when missing.
+      - "B(Note:) images are only pulled when specified by name. If the image is specified
+        as a image ID (hash), it cannot be pulled."
     type: bool
     default: false
   purge_networks:
     description:
-       - Remove the container from ALL networks not included in I(networks) parameter.
-       - Any default networks such as C(bridge), if not found in I(networks), will be removed as well.
+      - Remove the container from ALL networks not included in I(networks) parameter.
+      - Any default networks such as C(bridge), if not found in I(networks), will be removed as well.
+      - "This option is deprecated since community.docker 3.2.0 and will be removed in community.docker 4.0.0.
+        Use C(networks: strict) in I(comparisons) instead of I(purge_networks=true) and make sure that
+        I(networks) is specified. If you want to remove all networks, specify I(networks: [])."
     type: bool
     default: false
   read_only:
@@ -824,8 +829,8 @@
         state. Use I(restart) to force a matching container to be stopped and restarted.'
       - 'C(stopped) - Asserts that the container is first C(present), and then if the container is running moves it to a stopped
         state.'
-      - To control what will be taken into account when comparing configuration, see the I(comparisons) option. To avoid that the
-        image version will be taken into account, you can also use the I(ignore_image) option.
+      - "To control what will be taken into account when comparing configuration, see the I(comparisons) option. To avoid that the
+        image version will be taken into account, you can also use the C(image: ignore) in the I(comparisons) option."
       - Use the I(recreate) option to always force re-creation of a matching container, even if it is running.
       - If the container should be killed instead of stopped in case it needs to be stopped for recreation, or because I(state) is
         C(stopped), please use the I(force_kill) option. Use I(keep_volumes) to retain anonymous volumes associated with a removed container.
@@ -1065,12 +1070,14 @@
     name: sleepy
     networks:
       - name: TestingNet2
-    purge_networks: true
+    comparisons:
+      networks: strict
 
 - name: Remove container from all networks
   community.docker.docker_container:
     name: sleepy
-    purge_networks: true
+    comparisons:
+      networks: strict
 
 - name: Start a container and use an env file
   community.docker.docker_container:

tests/integration/targets/docker_container/tasks/tests/network.yml

@@ -179,7 +179,8 @@
     command: '/bin/sh -c "sleep 10m"'
     name: "{{ cname }}"
     state: started
-    purge_networks: yes
+    comparisons:
+      networks: strict
     networks:
     - name: bridge
     - name: "{{ nname_1 }}"
@@ -193,7 +194,8 @@
     command: '/bin/sh -c "sleep 10m"'
     name: "{{ cname }}"
     state: started
-    purge_networks: yes
+    comparisons:
+      networks: strict
     networks:
     - name: "{{ nname_1 }}"
     - name: bridge
@@ -217,7 +219,8 @@
     command: '/bin/sh -c "sleep 10m"'
     name: "{{ cname }}"
     state: started
-    purge_networks: yes
+    comparisons:
+      networks: strict
     networks:
     - name: bridge
     networks_cli_compatible: no
@@ -230,7 +233,8 @@
     command: '/bin/sh -c "sleep 10m"'
     name: "{{ cname }}"
     state: started
-    purge_networks: yes
+    comparisons:
+      networks: strict
     networks:
     - name: bridge
     - name: "{{ nname_2 }}"
@@ -350,7 +354,8 @@
     state: started
     networks: []
     networks_cli_compatible: yes
-    purge_networks: yes
+    comparisons:
+      networks: strict
     force_kill: yes
   register: networks_5
 
@@ -387,7 +392,11 @@
     name: "{{ cname }}"
     state: started
     networks_cli_compatible: yes
-    purge_networks: yes
+    purge_networks: true
+    # To replace `purge_networks=true`, we have to specify `networks: []`:
+    #   comparisons:
+    #     networks: strict
+    #   networks: []
     force_kill: yes
   register: networks_8
 

tests/integration/targets/docker_container/tasks/tests/options.yml

@@ -2205,7 +2205,8 @@
 - name: ignore_image
   docker_container:
     image: "{{ docker_test_image_hello_world }}"
-    ignore_image: yes
+    comparisons:
+      image: ignore
     name: "{{ cname }}"
     state: started
   register: ignore_image
@@ -2214,7 +2215,8 @@
 - name: ignore_image (labels and env differ in image, image_comparison=current-image)
   docker_container:
     image: "{{ docker_test_image_registry_nginx }}"
-    ignore_image: yes
+    comparisons:
+      image: ignore
     image_comparison: current-image
     name: "{{ cname }}"
     state: started
@@ -2224,7 +2226,8 @@
 - name: ignore_image (labels and env differ in image, image_comparison=desired-image)
   docker_container:
     image: "{{ docker_test_image_registry_nginx }}"
-    ignore_image: yes
+    comparisons:
+      image: ignore
     image_comparison: desired-image
     name: "{{ cname }}"
     state: started