From 89a1c68f982aab6ef52ce732391a8728688eb585 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sun, 3 Feb 2019 21:09:24 +0100 Subject: [PATCH] docker_volume: improve force option (deprecate, add new option) (#51145) * docker_volume: Deprecating force option, adding recreate option. * Add changelog. * Remove mis-placed force: yes for docker_volume. --- .../fragments/51145-docker_volume-force.yaml | 4 ++ .../modules/cloud/docker/docker_volume.py | 37 +++++++++++++++++-- .../docker_swarm_service/tasks/main.yml | 1 - .../tasks/tests/options.yml | 1 - .../targets/docker_volume/tasks/main.yml | 1 - .../docker_volume/tasks/tests/basic.yml | 23 ++++++++---- .../docker_volume_facts/tasks/main.yml | 2 - 7 files changed, 53 insertions(+), 16 deletions(-) create mode 100644 changelogs/fragments/51145-docker_volume-force.yaml diff --git a/changelogs/fragments/51145-docker_volume-force.yaml b/changelogs/fragments/51145-docker_volume-force.yaml new file mode 100644 index 0000000000..6e539ffce0 --- /dev/null +++ b/changelogs/fragments/51145-docker_volume-force.yaml @@ -0,0 +1,4 @@ +minor_changes: +- "docker_volume - the ``force`` option has been deprecated, and a new option ``recreate`` + has been added with default value ``never``. If you use ``force: yes`` in a playbook, + change it to ``recreate: options-changed`` instead." diff --git a/lib/ansible/modules/cloud/docker/docker_volume.py b/lib/ansible/modules/cloud/docker/docker_volume.py index 9a1f6d00c7..bb0739e089 100644 --- a/lib/ansible/modules/cloud/docker/docker_volume.py +++ b/lib/ansible/modules/cloud/docker/docker_volume.py @@ -51,8 +51,27 @@ options: - With state C(present) causes the volume to be deleted and recreated if the volume already exist and the driver, driver options or labels differ. This will cause any data in the existing volume to be lost. + - Deprecated. Will be removed in Ansible 2.12. Set I(recreate) to C(options-changed) instead + for the same behavior of setting I(force) to C(yes). type: bool - default: 'no' + default: no + + recreate: + version_added: "2.8" + description: + - Controls when a volume will be recreated when I(state) is C(present). Please + note that recreating an existing volume will cause I(any data in the existing volume + to be lost!) The volume will be deleted and a new volume with the same name will be + created. + - The value C(always) forces the volume to be always recreated. + - The value C(never) makes sure the volume will not be recreated. + - The value C(options-changed) makes sure the volume will be recreated if the volume + already exist and the driver, driver options or labels differ. + choices: + - always + - never + - options-changed + default: never state: description: @@ -133,11 +152,22 @@ class TaskParameters(DockerBaseClass): self.driver_options = None self.labels = None self.force = None + self.recreate = None self.debug = None for key, value in iteritems(client.module.params): setattr(self, key, value) + if self.force is not None: + if self.recreate != 'never': + client.module.fail_json(msg='Cannot use the deprecated "force" ' + 'option when "recreate" is set. Please stop ' + 'using the force option.') + client.module.warn('The "force" option of docker_volume has been deprecated ' + 'in Ansible 2.8. Please use the "recreate" ' + 'option, which provides the same functionality as "force".') + self.recreate = 'options-changed' if self.force else 'never' + class DockerVolumeManager(object): @@ -249,7 +279,7 @@ class DockerVolumeManager(object): differences = self.has_different_config() self.diff_tracker.add('exists', parameter=True, active=self.existing_volume is not None) - if not differences.empty and self.parameters.force: + if (not differences.empty and self.parameters.recreate == 'options-changed') or self.parameters.recreate == 'always': self.remove_volume() self.existing_volume = None @@ -276,7 +306,8 @@ def main(): driver=dict(type='str', default='local'), driver_options=dict(type='dict', default={}), labels=dict(type='dict'), - force=dict(type='bool', default=False), + force=dict(type='bool', removed_in_version='2.12'), + recreate=dict(type='str', default='never', choices=['always', 'never', 'options-changed']), debug=dict(type='bool', default=False) ) diff --git a/test/integration/targets/docker_swarm_service/tasks/main.yml b/test/integration/targets/docker_swarm_service/tasks/main.yml index a0b3d1e0c6..72828dfc15 100644 --- a/test/integration/targets/docker_swarm_service/tasks/main.yml +++ b/test/integration/targets/docker_swarm_service/tasks/main.yml @@ -52,7 +52,6 @@ docker_volume: name: "{{ item }}" state: absent - force: yes loop: "{{ volume_names }}" ignore_errors: yes diff --git a/test/integration/targets/docker_swarm_service/tasks/tests/options.yml b/test/integration/targets/docker_swarm_service/tasks/tests/options.yml index ae418f0131..6b9d8cb8e9 100644 --- a/test/integration/targets/docker_swarm_service/tasks/tests/options.yml +++ b/test/integration/targets/docker_swarm_service/tasks/tests/options.yml @@ -1844,7 +1844,6 @@ docker_volume: name: "{{ volume_name }}" state: absent - force: yes loop: - "{{ volume_name_1 }}" - "{{ volume_name_2 }}" diff --git a/test/integration/targets/docker_volume/tasks/main.yml b/test/integration/targets/docker_volume/tasks/main.yml index 17432bc4e4..43b417d41f 100644 --- a/test/integration/targets/docker_volume/tasks/main.yml +++ b/test/integration/targets/docker_volume/tasks/main.yml @@ -17,7 +17,6 @@ docker_volume: name: "{{ item }}" state: absent - force: yes with_items: "{{ vnames }}" when: docker_py_version is version('1.10.0', '>=') and docker_api_version is version('1.20', '>=') # FIXME: find out API version! diff --git a/test/integration/targets/docker_volume/tasks/tests/basic.yml b/test/integration/targets/docker_volume/tasks/tests/basic.yml index 35dbb37341..a01bb5865d 100644 --- a/test/integration/targets/docker_volume/tasks/tests/basic.yml +++ b/test/integration/targets/docker_volume/tasks/tests/basic.yml @@ -20,12 +20,18 @@ name: "{{ vname }}" register: create_2 -- name: Create a volume (force) +- name: "Create a volume (recreate: options-changed)" docker_volume: name: "{{ vname }}" - force: yes + recreate: options-changed register: create_3 +- name: "Create a volume (recreate: always)" + docker_volume: + name: "{{ vname }}" + recreate: always + register: create_4 + - name: Remove a volume docker_volume: name: "{{ vname }}" @@ -43,6 +49,7 @@ - create_1 is changed - create_2 is not changed - create_3 is not changed + - create_4 is changed - absent_1 is changed - absent_2 is not changed @@ -80,7 +87,7 @@ o: size=200m,uid=1000 register: driver_options_3 -- name: Create a volume with options (changed, force) +- name: "Create a volume with options (changed, recreate: options-changed)" docker_volume: name: "{{ vname }}" driver: local @@ -88,7 +95,7 @@ type: tempfs device: tmpfs o: size=200m,uid=1000 - force: yes + recreate: options-changed register: driver_options_4 - name: Cleanup @@ -130,12 +137,12 @@ ansible.test.1: hello register: driver_labels_3 -- name: Create a volume with labels (less, force) +- name: "Create a volume with labels (less, recreate: options-changed)" docker_volume: name: "{{ vname }}" labels: ansible.test.1: hello - force: yes + recreate: options-changed register: driver_labels_4 - name: Create a volume with labels (more) @@ -146,13 +153,13 @@ ansible.test.3: ansible register: driver_labels_5 -- name: Create a volume with labels (more, force) +- name: "Create a volume with labels (more, recreate: options-changed)" docker_volume: name: "{{ vname }}" labels: ansible.test.1: hello ansible.test.3: ansible - force: yes + recreate: options-changed register: driver_labels_6 - name: Cleanup diff --git a/test/integration/targets/docker_volume_facts/tasks/main.yml b/test/integration/targets/docker_volume_facts/tasks/main.yml index 1c834e5071..5537f486cf 100644 --- a/test/integration/targets/docker_volume_facts/tasks/main.yml +++ b/test/integration/targets/docker_volume_facts/tasks/main.yml @@ -8,7 +8,6 @@ docker_volume: name: "{{ cname }}" state: absent - force: yes - name: Inspect a non-present volume docker_volume_facts: @@ -44,7 +43,6 @@ docker_volume: name: "{{ cname }}" state: absent - force: yes - assert: that: