diff --git a/lib/ansible/module_utils/xenserver.py b/lib/ansible/module_utils/xenserver.py index 570677775e..dbc6a0adbe 100644 --- a/lib/ansible/module_utils/xenserver.py +++ b/lib/ansible/module_utils/xenserver.py @@ -9,15 +9,17 @@ __metaclass__ = type import atexit import time import re +import traceback -HAS_XENAPI = False +XENAPI_IMP_ERR = None try: import XenAPI HAS_XENAPI = True except ImportError: - pass + HAS_XENAPI = False + XENAPI_IMP_ERR = traceback.format_exc() -from ansible.module_utils.basic import env_fallback +from ansible.module_utils.basic import env_fallback, missing_required_lib from ansible.module_utils.common.network import is_mac from ansible.module_utils.ansible_release import __version__ as ANSIBLE_VERSION @@ -847,9 +849,7 @@ class XenServerObject(object): module: Reference to Ansible module object. """ if not HAS_XENAPI: - module.fail_json(changed=False, msg=("XenAPI Python library is required for this module! " - "Please download XenServer SDK and copy XenAPI.py to your Python site-packages. " - "Check Notes section in module documentation for more info.")) + module.fail_json(changed=False, msg=missing_required_lib("XenAPI"), exception=XENAPI_IMP_ERR) self.module = module self.xapi_session = XAPI.connect(module) diff --git a/lib/ansible/modules/cloud/xenserver/xenserver_guest.py b/lib/ansible/modules/cloud/xenserver/xenserver_guest.py index fc2c97cd36..bc0a296c83 100644 --- a/lib/ansible/modules/cloud/xenserver/xenserver_guest.py +++ b/lib/ansible/modules/cloud/xenserver/xenserver_guest.py @@ -14,7 +14,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', DOCUMENTATION = r''' --- module: xenserver_guest -short_description: Manages virtual machines running on Citrix XenServer host or pool +short_description: Manages virtual machines running on Citrix Hypervisor/XenServer host or pool description: > This module can be used to create new virtual machines from templates or other virtual machines, modify various virtual machine components like network and disk, rename a virtual machine and @@ -24,9 +24,10 @@ author: - Bojan Vitnik (@bvitnik) notes: - Minimal supported version of XenServer is 5.6. -- Module was tested with XenServer 6.5, 7.1 and 7.2. -- 'XenAPI Python library can be acquired from XenServer SDK (downloadable from Citrix website) or by running C(pip install XenAPI) (possibly very old - version, not compatible with Python 3.x). Latest version can also be acquired from GitHub: +- Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0. +- 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside + Citrix Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the XenAPI.py file from the SDK to your Python site-packages on your + Ansible Control Node to use it. Latest version of the library can also be acquired from GitHub: https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI.py' - '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.' @@ -36,16 +37,16 @@ notes: XenServer 7.0 or newer for Windows guests by using official XenServer Guest agent support for network configuration. The module will try to detect if such support is available and utilize it, else it will use a custom method of configuration via xenstore. Since XenServer Guest agent only support None and Static types of network configuration, where None means DHCP configured interface, C(networks.type) and C(networks.type6) - values C(none) and C(dhcp) have same effect. - More info here: https://xenserver.org/blog/entry/set-windows-guest-vm-static-ip-address-in-xenserver.html' + values C(none) and C(dhcp) have same effect. More info here: + https://www.citrix.com/community/citrix-developer/citrix-hypervisor-developer/citrix-hypervisor-developing-products/citrix-hypervisor-staticip.html' - 'On platforms without official support for network configuration inside a guest OS, network parameters will be written to xenstore C(vm-data/networks/) key. Parameters can be inspected by using C(xenstore ls) and C(xenstore read) tools on \*nix guests or trough WMI interface on Windows guests. They can also be found in VM facts C(instance.xenstore_data) key as returned by the module. It is up to the user to implement a boot time scripts or custom agent that will read the parameters from xenstore and configure network with given parameters. Take note that for xenstore data to become available inside a guest, a VM restart is needed hence module will require VM restart if any parameter is changed. This is a limitation of XenAPI and xenstore. Considering these limitations, network configuration trough xenstore is most - useful for bootstraping newly deployed VMs, much less for reconfiguring existing ones. - More info here: https://support.citrix.com/article/CTX226713' + useful for bootstraping newly deployed VMs, much less for reconfiguring existing ones. More info here: + https://support.citrix.com/article/CTX226713' requirements: - python >= 2.6 - XenAPI diff --git a/lib/ansible/modules/cloud/xenserver/xenserver_guest_info.py b/lib/ansible/modules/cloud/xenserver/xenserver_guest_info.py index 7cee1c6679..dfa6b37b99 100644 --- a/lib/ansible/modules/cloud/xenserver/xenserver_guest_info.py +++ b/lib/ansible/modules/cloud/xenserver/xenserver_guest_info.py @@ -14,7 +14,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', DOCUMENTATION = r''' --- module: xenserver_guest_info -short_description: Gathers information for virtual machines running on Citrix XenServer host or pool +short_description: Gathers information for virtual machines running on Citrix Hypervisor/XenServer host or pool description: > This module can be used to gather essential VM facts. version_added: '2.8' @@ -22,9 +22,10 @@ author: - Bojan Vitnik (@bvitnik) notes: - Minimal supported version of XenServer is 5.6. -- Module was tested with XenServer 6.5, 7.1 and 7.2. -- 'XenAPI Python library can be acquired from XenServer SDK (downloadable from Citrix website) or by running C(pip install XenAPI) (possibly very old - version, not compatible with Python 3.x). Latest version can also be acquired from GitHub: +- Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0. +- 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside + Citrix Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the XenAPI.py file from the SDK to your Python site-packages on your + Ansible Control Node to use it. Latest version of the library can also be acquired from GitHub: https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI.py' - '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.' @@ -206,6 +207,7 @@ def main(): ['name', 'uuid'], ], ) + if module._name == 'xenserver_guest_facts': module.deprecate("The 'xenserver_guest_facts' module has been renamed to 'xenserver_guest_info'", version='2.13') diff --git a/lib/ansible/modules/cloud/xenserver/xenserver_guest_powerstate.py b/lib/ansible/modules/cloud/xenserver/xenserver_guest_powerstate.py index ce01e948bb..0cc712679a 100644 --- a/lib/ansible/modules/cloud/xenserver/xenserver_guest_powerstate.py +++ b/lib/ansible/modules/cloud/xenserver/xenserver_guest_powerstate.py @@ -14,7 +14,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', DOCUMENTATION = r''' --- module: xenserver_guest_powerstate -short_description: Manages power states of virtual machines running on Citrix XenServer host or pool +short_description: Manages power states of virtual machines running on Citrix Hypervisor/XenServer host or pool description: > This module can be used to power on, power off, restart or suspend virtual machine and gracefully reboot or shutdown guest OS of virtual machine. version_added: '2.8' @@ -22,9 +22,10 @@ author: - Bojan Vitnik (@bvitnik) notes: - Minimal supported version of XenServer is 5.6. -- Module was tested with XenServer 6.5, 7.1 and 7.2. -- 'XenAPI Python library can be acquired from XenServer SDK (downloadable from Citrix website) or by running C(pip install XenAPI) (possibly very old - version, not compatible with Python 3.x). Latest version can also be acquired from GitHub: +- Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0. +- 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside + Citrix Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the XenAPI.py file from the SDK to your Python site-packages on your + Ansible Control Node to use it. Latest version of the library can also be acquired from GitHub: https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI.py' - '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.' diff --git a/test/units/module_utils/xenserver/test_xenserverobject.py b/test/units/module_utils/xenserver/test_xenserverobject.py index 881acfd3c1..b45c4a2f62 100644 --- a/test/units/module_utils/xenserver/test_xenserverobject.py +++ b/test/units/module_utils/xenserver/test_xenserverobject.py @@ -20,9 +20,7 @@ def test_xenserverobject_xenapi_lib_detection(mocker, fake_ansible_module, xense with pytest.raises(FailJsonException) as exc_info: xenserver.XenServerObject(fake_ansible_module) - assert exc_info.value.kwargs['msg'] == ("XenAPI Python library is required for this module! " - "Please download XenServer SDK and copy XenAPI.py to your Python site-packages. " - "Check Notes section in module documentation for more info.") + assert 'Failed to import the required Python library (XenAPI) on' in exc_info.value.kwargs['msg'] def test_xenserverobject_xenapi_failure(mock_xenapi_failure, fake_ansible_module, xenserver):