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
```

Supported environments

The following versions of Python are supported:

Python 2.7
Python 3.5 and higher

The following operating systems are supported:

Linux
macOS (OS-X)
Windows

The following versions of Ansible are supported:

Ansible 2.9
Ansible 2.10
Ansible 3.0 (ansible-base 2.10)
Ansible 4.0 (ansible-core 2.11)
Ansible 5.0 (ansible-core 2.12)

The following Z and LinuxONE machine generations are supported:

z13 / z13s / Emperor / Rockhopper
z14 / Emperor II / Rockhopper II
z15 / LinuxONE III