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.
2025-12-16 03:52:05 +00:00 · 2022-11-01 19:57:56 +01:00 · 2022-11-01 19:57:56 +01:00 · 51d5744cb0
commit 51d5744cb0
parent 1ac3a99e7c
5 changed files with 60 additions and 31 deletions
--- a/changelogs/fragments/487-docker_container-deprecate.yml
+++ b/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)."
--- a/plugins/module_utils/module_container/module.py
+++ b/plugins/module_utils/module_container/module.py
@ -75,7 +75,6 @@ class ContainerManager(DockerBaseClass):
        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 @@ class ContainerManager(DockerBaseClass):
        # 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 @@ class ContainerManager(DockerBaseClass):
        # 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 @@ class ContainerManager(DockerBaseClass):
                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),
--- a/plugins/modules/docker_container.py
+++ b/plugins/modules/docker_container.py
@ -396,6 +396,8 @@ options:
        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 @@ options:
    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 @@ options:
         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 @@ options:
      - 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 @@ options:
        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 @@ EXAMPLES = '''
    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:
--- a/tests/integration/targets/docker_container/tasks/tests/network.yml
+++ b/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

--- a/tests/integration/targets/docker_container/tasks/tests/options.yml
+++ b/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