Add new role for VM snapshot management

changelogs/fragments/24-snapshot_management.yml

@@ -0,0 +1,3 @@
+major_changes:
+  - snapshot_management - Add a new role and playbooks to manages virtual machines snapshots in vCenter.
+    (https://github.com/redhat-cop/cloud.vmware_ops/pull/24)

playbooks/snapshot_management/create_snapshot.yml

@@ -0,0 +1,9 @@
+---
+- name: Playbook to create a VM snapshot
+  hosts: all
+  gather_facts: false
+
+  roles:
+    - role: cloud.vmware_ops.snapshot_management
+      vars:
+        snapshot_management_state: present

playbooks/snapshot_management/remove_all_snapshots.yml

@@ -0,0 +1,9 @@
+---
+- name: Playbook to remove all VM snapshots
+  hosts: all
+  gather_facts: false
+
+  roles:
+    - role: cloud.vmware_ops.snapshot_management
+      vars:
+        snapshot_management_state: remove_all

playbooks/snapshot_management/remove_snapshot.yml

@@ -0,0 +1,9 @@
+---
+- name: Playbook to remove a VM snapshot
+  hosts: all
+  gather_facts: false
+
+  roles:
+    - role: cloud.vmware_ops.snapshot_management
+      vars:
+        snapshot_management_state: absent

playbooks/snapshot_management/revert_to_a_snapshot.yml

@@ -0,0 +1,9 @@
+---
+- name: Playbook to revert a VM state to a given snapshot
+  hosts: all
+  gather_facts: false
+
+  roles:
+    - role: cloud.vmware_ops.snapshot_management
+      vars:
+        snapshot_management_state: revert

roles/snapshot_management/README.md

@@ -0,0 +1,233 @@
+# Provision virtual machine
+A role to manages virtual machines snapshots in vCenter.
+This role can be used to create, delete and update snapshot(s) of the given virtual machine.
+
+
+## Requirements 
+N/A
+
+
+## Role Variables
+### Auth
+- **snapshot_management_username**: (string, Required)
+  - The vSphere vCenter username.
+
+- **snapshot_management_password**: (string, Required)
+  - The vSphere vCenter password.
+
+- **snapshot_management_hostname**: (string, Required)
+  - The hostname or IP address of the vSphere vCenter.
+
+- **snapshot_management_validate_certs** (boolean)
+  - Allows connection when SSL certificates are not valid. Set to false when certificates are not trusted.
+
+- **snapshot_management_port** (integer):
+    The port number of the vSphere vCenter or ESXi server.
+    If the value is not specified in the task, the value of environment variable VMWARE_PORT will be used instead.
+    Default: 443
+
+- **snapshot_management_proxy_host** (string):
+    Address of a proxy that will receive all HTTPS requests and relay them.
+    The format is a hostname or a IP.
+    If the value is not specified in the task, the value of environment variable VMWARE_PROXY_HOST will be used instead.
+
+- **snapshot_management_proxy_port** (integer):
+    Port of the HTTP proxy that will receive all HTTPS requests and relay them.
+    If the value is not specified in the task, the value of environment variable VMWARE_PROXY_PORT will be used instead.
+
+### Manage a VM snapshot
+- **snapshot_management_state**: 
+  - Manage snapshot(s) attached to a specific virtual machine.
+  - If set to C(present) and snapshot absent, then will create a new snapshot with the given name.
+     - If set to C(present) and snapshot present, then no changes are made.
+     - If set to C(absent) and snapshot present, then snapshot with the given name is removed.
+     - If set to C(absent) and snapshot absent, then no changes are made.
+     - If set to C(revert) and snapshot present, then virtual machine state is reverted to the given snapshot.
+     - If set to C(revert) and snapshot absent, then no changes are made.
+     - If set to C(remove_all) and snapshot(s) present, then all snapshot(s) will be removed.
+     - If set to C(remove_all) and snapshot(s) absent, then no changes are made.
+  - choices: ['present', 'absent', 'revert', 'remove_all']
+  - default: 'present'
+
+- **snapshot_management_name**:
+  - Name of the virtual machine to work with.
+  - This is required parameter, if C(uuid) or C(moid) is not supplied.
+
+- **snapshot_management_name_match**: 
+  - If multiple VMs matching the name, use the first or last found.
+  - default: 'first'
+  - choices: ['first', 'last']
+
+- **snapshot_management_uuid**: 
+  - UUID of the instance to manage if known, this is VMware's BIOS UUID by default.
+  - This is required if C(name) or C(moid) parameter is not supplied.
+
+- **snapshot_management_moid**: 
+  - Managed Object ID of the instance to manage if known, this is a unique identifier only within a single vCenter instance.
+  - This is required if C(name) or C(uuid) is not supplied.
+
+- **snapshot_management_use_instance_uuid**: 
+  - Whether to use the VMware instance UUID rather than the BIOS UUID.
+  - default: false
+
+- **snapshot_management_folder**: 
+  - Destination folder, absolute or relative path to find an existing guest.
+  - This is required parameter, if C(name) is supplied.
+  - 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'
+
+- **snapshot_management_datacenter**: 
+  - Destination datacenter for the deploy operation.
+  - required: true
+
+- **snapshot_management_snapshot_name**: 
+  - Sets the snapshot name to manage.
+  - This param or C(snapshot_id) is required only if state is not C(remove_all)
+
+- **snapshot_management_snapshot_id**: 
+  - Sets the snapshot ID to manage.
+  - This param is available when state is C(absent).
+
+- **snapshot_management_description**: 
+  - Define an arbitrary description to attach to snapshot.
+  - default: ''
+
+- **snapshot_management_quiesce**: 
+  - If set to C(true) and virtual machine is powered on, it will quiesce the file system in the virtual machine.
+  - Note that VMware Tools are required for this flag.
+  - If virtual machine is powered off or VMware Tools are not available, then this flag is set to C(false).
+  - If virtual machine does not provide capability to take quiesce snapshot, then this flag is set to C(false).
+  - default: false
+
+- **snapshot_management_memory_dump**: 
+  - If set to C(true), memory dump of virtual machine is also included in snapshot.
+  - Note that memory snapshots take time and resources, this will take longer time to create.
+  - If virtual machine does not provide capability to take memory snapshot, then this flag is set to C(false).
+  - default: false
+
+- **snapshot_management_remove_children**: 
+  - If set to C(true) and state is set to C(absent), then the entire snapshot subtree is set for removal.
+  - default: false
+
+- **snapshot_management_new_snapshot_name**: 
+  - Value to rename the existing snapshot to.
+
+- **snapshot_management_new_description**: 
+  - Value to change the description of an existing snapshot to.
+
+
+## Dependencies
+
+N/A
+
+## Example Playbooks
+
+All the variables defined in section [Role Variables](#role-variables) can be defined inside the ``vars.yml`` file.
+
+Create a ``playbook.yml`` file like this:
+
+```
+---
+- name: Create a VM snapshot
+  hosts: all
+  gather_facts: false
+
+  roles:
+    - role: cloud.vmware_ops.snapshot_management
+      vars:
+        snapshot_management_state: present
+        snapshot_management_hostname: "test"
+        snapshot_management_username: "test"
+        snapshot_management_password: "test"
+        snapshot_management_validate_certs: false
+        snapshot_management_port: "8989"
+        snapshot_management_folder: "/DC0/vm"
+        snapshot_management_datacenter: "DC0"
+        snapshot_management_name: "vm-test"
+        snapshot_management_snapshot_name: "snap1"
+        snapshot_management_snapshot_description: "snap1_description"
+```
+```
+---
+- name: Remove a VM snapshot and snapshot subtree
+  hosts: all
+  gather_facts: false
+
+  roles:
+    - role: cloud.vmware_ops.snapshot_management
+      vars:
+        snapshot_management_state: absent
+        snapshot_management_hostname: "test"
+        snapshot_management_username: "test"
+        snapshot_management_password: "test"
+        snapshot_management_validate_certs: false
+        snapshot_management_port: "8989"
+        snapshot_management_folder: "/DC0/vm"
+        snapshot_management_datacenter: "DC0"
+        snapshot_management_name: "vm-test"
+        snapshot_management_snapshot_name: "snap1"
+        snapshot_management_snapshot_remove_children: true
+```
+```
+---
+- name: Revert VM to a snapshot
+  hosts: all
+  gather_facts: false
+
+  roles:
+    - role: cloud.vmware_ops.snapshot_management
+      vars:
+        snapshot_management_state: revert
+        snapshot_management_hostname: "test"
+        snapshot_management_username: "test"
+        snapshot_management_password: "test"
+        snapshot_management_validate_certs: false
+        snapshot_management_port: "8989"
+        snapshot_management_folder: "/DC0/vm"
+        snapshot_management_datacenter: "DC0"
+        snapshot_management_name: "vm-test"
+        snapshot_management_snapshot_name: "snap1"
+```
+```
+---
+- name: Remove all snapshots of a VM
+  hosts: all
+  gather_facts: false
+
+  roles:
+    - role: cloud.vmware_ops.snapshot_management
+      vars:
+        snapshot_management_state: remove_all
+        snapshot_management_hostname: "test"
+        snapshot_management_username: "test"
+        snapshot_management_password: "test"
+        snapshot_management_validate_certs: false
+        snapshot_management_port: "8989"
+        snapshot_management_folder: "/DC0/vm"
+        snapshot_management_datacenter: "DC0"
+        snapshot_management_name: "vm-test"
+```
+Run the playbook:
+
+```shell
+ansible-playbook playbook.yml -e "@vars.yml"
+```
+
+## License
+
+GNU General Public License v3.0 or later
+
+See [LICENCE](https://github.com/ansible-collections/cloud.vmware_ops/blob/main/LICENSE) to see the full text.
+
+## Author Information
+
+- Ansible Cloud Content Team

roles/snapshot_management/tasks/main.yml

@@ -0,0 +1,33 @@
+---
+- name: Manages virtual machines snapshots in vCenter
+  community.vmware.vmware_guest_snapshot:
+    hostname: "{{ snapshot_management_hostname | d(omit) }}"
+    username: "{{ snapshot_management_username | d(omit) }}"
+    password: "{{ snapshot_management_password | d(omit) }}"
+    validate_certs: "{{ snapshot_management_validate_certs | d(omit) }}"
+
+    port: "{{ snapshot_management_port | d(omit) }}"
+    proxy_host: "{{ snapshot_management_proxy_host | d(omit) }}"
+    proxy_port: "{{ snapshot_management_proxy_port | d(omit) }}"
+
+    state: "{{ snapshot_management_state | d(omit) }}"
+    name: "{{ snapshot_management_vm_name | d(omit) }}"
+    name_match: "{{ snapshot_management_vm_name_match | d(omit) }}"
+    uuid: "{{ snapshot_management_uuid | d(omit) }}"
+    moid: "{{ snapshot_management_moid | d(omit) }}"
+    use_instance_uuid: "{{ snapshot_management_use_instance_uuid | d(omit) }}"
+
+    folder: "{{ snapshot_management_folder | d(omit) }}"
+    datacenter: "{{ snapshot_management_datacenter | d(omit) }}"
+    esxi_hostname: "{{ snapshot_management_esxi_hostname | d(omit) }}"
+    datastore: "{{ snapshot_management_datastore | d(omit) }}"
+    resource_pool: "{{ snapshot_management_resource_pool | d(omit) }}"
+
+    snapshot_name: "{{ snapshot_management_snapshot_name | d(omit) }}"
+    new_snapshot_name: "{{ snapshot_management_new_snapshot_name | d(omit) }}"
+    snapshot_id: "{{ snapshot_management_snapshot_id | d(omit) }}"
+    description: "{{ snapshot_management_description | d(omit) }}"
+    quiesce: "{{ snapshot_management_quiesce | d(omit) }}"
+    memory_dump: "{{ snapshot_management_memory_dump | d(omit) }}"
+    remove_children: "{{ snapshot_management_remove_children | d(omit) }}"
+    new_description: "{{ snapshot_management_new_description | d(omit) }}"

tests/integration/targets/snapshot_management_test/run.yml

@@ -0,0 +1,13 @@
+- hosts: localhost
+  gather_facts: no
+  collections:
+    - community.general
+
+  tasks:
+    - name: Vcsim
+      ansible.builtin.import_role:
+        name: prepare_soap
+
+    - name: Import manage VM snapshot role
+      ansible.builtin.import_role:
+        name: snapshot_management_test

tests/integration/targets/snapshot_management_test/runme.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+source ../init.sh
+exec ansible-playbook run.yml

tests/integration/targets/snapshot_management_test/tasks/main.yml

@@ -0,0 +1,16 @@
+---
+- name: Create VM snapshot
+  ansible.builtin.import_role:
+    name: cloud.vmware_ops.snapshot_management
+  vars:
+    snapshot_management_hostname: "127.0.0.1"
+    snapshot_management_username: "test"
+    snapshot_management_password: "test"
+    snapshot_management_validate_certs: false
+    snapshot_management_folder: "/DC0/vm"
+    snapshot_management_datacenter: "DC0"
+    snapshot_management_vm_name: "DC0_H0_VM0"
+    snapshot_management_port: "8989"
+    snapshot_management_state: present
+    snapshot_management_snapshot_name: "snap1"
+    snapshot_management_snapshot_description: "snap1_description"