From 794002954c2db6cf37251e12aaa46c758801962c Mon Sep 17 00:00:00 2001 From: Samori Gorse Date: Mon, 3 Jun 2024 16:29:29 +0200 Subject: [PATCH 01/16] wip --- plugins/modules/xen_orchestra.py | 232 +++++++++++++++++++++++++++++++ 1 file changed, 232 insertions(+) create mode 100644 plugins/modules/xen_orchestra.py diff --git a/plugins/modules/xen_orchestra.py b/plugins/modules/xen_orchestra.py new file mode 100644 index 0000000000..d857cf9c8c --- /dev/null +++ b/plugins/modules/xen_orchestra.py @@ -0,0 +1,232 @@ +# -*- coding: utf-8 -*- +# Copyright (c) 2021 Ansible Project +# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) +# SPDX-License-Identifier: GPL-3.0-or-later + +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + +DOCUMENTATION = ''' + name: xen_orchestra + short_description: Xen Orchestra inventory source + version_added: 4.1.0 + author: + - Dom Del Nano (@ddelnano) + - Samori Gorse (@shinuza) + requirements: + - websocket-client >= 1.0.0 + description: + - Get inventory hosts from a Xen Orchestra deployment. + - 'Uses a configuration file as an inventory source, it must end in C(.xen_orchestra.yml) or C(.xen_orchestra.yaml).' + extends_documentation_fragment: + - constructed + - inventory_cache + options: + plugin: + description: The name of this plugin, it should always be set to V(community.general.xen_orchestra) for this plugin to recognize it as its own. + required: true + choices: ['community.general.xen_orchestra'] + type: str + api_host: + description: + - API host to XOA API. + - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_HOST) will be used instead. + type: str + env: + - name: ANSIBLE_XO_HOST + user: + description: + - Xen Orchestra user. + - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_USER) will be used instead. + required: true + type: str + env: + - name: ANSIBLE_XO_USER + password: + description: + - Xen Orchestra password. + - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_PASSWORD) will be used instead. + required: true + type: str + env: + - name: ANSIBLE_XO_PASSWORD + validate_certs: + description: Verify TLS certificate if using HTTPS. + type: boolean + default: true + use_ssl: + description: Use wss when connecting to the Xen Orchestra API + type: boolean + default: true +''' + + +EXAMPLES = ''' +# file must be named xen_orchestra.yaml or xen_orchestra.yml +plugin: community.general.xen_orchestra +api_host: 192.168.1.255 +user: xo +password: xo_pwd +validate_certs: true +use_ssl: true +groups: + kube_nodes: "'kube_node' in tags" +compose: + ansible_port: 2222 + +''' + +import json +import ssl +from time import sleep + +from ansible.errors import AnsibleError + +from ansible_collections.community.general.plugins.module_utils.version import LooseVersion +from ansible.module_utils.basic import AnsibleModule + +# 3rd party imports +try: + HAS_WEBSOCKET = True + import websocket + from websocket import create_connection + + if LooseVersion(websocket.__version__) <= LooseVersion('1.0.0'): + raise ImportError +except ImportError as e: + HAS_WEBSOCKET = False + + +HALTED = 'Halted' +PAUSED = 'Paused' +RUNNING = 'Running' +SUSPENDED = 'Suspended' +POWER_STATES = [RUNNING, HALTED, SUSPENDED, PAUSED] +HOST_GROUP = 'xo_hosts' +POOL_GROUP = 'xo_pools' + + +def clean_group_name(label): + return label.lower().replace(' ', '-').replace('-', '_') + + +class XenOrchestra(object): + ''' Host inventory parser for ansible using XenOrchestra as source. ''' + + NAME = 'community.general.xen_orchestra' + CALL_TIMEOUT = 100 + """Number of 1/10ths of a second to wait before method call times out.""" + + + def __init__(self, module): + # from config + self.counter = -1 + self.con = None + self.module = module + + self.create_connection(module['api_host']) + self.login(module['user'], module['password']) + + @property + def pointer(self): + self.counter += 1 + return self.counter + + def create_connection(self, xoa_api_host): + validate_certs = self.module['validate_certs'] + use_ssl = self.module['use_ssl'] + proto = 'wss' if use_ssl else 'ws' + + sslopt = None if validate_certs else {'cert_reqs': ssl.CERT_NONE} + self.conn = create_connection( + '{0}://{1}/api/'.format(proto, xoa_api_host), sslopt=sslopt) + + def call(self, method, params): + """Calls a method on the XO server with the provided parameters.""" + id = self.pointer + self.conn.send(json.dumps({ + 'id': id, + 'jsonrpc': '2.0', + 'method': method, + 'params': params + })) + + waited = 0 + while waited < self.CALL_TIMEOUT: + response = json.loads(self.conn.recv()) + if 'id' in response and response['id'] == id: + return response + else: + sleep(0.1) + waited += 1 + + raise AnsibleError( + 'Method call {method} timed out after {timeout} seconds.'.format(method=method, timeout=self.CALL_TIMEOUT / 10)) + + def login(self, user, password): + answer = self.call('session.signIn', { + 'username': user, 'password': password + }) + + if 'error' in answer: + raise AnsibleError( + 'Could not connect: {0}'.format(answer['error'])) + + def stop_vm(self, vm_uid): + answer = self.call('vm.stop', {'id': vm_uid}) + + if 'error' in answer: + raise AnsibleError( + 'Could not request: {0}'.format(answer['error'])) + + return answer['result'] + + def start_vm(self, vm_uid): + answer = self.call('vm.start', {'id': vm_uid}) + + if 'error' in answer: + raise AnsibleError( + 'Could not request: {0}'.format(answer['error'])) + + return answer['result'] + + def get_object(self, name): + answer = self.call('xo.getAllObjects', {'filter': {'type': name}}) + + if 'error' in answer: + raise AnsibleError( + 'Could not request: {0}'.format(answer['error'])) + + return answer['result'] + + +def main(): + module_args = dict( + api_host=dict(type='str', required=True), + user=dict(type='str', required=True), + password=dict(type='str', required=True, no_log=True), + validate_certs=dict(type='bool', default=True), + use_ssl=dict(type='bool', default=True), + vm_uid=dict(type='str'), + state=dict(default='present', choices=['absent', 'stopped', 'started', 'restarted']), + ) + + xen_orchestra = XenOrchestra() + module = AnsibleModule( + argument_spec=module_args, + required_one_of=[('api_password', 'api_token_id')], + ) + + state = module.params['state'] + vm_uid = module.params['vm_uid'] + + if state == 'stopped': + xen_orchestra.stop_vm(vm_uid) + module.exit_json(changed=True) + + if state == 'started': + xen_orchestra.start_vm(vm_uid) + module.exit_json(changed=True) + +if __name__ == '__main__': + main() From b9b19745ebcd8a1b80d953a3f7407674202adb02 Mon Sep 17 00:00:00 2001 From: Samori Gorse Date: Thu, 6 Jun 2024 15:31:58 +0200 Subject: [PATCH 02/16] Added xen_orchestra module --- plugins/modules/xen_orchestra.py | 544 ++++++++++++++++++------------- 1 file changed, 312 insertions(+), 232 deletions(-) diff --git a/plugins/modules/xen_orchestra.py b/plugins/modules/xen_orchestra.py index d857cf9c8c..d795c83824 100644 --- a/plugins/modules/xen_orchestra.py +++ b/plugins/modules/xen_orchestra.py @@ -1,232 +1,312 @@ -# -*- coding: utf-8 -*- -# Copyright (c) 2021 Ansible Project -# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) -# SPDX-License-Identifier: GPL-3.0-or-later - -from __future__ import (absolute_import, division, print_function) -__metaclass__ = type - -DOCUMENTATION = ''' - name: xen_orchestra - short_description: Xen Orchestra inventory source - version_added: 4.1.0 - author: - - Dom Del Nano (@ddelnano) - - Samori Gorse (@shinuza) - requirements: - - websocket-client >= 1.0.0 - description: - - Get inventory hosts from a Xen Orchestra deployment. - - 'Uses a configuration file as an inventory source, it must end in C(.xen_orchestra.yml) or C(.xen_orchestra.yaml).' - extends_documentation_fragment: - - constructed - - inventory_cache - options: - plugin: - description: The name of this plugin, it should always be set to V(community.general.xen_orchestra) for this plugin to recognize it as its own. - required: true - choices: ['community.general.xen_orchestra'] - type: str - api_host: - description: - - API host to XOA API. - - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_HOST) will be used instead. - type: str - env: - - name: ANSIBLE_XO_HOST - user: - description: - - Xen Orchestra user. - - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_USER) will be used instead. - required: true - type: str - env: - - name: ANSIBLE_XO_USER - password: - description: - - Xen Orchestra password. - - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_PASSWORD) will be used instead. - required: true - type: str - env: - - name: ANSIBLE_XO_PASSWORD - validate_certs: - description: Verify TLS certificate if using HTTPS. - type: boolean - default: true - use_ssl: - description: Use wss when connecting to the Xen Orchestra API - type: boolean - default: true -''' - - -EXAMPLES = ''' -# file must be named xen_orchestra.yaml or xen_orchestra.yml -plugin: community.general.xen_orchestra -api_host: 192.168.1.255 -user: xo -password: xo_pwd -validate_certs: true -use_ssl: true -groups: - kube_nodes: "'kube_node' in tags" -compose: - ansible_port: 2222 - -''' - -import json -import ssl -from time import sleep - -from ansible.errors import AnsibleError - -from ansible_collections.community.general.plugins.module_utils.version import LooseVersion -from ansible.module_utils.basic import AnsibleModule - -# 3rd party imports -try: - HAS_WEBSOCKET = True - import websocket - from websocket import create_connection - - if LooseVersion(websocket.__version__) <= LooseVersion('1.0.0'): - raise ImportError -except ImportError as e: - HAS_WEBSOCKET = False - - -HALTED = 'Halted' -PAUSED = 'Paused' -RUNNING = 'Running' -SUSPENDED = 'Suspended' -POWER_STATES = [RUNNING, HALTED, SUSPENDED, PAUSED] -HOST_GROUP = 'xo_hosts' -POOL_GROUP = 'xo_pools' - - -def clean_group_name(label): - return label.lower().replace(' ', '-').replace('-', '_') - - -class XenOrchestra(object): - ''' Host inventory parser for ansible using XenOrchestra as source. ''' - - NAME = 'community.general.xen_orchestra' - CALL_TIMEOUT = 100 - """Number of 1/10ths of a second to wait before method call times out.""" - - - def __init__(self, module): - # from config - self.counter = -1 - self.con = None - self.module = module - - self.create_connection(module['api_host']) - self.login(module['user'], module['password']) - - @property - def pointer(self): - self.counter += 1 - return self.counter - - def create_connection(self, xoa_api_host): - validate_certs = self.module['validate_certs'] - use_ssl = self.module['use_ssl'] - proto = 'wss' if use_ssl else 'ws' - - sslopt = None if validate_certs else {'cert_reqs': ssl.CERT_NONE} - self.conn = create_connection( - '{0}://{1}/api/'.format(proto, xoa_api_host), sslopt=sslopt) - - def call(self, method, params): - """Calls a method on the XO server with the provided parameters.""" - id = self.pointer - self.conn.send(json.dumps({ - 'id': id, - 'jsonrpc': '2.0', - 'method': method, - 'params': params - })) - - waited = 0 - while waited < self.CALL_TIMEOUT: - response = json.loads(self.conn.recv()) - if 'id' in response and response['id'] == id: - return response - else: - sleep(0.1) - waited += 1 - - raise AnsibleError( - 'Method call {method} timed out after {timeout} seconds.'.format(method=method, timeout=self.CALL_TIMEOUT / 10)) - - def login(self, user, password): - answer = self.call('session.signIn', { - 'username': user, 'password': password - }) - - if 'error' in answer: - raise AnsibleError( - 'Could not connect: {0}'.format(answer['error'])) - - def stop_vm(self, vm_uid): - answer = self.call('vm.stop', {'id': vm_uid}) - - if 'error' in answer: - raise AnsibleError( - 'Could not request: {0}'.format(answer['error'])) - - return answer['result'] - - def start_vm(self, vm_uid): - answer = self.call('vm.start', {'id': vm_uid}) - - if 'error' in answer: - raise AnsibleError( - 'Could not request: {0}'.format(answer['error'])) - - return answer['result'] - - def get_object(self, name): - answer = self.call('xo.getAllObjects', {'filter': {'type': name}}) - - if 'error' in answer: - raise AnsibleError( - 'Could not request: {0}'.format(answer['error'])) - - return answer['result'] - - -def main(): - module_args = dict( - api_host=dict(type='str', required=True), - user=dict(type='str', required=True), - password=dict(type='str', required=True, no_log=True), - validate_certs=dict(type='bool', default=True), - use_ssl=dict(type='bool', default=True), - vm_uid=dict(type='str'), - state=dict(default='present', choices=['absent', 'stopped', 'started', 'restarted']), - ) - - xen_orchestra = XenOrchestra() - module = AnsibleModule( - argument_spec=module_args, - required_one_of=[('api_password', 'api_token_id')], - ) - - state = module.params['state'] - vm_uid = module.params['vm_uid'] - - if state == 'stopped': - xen_orchestra.stop_vm(vm_uid) - module.exit_json(changed=True) - - if state == 'started': - xen_orchestra.start_vm(vm_uid) - module.exit_json(changed=True) - -if __name__ == '__main__': - main() +# -*- coding: utf-8 -*- +# Copyright (c) 2021 Ansible Project +# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) +# SPDX-License-Identifier: GPL-3.0-or-later + +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + +DOCUMENTATION = ''' + name: xen_orchestra + short_description: Management of instances on Xen Orchestra + version_added: 4.1.0 + author: + - Samori Gorse (@shinuza) + requirements: + - websocket-client >= 1.0.0 + description: + - Allows you to create/delete/restart/stop instances on Xen Orchestra + options: + api_host: + description: API host to XOA API. + type: str + user: + description: Xen Orchestra user. + required: true + type: str + password: + description: Xen Orchestra password. + required: true + type: str + validate_certs: + description: Verify TLS certificate if using HTTPS. + type: boolean + default: true + use_ssl: + description: Use wss when connecting to the Xen Orchestra API + type: boolean + default: true + state: + description: State in which the Virtual Machine should be + choices: ['present', 'started', 'absent', 'stopped', 'restarted'] + default: present + label: + description: Label of the Virtual Machine to create, can be used when O(state=present) + type: boolean + default: false + description: + description: Description of the Virtual Machine to create, can be used when O(state=present) + type: boolean + default: false + boot_after_create: + description: Boot Virtual Machine after creation, can be used when O(state=present) + type: boolean + default: false +''' + + +EXAMPLES = r''' +- name: Create a new virtual machine + community.general.xen_orchestra: + api_host: xen-orchestra.lab + user: user + password: passw0rd + validate_certs: no + state: present + template: 355ee47d-ff4c-4924-3db2-fd86ae629676-a3d70e4d-c5ac-4dfb-999b-30a0a7efe546 + label: This is a test from ansible + description: This is a test from ansible + boot_after_create: no + +- name: Start an existing virtual machine + community.general.xen_orchestra: + api_host: xen-orchestra.lab + user: user + password: passw0rd + validate_certs: no + state: started + +- name: Stop an existing virtual machine + community.general.xen_orchestra: + api_host: xen-orchestra.lab + user: user + password: passw0rd + validate_certs: no + state: stop + +- name: Restart an existing virtual machine + community.general.xen_orchestra: + api_host: xen-orchestra.lab + user: user + password: passw0rd + validate_certs: no + state: stopped + +- name: Delete a virtual machine + community.general.xen_orchestra: + api_host: xen-orchestra.lab + user: user + password: passw0rd + validate_certs: no + state: absent +''' + +import json +import ssl +from time import sleep + +from ansible.errors import AnsibleError + +from ansible_collections.community.general.plugins.module_utils.version import LooseVersion +from ansible.module_utils.basic import AnsibleModule + +# 3rd party imports +try: + HAS_WEBSOCKET = True + import websocket + from websocket import create_connection + + if LooseVersion(websocket.__version__) <= LooseVersion('1.0.0'): + raise ImportError +except ImportError as e: + HAS_WEBSOCKET = False + +OBJECT_NOT_FOUND = 1 +VM_STATE_ERROR = 13 + + +class XenOrchestra(object): + ''' Host inventory parser for ansible using XenOrchestra as source. ''' + + NAME = 'community.general.xen_orchestra' + CALL_TIMEOUT = 100 + '''Number of 1/10ths of a second to wait before method call times out.''' + + + def __init__(self, module): + # from config + self.counter = -1 + self.con = None + self.module = module + + self.create_connection(module.params['api_host']) + self.login(module.params['user'], module.params['password']) + + @property + def pointer(self): + self.counter += 1 + return self.counter + + def create_connection(self, xoa_api_host): + validate_certs = self.module.params['validate_certs'] + use_ssl = self.module.params['use_ssl'] + proto = 'wss' if use_ssl else 'ws' + + sslopt = None if validate_certs else {'cert_reqs': ssl.CERT_NONE} + self.conn = create_connection( + '{0}://{1}/api/'.format(proto, xoa_api_host), sslopt=sslopt) + + def call(self, method, params): + '''Calls a method on the XO server with the provided parameters.''' + id = self.pointer + self.conn.send(json.dumps({ + 'id': id, + 'jsonrpc': '2.0', + 'method': method, + 'params': params + })) + + waited = 0 + while waited < self.CALL_TIMEOUT: + response = json.loads(self.conn.recv()) + if 'id' in response and response['id'] == id: + return response + else: + sleep(0.1) + waited += 1 + + raise AnsibleError( + 'Method call {method} timed out after {timeout} seconds.'.format(method=method, timeout=self.CALL_TIMEOUT / 10)) + + def login(self, user, password): + answer = self.call('session.signIn', { + 'username': user, 'password': password + }) + + if 'error' in answer: + raise self.module.fail_json( + 'Could not connect: {0}'.format(answer['error'])) + + return answer['result'] + + def create_vm(self): + params = { + 'template': self.module.params['template'], + 'name_label': self.module.params['label'], + 'bootAfterCreate': self.module.params.get('boot_after_create', False) + } + + description = self.module.params.get('description') + if description: + params['name_description'] = description + + answer = self.call('vm.create', params) + + if 'error' in answer: + raise self.module.fail_json( + 'Could not create vm: {0}'.format(answer['error'])) + + return answer['result'] + + def restart_vm(self, vm_uid): + answer = self.call('vm.restart', {'id': vm_uid, 'force': True }) + + if 'error' in answer: + raise self.module.fail_json( + 'Could not restart vm: {0}'.format(answer['error'])) + + return answer['result'] + + def stop_vm(self, vm_uid): + answer = self.call('vm.stop', {'id': vm_uid, 'force': True}) + + if 'error' in answer: + # VM is not paused, suspended or running + if answer['error']['code'] == VM_STATE_ERROR: + return False + raise self.module.fail_json( + 'Could not stop vm: {0}'.format(answer['error'])) + + return answer['result'] + + def start_vm(self, vm_uid): + answer = self.call('vm.start', {'id': vm_uid}) + + if 'error' in answer: + # VM is already started, nothing to do + if answer['error']['code'] == VM_STATE_ERROR: + return False + raise self.module.fail_json( + 'Could not start vm: {0}'.format(answer['error'])) + + return answer['result'] + + def delete_vm(self, vm_uid): + answer = self.call('vm.delete', {'id': vm_uid}) + + if 'error' in answer: + if answer['error']['code'] == OBJECT_NOT_FOUND: + return False + raise self.module.fail_json( + 'Could not delete vm: {0}'.format(answer['error'])) + + return answer['result'] + +def main(): + if not HAS_WEBSOCKET: + raise AnsibleError('This module requires websocket-client 1.0.0 or higher: ' + 'https://github.com/websocket-client/websocket-client.') + + module_args = dict( + api_host=dict(type='str', required=True), + user=dict(type='str', required=True), + password=dict(type='str', required=True, no_log=True), + validate_certs=dict(type='bool', default=True), + use_ssl=dict(type='bool', default=True), + vm_uid=dict(type='str'), + template=dict(type='str'), + label=dict(type='str'), + description=dict(type='str'), + boot_after_create=dict(type='bool', default=False), + state=dict(default='present', choices=['present', 'absent', 'stopped', 'started', 'restarted']), + + ) + + + module = AnsibleModule( + argument_spec=module_args, + required_if=[ + ('state', 'present', ['template', 'label']), + ('state', 'absent', ('vm_uid')), + ('state', 'started', ('vm_uid')), + ('state', 'restarted', ('vm_uid')), + ('state', 'stopped', ('vm_uid')), + ], + ) + xen_orchestra = XenOrchestra(module) + + state = module.params['state'] + vm_uid = module.params['vm_uid'] + + if state == 'stopped': + result = xen_orchestra.stop_vm(vm_uid) + module.exit_json(changed=result) + + if state == 'started': + result = xen_orchestra.start_vm(vm_uid) + module.exit_json(changed=result) + + if state == 'restarted': + result = xen_orchestra.restart_vm(vm_uid) + module.exit_json(changed=result) + + if state == 'absent': + result = xen_orchestra.delete_vm(vm_uid) + module.exit_json(changed=result) + + if state == 'present': + result = xen_orchestra.create_vm() + module.exit_json(changed=True, vm_uid=result) + +if __name__ == '__main__': + main() From bcaf5fe34208cbeec354a3423c31d251ab23d614 Mon Sep 17 00:00:00 2001 From: Samori Gorse Date: Tue, 11 Jun 2024 15:53:50 +0200 Subject: [PATCH 03/16] fix: pep8 --- plugins/modules/xen_orchestra.py | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/plugins/modules/xen_orchestra.py b/plugins/modules/xen_orchestra.py index d795c83824..d150506c63 100644 --- a/plugins/modules/xen_orchestra.py +++ b/plugins/modules/xen_orchestra.py @@ -8,8 +8,8 @@ __metaclass__ = type DOCUMENTATION = ''' name: xen_orchestra - short_description: Management of instances on Xen Orchestra - version_added: 4.1.0 + short_description: Management of instances on Xen Orchestra + version_added: 9.0.1 author: - Samori Gorse (@shinuza) requirements: @@ -116,7 +116,7 @@ try: import websocket from websocket import create_connection - if LooseVersion(websocket.__version__) <= LooseVersion('1.0.0'): + if LooseVersion(websocket.__version__) < LooseVersion('1.0.0'): raise ImportError except ImportError as e: HAS_WEBSOCKET = False @@ -132,7 +132,6 @@ class XenOrchestra(object): CALL_TIMEOUT = 100 '''Number of 1/10ths of a second to wait before method call times out.''' - def __init__(self, module): # from config self.counter = -1 @@ -205,16 +204,16 @@ class XenOrchestra(object): if 'error' in answer: raise self.module.fail_json( 'Could not create vm: {0}'.format(answer['error'])) - + return answer['result'] def restart_vm(self, vm_uid): - answer = self.call('vm.restart', {'id': vm_uid, 'force': True }) + answer = self.call('vm.restart', {'id': vm_uid, 'force': True}) if 'error' in answer: raise self.module.fail_json( 'Could not restart vm: {0}'.format(answer['error'])) - + return answer['result'] def stop_vm(self, vm_uid): @@ -226,9 +225,9 @@ class XenOrchestra(object): return False raise self.module.fail_json( 'Could not stop vm: {0}'.format(answer['error'])) - + return answer['result'] - + def start_vm(self, vm_uid): answer = self.call('vm.start', {'id': vm_uid}) @@ -238,7 +237,7 @@ class XenOrchestra(object): return False raise self.module.fail_json( 'Could not start vm: {0}'.format(answer['error'])) - + return answer['result'] def delete_vm(self, vm_uid): @@ -249,13 +248,14 @@ class XenOrchestra(object): return False raise self.module.fail_json( 'Could not delete vm: {0}'.format(answer['error'])) - + return answer['result'] + def main(): if not HAS_WEBSOCKET: raise AnsibleError('This module requires websocket-client 1.0.0 or higher: ' - 'https://github.com/websocket-client/websocket-client.') + 'https://github.com/websocket-client/websocket-client.') module_args = dict( api_host=dict(type='str', required=True), @@ -269,10 +269,8 @@ def main(): description=dict(type='str'), boot_after_create=dict(type='bool', default=False), state=dict(default='present', choices=['present', 'absent', 'stopped', 'started', 'restarted']), - ) - module = AnsibleModule( argument_spec=module_args, required_if=[ @@ -308,5 +306,6 @@ def main(): result = xen_orchestra.create_vm() module.exit_json(changed=True, vm_uid=result) + if __name__ == '__main__': main() From 749ff82292eee96535782f7e5f2b785cdde0134f Mon Sep 17 00:00:00 2001 From: Samori Gorse Date: Tue, 11 Jun 2024 17:02:17 +0200 Subject: [PATCH 04/16] fix: Documentation / conformance updates --- plugins/modules/xen_orchestra.py | 148 ++++++++++++++++--------------- 1 file changed, 78 insertions(+), 70 deletions(-) diff --git a/plugins/modules/xen_orchestra.py b/plugins/modules/xen_orchestra.py index d150506c63..4c5c13198a 100644 --- a/plugins/modules/xen_orchestra.py +++ b/plugins/modules/xen_orchestra.py @@ -1,5 +1,5 @@ # -*- coding: utf-8 -*- -# Copyright (c) 2021 Ansible Project +# Copyright (c) 2024 Ansible Project # GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) # SPDX-License-Identifier: GPL-3.0-or-later @@ -7,51 +7,61 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type DOCUMENTATION = ''' - name: xen_orchestra - short_description: Management of instances on Xen Orchestra - version_added: 9.0.1 - author: - - Samori Gorse (@shinuza) - requirements: - - websocket-client >= 1.0.0 +module: xen_orchestra +short_description: Management of instances on Xen Orchestra +description: + - Allows you to create/delete/restart/stop instances on Xen Orchestra. +version_added: 9.1.0 +options: + api_host: + description: API host to XOA API. + required: true + type: str + user: + description: Xen Orchestra user. + required: true + type: str + password: + description: Xen Orchestra password. + required: true + type: str + validate_certs: + description: Verify TLS certificate if using HTTPS. + type: bool + default: true + use_tls: + description: Use wss when connecting to the Xen Orchestra API. + type: bool + default: true + state: + description: State in which the Virtual Machine should be. + type: str + choices: ['present', 'started', 'absent', 'stopped', 'restarted'] + default: present + vm_uid: + description: + - UID of the target Virtual Machine. Required when O(state=absent), O(state=started), O(state=stopped) or + O(state=restarted) + type: str + label: + description: Label of the Virtual Machine to create, can be used when O(state=present). + type: str + description: + description: Description of the Virtual Machine to create, can be used when O(state=present). + type: str + template: description: - - Allows you to create/delete/restart/stop instances on Xen Orchestra - options: - api_host: - description: API host to XOA API. - type: str - user: - description: Xen Orchestra user. - required: true - type: str - password: - description: Xen Orchestra password. - required: true - type: str - validate_certs: - description: Verify TLS certificate if using HTTPS. - type: boolean - default: true - use_ssl: - description: Use wss when connecting to the Xen Orchestra API - type: boolean - default: true - state: - description: State in which the Virtual Machine should be - choices: ['present', 'started', 'absent', 'stopped', 'restarted'] - default: present - label: - description: Label of the Virtual Machine to create, can be used when O(state=present) - type: boolean - default: false - description: - description: Description of the Virtual Machine to create, can be used when O(state=present) - type: boolean - default: false - boot_after_create: - description: Boot Virtual Machine after creation, can be used when O(state=present) - type: boolean - default: false + - UID of a template to create Virtual Machine from. + - Muse be provided when O(state=present) + type: str + boot_after_create: + description: Boot Virtual Machine after creation, can be used when O(state=present). + type: bool + default: false +requirements: +- websocket-client >= 1.0.0 +author: +- Samori Gorse (@shinuza) ''' @@ -61,7 +71,7 @@ EXAMPLES = r''' api_host: xen-orchestra.lab user: user password: passw0rd - validate_certs: no + validate_certs: false state: present template: 355ee47d-ff4c-4924-3db2-fd86ae629676-a3d70e4d-c5ac-4dfb-999b-30a0a7efe546 label: This is a test from ansible @@ -73,7 +83,7 @@ EXAMPLES = r''' api_host: xen-orchestra.lab user: user password: passw0rd - validate_certs: no + validate_certs: false state: started - name: Stop an existing virtual machine @@ -81,7 +91,7 @@ EXAMPLES = r''' api_host: xen-orchestra.lab user: user password: passw0rd - validate_certs: no + validate_certs: false state: stop - name: Restart an existing virtual machine @@ -89,7 +99,7 @@ EXAMPLES = r''' api_host: xen-orchestra.lab user: user password: passw0rd - validate_certs: no + validate_certs: false state: stopped - name: Delete a virtual machine @@ -97,28 +107,29 @@ EXAMPLES = r''' api_host: xen-orchestra.lab user: user password: passw0rd - validate_certs: no + validate_certs: false state: absent ''' import json import ssl +import traceback from time import sleep -from ansible.errors import AnsibleError - from ansible_collections.community.general.plugins.module_utils.version import LooseVersion -from ansible.module_utils.basic import AnsibleModule +from ansible.module_utils.basic import AnsibleModule, missing_required_lib # 3rd party imports try: HAS_WEBSOCKET = True + WEBSOCKET_IMP_ERR = None import websocket from websocket import create_connection if LooseVersion(websocket.__version__) < LooseVersion('1.0.0'): raise ImportError -except ImportError as e: +except ImportError: + WEBSOCKET_IMP_ERR = traceback.format_exc() HAS_WEBSOCKET = False OBJECT_NOT_FOUND = 1 @@ -126,9 +137,6 @@ VM_STATE_ERROR = 13 class XenOrchestra(object): - ''' Host inventory parser for ansible using XenOrchestra as source. ''' - - NAME = 'community.general.xen_orchestra' CALL_TIMEOUT = 100 '''Number of 1/10ths of a second to wait before method call times out.''' @@ -148,8 +156,8 @@ class XenOrchestra(object): def create_connection(self, xoa_api_host): validate_certs = self.module.params['validate_certs'] - use_ssl = self.module.params['use_ssl'] - proto = 'wss' if use_ssl else 'ws' + use_tls = self.module.params['use_tls'] + proto = 'wss' if use_tls else 'ws' sslopt = None if validate_certs else {'cert_reqs': ssl.CERT_NONE} self.conn = create_connection( @@ -174,7 +182,7 @@ class XenOrchestra(object): sleep(0.1) waited += 1 - raise AnsibleError( + raise self.module.fail_json( 'Method call {method} timed out after {timeout} seconds.'.format(method=method, timeout=self.CALL_TIMEOUT / 10)) def login(self, user, password): @@ -253,18 +261,14 @@ class XenOrchestra(object): def main(): - if not HAS_WEBSOCKET: - raise AnsibleError('This module requires websocket-client 1.0.0 or higher: ' - 'https://github.com/websocket-client/websocket-client.') - module_args = dict( api_host=dict(type='str', required=True), user=dict(type='str', required=True), password=dict(type='str', required=True, no_log=True), validate_certs=dict(type='bool', default=True), - use_ssl=dict(type='bool', default=True), - vm_uid=dict(type='str'), + use_tls=dict(type='bool', default=True), template=dict(type='str'), + vm_uid=dict(type='str'), label=dict(type='str'), description=dict(type='str'), boot_after_create=dict(type='bool', default=False), @@ -275,12 +279,16 @@ def main(): argument_spec=module_args, required_if=[ ('state', 'present', ['template', 'label']), - ('state', 'absent', ('vm_uid')), - ('state', 'started', ('vm_uid')), - ('state', 'restarted', ('vm_uid')), - ('state', 'stopped', ('vm_uid')), + ('state', 'absent', ('vm_uid',)), + ('state', 'started', ('vm_uid',)), + ('state', 'restarted', ('vm_uid',)), + ('state', 'stopped', ('vm_uid',)), ], ) + + if HAS_WEBSOCKET is False: + module.fail_json(msg=missing_required_lib('websocket-client'), exception=WEBSOCKET_IMP_ERR) + xen_orchestra = XenOrchestra(module) state = module.params['state'] From 0c0a87f87cc7b73aad236ab4831f3a67c6825d73 Mon Sep 17 00:00:00 2001 From: Samori Gorse Date: Tue, 11 Jun 2024 17:12:53 +0200 Subject: [PATCH 05/16] fix: Trailing space --- plugins/modules/xen_orchestra.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/modules/xen_orchestra.py b/plugins/modules/xen_orchestra.py index 4c5c13198a..588b3d580e 100644 --- a/plugins/modules/xen_orchestra.py +++ b/plugins/modules/xen_orchestra.py @@ -39,7 +39,7 @@ options: choices: ['present', 'started', 'absent', 'stopped', 'restarted'] default: present vm_uid: - description: + description: - UID of the target Virtual Machine. Required when O(state=absent), O(state=started), O(state=stopped) or O(state=restarted) type: str From adecd5384682fcec5a58612b8000783c5dd89e26 Mon Sep 17 00:00:00 2001 From: Samori Gorse Date: Tue, 11 Jun 2024 17:21:49 +0200 Subject: [PATCH 06/16] fix: Updated maintainers meta file --- .github/BOTMETA.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index 1beb35c57b..3bbeef69c5 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -1437,6 +1437,8 @@ files: maintainers: dinoocch the-maldridge $modules/xcc_: maintainers: panyy3 renxulei + $modules/xen_orchestra.py: + maintainers: shinuza $modules/xenserver_: maintainers: bvitnik $modules/xenserver_facts.py: From 0f7ef7a3bc5c8b16099ac4a8799043b1b17bd963 Mon Sep 17 00:00:00 2001 From: Samori Gorse Date: Sat, 22 Jun 2024 11:33:55 +0200 Subject: [PATCH 07/16] Update plugins/modules/xen_orchestra.py Co-authored-by: Felix Fontein --- plugins/modules/xen_orchestra.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/modules/xen_orchestra.py b/plugins/modules/xen_orchestra.py index 588b3d580e..3fd60184d2 100644 --- a/plugins/modules/xen_orchestra.py +++ b/plugins/modules/xen_orchestra.py @@ -76,7 +76,7 @@ EXAMPLES = r''' template: 355ee47d-ff4c-4924-3db2-fd86ae629676-a3d70e4d-c5ac-4dfb-999b-30a0a7efe546 label: This is a test from ansible description: This is a test from ansible - boot_after_create: no + boot_after_create: false - name: Start an existing virtual machine community.general.xen_orchestra: From 99ff687b8fe1d8424c1f2ce4272a1a15aa710e16 Mon Sep 17 00:00:00 2001 From: Samori Gorse Date: Mon, 24 Jun 2024 09:24:40 +0000 Subject: [PATCH 08/16] feat: Renamed xen_orchestra -> xen_orchestra_instance --- plugins/modules/{xen_orchestra.py => xen_orchestra_instance.py} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename plugins/modules/{xen_orchestra.py => xen_orchestra_instance.py} (99%) diff --git a/plugins/modules/xen_orchestra.py b/plugins/modules/xen_orchestra_instance.py similarity index 99% rename from plugins/modules/xen_orchestra.py rename to plugins/modules/xen_orchestra_instance.py index 3fd60184d2..7d8781c847 100644 --- a/plugins/modules/xen_orchestra.py +++ b/plugins/modules/xen_orchestra_instance.py @@ -7,7 +7,7 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type DOCUMENTATION = ''' -module: xen_orchestra +module: xen_orchestra_instance short_description: Management of instances on Xen Orchestra description: - Allows you to create/delete/restart/stop instances on Xen Orchestra. From 834e05ecd3626e205c67eef427003270838a197f Mon Sep 17 00:00:00 2001 From: Samori Gorse Date: Mon, 24 Jun 2024 09:29:57 +0000 Subject: [PATCH 09/16] chore: Update BOTMETA file --- .github/BOTMETA.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index 3bbeef69c5..f22118f05f 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -1437,7 +1437,7 @@ files: maintainers: dinoocch the-maldridge $modules/xcc_: maintainers: panyy3 renxulei - $modules/xen_orchestra.py: + $modules/xen_orchestra_instance.py: maintainers: shinuza $modules/xenserver_: maintainers: bvitnik From e3faa8f29eec884e5b53bb7d877fe0754cca157d Mon Sep 17 00:00:00 2001 From: Samori Gorse Date: Thu, 27 Jun 2024 18:56:47 +0200 Subject: [PATCH 10/16] Update plugins/modules/xen_orchestra_instance.py Update version from 9.1.0 to 9.2.0 Co-authored-by: Felix Fontein --- plugins/modules/xen_orchestra_instance.py | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/plugins/modules/xen_orchestra_instance.py b/plugins/modules/xen_orchestra_instance.py index 7d8781c847..0ed679b890 100644 --- a/plugins/modules/xen_orchestra_instance.py +++ b/plugins/modules/xen_orchestra_instance.py @@ -11,7 +11,14 @@ module: xen_orchestra_instance short_description: Management of instances on Xen Orchestra description: - Allows you to create/delete/restart/stop instances on Xen Orchestra. -version_added: 9.1.0 +version_added: 9.2.0 +extends_documentation_fragment: + - community.general.attributes +attributes: + check_mode: + support: none + diff_mode: + support: none options: api_host: description: API host to XOA API. From 372f6e41ffffdb47f7c69f5787e23eab8ccaa26b Mon Sep 17 00:00:00 2001 From: Samori Gorse Date: Sun, 5 Jan 2025 16:58:01 +0100 Subject: [PATCH 11/16] feat: Include feedback --- plugins/modules/xen_orchestra_instance.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/plugins/modules/xen_orchestra_instance.py b/plugins/modules/xen_orchestra_instance.py index 0ed679b890..b0dea92a04 100644 --- a/plugins/modules/xen_orchestra_instance.py +++ b/plugins/modules/xen_orchestra_instance.py @@ -48,7 +48,7 @@ options: vm_uid: description: - UID of the target Virtual Machine. Required when O(state=absent), O(state=started), O(state=stopped) or - O(state=restarted) + O(state=restarted). type: str label: description: Label of the Virtual Machine to create, can be used when O(state=present). @@ -59,7 +59,7 @@ options: template: description: - UID of a template to create Virtual Machine from. - - Muse be provided when O(state=present) + - Muse be provided when O(state=present). type: str boot_after_create: description: Boot Virtual Machine after creation, can be used when O(state=present). @@ -172,9 +172,9 @@ class XenOrchestra(object): def call(self, method, params): '''Calls a method on the XO server with the provided parameters.''' - id = self.pointer + pointer = self.pointer self.conn.send(json.dumps({ - 'id': id, + 'id': pointer, 'jsonrpc': '2.0', 'method': method, 'params': params @@ -183,7 +183,7 @@ class XenOrchestra(object): waited = 0 while waited < self.CALL_TIMEOUT: response = json.loads(self.conn.recv()) - if 'id' in response and response['id'] == id: + if response.get('id') == pointer: return response else: sleep(0.1) @@ -319,7 +319,7 @@ def main(): if state == 'present': result = xen_orchestra.create_vm() - module.exit_json(changed=True, vm_uid=result) + module.exit_json(changed=False, vm_uid=result) if __name__ == '__main__': From 2fb5b75fcda6b8b34f7995d7cad9c08c28aec332 Mon Sep 17 00:00:00 2001 From: Samori Gorse Date: Wed, 8 Jan 2025 10:26:31 +0100 Subject: [PATCH 12/16] chore: Yaml formatting, version bumped --- plugins/modules/xen_orchestra_instance.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/plugins/modules/xen_orchestra_instance.py b/plugins/modules/xen_orchestra_instance.py index b0dea92a04..3fe4057ec2 100644 --- a/plugins/modules/xen_orchestra_instance.py +++ b/plugins/modules/xen_orchestra_instance.py @@ -11,9 +11,9 @@ module: xen_orchestra_instance short_description: Management of instances on Xen Orchestra description: - Allows you to create/delete/restart/stop instances on Xen Orchestra. -version_added: 9.2.0 +version_added: 10.3.0 extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: support: none @@ -66,9 +66,9 @@ options: type: bool default: false requirements: -- websocket-client >= 1.0.0 + - websocket-client >= 1.0.0 author: -- Samori Gorse (@shinuza) + - Samori Gorse (@shinuza) ''' From 34fbc6d05adef862585a6c1444ea25eb65f9a29f Mon Sep 17 00:00:00 2001 From: Samori Gorse Date: Wed, 12 Feb 2025 15:48:05 +0100 Subject: [PATCH 13/16] Added see also section --- plugins/modules/xen_orchestra_instance.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/plugins/modules/xen_orchestra_instance.py b/plugins/modules/xen_orchestra_instance.py index 3fe4057ec2..2c7b53db14 100644 --- a/plugins/modules/xen_orchestra_instance.py +++ b/plugins/modules/xen_orchestra_instance.py @@ -69,6 +69,10 @@ requirements: - websocket-client >= 1.0.0 author: - Samori Gorse (@shinuza) +seealso: + - name: Xen Orchestra documentation + description: Official documentation of Xen Orchestra CLI. + link: https://docs.xen-orchestra.com/architecture#xo-cli-cli ''' From bf389ea3facd105332d61f76abbe3e7d47a0abf3 Mon Sep 17 00:00:00 2001 From: Samori Gorse Date: Wed, 12 Feb 2025 16:06:20 +0100 Subject: [PATCH 14/16] Fixed typo in example --- plugins/modules/xen_orchestra_instance.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/modules/xen_orchestra_instance.py b/plugins/modules/xen_orchestra_instance.py index 2c7b53db14..e32e73739b 100644 --- a/plugins/modules/xen_orchestra_instance.py +++ b/plugins/modules/xen_orchestra_instance.py @@ -103,7 +103,7 @@ EXAMPLES = r''' user: user password: passw0rd validate_certs: false - state: stop + state: stopped - name: Restart an existing virtual machine community.general.xen_orchestra: From a17a84a0604c06ec57a353a9dd104bc1bd761cc5 Mon Sep 17 00:00:00 2001 From: Samori Gorse Date: Wed, 12 Feb 2025 16:10:14 +0100 Subject: [PATCH 15/16] Fixed raw strings, to align with the rest of the project --- plugins/modules/xen_orchestra_instance.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/plugins/modules/xen_orchestra_instance.py b/plugins/modules/xen_orchestra_instance.py index e32e73739b..b2dd3f44e1 100644 --- a/plugins/modules/xen_orchestra_instance.py +++ b/plugins/modules/xen_orchestra_instance.py @@ -6,7 +6,7 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: xen_orchestra_instance short_description: Management of instances on Xen Orchestra description: @@ -73,10 +73,10 @@ seealso: - name: Xen Orchestra documentation description: Official documentation of Xen Orchestra CLI. link: https://docs.xen-orchestra.com/architecture#xo-cli-cli -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Create a new virtual machine community.general.xen_orchestra: api_host: xen-orchestra.lab @@ -120,7 +120,7 @@ EXAMPLES = r''' password: passw0rd validate_certs: false state: absent -''' +""" import json import ssl From ae60f3032567d6996989d49443df6fe1bf6c37de Mon Sep 17 00:00:00 2001 From: Samori Gorse Date: Wed, 12 Feb 2025 16:39:43 +0100 Subject: [PATCH 16/16] Updated state documentation --- plugins/modules/xen_orchestra_instance.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/plugins/modules/xen_orchestra_instance.py b/plugins/modules/xen_orchestra_instance.py index b2dd3f44e1..77eb01508e 100644 --- a/plugins/modules/xen_orchestra_instance.py +++ b/plugins/modules/xen_orchestra_instance.py @@ -41,7 +41,12 @@ options: type: bool default: true state: - description: State in which the Virtual Machine should be. + description: + - State in which the Virtual Machine should be. + - If O(state=present) then O(template) and O(label) are required. + - If O(state=absent), O(state=started), O(state=stopped) or O(state=restarted) then O(vm_uid) is required. + - When state is O(present) then O(boot_after_create) can be used to boot the VM after creation. + - There is no idempotence guarantee when O(state=present), a new VM will always be created. type: str choices: ['present', 'started', 'absent', 'stopped', 'restarted'] default: present