zhmc: Restructured sample playbooks

Details:

* Restructured the sample playbooks as follows:

  - Renamed them so that the resource they work on appears first in the file
    name, and then the action. This orders them in the directory listing in
    a more meaningful way.

  - Changed the variable that selects the inventory entry from 'host' to
    'hmc'.

  - Removed the 'cpc_name' variable from the vault file, since it is
    different for any HMC anyway, and it is easier to understand if it
    does not appear defined by magic. The CPC is now defined in each
    playbook with the 'cpc' variable and thus can be overridden from
    the command line with '-e cpc=mycpc'.

  - Simplified the variable names that specify resource names to remove
    '_name' for easier use with the '-e' option.

  - Added 'gather_facts: no' to the playbooks.

  - Added a zhmc log file 'zhmc.log' to the playbooks.

* Simplifications in the inventory and vault files:

  - Added the 'verify' variable to the example vault file.

  - Removed 'ansible_connection: local' from the example inventory file
    since it is not needed, when the tasks specify 'delegate_to: local'.

  - Improved the documentation in the example inventory  and vault files.

* Major improvements in the z_systems_administration/zhmc/README.md file
  that documents how to use the sample playbooks.

Signed-off-by: Andreas Maier <[email protected]>

z_systems_administration/zhmc/README.md

@@ -12,26 +12,41 @@ to clone this Git repository to your local system.
 The sample playbooks for the IBM Z HMC Collection are located in the
 directory ``z_systems_administration/zhmc/playbooks`` of the cloned repository.
 
-## Creating a vault file
+The sample playbooks make use of an inventory file and a vault file that are
+briefly described in the next sections.
 
-The sample playbooks use a vault file named ``vault.yml`` that defines
-HMC authentication data and other variables that are used in the sample playbooks.
+## Creating an inventory file
 
-In order to ensure that the vault file used by developers of this repository
-is not stored in the repository by mistake, the ``vault.yml`` file is excluded
-from Git, and the playbook directory contains an example copy of that file under
-the name:
+The sample playbooks of the IBM Z HMC Collection are designed to run with an
+Ansible inventory file that specifies the HMCs to run against.
 
-* ``vault_example.yml``
+The format of Ansible inventory files is described in the Ansible documentation
+in section
+[Inventory basics: formats, hosts, and groups](https://docs.ansible.com/ansible/latest/inventory_guide/intro_inventory.html#inventory-basics-formats-hosts-and-groups) and allows
+many flexibilities.
 
-To use the sample playbooks for the IBM Z HMC Collection, you need to copy that
-file to ``vault.yml`` and adjust the content of the copy as needed.
+The following data structure in the inventory file is sufficient for purposes
+of the sample playbooks:
 
-## Creating an inventory file
+```
+---
+default:  # A group nickname
 
-The sample playbooks are designed to run with a certain sample host group in
-order to show how running against multiple HMCs can be achieved. That requires
-using an inventory file that defines that host group.
+  hosts:
+
+    myhmc13:  # An HMC nickname (must match the nickname in the vault file)
+      ansible_host: 10.11.12.13
+
+    # ... more HMC entries for this group, as needed
+
+# ... more groups, as needed
+```
+
+The sample playbooks by default run against the HMCs defined in the group named
+``default``. They can run against any other group or single HMC by setting the
+``hmc`` variable to the nickname of the group or HMC. This can be done for
+example by using the ``-e hmc=nickname`` option of the ``ansible-playbook``
+command.
 
 In order to ensure that the inventory file used by developers of this repository
 is not stored in the repository by mistake, the ``inventory.yml`` file is excluded
@@ -41,24 +56,81 @@ the name:
 * ``inventory_example.yml``
 
 To use the sample playbooks for the IBM Z HMC Collection, you need to copy that
-file to ``inventory.yml`` and adjust the content of the copy as needed.
+example inventory file to e.g. ``inventory.yml`` and and adjust its content to
+your HMC environment.
+
+## Creating a vault file
+
+The sample playbooks of the IBM Z HMC Collection use a vault file named
+``vault.yml`` that defines credentials for the HMCs you want to use the sample
+playbooks with.
+
+From an Ansible perspective, the vault file is just a YAML file with arbitrary
+content that is included into the playbooks with the ``vars_files`` directive.
+
+The sample playbooks assume the following data structure in the vault file:
+
+```
+---
+hmc_auth:
+
+  myhmc13:  # An HMC nickname (must match the nickname in the inventory file)
+    userid: myuserid
+    password: mypassword
+    verify: false   # optional, only if you need to disable certificate validation
+
+  # ... more HMC entries, as needed
+```
+
+The vault file can store multiple entries for HMCs that are identified with a
+nickname. Each HMC entry specifies HMC userid and password to use. Optionally,
+validation of the server certificate can be disabled using ``verify: false``.
+
+In order to ensure that the vault file used by developers of this repository
+is not stored in the repository by mistake, the ``vault.yml`` file is excluded
+from Git, and the playbook directory contains an example vault file:
+
+* ``vault_example.yml``
+
+To use the sample playbooks for the IBM Z HMC Collection, you need to copy that
+example vault file to ``vault.yml`` and adjust its content to your HMC
+environment.
+
+You can encrypt the vault file using the ``ansible-vault`` command, and if you
+do, you either need to specify the ``--ask-vault-password`` option when
+running the playbooks using the ``ansible-playbook`` command, or use a vault
+password file (see Ansible documentation).
 
 ## Running the playbooks
 
-To run any of the sample playbooks, it is recommended to first look at them and
-to adjust any parameters as documented in the playbook files.
+To run any of the sample playbooks of the IBM Z HMC Collection, it is
+recommended to first look at them and to adjust any parameters as documented in
+the playbook files.
 
 You use the
 [ansible-playbook](https://docs.ansible.com/ansible/latest/cli/ansible-playbook.html)
-command to run playbooks.
-
-Since the sample playbooks are designed to run with a certain sample host group,
-the inventory file needs to be specified in the command, e.g.:
+command to run playbooks:
 
 ```
 $ ansible-playbook -i inventory.yml playbook.yml
 ```
 
+You can set variables or override variables defined in the playbook by using
+the ``-e name=value`` option. For example, the following command sets the ``hmc``
+variable to an HMC nickname ``myhmc42`` defined in the inventory file (and vault
+file) to run the playbook against that specific HMC:
+
+```
+$ ansible-playbook -i inventory.yml -e hmc=myhmc42 playbook.yml
+```
+
+If you have encrypted the vault file, you can have Ansible prompt for the
+vault password by using the ``--ask-vault-password`` option:
+
+```
+$ ansible-playbook -i inventory.yml --ask-vault-password playbook.yml
+```
+
 ## Sample playbooks
 
 The sample playbooks whose filename starts with ``module_`` are very simple
@@ -77,109 +149,17 @@ Ansible must be configured to run the HMC related tasks of the playbook on the
 control node (= local host), from where the zhmc modules then connect to the HMC
 based on their input parameters.
 
-There are multiple ways how this can be achieved in Ansible. The sample playbooks
-are designed to use delegation to localhost in the zhmc tasks. The key elements
-in that design are:
-
-* There is an inventory file that specifies a host group with the HMCs to target,
-  where each HMC has its IP addresses (or hostnames) defined and specifies that
-  the connection to that HMC is local, e.g.:
-
-  File ``inventory.yml``:
-
-  ```
-  my_hmc_list:    # name of the host group
-    hosts:
-      myhmc13:   # Ansible name for the HMC
-        ansible_host: 10.11.12.13    # IP address or hostname of the HMC
-        ansible_connection: local    # connection is local (for this host, on all playbook tasks)
-  ```
-
-* There is a vault file that specifies the authentication data for each HMC,
-  using the same Ansible names for the HMCs as defined in the inventory file,
-  e.g.:
-
-  File ``vault.yml``:
-
-  ```
-  hmc_auth:
-    myhmc13:   # Ansible name for the HMC
-      userid: myuserid
-      password: mypassword
-      verify: false
-  ```
-
-* The playbook references the host group defined in the inventory file,
-  loads the variables from the vault file, delegates each zhmc task to localhost,
-  and uses magic Ansible variables for obtaining the HMC IP address and
-  HMC authentication data, e.g.:
-
-  File ``module_facts_cpc.yml``:
-
-  ```
-  - hosts:
-      - my_hmc_list    # references the host group defined in the inventory file
-    vars_files:
-      - vault.yml    # loads the variables from the vault file
-    vars:
-      cpc_name: CPCA
-    collections:
-      - ibm.ibm_zhmc
-    tasks:
-      - name: "Get facts for CPC {{ cpc_name }}"
-        delegate_to: localhost    # delegates this task to run on localhost
-        zhmc_cpc:
-          hmc_host: "{{ ansible_host }}"    # uses Ansible magic variable for HMC IP address
-          hmc_auth: "{{ hmc_auth[inventory_hostname] }}"    # uses Ansible magic variable for HMC auth.data
-          name: "{{ cpc_name }}"
-          state: facts
-  ```
-
-The examples above show how the sample playbooks are designed. There are
-alternative ways to define the HMC hosts, the HMC authentication data, and
-to ensure that the Ansible tasks run locally on the control node.
-
-One alternative approach is not to use an Ansible inventory and to define
-only a single HMC to work with, and local connection for all tasks of the
-playbook:
-
-* The vault file specifies the IP address / hostname of the HMC and the
-  authentication data for the HMC, e.g.:
-
-  File ``alternative_vault.yml``:
-
-  ```
-  hmc_host: 10.11.12.13
-  hmc_auth:
-    userid: myuserid
-    password: mypassword
-    verify: false
-  ```
-
-* The playbook defines only localhost as a host, and defines the connection
-  to be local for the entire playbook. Non-zhmc tasks that need to run on
-  a specific other host can still do that by using the Ansible ``delegate_to``
-  attribute, but the host will be a single host and not defined by an inventory.
-
-  The playbook uses variables defined in the vault file for obtaining the HMC
-  IP address and HMC authentication data, e.g.:
-
-  File ``alternative_module_facts_cpc.yml``:
-
-  ```
-  - hosts: localhost    # runs all tasks on localhost
-    connection: local   # connection is local for all tasks
-    vars_files:
-      - alternative_vault.yml    # loads the variables from the vault file
-    vars:
-      cpc_name: CPCA
-    collections:
-      - ibm.ibm_zhmc
-    tasks:
-      - name: "Get facts for CPC {{ cpc_name }}"
-        zhmc_cpc:
-          hmc_host: "{{ hmc_host }}"    # uses variable from vault file
-          hmc_auth: "{{ hmc_auth }}"    # uses variable from vault file
-          name: "{{ cpc_name }}"
-          state: facts
-  ```
+The sample playbooks are designed to use delegation to localhost in the zhmc
+tasks, for example:
+
+```
+- . . .
+  tasks:
+    - name: "Get facts for CPC {{ cpc }}"
+      delegate_to: localhost                # <-- delegates this task to run on localhost
+      zhmc_cpc:
+        hmc_host: "{{ ansible_host }}"
+        hmc_auth: "{{ hmc_auth[inventory_hostname] }}"
+        name: "{{ cpc }}"
+        state: facts
+```

z_systems_administration/zhmc/playbooks/README.md

@@ -8,3 +8,6 @@ and implement a particular use case.
 
 * [single module playbooks](../docs/module_playbooks.md)
 * [use case playbooks](../docs/usecase_playbooks.md)
+
+For more documentation, see
+[Samples for the IBM Z HMC Collection](https://github.com/IBM/z_ansible_collections_samples/tree/main/z_systems_administration/zhmc).

z_systems_administration/zhmc/playbooks/inventory_example.yml

@@ -1,9 +1,13 @@
 ---
 # inventory.yml file for the sample playbooks of the IBM Z HMC Collection
 
-# The HMC inventory the sample playbooks will use:
-my_hmc_list:
+default:  # A group nickname
+
   hosts:
-    myhmc13:  # must match the key name in the vault file
+
+    myhmc13:  # An HMC nickname (must match the nickname in the vault file)
       ansible_host: 10.11.12.13
-      ansible_connection: local  # defaults connection=local for this host on all playbook tasks
+
+    # ... more HMC entries for this group, as needed
+
+# ... more groups, as needed

z_systems_administration/zhmc/playbooks/module_adapter_facts.yml

@@ -0,0 +1,35 @@
+---
+# Sample playbook for the zhmc_adapter module of the ibm.ibm_zhmc collection:
+#
+# Get facts for an adapter
+#
+# Command to run this playbook:
+# ansible-playbook -i inventory.yml -e hmc={myhmc} -e cpc={mycpc} -e adapter={myadapter} module_adapter_facts.yml
+
+- hosts:
+    - "{{ hmc | default('default') }}"  # HMC nickname from inventory entry
+  gather_facts: no
+  vars_files:
+    - vault.yml
+  vars:
+    cpc: MYCPC                          # Adjust or override with -e option
+    adapter: sample-hs-1                # Adjust or override with -e option
+    log_file: zhmc.log
+  collections:
+    - ibm.ibm_zhmc
+  tasks:
+
+    - name: "Get facts for adapter {{ adapter }} on CPC {{ cpc }}"
+      delegate_to: localhost
+      zhmc_adapter:
+        hmc_host: "{{ ansible_host }}"
+        hmc_auth: "{{ hmc_auth[inventory_hostname] }}"
+        cpc_name: "{{ hmc_auth[inventory_hostname] }}"
+        name: "{{ adapter }}"
+        state: facts
+        log_file: "{{ log_file | default(omit) }}"
+      register: result
+
+    - name: Print the result
+      ansible.builtin.debug:
+        var: result

z_systems_administration/zhmc/playbooks/module_adapter_rename.yml

@@ -0,0 +1,38 @@
+---
+# Sample playbook for the zhmc_adapter module of the ibm.ibm_zhmc collection:
+#
+# Rename an adapter
+#
+# Command to run this playbook:
+# ansible-playbook -i inventory.yml -e hmc={myhmc} -e cpc={mycpc} -e adapter_id={myid} -e new_adapter_name={mynewname} module_adapter_rename.yml
+
+- hosts:
+    - "{{ hmc | default('default') }}"  # HMC nickname from inventory entry
+  gather_facts: no
+  vars_files:
+    - vault.yml
+  vars:
+    cpc: MYCPC                          # Adjust or override with -e option
+    adapter_id: '7c3'                   # Adjust or override with -e option
+    new_adapter_name: sample-hs-1       # Adjust or override with -e option
+    log_file: zhmc.log
+  collections:
+    - ibm.ibm_zhmc
+  tasks:
+
+    - name: "Ensure adapter with PCHID {{ adapter_id }} has name {{ new_adapter_name }}"
+      delegate_to: localhost
+      zhmc_adapter:
+        hmc_host: "{{ ansible_host }}"
+        hmc_auth: "{{ hmc_auth[inventory_hostname] }}"
+        cpc_name: "{{ cpc }}"
+        name: "{{ new_adapter_name }}"
+        match:
+          adapter_id: "{{ adapter_id }}"
+        state: set
+        log_file: "{{ log_file | default(omit) }}"
+      register: result
+
+    - name: Print the result
+      ansible.builtin.debug:
+        var: result