powervm_inventory – HMC-based inventory source for Power Servers
Synopsis
This plugin utilizes HMC APIs to build a dynamic inventory of defined partitions (LPAR, VIOS) and Power Servers. Inventory sources must be structured as *.power_hmc.yml or *.power_hmc.yaml.
To create a usable Ansible host for a given LPAR or Power Server, the IP or hostname of the LPAR or Power Server must be exposed through the HMC in some way. Currently there are only two such sources supported by this plugin, either an RMC IP address(not valid for IBMi partition) or the name of the LPAR or Power Server must be also a valid hostname.
Valid LPAR/VIOS properties that can be used for groups, keyed groups, filters, unknown partition identification, and composite variables can be found in the HMC REST API documentation. By default, valid properties include those listed as “Quick Properties”, but if `advanced_fields` are enabled, you may be able to use more advanced properties of the partition. Further information about the LPAR APIs can be found in the Knowledge Center.
Valid Power Server properties that can be used for system_groups, system_keyed_groups, system_filters and system_composit variables can be found in HMC REST API documentation listed as ‘Quick Properties’. (These options works only when `group_lpars_by_managed_system` option set to false) Knowledge Center.
Apart from properties defined in HMC REST API Documentation we can use the following properties also with Power Server, and LPAR/VIOS ‘AssociatedGroups’ (Tagged group name), ‘AssociatedHMC’ (HMC IP/Hostname), ‘AssociatedHMCUserName’ (HMC username) for LPAR/VIOS or Power server grouping and compose.
If a property is used in the inventory source that is unique to a partition type, only partitions for which that property is defined may be included. Non-compatible partitions can be filtered out by `OperatingSystemVersion` or `PartitionType` as detailed in the second example.
A group named ‘MaagedSystems’ gets created with all the Power Server Managed by the HMC and Power Server grouping features enables only when `group_lpars_by_managed_system` option set to false in the dynamic inventory playbook.
Requirements
The below requirements are needed on the host that executes this module.
Python >= 3
Parameters
- hmc_hosts (True, list, None)
A List of hosts and their associated usernames and passwords.
- filters (optional, any, {})
A key value pair for filtering by various LPAR/VIOS attributes. Only results matching the filter will be included in the inventory.
- system_filters (optional, any, {})
A key value pair for filtering by various Power Server attributes. Results include only system_filter matching Power Servers and LPAR/VIOS belongs to it.
- compose (optional, dict, {})
Create vars from Jinja2 expressions(Valid only for LPAR or VIOS).
- system_compose (optional, dict, {})
Create vars from Jinja2 expressions(Valid only for Power Server).
- groups (optional, dict, {})
Add LPAR or VIOS hosts to group based on Jinja2 conditionals.
- system_groups (optional, dict, {})
Add Power Server hosts to group based on Jinja2 conditionals.
- keyed_groups (optional, list, None)
Add LPAR or VIOS hosts to group based on the values of a variable.
- system_keyed_groups (optional, list, None)
Add Power Server hosts to group based on the values of a variable.
- exclude_ip (optional, list, None)
A list of IP addresses to exclude from the inventory. This will be compared to the IP address specified in the HMC. Currently, no hostname lookup is performed, so only IP addresses that match the IP address specified in the HMC will be excluded. This is not valid for IBMi LPARs.
- exclude_lpar (optional, list, None)
A list of partitions (LPAR, VIOS) to exclude by partition name.
- exclude_system (optional, list, None)
A list of HMC managed Power Server and their partitions (LPAR, VIOS) will be excluded from the dynamic inventory. Works only with HMC Discovered Power Server name.
- ansible_display_name (optional, str, name)
By default, partitions/Power Servers name will be used as the name displayed by Ansible in output. If you wish this to display the IP address instead you may set this to “ip”.
- ansible_host_type (optional, str, ip)
Determines if the IP Address or the LPAR/Power Server name will be used as the “ansible_host” variable in playbooks.
- advanced_fields (optional, bool, False)
Allows for additional LPAR/VIOS properties to be used for the purposes of grouping and filtering.
Retrieving these properties could increase dynamic inventory generation run time, depending on the size of your environment and the properties to be fetched.
- group_lpars_by_managed_system (optional, bool, True)
Creates a grouping of partitions by managed system name. This is enabled by default.
This option should be set to false to enable Power Server grouping feature.
- identify_unknown_by (optional, str, omit)
Allows you to include partitions unable to be automatically detected as a valid Ansible target.
By default, Aix/Linux partitions without IP’s and IBMi partitions in not running state are omitted from the inventory. This is not be the case in the event you have name set for ansible_host_type. If not, omitted partitions will be added to a group called “unknown” and will can be identified by any LPAR property of your choosing (PartitionName or UUID are common identifiers).
If you do not omit unknown partitions, you may run into issues targeting groups that include them. To avoid this, you can specify a host pattern in a playbooks such as `targetgroup:!unknown`. This will your playbook to run against all known hosts in your target group.
This is not valid for Power Servers.
Examples
# The most minimal example, targeting only a single HMC
plugin: ibm.power_hmc.powervm_inventory
hmc_hosts:
- hmc: <hmc_host_name>
user: <HMC_Username>
password: <HMC_Password>
# Create an inventory consisting of only Virtual IO Servers.
# This may be important if grouping by advanced_fields exclusive to VIOS.
plugin: ibm.power_hmc.powervm_inventory
hmc_hosts:
- hmc: <hmc_host_name>
user: <HMC_Username>
password: <HMC_Password>
filters:
PartitionType: 'Virtual IO Server'
# Target multiple HMC hosts and only add running partitions to the inventory
plugin: ibm.power_hmc.powervm_inventory
hmc_hosts:
- hmc: <hmc_host_name>
user: <HMC1_Username>
password: <HMC1_Password>
- hmc: <hmc_host_name>
user: <HMC2_Username>
password: <HMC2_Password>
filters:
PartitionState: 'running'
# Generate an inventory of all running partitions and create a separate group for AIX 7.2 and IBMi type of partitions
plugin: ibm.power_hmc.powervm_inventory
hmc_hosts:
- hmc: <hmc_host_name>
user: <HMC1_Username>
password: <HMC1_Password>
- hmc: <hmc_host_name>
user: <HMC2_Username>
password: <HMC2_Password>
filters:
PartitionState: 'running'
groups:
AIX_72: "'7.2' in OperatingSystemVersion"
IBMi: "'IBM' in OperatingSystemVersion"
# Generate an inventory of running partitions and group them by PartitionType with a prefix of type_
# Groups will be created will resemble "type_Virtual_IO_Server", "type_AIX_Linux", "type_OS400", etc.
# Additionally, include the following variables as host_vars for a given target host: CurrentMemory, OperatingSystemVersion, PartitionName
plugin: ibm.power_hmc.powervm_inventory
hmc_hosts:
- hmc: <hmc_host_name>
user: <HMC1_Username>
password: <HMC1_Password>
- hmc: <hmc_host_name>
user: <HMC2_Username>
password: <HMC2_Password>
filters:
PartitionState: 'running'
keyed_groups:
- prefix: type
key: PartitionType
compose:
current_memory: CurrentMemory
os: OperatingSystemVersion
name: PartitionName
HMCIP: AssociatedHMC
HMCUSERNAME: AssociatedHMCUserName
## Generate an inventory that excludes partitions by ip, name, or the name of managed system on which they run
plugin: ibm.power_hmc.powervm_inventory
hmc_hosts:
- hmc: <hmc_host_name>
user: <HMC2_Username>
password: <HMC_Password>
exclude_ip:
- 10.0.0.44
- 10.0.0.46
exclude_lpar:
- aixlparnameX1
- aixlparnameX2
- vioslparnameX1
- vioslparnameX2
exclude_system:
- Frame1-XXX-WWWWWW
- Frame2-XXX-WWWWWW
# Generate an inventory of operating Power Servers and group them by SystemType with a prefix of type_
# Groups will be created will resemble "type_fsp", "type_ebmc", etc.
# Additionally, include the following variables as host_vars for a given target host: MaximumPartitions, SystemFirmware, SystemName
plugin: ibm.power_hmc.powervm_inventory
hmc_hosts:
- hmc: <hmc_host_name>
user: <HMC2_Username>
password: <HMC_Password>
group_lpars_by_managed_system: false
system_filters:
State: 'operating'
system_keyed_groups:
- prefix: type
key: SystemType
system_compose:
maximum_partitions: MaximumPartitions
system_firmware: SystemFirmware
HMCIP: AssociatedHMC
HMCUSERNAME: AssociatedHMCUserName
# Generate an inventory of all running partitions and operating Power Servers
# Create a seperate group for partitions tagged with associated group name 'production_lpars'
# Create a seperate group for Power Servers tagged with associated group name 'Production_systems'
plugin: ibm.power_hmc.powervm_inventory
hmc_hosts:
- hmc: <hmc_host_name>
user: <HMC2_Username>
password: <HMC_Password>
group_lpars_by_managed_system: false
system_filters:
State: 'operating'
groups:
ProductionLpars: "'production_lpars' in AssociatedGroups"
system_groups:
ProductionSystems: "'Production_systems' in AssociatedGroups"