diff --git a/CHANGELOG.md b/CHANGELOG.md index 414703d7e6f..6637a4b3e93 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -212,6 +212,7 @@ While neither is technically a new plugin, these connections may now be used dir * vmware_drs_rule_facts * vmware_guest_file_operation * vmware_guest_powerstate + * vmware_guest_snapshot_facts * vmware_host_acceptance * vmware_host_config_facts * vmware_host_config_manager diff --git a/lib/ansible/modules/cloud/vmware/vmware_guest_snapshot_facts.py b/lib/ansible/modules/cloud/vmware/vmware_guest_snapshot_facts.py new file mode 100644 index 00000000000..88b836d094c --- /dev/null +++ b/lib/ansible/modules/cloud/vmware/vmware_guest_snapshot_facts.py @@ -0,0 +1,157 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- +# Copyright: (c) 2018, Ansible Project +# Copyright: (c) 2018, Abhijeet Kasurde +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +ANSIBLE_METADATA = { + 'metadata_version': '1.1', + 'status': ['preview'], + 'supported_by': 'community' +} + + +DOCUMENTATION = ''' +--- +module: vmware_guest_snapshot_facts +short_description: Gather facts about virtual machine's snapshots in vCenter +description: + - This module can be used to gather facts about virtual machine's snapshots. +version_added: 2.6 +author: + - Abhijeet Kasurde (@akasurde) +notes: + - Tested on vSphere 6.0 and 6.5 +requirements: + - "python >= 2.6" + - PyVmomi +options: + name: + description: + - Name of the VM to work with. + - This is required if C(uuid) is not supplied. + uuid: + description: + - UUID of the instance to manage if known, this value is VMware's unique identifier. + - This is required if C(name) is not supplied. + - The C(folder) is ignored, if C(uuid) is provided. + folder: + description: + - Destination folder, absolute or relative path to find an existing guest. + - This is required only, if multiple virtual machines with same name are found on given vCenter. + - The folder should include the datacenter. ESX's datacenter is ha-datacenter + - 'Examples:' + - ' folder: /ha-datacenter/vm' + - ' folder: ha-datacenter/vm' + - ' folder: /datacenter1/vm' + - ' folder: datacenter1/vm' + - ' folder: /datacenter1/vm/folder1' + - ' folder: datacenter1/vm/folder1' + - ' folder: /folder1/datacenter1/vm' + - ' folder: folder1/datacenter1/vm' + - ' folder: /folder1/datacenter1/vm/folder2' + datacenter: + description: + - Name of the datacenter. + required: True +extends_documentation_fragment: vmware.documentation +''' + +EXAMPLES = ''' + - name: Gather facts about the virtual machine in given vCenter + vmware_guest_snapshot_facts: + hostname: 192.168.1.209 + username: administrator@vsphere.local + password: vmware + datacenter: datacenter_name + name: dummy_vm + delegate_to: localhost + register: snapshot_facts +''' + +RETURN = """ +guest_snapshots: + description: metadata about the snapshot facts + returned: always + type: dict + sample: { + "current_snapshot": { + "creation_time": "2018-02-10T14:48:31.999459+00:00", + "description": "", + "id": 28, + "name": "snap_0003", + "state": "poweredOff" + }, + "snapshots": [ + { + "creation_time": "2018-02-10T14:48:31.999459+00:00", + "description": "", + "id": 28, + "name": "snap_0003", + "state": "poweredOff" + } + ] + } +""" + +from ansible.module_utils.basic import AnsibleModule +from ansible.module_utils.vmware import PyVmomi, list_snapshots, vmware_argument_spec + + +class PyVmomiHelper(PyVmomi): + def __init__(self, module): + super(PyVmomiHelper, self).__init__(module) + + @staticmethod + def gather_guest_snapshot_facts(vm_obj=None): + """ + Function to return snpashot related facts about given virtual machine + Args: + vm_obj: Virtual Machine Managed object + + Returns: Dictionary containing snapshot facts + + """ + if vm_obj is None: + return {} + return list_snapshots(vm=vm_obj) + + +def main(): + argument_spec = vmware_argument_spec() + argument_spec.update( + name=dict(type='str'), + uuid=dict(type='str'), + folder=dict(type='str'), + datacenter=dict(required=True, type='str'), + ) + module = AnsibleModule(argument_spec=argument_spec, + required_together=[['name', 'folder']], + required_one_of=[['name', 'uuid']], + ) + + if module.params['folder']: + # FindByInventoryPath() does not require an absolute path + # so we should leave the input folder path unmodified + module.params['folder'] = module.params['folder'].rstrip('/') + + pyv = PyVmomiHelper(module) + # Check if the VM exists before continuing + vm = pyv.get_vm() + + if not vm: + # If UUID is set, getvm select UUID, show error message accordingly. + module.fail_json(msg="Unable to gather facts about snapshots for" + " non-existing VM ['%s']" % (module.params.get('uuid') or + module.params.get('name'))) + + results = dict(changed=False, guest_snapshots=pyv.gather_guest_snapshot_facts(vm_obj=vm)) + module.exit_json(**results) + + +if __name__ == '__main__': + main() diff --git a/test/integration/targets/vmware_guest_snapshot_facts/aliases b/test/integration/targets/vmware_guest_snapshot_facts/aliases new file mode 100644 index 00000000000..dcb429935f2 --- /dev/null +++ b/test/integration/targets/vmware_guest_snapshot_facts/aliases @@ -0,0 +1,3 @@ +posix/ci/cloud/group4/vcenter +cloud/vcenter +destructive diff --git a/test/integration/targets/vmware_guest_snapshot_facts/tasks/main.yml b/test/integration/targets/vmware_guest_snapshot_facts/tasks/main.yml new file mode 100644 index 00000000000..3433c59d5f9 --- /dev/null +++ b/test/integration/targets/vmware_guest_snapshot_facts/tasks/main.yml @@ -0,0 +1,73 @@ +# Test code for the vmware_host_dns_facts module. +# Copyright: (c) 2018, Abhijeet Kasurde +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +# TODO: vcsim does not support snapshot related functionalities + +# - name: make sure pyvmomi is installed +# pip: +# name: pyvmomi +# state: latest +# when: ansible_user_id == 'root' +# +# - name: store the vcenter container ip +# set_fact: +# vcsim: "{{ lookup('env', 'vcenter_host') }}" +# - debug: var=vcsim +# +# - 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=1' }}" +# 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 +# +# - set_fact: +# vm1: "{{ vmlist['json'][0] }}" +# +# - name: get a list of datacenters from vcsim +# uri: +# url: "{{ 'http://' + vcsim + ':5000/govc_find?filter=DC' }}" +# register: datacenters +# +# - set_fact: +# dc1: "{{ datacenters['json'][0] }}" +# +# - debug: var=vcsim_instance +# - debug: var=vmlist +# - debug: var=vm1 +# - debug: var=dc1 +# +# - name: Gather snapshot facts about given virtual machine +# vmware_guest_snapshot_facts: +# validate_certs: False +# hostname: "{{ vcsim }}" +# username: "{{ vcsim_instance['json']['username'] }}" +# password: "{{ vcsim_instance['json']['password'] }}" +# datacenter: "{{ dc1 | basename }}" +# folder: "{{ vm1 | dirname }}" +# register: vm_snapshot_facts + +# - debug: vm_snapshot_facts + +# - assert: +# that: +# - "not vm_snapshot_facts.changed"