UCS Server UUID pool modules and integration tests (#41743)

* UCS Server UUID pool modules and integration tests

* change version added to 2.7

* Doc and result changed updates from review.

lib/ansible/modules/remote_management/ucs/ucs_uuid_pool.py

@@ -0,0 +1,197 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# 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: ucs_uuid_pool
+short_description: Configures server UUID pools on Cisco UCS Manager
+description:
+- Configures server UUID pools and UUID blocks on Cisco UCS Manager.
+- Examples can be used with the L(UCS Platform Emulator,https://communities.cisco.com/ucspe).
+extends_documentation_fragment: ucs
+options:
+  state:
+    description:
+    - If C(present), will verify UUID pool is present and will create if needed.
+    - If C(absent), will verify UUID pool is absent and will delete if needed.
+    choices: [present, absent]
+    default: present
+  name:
+    description:
+    - The name of the UUID pool.
+    - This name can be between 1 and 32 alphanumeric characters.
+    - "You cannot use spaces or any special characters other than - (hyphen), \"_\" (underscore), : (colon), and . (period)."
+    - You cannot change this name after the UUID pool is created.
+    required: yes
+  description:
+    description:
+    - "The user-defined description of the UUID pool."
+    - Enter up to 256 characters.
+    - "You can use any characters or spaces except the following:"
+    - "` (accent mark), \ (backslash), ^ (carat), \" (double quote), = (equal sign), > (greater than), < (less than), or ' (single quote)."
+    aliases: [ descr ]
+  prefix:
+    description:
+    - UUID prefix used for the range of server UUIDs.
+    - "If no value is provided, the system derived prefix will be used (equivalent to selecting 'derived' option in UI)."
+    - "If the user provides a value, the user provided prefix will be used (equivalent to selecting 'other' option in UI)."
+    - A user provided value should be in the format XXXXXXXX-XXXX-XXXX.
+  order:
+    description:
+    - The Assignment Order field.
+    - "This can be one of the following:"
+    - "default - Cisco UCS Manager selects a random identity from the pool."
+    - "sequential - Cisco UCS Manager selects the lowest available identity from the pool."
+    choices: [default, sequential]
+    default: default
+  first_uuid:
+    description:
+    - The first UUID in the block of UUIDs.
+    - This is the From field in the UCS Manager UUID Blocks menu.
+  last_uuid:
+    description:
+    - The last UUID in the block of UUIDs.
+    - This is the To field in the UCS Manager Add UUID Blocks menu.
+  org_dn:
+    description:
+    - The distinguished name (dn) of the organization where the resource is assigned.
+    default: org-root
+requirements:
+- ucsmsdk
+author:
+- David Soper (@dsoper2)
+- CiscoUcs (@CiscoUcs)
+version_added: '2.7'
+'''
+
+EXAMPLES = r'''
+- name: Configure UUID address pool
+  ucs_uuid_pool:
+    hostname: 172.16.143.150
+    username: admin
+    password: password
+    name: UUID-Pool
+    order: sequential
+    first_uuid: 0000-000000000001
+    last_uuid: 0000-000000000078
+
+- name: Remove UUID address pool
+  ucs_uuid_pool:
+    hostname: 172.16.143.150
+    username: admin
+    password: password
+    name: UUID-Pool
+    state: absent
+'''
+
+RETURN = r'''
+#
+'''
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.remote_management.ucs import UCSModule, ucs_argument_spec
+
+
+def main():
+    argument_spec = ucs_argument_spec
+    argument_spec.update(
+        org_dn=dict(type='str', default='org-root'),
+        name=dict(type='str', required=True),
+        description=dict(type='str', aliases=['descr'], default=''),
+        order=dict(type='str', default='default', choices=['default', 'sequential']),
+        prefix=dict(type='str', default=''),
+        first_uuid=dict(type='str'),
+        last_uuid=dict(type='str'),
+        state=dict(default='present', choices=['present', 'absent'], type='str'),
+    )
+    module = AnsibleModule(
+        argument_spec,
+        supports_check_mode=True,
+    )
+    # UCSModule verifies ucsmsdk is present and exits on failure.  Imports are below ucs object creation.
+    ucs = UCSModule(module)
+
+    err = False
+
+    from ucsmsdk.mometa.uuidpool.UuidpoolPool import UuidpoolPool
+    from ucsmsdk.mometa.uuidpool.UuidpoolBlock import UuidpoolBlock
+
+    ucs.result['changed'] = False
+    try:
+        mo_exists = False
+        props_match = False
+        # dn is <org_dn>/uuid-pool-<name>
+        dn = module.params['org_dn'] + '/uuid-pool-' + module.params['name']
+        mo = ucs.login_handle.query_dn(dn)
+        if mo:
+            mo_exists = True
+
+        if module.params['state'] == 'absent':
+            if mo_exists:
+                if not module.check_mode:
+                    ucs.login_handle.remove_mo(mo)
+                    ucs.login_handle.commit()
+                ucs.result['changed'] = True
+        else:
+            if mo_exists:
+                # check top-level mo props
+                kwargs = dict(assignment_order=module.params['order'])
+                kwargs['descr'] = module.params['description']
+                if module.params['prefix']:
+                    kwargs['prefix'] = module.params['prefix']
+                if mo.check_prop_match(**kwargs):
+                    # top-level props match, check next level mo/props
+                    if module.params['last_uuid'] and module.params['first_uuid']:
+                        # uuid address block specified, check properties
+                        block_dn = dn + '/block-from-' + module.params['first_uuid'].upper() + '-to-' + module.params['last_uuid'].upper()
+                        mo_1 = ucs.login_handle.query_dn(block_dn)
+                        if mo_1:
+                            props_match = True
+                    else:
+                        # no UUID address block specified, but top-level props matched
+                        props_match = True
+
+            if not props_match:
+                if not module.check_mode:
+                    # create if mo does not already exist
+                    if not module.params['prefix']:
+                        module.params['prefix'] = 'derived'
+                    mo = UuidpoolPool(
+                        parent_mo_or_dn=module.params['org_dn'],
+                        name=module.params['name'],
+                        descr=module.params['description'],
+                        assignment_order=module.params['order'],
+                        prefix=module.params['prefix']
+                    )
+
+                    if module.params['last_uuid'] and module.params['first_uuid']:
+                        mo_1 = UuidpoolBlock(
+                            parent_mo_or_dn=mo,
+                            to=module.params['last_uuid'],
+                            r_from=module.params['first_uuid'],
+                        )
+
+                    ucs.login_handle.add_mo(mo, True)
+                    ucs.login_handle.commit()
+                ucs.result['changed'] = True
+
+    except Exception as e:
+        err = True
+        ucs.result['msg'] = "setup error: %s " % str(e)
+
+    if err:
+        module.fail_json(**ucs.result)
+    module.exit_json(**ucs.result)
+
+
+if __name__ == '__main__':
+    main()

test/integration/targets/ucs_uuid_pool/aliases

@@ -0,0 +1,7 @@
+# Not enabled, but can be used with the UCS Platform Emulator or UCS hardware.
+# Example integration_config.yml:
+# ---
+# ucs_hostname: 172.16.143.136
+# ucs_username: admin
+# ucs_password: password
+unsupported

test/integration/targets/ucs_uuid_pool/tasks/main.yml

@@ -0,0 +1,128 @@
+# Test code for the UCS modules
+# Copyright 2018, David Soper (@dsoper2)
+
+- name: Test that we have a UCS host, UCS username, and UCS password
+  fail:
+    msg: 'Please define the following variables: ucs_hostname, ucs_username and ucs_password.'
+  when: ucs_hostname is not defined or ucs_username is not defined or ucs_password is not defined
+  vars:
+    login_info: &login_info
+      hostname: "{{ ucs_hostname }}"
+      username: "{{ ucs_username }}"
+      password: "{{ ucs_password }}"
+
+# Setup (clean environment)
+- name: Server UUID Pools absent
+  ucs_uuid_pool: &uuid_pool_absent
+    <<: *login_info
+    name: UUID-Pool
+    state: absent
+
+
+# Test present (check_mode)
+- name: Server UUID Pools present (check_mode)
+  ucs_uuid_pool: &uuid_pool_present
+    <<: *login_info
+    name: UUID-Pool
+    order: sequential
+    first_uuid: 0000-000000000001
+    last_uuid: 0000-000000000078
+  check_mode: yes
+  register: cm_uuid_pool_present
+
+
+# Present (normal mode)
+- name: Server UUID Pools present (normal mode)
+  ucs_uuid_pool: *uuid_pool_present
+  register: nm_uuid_pool_present
+
+
+# Test present again (idempotent)
+- name: Server UUID Pools present again (check_mode)
+  ucs_uuid_pool: *uuid_pool_present
+  check_mode: yes
+  register: cm_uuid_pool_present_again
+
+
+# Present again (normal mode)
+- name: Server UUID Pools present again (normal mode)
+  ucs_uuid_pool: *uuid_pool_present
+  register: nm_uuid_pool_present_again
+
+
+# Verfiy present
+- name: Verify Server UUID Pools present results
+  assert:
+    that:
+    - cm_uuid_pool_present.changed == nm_uuid_pool_present.changed == true
+    - cm_uuid_pool_present_again.changed == nm_uuid_pool_present_again.changed == false
+
+
+# Test change (check_mode)
+- name: Server UUID Pools description change (check_mode)
+  ucs_uuid_pool: &uuid_pool_change
+    <<: *uuid_pool_present
+    descr: Testing Ansible
+  check_mode: yes
+  register: cm_uuid_pool_descr_change
+
+
+# Change (normal mode)
+- name: Server UUID Pools description change (normal mode)
+  ucs_uuid_pool: *uuid_pool_change
+  register: nm_uuid_pool_descr_change
+
+
+# Test change again (idempotent)
+- name: Server UUID Pools description again (check_mode)
+  ucs_uuid_pool: *uuid_pool_change
+  check_mode: yes
+  register: cm_uuid_pool_descr_change_again
+
+
+# Change again (normal mode)
+- name: Server UUID Pools description change again (normal mode)
+  ucs_uuid_pool: *uuid_pool_change
+  register: nm_uuid_pool_descr_change_again
+
+
+# Verfiy change
+- name: Verify Server UUID Pools change results
+  assert:
+    that:
+    - cm_uuid_pool_descr_change.changed == nm_uuid_pool_descr_change.changed == true
+    - cm_uuid_pool_descr_change_again.changed == nm_uuid_pool_descr_change_again.changed == false
+
+
+# Teardown (clean environment)
+- name: Server UUID Pools absent (check_mode)
+  ucs_uuid_pool: *uuid_pool_absent
+  check_mode: yes
+  register: cm_uuid_pool_absent
+
+
+# Absent (normal mode)
+- name: Server UUID Pools absent (normal mode)
+  ucs_uuid_pool: *uuid_pool_absent
+  register: nm_uuid_pool_absent
+
+
+# Test absent again (idempotent)
+- name: Server UUID Pools absent again (check_mode)
+  ucs_uuid_pool: *uuid_pool_absent
+  check_mode: yes
+  register: cm_uuid_pool_absent_again
+
+
+# Absent again (normal mode)
+- name: Server UUID Pools absent again (normal mode)
+  ucs_uuid_pool: *uuid_pool_absent
+  register: nm_uuid_pool_absent_again
+
+
+# Verfiy absent
+- name: Verify Server UUID Pools absent results
+  assert:
+    that:
+    - cm_uuid_pool_absent.changed == nm_uuid_pool_absent.changed == true
+    - cm_uuid_pool_absent_again.changed == nm_uuid_pool_absent_again.changed == false