zhmc: Restructured sample playbooks

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