Installation

The system Ansible is installed on is called the “control system”. This is where Ansible commands (such as ansible-playbook) are invoked.

Ansible is written in Python but invokes Ansible modules always as executables, even when they are also written in Python. Therefore, Ansible modules implemented in Python are run as Python scripts and are not imported as Python modules.

The standard installation is that Ansible is installed as an operating system package and uses the existing system Python. The Ansible modules then also use the system Python.

As an alternative to the standard installation, it is possible to use a virtual Python environment for Ansible itself and for Ansible modules written in Python. Using a virtual Python environment has the main advantages that it minimizes the risk of incompatibilities between Python packages because the virtual environment contains only the packages that are needed for the specific use case, and that it does not pollute your system Python installation with other Python packages, keeping the risk of incompatibilities away from your system Python.

The following sections describe these two installation methods.

Standard installation with system Python

All commands shown are to be executed in a terminal or command prompt on the control system. The instructions are written for a bash shell.

Install Ansible as an operating system package on the control system.

For details, see Installing Ansible on specific operating systems.
Install the IBM Z HMC collection from Ansible Galaxy:
```
$ ansible-galaxy collection install ibm.ibm_zhmc
```
This will install the collection to your local Ansible collections tree, which is by default $HOME/.ansible/collections/ansible_collections. It does not install any dependent Python packages.
Install the dependent Python packages into your system Python:

Double check where the ibm.ibm_zhmc collection got installed:
```
$ ansible-galaxy collection list ibm.ibm_zhmc
# /Users/johndoe/.ansible/collections/ansible_collections
Collection   Version
------------ -------
ibm.ibm_zhmc 1.0.0
```
Set a variable to the installation directory shown in the command output:
```
$ anco_dir=/Users/johndoe/.ansible/collections/ansible_collections
```
Using the requirements.txt file in the installation directory of the ibm.ibm_zhmc collection, install dependent Python packages into your system Python:
```
$ sudo pip install -r $anco_dir/ibm/ibm_zhmc/requirements.txt
```

Alternative installation with virtual Python environment

This section describes the installation of Ansible and the ibm.ibm_zhmc Ansible Galaxy collection into a virtual Python environment that is set up using virtualenv.

This installation method utilizes the ability of Ansible to configure the Python environment it uses, and configures it to use the active Python (which can be a virtual Python environment or the system Python).

All commands shown are to be executed in a terminal or command prompt on the control system. The instructions are written for a bash shell.

Create a virtual Python environment and activate it:
```
$ mkvirtualenv myenv
```
Note: Using the command shown requires the virtualenvwrapper package.

For details, see virtualenv.
Install Ansible as a Python package on the control system:
```
$ pip install ansible
```
This will install Ansible into the active Python, i.e. into the virtual Python environment. Note that an OS-level Ansible and a Python-level Ansible have shared configuration files, e.g. in /etc/ansible.
Create a shell script that invokes the active Python.

Adjust the file name and path for the shell script in the python_script variable as needed, the only requirement is that the shell script must be found in the PATH:
```
$ python_script=$HOME/local/bin/env_python

$ cat >$python_script \<\<'EOT'
#!/bin/bash
py=$(which python)
$py "$@"
EOT

$ chmod 755 $python_script
```

Configure Ansible to invoke Python via the new shell script (using the python_script variable from the previous step):

$ sudo tee -a /etc/ansible/hosts >/dev/null \<\<EOT
[local:vars]
ansible_python_interpreter=$python_script
EOT

Install the IBM Z HMC collection from Ansible Galaxy:
```
$ ansible-galaxy collection install ibm.ibm_zhmc
```
This will install the collection to your local Ansible collections tree, which is by default $HOME/.ansible/collections/ansible_collections. It does not install any dependent Python packages.
Install the dependent Python packages into the active Python:

Double check where the ibm.ibm_zhmc collection got installed:
```
$ ansible-galaxy collection list ibm.ibm_zhmc
# /Users/johndoe/.ansible/collections/ansible_collections
Collection   Version
------------ -------
ibm.ibm_zhmc 1.0.0
```
Set a variable to the installation directory shown in the command output:
```
$ anco_dir=/Users/johndoe/.ansible/collections/ansible_collections
```
Using the requirements.txt file in the installation directory of the ibm.ibm_zhmc collection, install dependent Python packages into your active Python:
```
$ pip install -r $anco_dir/ibm/ibm_zhmc/requirements.txt
```

Setting up the HMC

Usage of this collection requires that the HMC in question is prepared accordingly:

The Web Services API must be enabled on the HMC.

You can do that in the HMC GUI by selecting “HMC Management” in the left pane, then opening the “Configure API Settings” icon on the pain pane, then selecting the “Web Services” tab on the page that comes up, and finally enabling the Web Services API on that page.

The above is on a z16 HMC, it may be different on older HMCs.

If you cannot find this icon, then your userid does not have permission for the respective task on the HMC. In that case, there should be some other HMC admin you can go to to get the Web Services API enabled.

HMC userid requirements

The HMC userid used for running the modules of this collection must have the following task permissions:

Use of the Web Services API

The HMC userid used for running the modules of this collection must in addition have the permissions documented in the description of each module (see Modules). These descriptions document the complete set of permissions needed for all operations of the module.

Setting up firewalls or proxies

If you have to configure firewalls or proxies between the system where you run the zhmc_prometheus_exporter command and the HMC, the following ports need to be opened:

6794 (TCP) - for the HMC API HTTP server
61612 (TCP) - for the HMC API message broker via JMS over STOMP

For details, see sections “Connecting to the API HTTP server” and “Connecting to the API message broker” in the HMC API book.

Supported environments

The following Z and LinuxONE machine generations are supported:

z196 / z114
zEC12 / zBC12
z13 / z13s / Emperor / Rockhopper
z14 / Emperor II / Rockhopper II
z15 / LinuxONE III
z16 / LinuxONE 4

The following environments are supported for running the Ansible modules of the ibm.ibm_zhmc collection.

Operating systems:

Linux
macOS (OS-X)
Windows

Python versions:

Python 2.7 to Python 3.8 are supported on a best-can-do basis
Python 3.9 and higher are officially supported (depends on the Ansible version used)

Ansible versions:

Ansible 2.9 to 6 (ansible-core 2.13) are supported on a best-can-do basis
Ansible 7 (ansible-core 2.14) and higher are officially supported

See Ansible-core Support Matrix for the officially supported Ansible / ansible-core versions and their Python versions.

See Red Hat Ansible Automation Platform Life Cycle for the officially supported Ansible Automation Platform versions and their ansible-core versions.

The general strategy for the ibm.ibm_zhmc collection is that all Python versions supported by the sanity test tool of a particular Ansible version are supported, as shown in the following tables:

Ansible	Ansible core	Supported Python versions	Support
2.9	ansible 2.9	2.7, 3.5 - 3.8	best-can-do
2.10	ansible 2.10	2.7, 3.5 - 3.8	best-can-do
3	ansible-base 2.10	2.7, 3.5 - 3.8	best-can-do
4	ansible-core 2.11	2.7, 3.5 - 3.9	best-can-do
5	ansible-core 2.12	3.8 - 3.10	best-can-do
6	ansible-core 2.13	3.8 - 3.10	best-can-do
7	ansible-core 2.14	3.9 - 3.11	official
8	ansible-core 2.15	3.9 - 3.11	official
9	ansible-core 2.16	3.10 - 3.12	official

Python	Supported Ansible versions
2.7	2.9 - 2.10, 3 - 4
3.5	2.9 - 2.10, 3 - 4
3.6	2.9 - 2.10, 3 - 4
3.7	2.9 - 2.10, 3 - 4
3.8	2.9 - 2.10, 3 - 6
3.9	4 - 8
3.10	5 - 9
3.11	7 - 9
3.12	9 and higher