Added new module lxca_nodes for Lenovo XClarity Administrator (#46767)

* Added new module lxca_nodes

lib/ansible/module_utils/remote_management/lxca/common.py

@@ -0,0 +1,95 @@
+# This code is part of Ansible, but is an independent component.
+# This particular file snippet, and this file snippet only, is BSD licensed.
+# Modules you write using this snippet, which is embedded dynamically by
+# Ansible still belong to the author of the module, and may assign their
+# own license to the complete work.
+#
+# Copyright (C) 2017 Lenovo, Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#  * Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+#  * Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+#
+# Contains LXCA common class
+# Lenovo xClarity Administrator (LXCA)
+
+import traceback
+try:
+    from pylxca import connect, disconnect
+    HAS_PYLXCA = True
+except ImportError:
+    HAS_PYLXCA = False
+
+
+PYLXCA_REQUIRED = "Lenovo xClarity Administrator Python Client (Python package 'pylxca') is required for this module."
+
+
+def has_pylxca(module):
+    """
+    Check pylxca is installed
+    :param module:
+    """
+    if not HAS_PYLXCA:
+        module.fail_json(msg=PYLXCA_REQUIRED)
+
+
+LXCA_COMMON_ARGS = dict(
+    login_user=dict(required=True),
+    login_password=dict(required=True, no_log=True),
+    auth_url=dict(required=True),
+)
+
+
+class connection_object:
+    def __init__(self, module):
+        self.module = module
+
+    def __enter__(self):
+        return setup_conn(self.module)
+
+    def __exit__(self, type, value, traceback):
+        close_conn()
+
+
+def setup_conn(module):
+    """
+    this function create connection to LXCA
+    :param module:
+    :return:  lxca connection
+    """
+    lxca_con = None
+    try:
+        lxca_con = connect(module.params['auth_url'],
+                           module.params['login_user'],
+                           module.params['login_password'],
+                           "True")
+    except Exception as exception:
+        error_msg = '; '.join(exception.args)
+        module.fail_json(msg=error_msg, exception=traceback.format_exc())
+    return lxca_con
+
+
+def close_conn():
+    """
+    this function close connection to LXCA
+    :param module:
+    :return:  None
+    """
+    disconnect()

lib/ansible/modules/remote_management/lxca/lxca_nodes.py

@@ -0,0 +1,207 @@
+#!/usr/bin/python
+# 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',
+    'supported_by': 'community',
+    'status': ['preview']
+}
+
+
+DOCUMENTATION = '''
+---
+version_added: "2.8"
+author:
+  - Naval Patel (@navalkp)
+  - Prashant Bhosale (@prabhosa)
+module: lxca_nodes
+short_description: Custom module for lxca nodes inventory utility
+description:
+  - This module returns/displays a inventory details of nodes
+
+options:
+  uuid:
+    description:
+      uuid of device, this is string with length greater than 16.
+
+  command_options:
+    description:
+      options to filter nodes information
+    default: nodes
+    choices:
+        - nodes
+        - nodes_by_uuid
+        - nodes_by_chassis_uuid
+        - nodes_status_managed
+        - nodes_status_unmanaged
+
+  chassis:
+    description:
+      uuid of chassis, this is string with length greater than 16.
+
+extends_documentation_fragment:
+    - lxca_common
+'''
+
+EXAMPLES = '''
+# get all nodes info
+- name: get nodes data from LXCA
+  lxca_nodes:
+    login_user: USERID
+    login_password: Password
+    auth_url: "https://10.243.15.168"
+    command_options: nodes
+
+# get specific nodes info by uuid
+- name: get nodes data from LXCA
+  lxca_nodes:
+    login_user: USERID
+    login_password: Password
+    auth_url: "https://10.243.15.168"
+    uuid: "3C737AA5E31640CE949B10C129A8B01F"
+    command_options: nodes_by_uuid
+
+# get specific nodes info by chassis uuid
+- name: get nodes data from LXCA
+  lxca_nodes:
+    login_user: USERID
+    login_password: Password
+    auth_url: "https://10.243.15.168"
+    chassis: "3C737AA5E31640CE949B10C129A8B01F"
+    command_options: nodes_by_chassis_uuid
+
+# get managed nodes
+- name: get nodes data from LXCA
+  lxca_nodes:
+    login_user: USERID
+    login_password: Password
+    auth_url: "https://10.243.15.168"
+    command_options: nodes_status_managed
+
+# get unmanaged nodes
+- name: get nodes data from LXCA
+  lxca_nodes:
+    login_user: USERID
+    login_password: Password
+    auth_url: "https://10.243.15.168"
+    command_options: nodes_status_unmanaged
+
+'''
+
+RETURN = r'''
+result:
+    description: nodes detail from lxca
+    returned: always
+    type: dict
+    sample:
+      nodeList:
+        - machineType: '6241'
+          model: 'AC1'
+          type: 'Rack-TowerServer'
+          uuid: '118D2C88C8FD11E4947B6EAE8B4BDCDF'
+          # bunch of properties
+        - machineType: '8871'
+          model: 'AC1'
+          type: 'Rack-TowerServer'
+          uuid: '223D2C88C8FD11E4947B6EAE8B4BDCDF'
+          # bunch of properties
+        # Multiple nodes details
+'''
+
+import traceback
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.remote_management.lxca.common import LXCA_COMMON_ARGS, has_pylxca, connection_object
+try:
+    from pylxca import nodes
+except ImportError:
+    pass
+
+
+UUID_REQUIRED = 'UUID of device is required for nodes_by_uuid command.'
+CHASSIS_UUID_REQUIRED = 'UUID of chassis is required for nodes_by_chassis_uuid command.'
+SUCCESS_MSG = "Success %s result"
+
+
+def _nodes(module, lxca_con):
+    return nodes(lxca_con)
+
+
+def _nodes_by_uuid(module, lxca_con):
+    if not module.params['uuid']:
+        module.fail_json(msg=UUID_REQUIRED)
+    return nodes(lxca_con, module.params['uuid'])
+
+
+def _nodes_by_chassis_uuid(module, lxca_con):
+    if not module.params['chassis']:
+        module.fail_json(msg=CHASSIS_UUID_REQUIRED)
+    return nodes(lxca_con, chassis=module.params['chassis'])
+
+
+def _nodes_status_managed(module, lxca_con):
+    return nodes(lxca_con, status='managed')
+
+
+def _nodes_status_unmanaged(module, lxca_con):
+    return nodes(lxca_con, status='unmanaged')
+
+
+def setup_module_object():
+    """
+    this function merge argument spec and create ansible module object
+    :return:
+    """
+    args_spec = dict(LXCA_COMMON_ARGS)
+    args_spec.update(INPUT_ARG_SPEC)
+    module = AnsibleModule(argument_spec=args_spec, supports_check_mode=False)
+
+    return module
+
+
+FUNC_DICT = {
+    'nodes': _nodes,
+    'nodes_by_uuid': _nodes_by_uuid,
+    'nodes_by_chassis_uuid': _nodes_by_chassis_uuid,
+    'nodes_status_managed': _nodes_status_managed,
+    'nodes_status_unmanaged': _nodes_status_unmanaged,
+}
+
+
+INPUT_ARG_SPEC = dict(
+    command_options=dict(default='nodes', choices=['nodes', 'nodes_by_uuid',
+                                                   'nodes_by_chassis_uuid',
+                                                   'nodes_status_managed',
+                                                   'nodes_status_unmanaged']),
+    uuid=dict(default=None), chassis=dict(default=None)
+)
+
+
+def execute_module(module):
+    """
+    This function invoke commands
+    :param module: Ansible module object
+    """
+    try:
+        with connection_object(module) as lxca_con:
+            result = FUNC_DICT[module.params['command_options']](module, lxca_con)
+            module.exit_json(changed=False,
+                             msg=SUCCESS_MSG % module.params['command_options'],
+                             result=result)
+    except Exception as exception:
+        error_msg = '; '.join(exception.args)
+        module.fail_json(msg=error_msg, exception=traceback.format_exc())
+
+
+def main():
+    module = setup_module_object()
+    has_pylxca(module)
+    execute_module(module)
+
+
+if __name__ == '__main__':
+    main()

lib/ansible/utils/module_docs_fragments/lxca_common.py

@@ -0,0 +1,63 @@
+# This code is part of Ansible, but is an independent component.
+# This particular file snippet, and this file snippet only, is BSD licensed.
+# Modules you write using this snippet, which is embedded dynamically by
+# Ansible still belong to the author of the module, and may assign their
+# own license to the complete work.
+#
+# Copyright (C) 2017 Lenovo, Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#  * Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+#  * Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+#
+
+
+class ModuleDocFragment(object):
+    # Standard Pylxca documentation fragment
+    DOCUMENTATION = '''
+author:
+  - Naval Patel (@navalkp)
+  - Prashant Bhosale (@prabhosa)
+
+options:
+  login_user:
+    description:
+      The username for use in HTTP basic authentication.
+
+    required: true
+
+  login_password:
+    description:
+      The password for use in HTTP basic authentication.
+    required: true
+
+  auth_url:
+    description:
+      lxca https full web address
+    required: true
+
+requirement:
+  - pylxca
+
+notes:
+  -  Additional detail about pylxca can be found at U(https://github.com/lenovo/pylxca)
+  -  Playbooks using these modules can be found at U(https://github.com/lenovo/ansible.lenovo-lxca)
+  -  Check mode is not supported.
+'''

test/units/modules/remote_management/lxca/test_lxca_nodes.py

@@ -0,0 +1,100 @@
+import json
+
+import pytest
+from units.compat import mock
+from ansible.module_utils import basic
+from ansible.module_utils._text import to_bytes
+from ansible.modules.remote_management.lxca import lxca_nodes
+from ansible.module_utils.remote_management.lxca.common import setup_conn
+from ansible.module_utils.remote_management.lxca.common import close_conn
+
+
+@pytest.fixture(scope='module')
+@mock.patch("ansible.module_utils.remote_management.lxca.common.close_conn", autospec=True)
+def setup_module(close_conn):
+    close_conn.return_value = True
+
+
+class TestMyModule():
+    @pytest.mark.parametrize('patch_ansible_module',
+                             [
+                                 {},
+                                 {
+                                     "auth_url": "https://10.240.14.195",
+                                     "login_user": "USERID",
+                                 },
+                                 {
+                                     "auth_url": "https://10.240.14.195",
+                                     "login_password": "Password",
+                                 },
+                                 {
+                                     "login_user": "USERID",
+                                     "login_password": "Password",
+                                 },
+                             ],
+                             indirect=['patch_ansible_module'])
+    @pytest.mark.usefixtures('patch_ansible_module')
+    @mock.patch("ansible.module_utils.remote_management.lxca.common.setup_conn", autospec=True)
+    @mock.patch("ansible.modules.remote_management.lxca.lxca_nodes.execute_module", autospec=True)
+    def test_without_required_parameters(self, _setup_conn, _execute_module,
+                                         mocker, capfd, setup_module):
+        """Failure must occurs when all parameters are missing"""
+        with pytest.raises(SystemExit):
+            _setup_conn.return_value = "Fake connection"
+            _execute_module.return_value = "Fake execution"
+            lxca_nodes.main()
+        out, err = capfd.readouterr()
+        results = json.loads(out)
+        assert results['failed']
+        assert 'missing required arguments' in results['msg']
+
+    @mock.patch("ansible.module_utils.remote_management.lxca.common.setup_conn", autospec=True)
+    @mock.patch("ansible.modules.remote_management.lxca.lxca_nodes.execute_module", autospec=True)
+    @mock.patch("ansible.modules.remote_management.lxca.lxca_nodes.AnsibleModule", autospec=True)
+    def test__argument_spec(self, ansible_mod_cls, _execute_module, _setup_conn, setup_module):
+        expected_arguments_spec = dict(
+            login_user=dict(required=True),
+            login_password=dict(required=True, no_log=True),
+            command_options=dict(default='nodes', choices=['nodes', 'nodes_by_uuid',
+                                                           'nodes_by_chassis_uuid',
+                                                           'nodes_status_managed',
+                                                           'nodes_status_unmanaged']),
+            auth_url=dict(required=True),
+            uuid=dict(default=None),
+            chassis=dict(default=None),
+        )
+        _setup_conn.return_value = "Fake connection"
+        _execute_module.return_value = []
+        mod_obj = ansible_mod_cls.return_value
+        args = {
+            "auth_url": "https://10.243.30.195",
+            "login_user": "USERID",
+            "login_password": "password",
+            "command_options": "nodes",
+        }
+        mod_obj.params = args
+        lxca_nodes.main()
+        assert(mock.call(argument_spec=expected_arguments_spec,
+                         supports_check_mode=False) == ansible_mod_cls.call_args)
+
+    @mock.patch("ansible.module_utils.remote_management.lxca.common.setup_conn", autospec=True)
+    @mock.patch("ansible.modules.remote_management.lxca.lxca_nodes._nodes_by_uuid",
+                autospec=True)
+    @mock.patch("ansible.modules.remote_management.lxca.lxca_nodes.AnsibleModule",
+                autospec=True)
+    def test__nodes_empty_list(self, ansible_mod_cls, _get_nodes, _setup_conn, setup_module):
+        mod_obj = ansible_mod_cls.return_value
+        args = {
+            "auth_url": "https://10.243.30.195",
+            "login_user": "USERID",
+            "login_password": "password",
+            "uuid": "3C737AA5E31640CE949B10C129A8B01F",
+            "command_options": "nodes_by_uuid",
+        }
+        mod_obj.params = args
+        _setup_conn.return_value = "Fake connection"
+        empty_nodes_list = []
+        _get_nodes.return_value = empty_nodes_list
+        ret_nodes = _get_nodes(mod_obj, args)
+        assert mock.call(mod_obj, mod_obj.params) == _get_nodes.call_args
+        assert _get_nodes.return_value == ret_nodes