From 51d5744cb049bd60bfa520fda105a821d55da2d6 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 1 Nov 2022 19:57:56 +0100 Subject: [PATCH] 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. --- .../487-docker_container-deprecate.yml | 3 ++ .../module_utils/module_container/module.py | 19 ++++++--- plugins/modules/docker_container.py | 39 +++++++++++-------- .../docker_container/tasks/tests/network.yml | 21 +++++++--- .../docker_container/tasks/tests/options.yml | 9 +++-- 5 files changed, 60 insertions(+), 31 deletions(-) create mode 100644 changelogs/fragments/487-docker_container-deprecate.yml diff --git a/changelogs/fragments/487-docker_container-deprecate.yml b/changelogs/fragments/487-docker_container-deprecate.yml new file mode 100644 index 000000000..0cb300d3e --- /dev/null +++ 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)." diff --git a/plugins/module_utils/module_container/module.py b/plugins/module_utils/module_container/module.py index 282901def..5c3623247 100644 --- a/plugins/module_utils/module_container/module.py +++ b/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), diff --git a/plugins/modules/docker_container.py b/plugins/modules/docker_container.py index bebd24a5b..13d257e10 100644 --- a/plugins/modules/docker_container.py +++ b/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: diff --git a/tests/integration/targets/docker_container/tasks/tests/network.yml b/tests/integration/targets/docker_container/tasks/tests/network.yml index bad742e3d..adab728ff 100644 --- 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 diff --git a/tests/integration/targets/docker_container/tasks/tests/options.yml b/tests/integration/targets/docker_container/tasks/tests/options.yml index d39fd2c32..ab15b8f1f 100644 --- 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