Ansible for IBM Z

There are several options for installing Ansible for IBM Z collections, including Ansible Galaxy, Ansible Automation Hub, private Galaxy server, or from a Git repository.

This guide will discuss installing Ansible for IBM Z collections; for collection requirements, see Software Requirements.

Option 1: Install from Ansible Galaxy

Ansible Galaxy is the community repository where Ansible for IBM Z … (expand for more)

Ansible Galaxy is the community repository where Ansible for IBM Z collections are available, for more details on the various collections visit Ansible Galaxy.

Install a collection from Ansible Galaxy … (expand for more)

Install a collection from Ansible Galaxy, here you can find the installation command for installing a specific collection.

  1. Using the ansible-galaxy command, the general command form below will install the latest version of a collection.

    ansible-galaxy collection install <namespace>.<collection name>

    The namespace for Ansible for IBM Z collections is ibm. The following are the available collection names you can select from:

    • ibm_zos_core

    • ibm_zos_ims

    • ibm_zos_cics

    • ibm_zhmc

    • ibm_zos_sysauto

    • ibm_zosmf

  2. Verify the location of the collection by running the following command. You’ll see the name, version, and location of the installed collection.

    ansible-galaxy collection list

    Note

    Some collections Ansible for IBM Z collections are dependent on other collections, such as the case for IBM z/OS IMS collection which has a dependency on the IBM z/OS Core collection. The collections dependencies will be automatically installed, even if you don’t selectively install them.

    If you have multiple collections to install, you can enter the collection names into a requirements.yml file and install them with ansible-galaxy collection install -r requirements.yml.

    The requirements.yml is a YAML file with the format:

    collections:
   - name: <namespace>.<collection name>
Install a specific collection version from Ansible Galaxy … (expand for more)

Install a specific collection version from Ansible Galaxy. For example, you can use the following command to install version 1.0.0 for the IBM z/OS Core collection:

ansible-galaxy collection install ibm.ibm_zos_core:1.0.0

A beta version is only available on Ansible Galaxy and is only supported by the community, once it is General Availability (GA), it will be promoted to Ansible Automation Platform and eligible for entitlement from Red Hat and IBM. When installing a beta from Galaxy, you must precisely indicate the beta version, for example to install a beta of the IBM z/OS Core collection, run the following command:

ansible-galaxy collection install ibm.ibm_zos_core:1.10.0-beta.1

For more information about installing Ansible collections, see Installing collections (Ansible Documentation).

Option 2: Install from Ansible Automation Hub

Configuring access to a Ansible Automation Platform … (expand for more)

Configuring access to a Ansible Automation Platform is the same as that of connecting a client to a private Galaxy server. You can use the ansible-galaxy collection install command to install a collection on the control node hosted in Ansible Automation Platform or a private Galaxy server.

By default, the ansible-galaxy command uses the Galaxy server … (expand for more)

By default, the ansible-galaxy command uses the Galaxy server (https://galaxy.ansible.com) to install collections, but you can configure the ansible-galaxy collection command to use other servers by editing the configuration file, ansible.cfg.

For more information, see Configuring the ansible-galaxy client (Ansible Documentation).

To configure:

  • Set the auth_url option for each server name.

  • Set the API token for each server name. To obtain an API token from Automation Hub, select the Offline token from Connect to Hub.

The automation hub API token authenticates your ansible-galaxy client to the Red Hat automation hub server. To learn more about configuration, see Creating the API token in automation hub.

The following example shows an ansible.cfg configuration for Ansible Automation Platform, a private Galaxy server, and Ansible Galaxy. The search order is managed with the server_list option contained in the configuration. The configuration will be accessed in this ordering:

  • ANSIBLE_CONFIG (environment variable if set)

  • ansible.cfg (in the current directory)

  • ~/.ansible.cfg (in the home directory)

  • /etc/ansible/ansible.cfg

[galaxy]
server_list = automation_hub, galaxy, private_galaxy

[galaxy_server.automation_hub]
url=https://cloud.redhat.com/api/automation-hub/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token=<hub_token>

[galaxy_server.galaxy]
url=https://galaxy.ansible.com/

[galaxy_server.private_galaxy]
url=https://galaxy-dev.ansible.com/
token=<private_token>

To learn more about configuration, see Ansible Configuration Settings (Ansible Documentation).

Install a specific collection version from Ansible Automation Hub … (expand for more)

After having configured access to Ansible Automation Platform, you can install a specific collection version from Ansible Automation Hub. For example, you can use the following command to install version 1.0.0 for the IBM z/OS Core collection:

ansible-galaxy collection install ibm.ibm_zos_core:1.0.0

For more information on installing and browsing collections, see Installing collections (Ansible Documentation) and certified collections.

Note

A beta version of a collection is only available on Ansible Galaxy, you will

not find any beta versions on Ansible Automation Hub.

Option 3: Install from a Git repository

Install a collection from a Git repository using the URI … (expand for more)

Install a collection from a Git repository using the URI of the repository and the ansible-galaxy collection install command. You can also specify a branch, commit, or tag using the comma-separated git commit-ish syntax.

To build and install a collection from a Git repository, for example, the IBM z/OS Core collection, use the below commands.

  1. Install a specific GitHub release (v1.12.0):

    ansible-galaxy collection install -f git@github.com:ansible-collections/ibm_zos_core.git,v1.12.0

  2. Install the collection from the dev branch:

    ansible-galaxy collection install git@github.com:ansible-collections/ibm_zos_core.git,dev

  3. Install from the dev branch using SSH authentication by including the prefix git+:

    ansible-galaxy collection install git+https://github.com/ansible-collections/ibm_zos_core.git,dev

For more information, see Installing a collection from a git repository (Ansible Documentation).