XenServer: Update docs with recent changes in XenAPI python lib and branding (#63728)

- xenserver module_util: XenAPI lib import error message handling is now ported to missing_required_lib(). Updated unit tests. - xenserver_guest, xenserver_guest_info, xenserver_guest_powerstate modules: docs are updated to reflect recent changes in availability of XenAPI lib on PyPI. - xenserver_guest, xenserver_guest_info, xenserver_guest_powerstate modules: docs are updated to reflect recent Citrix rebranding of XenServer. Broken URLs to external resources are fixed. - xenserver_guest, xenserver_guest_info, xenserver_guest_powerstate modules: more tested platforms are mentioned in docs.
5 years ago · 7afba9420a
parent a6e610a9ed
commit 7afba9420a
5 changed files with 27 additions and 25 deletions
--- 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)
--- 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) <bvitnik@mainstream.rs>
 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/<vif_device>) 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
--- 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) <bvitnik@mainstream.rs>
 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')

--- 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) <bvitnik@mainstream.rs>
 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.'
--- 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):