diff --git a/changelogs/fragments/51145-docker_volume-force.yaml b/changelogs/fragments/51145-docker_volume-force.yaml new file mode 100644 index 00000000000..6e539ffce0f --- /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 9a1f6d00c76..bb0739e089c 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 a0b3d1e0c68..72828dfc15a 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 ae418f01312..6b9d8cb8e92 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 17432bc4e4d..43b417d41ff 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 35dbb373416..a01bb5865d6 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 1c834e50716..5537f486cf7 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: