Package: zhmc-ansible-modules
zhmc-ansible-modules - Ansible modules for the IBM Z HMC Web Services APIMoving to Ansible GalaxyStarting with version 0.9.0, the zhmc Ansible modules are no longer distributed
as thezhmc-ansible-modules package on Pypi,
but as theibm.ibm_zhmc collection on Galaxy.OverviewThe zhmc-ansible-modules Python package containsAnsiblemodules that can
manage platform resources onIBM ZandLinuxONEmachines that are in
the Dynamic Partition Manager (DPM) operational mode.The goal of this package is to be able to utilize the power and ease of use
of Ansible for the management of IBM Z platform resources.The IBM Z resources that can be managed include Partitions, HBAs, NICs, and
Virtual Functions.The Ansible modules in the zhmc-ansible-modules package are fullyidempotent,
following an important principle for Ansible modules.The idempotency of a module allows Ansible playbooks to specify the desired end
state for a resource, regardless of what the current state is. For example, a
IBM Z partition can be specified to havestate=activewhich means that
it must exist and be in the active operational status. Depending on the current
state of the partition, actions will be taken by the module to reach this
desired end state: If the partition does not exist, it will be created and
started. If it exists but is not active, it will be started. If it is already
active, nothing will be done. Other initial states including transitional
states such as starting or stopping also will be taken care of.The idempotency of modules makes Ansible playbooks restartable: If an error
happens and some things have been changed already, the playbook can simply be
re-run and will automatically do the right thing, because the initial state
does not matter for reaching the desired end state.The Ansible modules in the zhmc-ansible-modules package are written in Python
and interact with the Web Services API of the Hardware Management Console (HMC)
of the machines to be managed, by using the API of thezhmcclientPython
package.DocumentationThis version of the project has its documentation on RTD:http://zhmc-ansible-modules.readthedocs.io/en/stable/Starting with version 0.9.0, the documentation is available on GitHub Pages:https://zhmcclient.github.io/zhmc-ansible-modules/Playbook examplesHere are some examples for using the Ansible modules in this project:Create a stopped partitionThis task ensures that a partition with this name exists, is in the stopped
status and has certain property values.----hosts:localhosttasks:-name:Ensure a partition exists and is stoppedzhmc_partition:hmc_host:"10.11.12.13"hmc_auth:"{{hmc_auth}}"cpc_name:P000S67Bname:"mypartition1"state:stoppedproperties:description:"zhmcAnsiblemodules:partition1"ifl_processors:2initial_memory:1024maximum_memory:1024minimum_ifl_processing_weight:50maximum_ifl_processing_weight:800initial_ifl_processing_weight:200...# all partition properties are supportedStart a partitionIf this task is run after the previous one shown above, no properties need to
be specified. If it is possible that the partition first needs to be created,
then properties would be specified, as above.----hosts:localhosttasks:-name:Ensure a partition exists and is activezhmc_partition:hmc_host:"10.11.12.13"hmc_auth:"{{hmc_auth}}"cpc_name:P000S67Bname:"mypartition1"state:activeproperties:...# see aboveDelete a partitionThis task ensures that a partition with this name does not exist. If it
currently exists, it is stopped (if needed) and deleted.----hosts:localhosttasks:-name:Ensure a partition does not existzhmc_partition:hmc_host:"10.11.12.13"hmc_auth:"{{hmc_auth}}"cpc_name:P000S67Bname:"mypartition1"state:absentCreate an HBA in a partition----hosts:localhosttasks:-name:Ensure HBA exists in the partitionzhmc_hba:hmc_host:"10.11.12.13"hmc_auth:"{{hmc_auth}}"cpc_name:P000S67Bpartition_name:"mypartition1"name:"hba1"state:presentproperties:adapter_name:"fcp1"adapter_port:0description:The HBA to our storagedevice_number:"023F"...# all HBA properties are supportedCreate a NIC in a partition----hosts:localhosttasks:-name:Ensure NIC exists in the partitionzhmc_nic:hmc_host:"10.11.12.13"hmc_auth:"{{hmc_auth}}"cpc_name:P000S67Bpartition_name:"mypartition1"name:"nic1"state:presentproperties:adapter_name:"osa1"adapter_port:1description:The NIC to our data networkdevice_number:"013F"...# all NIC properties are supportedCreate a Virtual Function in a partition----hosts:localhosttasks:-name:Ensure virtual function for zEDC adapter exists in the partitionzhmc_virtual_function:hmc_host:"10.11.12.13"hmc_auth:"{{hmc_auth}}"cpc_name:P000S67Bpartition_name:"mypartition1"name:"vf1"state:presentproperties:adapter_name:"zedc1"description:The virtual function for our accelerator adapterdevice_number:"043F"...# all VF properties are supportedConfigure partition for booting from FCP LUN----hosts:localhosttasks:-name:Configure partition for booting via HBAzhmc_partition:hmc_host:"10.11.12.13"hmc_auth:"{{hmc_auth}}"cpc_name:P000S67Bname:"mypartition1"state:stoppedproperties:boot_device:storage-adapterboot_storage_hba_name:"hba1"boot_logical_unit_number:"0001"boot_world_wide_port_name:"00cdef01abcdef01"Configure crypto config of a partition----hosts:localhosttasks:-name:Ensure crypto config for partitionzhmc_partition:hmc_host:"10.11.12.13"hmc_auth:"{{hmc_auth}}"cpc_name:P000S67Bname:"mypartition1"state:stoppedproperties:crypto_configuration:crypto_adapter_names:-"crypto1"crypto_domain_configurations:-domain_index:17access_mode:"control-usage"-domain_index:19access_mode:"control"QuickstartFor installation instructions, seeInstallation of zhmc-ansible-modules package.After having installed the zhmc-ansible-modules package, you can download and
run the example playbooks infolder ‘playbooks’ of the Git repository:create_partition.ymlcreates a partition with a NIC, HBA and virtual
function to an accelerator adapter.delete_partition.ymldeletes a partition.vars_example.ymlis an example variable file defining variables such as
CPC name, partition name, etc.vault_example.ymlis an example password vault file defining variables
for authenticating with the HMC.Before you run a playbook, copyvars_example.ymltovars.ymlandvault_example.ymltovault.ymland change the variables in those files
as needed.Then, run the example playbooks:$ ansible-playbook create_partition.yml

PLAY [localhost] **********************************************************

TASK [Gathering Facts] ****************************************************
ok: [127.0.0.1]

TASK [Ensure partition exists and is stopped] *****************************
changed: [127.0.0.1]

TASK [Ensure HBA exists in the partition] *********************************
changed: [127.0.0.1]

TASK [Ensure NIC exists in the partition] *********************************
changed: [127.0.0.1]

TASK [Ensure virtual function exists in the partition] ********************
changed: [127.0.0.1]

TASK [Configure partition for booting via HBA] ****************************
changed: [127.0.0.1]

PLAY RECAP ****************************************************************
127.0.0.1                  : ok=6    changed=5    unreachable=0    failed=0

$ ansible-playbook delete_partition.yml

PLAY [localhost] **********************************************************

TASK [Gathering Facts] ****************************************************
ok: [127.0.0.1]

TASK [Ensure partition does not exist] ************************************
changed: [127.0.0.1]

PLAY RECAP ****************************************************************
127.0.0.1                  : ok=2    changed=1    unreachable=0    failed=0