VMWare: update documentation for linked_clone (#42881)

linked_clone requires snapshot_src parameter. This fix makes them required_together
and update documentation. Also, testcase is added.

Fixes: #42349

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>

lib/ansible/modules/cloud/vmware/vmware_guest.py

@@ -208,10 +208,12 @@ options:
     description:
     - Name of the existing snapshot to use to create a clone of a virtual machine.
     - This parameter is case sensitive.
+    - While creating linked clone using C(linked_clone) parameter, this parameter is required.
     version_added: '2.4'
   linked_clone:
     description:
     - Whether to create a linked clone from the snapshot specified.
+    - If specified, then C(snapshot_src) is required parameter.
     default: 'no'
     type: bool
     version_added: '2.4'
@@ -2012,17 +2014,25 @@ class PyVmomiHelper(PyVmomi):
                 # > pool: For a clone operation from a template to a virtual machine, this argument is required.
                 relospec.pool = resource_pool
 
-                if self.params['snapshot_src'] is not None and self.params['linked_clone']:
+                linked_clone = self.params.get('linked_clone')
-                    relospec.diskMoveType = vim.vm.RelocateSpec.DiskMoveOptions.createNewChildDiskBacking
+                snapshot_src = self.params.get('snapshot_src', None)
+                if linked_clone:
+                    if snapshot_src is not None:
+                        relospec.diskMoveType = vim.vm.RelocateSpec.DiskMoveOptions.createNewChildDiskBacking
+                    else:
+                        self.module.fail_json(msg="Parameter 'linked_src' and 'snapshot_src' are"
+                                                  " required together for linked clone operation.")
 
                 clonespec = vim.vm.CloneSpec(template=self.params['is_template'], location=relospec)
                 if self.customspec:
                     clonespec.customization = self.customspec
 
-                if self.params['snapshot_src'] is not None:
+                if snapshot_src is not None:
-                    snapshot = self.get_snapshots_by_name_recursively(snapshots=vm_obj.snapshot.rootSnapshotList, snapname=self.params['snapshot_src'])
+                    snapshot = self.get_snapshots_by_name_recursively(snapshots=vm_obj.snapshot.rootSnapshotList,
+                                                                      snapname=snapshot_src)
                     if len(snapshot) != 1:
-                        self.module.fail_json(msg='virtual machine "%(template)s" does not contain snapshot named "%(snapshot_src)s"' % self.params)
+                        self.module.fail_json(msg='virtual machine "%(template)s" does not contain'
+                                                  ' snapshot named "%(snapshot_src)s"' % self.params)
 
                     clonespec.snapshot = snapshot[0].snapshot
 

test/integration/targets/vmware_guest/tasks/linked_clone_d1_c1_f0.yml

@@ -0,0 +1,129 @@
+# Test code for the vmware_guest module.
+# Copyright: (c) 2018, Abhijeet Kasurde <akasurde@redhat.com>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+- name: Wait for Flask controller to come up online
+  wait_for:
+    host: "{{ vcsim }}"
+    port: 5000
+    state: started
+
+- name: kill vcsim
+  uri:
+    url: http://{{ vcsim }}:5000/killall
+- name: start vcsim with no folders
+  uri:
+    url: http://{{ vcsim }}:5000/spawn?datacenter=1&cluster=1&folder=0
+  register: vcsim_instance
+
+- name: Wait for Flask controller to come up online
+  wait_for:
+    host: "{{ vcsim }}"
+    port: 443
+    state: started
+
+- name: get a list of VMS from vcsim
+  uri:
+    url: http://{{ vcsim }}:5000/govc_find?filter=VM
+  register: vmlist
+
+- debug: var=vcsim_instance
+- debug: var=vmlist
+
+- name: create new linked clone without specifying snapshot_src
+  vmware_guest:
+    validate_certs: False
+    hostname: "{{ vcsim }}"
+    username: "{{ vcsim_instance['json']['username'] }}"
+    password: "{{ vcsim_instance['json']['password'] }}"
+    name: "{{ 'new_vm_' + item|basename }}"
+    template: "{{ item|basename }}"
+    guest_id: centos64Guest
+    datacenter: "{{ (item|basename).split('_')[0] }}"
+    folder: "{{ item|dirname }}"
+    linked_clone: True
+  with_items: "{{ vmlist['json'] }}"
+  register: linked_clone_d1_c1_f0
+  ignore_errors: True
+
+- debug: var=linked_clone_d1_c1_f0
+
+- name: assert that changes were not made
+  assert:
+    that:
+        - "linked_clone_d1_c1_f0.results|map(attribute='changed')|unique|list == [false]"
+
+- name: create new linked clone without specifying linked_clone
+  vmware_guest:
+    validate_certs: False
+    hostname: "{{ vcsim }}"
+    username: "{{ vcsim_instance['json']['username'] }}"
+    password: "{{ vcsim_instance['json']['password'] }}"
+    name: "{{ 'new_vm_' + item|basename }}"
+    template: "{{ item|basename }}"
+    guest_id: centos64Guest
+    datacenter: "{{ (item|basename).split('_')[0] }}"
+    folder: "{{ item|dirname }}"
+    snapshot_src: "snap_shot1"
+  with_items: "{{ vmlist['json'] }}"
+  register: linked_clone_d1_c1_f0
+  ignore_errors: True
+
+- debug: var=linked_clone_d1_c1_f0
+
+- name: assert that changes were not made
+  assert:
+    that:
+        - "linked_clone_d1_c1_f0.results|map(attribute='changed')|unique|list == [false]"
+
+# TODO: VCSIM: snapshot is not supported in current vcsim
+#
+#- name: create new linked clone with linked_clone and snapshot_src
+#  vmware_guest:
+#    validate_certs: False
+#    hostname: "{{ vcsim }}"
+#    username: "{{ vcsim_instance['json']['username'] }}"
+#    password: "{{ vcsim_instance['json']['password'] }}"
+#    name: "{{ 'new_vm_' + item|basename }}"
+#    template: "{{ item|basename }}"
+#    guest_id: centos64Guest
+#    datacenter: "{{ (item|basename).split('_')[0] }}"
+#    folder: "{{ item|dirname }}"
+#    snapshot_src: "snap_shot1"
+#    linked_clone: True
+#  with_items: "{{ vmlist['json'] }}"
+#  register: linked_clone_d1_c1_f0
+#  ignore_errors: True
+
+#- debug: var=linked_clone_d1_c1_f0
+
+#- name: assert that changes were made
+#  assert:
+#    that:
+#        - "linked_clone_d1_c1_f0.results|map(attribute='changed')|unique|list == [true]"
+
+# TODO: VCSIM: snapshot is not supported in current vcsim
+#
+#- name: create new linked clone with linked_clone and snapshot_src again
+#  vmware_guest:
+#    validate_certs: False
+#    hostname: "{{ vcsim }}"
+#    username: "{{ vcsim_instance['json']['username'] }}"
+#    password: "{{ vcsim_instance['json']['password'] }}"
+#    name: "{{ 'new_vm_' + item|basename }}"
+#    template: "{{ item|basename }}"
+#    guest_id: centos64Guest
+#    datacenter: "{{ (item|basename).split('_')[0] }}"
+#    folder: "{{ item|dirname }}"
+#    snapshot_src: "snap_shot1"
+#    linked_clone: True
+#  with_items: "{{ vmlist['json'] }}"
+#  register: linked_clone_d1_c1_f0
+#  ignore_errors: True
+
+#- debug: var=linked_clone_d1_c1_f0
+
+#- name: assert that changes were not made
+#  assert:
+#    that:
+#        - "linked_clone_d1_c1_f0.results|map(attribute='changed')|unique|list == [false]"

test/integration/targets/vmware_guest/tasks/main.yml

@@ -30,3 +30,4 @@
 - include: disk_size_d1_c1_f0.yml
 - include: network_with_device.yml
 - include: disk_mode_d1_c1_f0.yml
+- include: linked_clone_d1_c1_f0.yml