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.

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."

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)
     )
 

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
 

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 }}"

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!

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

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: