README.md

IBM® Z HMC collection

The IBM Z HMC collection enables automation with the IBM Z Hardware Management Console (HMC) to manage platform resources on IBM Z and IBM LinuxONE machines.

Description

The IBM Z HMC collection is part of the Red Hat® Ansible Certified Content for IBM Z® offering that brings Ansible automation to IBM Z®.

This collection supports automation tasks on the IBM Z HMC such as creating, updating or deleting partitions, accesssing operating system messages, configuring adapters, managing HMC users, upgrading the SE and HMC firmware, and many more. It supports CPCs in classic mode and in DPM mode.

The IBM Z HMC collection uses the Web Services API of the HMC and therefore its modules run on the Ansible control node (there is no separate Ansible managed node in this case).

For guides and reference, please review the documentation or the Z HMC section in the unified documentation.

Requirements

Before you install the IBM Z HMC collection, you must have a minimum Python version and Ansible version on the Ansible control node. The documentation section Support matrix details the specific version requirements.

Installation

Before using this collection, you need to install it with the Ansible Galaxy command-line tool:

ansible-galaxy collection install ibm.ibm_zhmc

You can also include it in a requirements.yml file and install it with ansible-galaxy collection install -r requirements.yml, using the format:

collections:
  - name: ibm.ibm_zhmc

The installation of the collection will not cause any required Python packages to be installed. They need to be installed separately, either as OS-level packages or as Python packages, depending on how you manage the Python packages on your system. A requirements.txt file is provided in the installation directory of the ibm.ibm_zhmc collection for that purpose, either for direct use with pip install -r requirements.txt, or for manually checking and installing the corresponding OS-level packages.

Note that if you install the collection from Ansible Galaxy, it will not be upgraded automatically when you upgrade the Ansible (OS-level or Python) package.

To upgrade the collection to the latest available version, run the following command:

ansible-galaxy collection install ibm.ibm_zhmc --upgrade

You can also install a specific version of the collection, for example, if you need to downgrade for some reason. For example, the following command installs version 1.0.0:

ansible-galaxy collection install ibm.ibm_zhmc:1.0.0

Use Cases

• Use Case Name: Create partition (DPM mode)

  • Actors:
    • System Programmer
  • Description:
    • The system programmer can automate the creation of a partition on a Z system (that is in DPM mode).
  • Flow:
    • If the partition does not exist, create it.
    • Update properties of the partition, including boot mode.
    • Bring the partition into the specified status (active, stopped).

• Use Case Name: Adjust workload related LPAR properties (classic mode)

  • Actors:
    • System Programmer
  • Description:
    • The system programmer can automate the adjustment of workload related LPAR properties in order to optimize the performance of applications running in the LPAR.
  • Flow:
    • Verify LPAR exists on the HMC
    • Update the specified LPAR properties.

• Use Case Name: Update password of HMC user

  • Actors:
    • System Programmer
  • Description:
    • The system programmer can automate the password update for their userid on the HMC.
  • Flow:
    • Verify user exists on the HMC
    • Update password of the user

Testing

All releases will meet the following test criteria:

• 100% success for Unit tests.
• 100% success for Function tests.
• 100% success for End2end tests.
• 100% success for Ansible sanity tests as part of ansible-test.
• 100% success for flake8.
• 100% success for pylint.
• 100% success for ansible-lint allowing only false positives.
• 100% success for safety vulnerability checks.
• 100% success for bandit vulnerability checks.
• 100% success for pip-missing-reqs checks for missing dependencies.

For more details on testing the IBM Z HMC collection, including the specific version combinations that were tested, refer to documentation section Testing.

Contributing

This community is not currently accepting contributions. However, we encourage you to open git issues for bugs, comments or feature requests and check back periodically for when community contributions will be accepted in the near future.

Review the development docs to learn how you can create an environment and test the collections modules.

Communication

If you would like to communicate with this community, you can do so through the following options:

• GitHub IBM Z HMC issues.
• Discord ansible in System Z Enthusiasts
  • Invitation link for server System Z Enthusiasts
  • Invitation link for channel ansible

Support

As Red Hat Ansible Certified Content, this collection is entitled to support through Ansible Automation Platform (AAP). After creating a Red Hat support case, if it is determined the issue belongs to IBM, Red Hat will instruct you to create an IBM support case and share the case number with Red Hat so that a collaboration can begin between Red Hat and IBM.

If a support case cannot be opened with Red Hat and the collection has been obtained either from Galaxy or its GitHub repo, there is community support available at no charge. Community support is limited to the collection; community support does not include any of the Ansible Automation Platform components or Ansible.

The current supported versions of this collection can be found listed in the following section.

Release Notes and Roadmap

The collection's cumulative release notes can be reviewed here. Note, some collection versions release before an ansible-core version reaches End of Life (EOL), thus the version of ansible-core that is supported must be a version that is currently supported.

For AAP users, to see the supported ansible-core versions, review the AAP Life Cycle.

For Galaxy and GitHub users, to see the supported ansible-core versions, review the ansible-core support matrix.

The collection's changelogs can be reviewed in the following table:

Version	Status	Release notes & change log
1.10.0	In development	unreleased
1.9.0	Released	Release notes & change log
1.8.3	Released	Release notes & change log
1.7.4	Released	Release notes & change log
1.6.1	Released	Release notes & change log
1.5.0	Released	Release notes & change log
1.4.1	Released	Release notes & change log
1.3.1	Released	Release notes & change log
1.2.1	Released	Release notes & change log
1.1.1	Released	Release notes & change log
1.0.3	Released	Release notes & change log

Related Information

Example playbooks and use cases can be be found in the IBM Z HMC sample playbooks repo.

Supplemental content on getting started with Ansible, architecture and use cases is available here.

License Information

This collection is licensed under Apache License, Version 2.0.