ansible/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00
Code Releases Activity

New module: xenserver_guest_powerstate - manages powerstate of XenServer VMs (#49425)

Browse source 
* Initial commit for xenserver_guest_powerstate module
* Added unit tests for the module, removed unused imports
This commit is contained in:
Bojan Vitnik 2019-02-28 13:25:05 +01:00 committed by Abhijeet Kasurde
parent 4d3a6123d5
commit 88e8330e3e
4 changed files with 614 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

264
lib/ansible/modules/cloud/xenserver/xenserver_guest_powerstate.py Normal file
View file

@ -0,0 +1,264 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
#
# Copyright: (c) 2018, Bojan Vitnik <bvitnik@mainstream.rs>
# 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 = r'''
---
module: xenserver_guest_powerstate
short_description: Manages power states of virtual machines running on Citrix XenServer host or pool
description: >
This module can be used to power on, power off, restart or suspend virtual machine and grecefully reboot or shutdown guest OS of virtual machine.
version_added: '2.8'
author:
- Bojan Vitnik (@bvitnik) <bvitnik@mainstream.rs>
notes:
- Minimal supported version of XenServer is 5.6
- Module was tested with XenServer 6.5, 7.1 and 7.2
- 'If no scheme is specified in C(hostname), module defaults to C(http://) because C(https://) is problematic in most setups. Make sure you are
accessing XenServer host in trusted environment or use C(https://) scheme explicitly.'
- 'To use C(https://) scheme for C(hostname) you have to either import host certificate to your OS certificate store or use C(validate_certs: no)
which requires XenAPI.py from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.'
requirements:
- python >= 2.6
- XenAPI
options:
state:
description:
- Specify the state VM should be in.
- If C(state) is set to value other than C(present), then VM is transitioned into required state and facts are returned.
- If C(state) is set to C(present), then VM is just checked for existance and facts are returned.
default: present
choices: [ powered-on, powered-off, restarted, shutdown-guest, reboot-guest, suspended, present ]
name:
description:
- Name of the VM to work with.
- VMs running on XenServer do not necessarily have unique names. The module will fail if multiple VMs with same name are found.
- In case of multiple VMs with same name, use C(uuid) to uniquely specify VM to manage.
- This parameter is case sensitive.
required: yes
aliases: [ 'name_label' ]
uuid:
description:
- UUID of the VM to manage if known, this is XenServer's unique identifier.
- It is required if name is not unique.
wait_for_ip_address:
description:
- Wait until XenServer detects an IP address for the VM.
- This requires XenServer Tools preinstaled on VM to properly work.
default: 'no'
type: bool
state_change_timeout:
description:
- 'By default, module will wait indefinitely for VM to change state or accquire an IP address if C(wait_for_ip_address: yes).'
- If this parameter is set to positive value, the module will instead wait specified number of seconds for the state change.
- In case of timeout, module will generate an error message.
default: 0
extends_documentation_fragment: xenserver.documentation
'''
EXAMPLES = r'''
- name: Power on VM
xenserver_guest_powerstate:
hostname: 192.168.1.209
username: root
password: xenserver
name: testvm_11
state: powered-on
delegate_to: localhost
register: facts
'''
RETURN = r'''
instance:
description: Metadata about the VM
returned: always
type: dict
sample: {
"cdrom": {
"type": "none"
},
"customization_agent": "native",
"disks": [
{
"name": "windows-template-testing-0",
"name_desc": "",
"os_device": "xvda",
"size": 42949672960,
"sr": "Local storage",
"sr_uuid": "0af1245e-bdb0-ba33-1446-57a962ec4075",
"vbd_userdevice": "0"
},
{
"name": "windows-template-testing-1",
"name_desc": "",
"os_device": "xvdb",
"size": 42949672960,
"sr": "Local storage",
"sr_uuid": "0af1245e-bdb0-ba33-1446-57a962ec4075",
"vbd_userdevice": "1"
}
],
"domid": "56",
"folder": "",
"hardware": {
"memory_mb": 8192,
"num_cpu_cores_per_socket": 2,
"num_cpus": 4
},
"home_server": "",
"is_template": false,
"name": "windows-template-testing",
"name_desc": "",
"networks": [
{
"gateway": "192.168.0.254",
"gateway6": "fc00::fffe",
"ip": "192.168.0.200",
"ip6": [
"fe80:0000:0000:0000:e9cb:625a:32c5:c291",
"fc00:0000:0000:0000:0000:0000:0000:0001"
],
"mac": "ba:91:3a:48:20:76",
"mtu": "1500",
"name": "Pool-wide network associated with eth1",
"netmask": "255.255.255.128",
"prefix": "25",
"prefix6": "64",
"vif_device": "0"
}
],
"other_config": {
"base_template_name": "Windows Server 2016 (64-bit)",
"import_task": "OpaqueRef:e43eb71c-45d6-5351-09ff-96e4fb7d0fa5",
"install-methods": "cdrom",
"instant": "true",
"mac_seed": "f83e8d8a-cfdc-b105-b054-ef5cb416b77e"
},
"platform": {
"acpi": "1",
"apic": "true",
"cores-per-socket": "2",
"device_id": "0002",
"hpet": "true",
"nx": "true",
"pae": "true",
"timeoffset": "-25200",
"vga": "std",
"videoram": "8",
"viridian": "true",
"viridian_reference_tsc": "true",
"viridian_time_ref_count": "true"
},
"state": "poweredon",
"uuid": "e3c0b2d5-5f05-424e-479c-d3df8b3e7cda",
"xenstore_data": {
"vm-data": ""
}
}
'''
import re
HAS_XENAPI = False
try:
import XenAPI
HAS_XENAPI = True
except ImportError:
pass
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.xenserver import (xenserver_common_argument_spec, XAPI, XenServerObject, get_object_ref,
gather_vm_params, gather_vm_facts, set_vm_power_state, wait_for_vm_ip_address)
class XenServerVM(XenServerObject):
"""Class for managing XenServer VM.
Attributes:
vm_ref (str): XAPI reference to VM.
vm_params (dict): A dictionary with VM parameters as returned
by gather_vm_params() function.
"""
def __init__(self, module):
"""Inits XenServerVM using module parameters.
Args:
module: Reference to Ansible module object.
"""
super(XenServerVM, self).__init__(module)
self.vm_ref = get_object_ref(self.module, self.module.params['name'], self.module.params['uuid'], obj_type="VM", fail=True, msg_prefix="VM search: ")
self.gather_params()
def gather_params(self):
"""Gathers all VM parameters available in XAPI database."""
self.vm_params = gather_vm_params(self.module, self.vm_ref)
def gather_facts(self):
"""Gathers and returns VM facts."""
return gather_vm_facts(self.module, self.vm_params)
def set_power_state(self, power_state):
"""Controls VM power state."""
state_changed, current_state = set_vm_power_state(self.module, self.vm_ref, power_state, self.module.params['state_change_timeout'])
# If state has changed, update vm_params.
if state_changed:
self.vm_params['power_state'] = current_state.capitalize()
return state_changed
def wait_for_ip_address(self):
"""Waits for VM to acquire an IP address."""
self.vm_params['guest_metrics'] = wait_for_vm_ip_address(self.module, self.vm_ref, self.module.params['state_change_timeout'])
def main():
argument_spec = xenserver_common_argument_spec()
argument_spec.update(
state=dict(type='str', default='present',
choices=['powered-on', 'powered-off', 'restarted', 'shutdown-guest', 'reboot-guest', 'suspended', 'present']),
name=dict(type='str', aliases=['name_label']),
uuid=dict(type='str'),
wait_for_ip_address=dict(type='bool', default=False),
state_change_timeout=dict(type='int', default=0),
)
module = AnsibleModule(argument_spec=argument_spec,
supports_check_mode=True,
required_one_of=[
['name', 'uuid'],
],
)
result = {'failed': False, 'changed': False}
vm = XenServerVM(module)
# Set VM power state.
if module.params['state'] != "present":
result['changed'] = vm.set_power_state(module.params['state'])
if module.params['wait_for_ip_address']:
vm.wait_for_ip_address()
result['instance'] = vm.gather_facts()
if result['failed']:
module.fail_json(**result)
else:
module.exit_json(**result)
if __name__ == '__main__':
main()

30
test/units/modules/cloud/xenserver/FakeAnsibleModule.py Normal file
View file

@ -0,0 +1,30 @@
# -*- coding: utf-8 -*-
#
# Copyright: (c) 2019, Bojan Vitnik <bvitnik@mainstream.rs>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
class AnsibleModuleException(Exception):
def __init__(self, *args, **kwargs):
self.args = args
self.kwargs = kwargs
class ExitJsonException(AnsibleModuleException):
pass
class FailJsonException(AnsibleModuleException):
pass
class FakeAnsibleModule:
def __init__(self, params=None, check_mode=False):
self.params = params
self.check_mode = check_mode
def exit_json(self, *args, **kwargs):
raise ExitJsonException(*args, **kwargs)
def fail_json(self, *args, **kwargs):
raise FailJsonException(*args, **kwargs)

31
test/units/modules/cloud/xenserver/conftest.py
View file

@ -11,6 +11,24 @@ import sys
import importlib
import pytest
from .FakeAnsibleModule import FakeAnsibleModule
@pytest.fixture
def fake_ansible_module(request):
"""Returns fake AnsibleModule with fake module params."""
if hasattr(request, 'param'):
return FakeAnsibleModule(request.param)
else:
params = {
"hostname": "somehost",
"username": "someuser",
"password": "somepwd",
"validate_certs": True,
}
return FakeAnsibleModule(params)
@pytest.fixture(autouse=True)
def XenAPI():
@ -42,3 +60,16 @@ def xenserver_guest_facts(XenAPI):
from ansible.modules.cloud.xenserver import xenserver_guest_facts
return xenserver_guest_facts
@pytest.fixture
def xenserver_guest_powerstate(XenAPI):
"""Imports and returns xenserver_guest_powerstate module."""
# Since we are wrapping fake XenAPI module inside a fixture, all modules
# that depend on it have to be imported inside a test function. To make
# this easier to handle and remove some code repetition, we wrap the import
# of xenserver_guest_powerstate module with a fixture.
from ansible.modules.cloud.xenserver import xenserver_guest_powerstate
return xenserver_guest_powerstate

289
test/units/modules/cloud/xenserver/test_xenserver_guest_powerstate.py Normal file
View file

@ -0,0 +1,289 @@
# -*- coding: utf-8 -*-
#
# Copyright: (c) 2019, Bojan Vitnik <bvitnik@mainstream.rs>
# 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
import json
import pytest
from .common import fake_xenapi_ref
testcase_set_powerstate = {
"params": [
(False, "someoldstate"),
(True, "somenewstate"),
],
"ids": [
"state-same",
"state-changed",
],
}
testcase_module_params_state_present = {
"params": [
{
"hostname": "somehost",
"username": "someuser",
"password": "somepwd",
"name": "somevmname",
},
{
"hostname": "somehost",
"username": "someuser",
"password": "somepwd",
"name": "somevmname",
"state": "present",
},
],
"ids": [
"present-implicit",
"present-explicit",
],
}
testcase_module_params_state_other = {
"params": [
{
"hostname": "somehost",
"username": "someuser",
"password": "somepwd",
"name": "somevmname",
"state": "powered-on",
},
{
"hostname": "somehost",
"username": "someuser",
"password": "somepwd",
"name": "somevmname",
"state": "powered-off",
},
{
"hostname": "somehost",
"username": "someuser",
"password": "somepwd",
"name": "somevmname",
"state": "restarted",
},
{
"hostname": "somehost",
"username": "someuser",
"password": "somepwd",
"name": "somevmname",
"state": "shutdown-guest",
},
{
"hostname": "somehost",
"username": "someuser",
"password": "somepwd",
"name": "somevmname",
"state": "reboot-guest",
},
{
"hostname": "somehost",
"username": "someuser",
"password": "somepwd",
"name": "somevmname",
"state": "suspended",
},
],
"ids": [
"powered-on",
"powered-off",
"restarted",
"shutdown-guest",
"reboot-guest",
"suspended",
],
}
testcase_module_params_wait = {
"params": [
{
"hostname": "somehost",
"username": "someuser",
"password": "somepwd",
"name": "somevmname",
"state": "present",
"wait_for_ip_address": "yes",
},
{
"hostname": "somehost",
"username": "someuser",
"password": "somepwd",
"name": "somevmname",
"state": "powered-on",
"wait_for_ip_address": "yes",
},
],
"ids": [
"wait-present",
"wait-other",
],
}
@pytest.mark.parametrize('power_state', testcase_set_powerstate['params'], ids=testcase_set_powerstate['ids'])
def test_xenserver_guest_powerstate_set_power_state(mocker, fake_ansible_module, XenAPI, xenserver_guest_powerstate, power_state):
"""Tests power state change handling."""
mocker.patch('ansible.modules.cloud.xenserver.xenserver_guest_powerstate.get_object_ref', return_value=fake_xenapi_ref('VM'))
mocker.patch('ansible.modules.cloud.xenserver.xenserver_guest_powerstate.gather_vm_params', return_value={"power_state": "Someoldstate"})
mocked_set_vm_power_state = mocker.patch('ansible.modules.cloud.xenserver.xenserver_guest_powerstate.set_vm_power_state',
return_value=power_state)
mocked_xenapi = mocker.patch.object(XenAPI.Session, 'xenapi', create=True)
mocked_returns = {
"pool.get_all.return_value": [fake_xenapi_ref('pool')],
"pool.get_default_SR.return_value": fake_xenapi_ref('SR'),
}
mocked_xenapi.configure_mock(**mocked_returns)
mocker.patch('ansible.module_utils.xenserver.get_xenserver_version', return_value=[7, 2, 0])
fake_ansible_module.params.update({
"name": "somename",
"uuid": "someuuid",
"state_change_timeout": 1,
})
vm = xenserver_guest_powerstate.XenServerVM(fake_ansible_module)
state_changed = vm.set_power_state(None)
mocked_set_vm_power_state.assert_called_once_with(fake_ansible_module, fake_xenapi_ref('VM'), None, 1)
assert state_changed == power_state[0]
assert vm.vm_params['power_state'] == power_state[1].capitalize()
@pytest.mark.parametrize('patch_ansible_module',
testcase_module_params_state_present['params'],
ids=testcase_module_params_state_present['ids'],
indirect=True)
def test_xenserver_guest_powerstate_present(mocker, patch_ansible_module, capfd, XenAPI, xenserver_guest_powerstate):
"""
Tests regular module invocation including parsing and propagation of
module params and module output when state is set to present.
"""
fake_vm_facts = {"fake-vm-fact": True}
mocker.patch('ansible.modules.cloud.xenserver.xenserver_guest_powerstate.get_object_ref', return_value=fake_xenapi_ref('VM'))
mocker.patch('ansible.modules.cloud.xenserver.xenserver_guest_powerstate.gather_vm_params', return_value={})
mocker.patch('ansible.modules.cloud.xenserver.xenserver_guest_powerstate.gather_vm_facts', return_value=fake_vm_facts)
mocked_set_vm_power_state = mocker.patch('ansible.modules.cloud.xenserver.xenserver_guest_powerstate.set_vm_power_state',
return_value=(True, "somenewstate"))
mocked_wait_for_vm_ip_address = mocker.patch('ansible.modules.cloud.xenserver.xenserver_guest_powerstate.wait_for_vm_ip_address',
return_value={})
mocked_xenapi = mocker.patch.object(XenAPI.Session, 'xenapi', create=True)
mocked_returns = {
"pool.get_all.return_value": [fake_xenapi_ref('pool')],
"pool.get_default_SR.return_value": fake_xenapi_ref('SR'),
}
mocked_xenapi.configure_mock(**mocked_returns)
mocker.patch('ansible.module_utils.xenserver.get_xenserver_version', return_value=[7, 2, 0])
with pytest.raises(SystemExit):
xenserver_guest_powerstate.main()
out, err = capfd.readouterr()
result = json.loads(out)
mocked_set_vm_power_state.assert_not_called()
mocked_wait_for_vm_ip_address.assert_not_called()
assert result['changed'] is False
assert result['instance'] == fake_vm_facts
@pytest.mark.parametrize('patch_ansible_module',
testcase_module_params_state_other['params'],
ids=testcase_module_params_state_other['ids'],
indirect=True)
def test_xenserver_guest_powerstate_other(mocker, patch_ansible_module, capfd, XenAPI, xenserver_guest_powerstate):
"""
Tests regular module invocation including parsing and propagation of
module params and module output when state is set to other value than
present.
"""
fake_vm_facts = {"fake-vm-fact": True}
mocker.patch('ansible.modules.cloud.xenserver.xenserver_guest_powerstate.get_object_ref', return_value=fake_xenapi_ref('VM'))
mocker.patch('ansible.modules.cloud.xenserver.xenserver_guest_powerstate.gather_vm_params', return_value={})
mocker.patch('ansible.modules.cloud.xenserver.xenserver_guest_powerstate.gather_vm_facts', return_value=fake_vm_facts)
mocked_set_vm_power_state = mocker.patch(
'ansible.modules.cloud.xenserver.xenserver_guest_powerstate.set_vm_power_state',
return_value=(True, "somenewstate"))
mocked_wait_for_vm_ip_address = mocker.patch(
'ansible.modules.cloud.xenserver.xenserver_guest_powerstate.wait_for_vm_ip_address',
return_value={})
mocked_xenapi = mocker.patch.object(XenAPI.Session, 'xenapi', create=True)
mocked_returns = {
"pool.get_all.return_value": [fake_xenapi_ref('pool')],
"pool.get_default_SR.return_value": fake_xenapi_ref('SR'),
}
mocked_xenapi.configure_mock(**mocked_returns)
mocker.patch('ansible.module_utils.xenserver.get_xenserver_version', return_value=[7, 2, 0])
with pytest.raises(SystemExit):
xenserver_guest_powerstate.main()
out, err = capfd.readouterr()
result = json.loads(out)
mocked_set_vm_power_state.assert_called_once()
mocked_wait_for_vm_ip_address.assert_not_called()
assert result['changed'] is True
assert result['instance'] == fake_vm_facts
@pytest.mark.parametrize('patch_ansible_module',
testcase_module_params_wait['params'],
ids=testcase_module_params_wait['ids'],
indirect=True)
def test_xenserver_guest_powerstate_wait(mocker, patch_ansible_module, capfd, XenAPI, xenserver_guest_powerstate):
"""
Tests regular module invocation including parsing and propagation of
module params and module output when wait_for_ip_address option is used.
"""
fake_vm_facts = {"fake-vm-fact": True}
mocker.patch('ansible.modules.cloud.xenserver.xenserver_guest_powerstate.get_object_ref', return_value=fake_xenapi_ref('VM'))
mocker.patch('ansible.modules.cloud.xenserver.xenserver_guest_powerstate.gather_vm_params', return_value={})
mocker.patch('ansible.modules.cloud.xenserver.xenserver_guest_powerstate.gather_vm_facts', return_value=fake_vm_facts)
mocked_set_vm_power_state = mocker.patch(
'ansible.modules.cloud.xenserver.xenserver_guest_powerstate.set_vm_power_state',
return_value=(True, "somenewstate"))
mocked_wait_for_vm_ip_address = mocker.patch(
'ansible.modules.cloud.xenserver.xenserver_guest_powerstate.wait_for_vm_ip_address',
return_value={})
mocked_xenapi = mocker.patch.object(XenAPI.Session, 'xenapi', create=True)
mocked_returns = {
"pool.get_all.return_value": [fake_xenapi_ref('pool')],
"pool.get_default_SR.return_value": fake_xenapi_ref('SR'),
}
mocked_xenapi.configure_mock(**mocked_returns)
mocker.patch('ansible.module_utils.xenserver.get_xenserver_version', return_value=[7, 2, 0])
with pytest.raises(SystemExit):
xenserver_guest_powerstate.main()
out, err = capfd.readouterr()
result = json.loads(out)
mocked_wait_for_vm_ip_address.assert_called_once()
assert result['instance'] == fake_vm_facts