The IBM Z core collection, referred to as ibm_zos_core, is part of the broader offering Red Hat® Ansible Certified Content for IBM Z. ibm_zos_core supports tasks such as creating data sets, submitting jobs, querying jobs, and retrieving job output.

Red Hat® Ansible Certified Content for IBM Z provides the ability to connect IBM Z® to clients' wider enterprise automation strategy through the Ansible Automation Platform ecosystem. This enables development and operations automation on Z through a seamless, unified workflow orchestration with configuration management, provisioning, and application deployment in one easy-to-use platform.

Collections, as part of the broader offering Red Hat® Ansible Certified Content for IBM Z, will initially be made available on Galaxy and later made available as certified content and accessible through Automation Hub.

The The IBM Z core collection includes connection plugins, action plugins, modules, sample playbooks, and ansible-doc to automate tasks on Z.

• normal: A fork of Ansible normal.py action plugin that is modified to allow a conditional shebang line in REXX modules.
• zos_job_submit: Used to submit a job from the controller and optionally monitor for job completion.

• zos_ssh: Enables the Ansible controller to communicate to a Z target machine by using ssh, with the added support to transfer ASCII as EBCDIC when transferring REXX modules. This connection plugin was forked from the Ansible ssh.py connection plugin.

• zos_data_set: Create, delete, and manage attributes for data sets.
• zos_job_query: Query Z for a list of jobs.
• zos_job_submit: Submit a job and optionally monitor for its completion.
• zos_job_output: Capture the job output for a submitted job.

Sample playbooks are included that demonstrate how to use the collection content in the ibm_zos_core collection.
See the playbooks README for detailed instructions and configuration information.

A control node is any machine with Ansible installed. From the control node, you can run commands and playbooks from a laptop, desktop, or server machine. However, you cannot run them on a Windows machine.

A managed node is often referred to as a target node, or host, and is the node that is managed by Ansible. Ansible does not need not need to be installed on a managed node, but SSH must be enabled.

The following nodes require specific versions of software:

• Ansible version: 2.9 or later
• Python: 2.7 or later
• OpenSSH

• Python: 3.6 or later
• z/OS: V02.02.00 or later
• IBM Z Open Automation Utilities: 1.0.1 (PTF UI66957 or later)
• OpenSSH

You have several options when you are ready to install the Red Hat Ansible Certified Content for IBM Z core collection that includes Ansible Galaxy, Ansible Hub, and local. For more information on installing collections, see Using collections.

You can use the ansible-galaxy command with the option install to install a collection on your system (control node) hosted in Galaxy.

Galaxy enables you to quickly configure your automation project with content from the Ansible community. Galaxy provides prepackaged units of work known as collections.

Here's an example command for installing the Red Hat Ansible Certified Content for IBM Z core collection:

ansible-galaxy collection install ibm.ibm_zos_core

The collection installation progress will be output to the console. Note the location of the installation so that you can review other content included with the collection, such as the sample playbook. By default, collections are installed in ~/.ansible/collections.

In this sample output of the collection installation, note the installation path to access the sample playbook:

Process install dependency map
Starting collection install process
Installing 'ibm.ibm_zos_core:0.0.4' to '/Users/user/.ansible/collections/ansible_collections/ibm/ibm_zos_core'

Installed collection content:

├── collections/
│  ├── ansible_collections/
│      ├── ibm/
│          ├── ibm_zos_core/
│              ├── docs/
│              ├── playbooks/
│              ├── plugins/
│                  ├── action/
│                  ├── connection/
│                  ├── module_utils/
│                  └── modules/

You can use the -p option with ansible-galaxy to specify the installation path such as ansible-galaxy collection install ibm.ibm_zos_core -p /home/ansible/collections. For more information on installing collections with Ansible Galaxy, see Installing collections.

Configuring access to a private Galaxy server follows the same instructions that you would use to configure your client to point to Automation Hub. When hosting a private Galaxy server or pointing to Hub, available content is not always consistent with what is available on the community Galaxy server.

You can use the ansible-galaxy command with option install to install a collection on your system (control node) hosted in Automation Hub or a private Galaxy server.

By default, the ansible-galaxy command uses https://galaxy.ansible.com as the Galaxy server when you install a collection. The ansible-galaxy client can be configured to point to HUB or other servers, such as a privately running Galaxy server, by configuring the server list in the ansible.cfg file.

Ansible searches for ansible.cfg in these locations in this order:

• ANSIBLE_CONFIG (environment variable if set)
• ansible.cfg (in the current directory)
• ~/.ansible.cfg (in the home directory)
• /etc/ansible/ansible.cfg

To configure a Galaxy server list in the ansible.cfg file:

1. Add the server_list option under the [galaxy] section to one or more server names.
2. Create a new section for each server name.
3. Set the url option for each server name.
4. Set the auth_url option for each server name.
5. Set the API token for each server name. For more information on API tokens, see Get API token from the version dropdown to copy your API token.

The following example shows a configuration for Hub, a private running Galaxy server, and Galaxy:

[galaxy]
server_list = automation_hub, release_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.release_galaxy]
url=https://galaxy.ansible.com/
token=release_token

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

For more configuration information, see Configuring the ansible-galaxy client and Ansible Configuration Settings.

You can use the ansible-galaxy collection install command to install a collection built from source. To build your own collection, you must clone the Git repository, build the collection archive, and install the collection. The ansible-galaxy collection build command packages the collection into an archive that can later be installed locally without having to use Hub or Galaxy.

To build your own collection:

1. Clone the sample repository:

git clone git@github.com:ansible-collections/ibm_zos_core.git

Collection archive names will change depending on the relase version. They adhere to this convention <namespace>-<collection>-<version>.tar.gz, for example, ibm-ibm_zos_core-0.0.4.tar.gz

2. Build the collection by running the ansible-galaxy collection build command, which must be run from inside the collection:

cd ibm_zos_core
ansible-galaxy collection build

Example output of a locally built collection:

user:[ ~/git/ibm/ibm_zos_core ]ansible-galaxy collection build
Created collection for ibm.ibm_zos_core at /Users/user/git/ibm/zos-ansible/ibm_zos_core/ibm-ibm_zos_core-0.0.4.tar.gz

Note: If you build the collection with Ansible version 2.9 or earlier, you will see the following warning that you can ignore. [WARNING]: Found unknown keys in collection galaxy.yml at '/Users/user/git/ibm/zos-ansible/ibm_zos_core/galaxy.yml': build_ignore

You can use the -p option with ansible-galaxy to specify the installation path, for example, ansible-galaxy collection install ibm-ibm_zos_core-0.0.4.tar.gz -p /home/ansible/collections. For more information, see Installing collections with Ansible Galaxy.

3. Install the locally built collection:

ansible-galaxy collection install ibm-ibm_zos_core-0.0.4.tar.gz

In the output of collection installation, note the installation path to access the sample playbook:

Process install dependency map
Starting collection install process
Installing 'ibm.ibm_zos_core:0.0.4' to '/Users/user/.ansible/collections/ansible_collections/ibm/ibm_zos_core'

After the collection is installed, you can access collection content for a playbook by referencing the name space ibm and collections fully qualified name ibm_zos_core, for example:

- hosts: all

  tasks:
  - name: Query submitted job 'HELLO'
    ibm.ibm_zos_core.zos_job_query:
      job_name: HELLO

In Ansible 2.9, the collections keyword was added and reduces the need to refer to the collection repeatedly. For example, you can use the collections keyword in your playbook:

- hosts: all
  collections:
   - ibm.ibm_zos_core

  tasks:
  - name: Query submitted job 'HELLO'
    zos_job_query:
       job_name: HELLO

Modules included in this collection provide additional documentation that is similar to a UNIX, or UNIX-like, operating system man page (manual page). This documentation can be accessed from the command line by using the ansible-doc command.

Here's how to use the Ansible-supplied command after you install the Red Hat Ansible Certified Content for IBM Z core collection: ansible-doc ibm.ibm_zos_core.zos_data_set

> ZOS_DATA_SET    (/Users/user/.ansible/collections/ansible_collections/ibm/ibm_zos_core/plugins/modules/zos_data_set.py)

        Create, delete and set attributes of data sets. When forcing data set replacement, contents will not be
        preserved.

  * This module is maintained by The Ansible Community
OPTIONS (= is mandatory):

- batch
        Batch can be used to perform operations on multiple data sets in a single module call.
        Each item in the list expects the same options as zos_data_set.
        [Default: (null)]
        type: list
        version_added: 2.9

- data_class
        The data class name (required for SMS-managed data sets)
        [Default: (null)]
        type: str
        version_added: 2.9

• Getting started Ansible guide.

Currently we are not accepting community contributions. Though, you may periodically review this content to learn when and how contributions can be made in the future.

© Copyright IBM Corporation 2020

Some portions of this collection are licensed under GNU General Public License, Version 3.0, and other portions of this collection are licensed under Apache License, Version 2.0. See individual files for applicable licenses.