Improvements in cpc and partition modules

Details:

* zhmc_cpc: Added an artificial property 'storage-groups' to the output
  that shows the storage groups attached to the partition, with only a subset
  of their properties.

* zhmc_partition: Added an artificial property 'storage-groups' to the output
  that shows the storage groups attached to the partition, with all of their
  properties and artificial properties as in the result of zhmc_storage_group.
  This is enabled by the new boolean input parameter 'expand_storage_groups'.

* zhmc_partition: Added an artificial property 'crypto-adapters' to the
  'crypto-configuration' property, showing the adapter properties of the
  crypto adapters attached to the partition, with all of their properties and
  artificial properties as in the result of zhmc_adapter. This is enabled by
  the new boolean input parameter 'expand_crypto_adapters'.

* zhmc_partition: Added artificial properties to the 'nics' property:

  * 'adapter-name': Name of the adapter backing the NIC
  * 'adapter-port': Port index on the adapter backing the NIC
  * 'adapter-id': Adapter ID (PCHID) of the adapter backing the NIC

* In test_func_partition-py, added missing property 'storage-group-uris' to
  faked partition. This is needed for testing the new boolean input parameter
  'expand_storage_groups'.

* Examples: Added an example playbook 'get_cpc_io.yml' which retrieves
  information about a CPC in DPM mode and its I/O configuration and
  creates a markdown file showing the result.

* Extended function and unit tests of zhmc_partition accordingly.

Signed-off-by: Andreas Maier <maiera@de.ibm.com>

docs/source/changes.rst

@@ -81,6 +81,31 @@ Released: not yet
   are specifically described on the module pages without referencing any
   common return value type.
 
+* zhmc_cpc: Added an artificial property 'storage-groups' to the output
+  that shows the storage groups attached to the partition, with only a subset
+  of their properties.
+
+* zhmc_partition: Added an artificial property 'storage-groups' to the output
+  that shows the storage groups attached to the partition, with all of their
+  properties and artificial properties as in the result of zhmc_storage_group.
+  This is enabled by the new boolean input parameter 'expand_storage_groups'.
+
+* zhmc_partition: Added an artificial property 'crypto-adapters' to the
+  'crypto-configuration' property, showing the adapter properties of the
+  crypto adapters attached to the partition, with all of their properties and
+  artificial properties as in the result of zhmc_adapter. This is enabled by
+  the new boolean input parameter 'expand_crypto_adapters'.
+
+* zhmc_partition: Added artificial properties to the 'nics' property:
+
+  * 'adapter-name': Name of the adapter backing the NIC
+  * 'adapter-port': Port index on the adapter backing the NIC
+  * 'adapter-id': Adapter ID (PCHID) of the adapter backing the NIC
+
+* Examples: Added an example playbook 'get_cpc_io.yml' which retrieves
+  information about a CPC in DPM mode and its I/O configuration and
+  creates a markdown file showing the result.
+
 **Known issues:**
 
 * See `list of open issues`_.

playbooks/get_cpc_io.md.j2

@@ -0,0 +1,60 @@
+{#
+ # This Jinja2 template file generates a markdown file with the I/O config of a CPC.
+ #
+ # Input variables:
+ #   cpc_out: Object that is the output of the zhmc_cpc module with state=facts
+ #   adapters_out: List of objects that are the output of the
+ #     zhmc_adapter module with state=facts
+ #   partitions_out: List of objects that are the output of the
+ #     zhmc_partition module with state=facts
+ #}
+{% set cpc_obj = cpc_out.cpc %}
+{% set cpc_name = cpc_obj.name %}
+# I/O configuration of CPC {{ cpc_name }}
+
+## Basic CPC information
+
+| Name | Description          | Model    | Mode | IFLs | Mem [GiB] |
+|:---- |:-------------------- |:-------- |:---- |:---- |:--------- |
+{{ '| %-4s | %-20s | %-4s-%-3s | %-4s | %-4s | %-9s |'
+   | format(cpc_name, cpc_obj.description, cpc_obj['machine-type'], cpc_obj['machine-model'], cpc_obj['iml-mode'], cpc_obj['processor-count-ifl'], (cpc_obj['storage-customer']/1024)|int) }}
+
+## Adapters of the CPC
+
+| PCHID | Name                 | Description          | Card Type                  |
+|:----- |:-------------------- |:-------------------- |:-------------------------- |
+{% for ad_item in adapters_out.results|sort(attribute='adapter.adapter-id') %}
+{% set ad_obj = ad_item.adapter %}
+{{ '| %-5s | %-20s | %-20s | %-26s |'
+   | format(ad_obj['adapter-id'], ad_obj.name, ad_obj.description, ad_obj['detected-card-type']) }}
+{% endfor %}
+
+## Partitions of the CPC
+
+| Name                 | Description          | Network Adapters               | Storage Adapters               | Crypto Adapters                |
+|:-------------------- |:-------------------- |:------------------------------ |:------------------------------ |:------------------------------ |
+{% for part_item in partitions_out.results|sort(attribute='partition.name') %}
+{% set part_obj = part_item.partition %}
+{% set net_ad_list = [] %}
+{% for nic_obj in part_obj.nics %}
+{% set dummy = net_ad_list.append(nic_obj['adapter-id']) %}
+{% endfor %}
+{% set net_ad_list = net_ad_list|sort|unique %}
+{% set sto_ad_list = [] %}
+{% for sg_obj in part_obj['storage-groups'] %}
+{% for cap_item in sg_obj['candidate-adapter-ports'] %}
+{% set ad_obj = cap_item['parent-adapter'] %}
+{% set dummy = sto_ad_list.append(ad_obj['adapter-id']) %}
+{% endfor %}
+{% endfor %}
+{% set sto_ad_list = sto_ad_list|sort|unique %}
+{% set cryp_ad_list = [] %}
+{% if part_obj['crypto-configuration'] %}
+{% for cryp_ad_item in part_obj['crypto-configuration']['crypto-adapters'] %}
+{% set dummy = cryp_ad_list.append(cryp_ad_item['adapter-id']) %}
+{% endfor %}
+{% set cryp_ad_list = cryp_ad_list|sort|unique %}
+{% endif %}
+{{ '| %-20s | %-20s | %-30s | %-30s | %-30s |'
+   | format(part_obj.name, part_obj.description, net_ad_list|join(', '), sto_ad_list|join(', '), cryp_ad_list|join(', ')) }}
+{% endfor %}

playbooks/get_cpc_io.yml

@@ -0,0 +1,58 @@
+# Get the I/O configuration for a single CPC and create a markdown file from it.
+---
+- hosts: localhost
+  vars_files:
+    - vars.yml
+    - vault.yml
+  tasks:
+
+  - name: "Get facts for CPC {{ cpc_name }}"
+    zhmc_cpc:
+      hmc_host: "{{ hmc_host }}"
+      hmc_auth: "{{ hmc_auth }}"
+      name: "{{ cpc_name }}"
+      state: facts
+    register: cpc_out
+
+  #- debug:
+  #    var: cpc_out
+
+  - name: "Get facts for all adapters of CPC {{ cpc_name }}"
+    zhmc_adapter:
+      hmc_host: "{{ hmc_host }}"
+      hmc_auth: "{{ hmc_auth }}"
+      cpc_name: "{{ cpc_name }}"
+      name: "{{ ad.name }}"
+      state: facts
+    with_items: "{{ cpc_out.cpc.adapters|sort(attribute='name') }}"
+    loop_control:
+      loop_var: ad
+      label: "{{ ad.name }}"
+    register: adapters_out
+
+  #- debug:
+  #    var: adapters_out
+
+  - name: "Get facts for all partitions of CPC {{ cpc_name }}"
+    zhmc_partition:
+      hmc_host: "{{ hmc_host }}"
+      hmc_auth: "{{ hmc_auth }}"
+      cpc_name: "{{ cpc_name }}"
+      name: "{{ part.name }}"
+      state: facts
+      expand_storage_groups: true
+      expand_crypto_adapters: true
+    with_items: "{{ cpc_out.cpc.partitions|sort(attribute='name') }}"
+    loop_control:
+      loop_var: part
+      label: "{{ part.name }}"
+    register: partitions_out
+
+  #- debug:
+  #    var: partitions_out
+
+  - name: "Using Jinja2 template to create output file: playbooks/cpc_io_{{ cpc_name }}.md"
+    template:
+      src: get_cpc_io.md.j2
+      dest: "cpc_io_{{ cpc_name }}.md"
+      mode: '0755'

plugins/modules/zhmc_cpc.py

@@ -187,6 +187,24 @@
             object_uri:
               description: "Canonical URI of the adapter"
               type: str
+    storage-groups:
+      description: "Artificial property for the storage groups associated with
+        the CPC, with a subset of its properties."
+      type: dict
+      contains:
+        "{name}":
+          description: "Storage group name"
+          type: dict
+          contains:
+            name:
+              description: "Storage group name"
+              type: str
+            fulfillment-status:
+              description: "Fulfillment status of the storage group"
+              type: str
+            object_uri:
+              description: "Canonical URI of the storage group"
+              type: str
 """
 
 import logging  # noqa: E402
@@ -306,6 +324,34 @@ def process_properties(cpc, params):
     return update_props
 
 
+def add_artificial_properties(cpc):
+    """
+    Add artificial properties to the CPC object.
+
+    Upon return, the properties of the cpc object have been
+    extended by these artificial properties:
+
+    * 'partitions': List of partitions of the CPC, with the list subset of
+      their properties.
+
+    * 'adapters': List of adapters of the CPC, with the list subset of their
+      properties.
+
+    * 'storage-groups': List of storage groups attached to the partition, with
+      the list subset of their properties.
+    """
+    partitions = cpc.partitions.list()
+    cpc.properties['partitions'] = [p.properties for p in partitions]
+
+    adapters = cpc.adapters.list()
+    cpc.properties['adapters'] = [a.properties for a in adapters]
+
+    storage_groups = cpc.manager.console.storage_groups.list(
+        filter_args={'cpc-uri': cpc.uri})
+    cpc.properties['storage-groups'] = [sg.properties
+                                        for sg in storage_groups]
+
+
 def ensure_set(params, check_mode):
     """
     Identify the target CPC and ensure that the specified properties are set on
@@ -332,7 +378,6 @@ def ensure_set(params, check_mode):
         # The default exception handling is sufficient for the above.
 
         cpc.pull_full_properties()
-        result = cpc.properties
         update_props = process_properties(cpc, params)
         if update_props:
             if not check_mode:
@@ -342,15 +387,12 @@ def ensure_set(params, check_mode):
             # second retrieval).
             # Therefore, we construct the modified result based upon the input
             # changes, and not based upon newly retrieved properties.
-            result.update(update_props)
+            cpc.properties.update(update_props)
             changed = True
 
-        partitions = cpc.partitions.list()
-        adapters = cpc.adapters.list()
-
-        result['partitions'] = [p.properties for p in partitions]
-        result['adapters'] = [a.properties for a in adapters]
+        add_artificial_properties(cpc)
 
+        result = cpc.properties
         return changed, result
 
     finally:
@@ -379,14 +421,10 @@ def facts(params, check_mode):
         # The default exception handling is sufficient for the above.
 
         cpc.pull_full_properties()
-        result = cpc.properties
-
-        partitions = cpc.partitions.list()
-        adapters = cpc.adapters.list()
 
-        result['partitions'] = [p.properties for p in partitions]
-        result['adapters'] = [a.properties for a in adapters]
+        add_artificial_properties(cpc)
 
+        result = cpc.properties
         return False, result
 
     finally: