The IBM z/OS core collection enables Ansible to interact with z/OS Data Sets and USS files. The collection focuses on operating system fundamental operations such as managing encodings, creating data sets, and submitting jobs.
The IBM z/OS core collection is part of the Red Hat® Ansible Certified Content for IBM Z® offering that brings Ansible automation to IBM Z®. This collection brings forward the possibility to manage batch jobs, perform program authorizations, run operator operations, and execute both JES and MVS commands as well as execute shell, python, and REXX scripts. It supports data set creation, searching, copying, fetching, and encoding. It provides both archiving and unarchiving of data sets, initializing volumes, performing backups and supports Jinja templating.
System programmers can enable pipelines to setup, tear down and deploy applications while system administrators can automate time consuming repetitive tasks inevitably freeing up their time. New z/OS users can find comfort in Ansible's familiarity and expedite their proficiency in record time.
Before you install the IBM z/OS core collection, you must configure the control node and z/OS managed node with a minimum set of requirements. The following table details the specific software requirements for the controller and managed node.
Before using this collection, you need to install it with the Ansible Galaxy command-line tool:
ansible-galaxy collection install ibm.ibm_zos_core
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_zos_core
Note that if you install the collection from Ansible Galaxy, it will not be upgraded automatically when you upgrade the Ansible package.
To upgrade the collection to the latest available version, run the following command:
ansible-galaxy collection install ibm.ibm_zos_core --upgrade
You can also install a specific version of the collection, for example, if you need to install a different version. Use the following syntax to install version 1.0.0:
ansible-galaxy collection install ibm.ibm_zos_core:1.0.0
You can also install a beta version of the collection. A beta version is only available on Galaxy and is only supported by the community until it is promoted to General Availability (GA). Use the following syntax to install a beta version:
ansible-galaxy collection install ibm.ibm_zos_core:1.10.0-beta.1
As part of the installation, the collection requirements must be made available to Ansible through the use of environment variables. The preferred configuration is to place the environment variables in group_vars and host_vars, you can find examples of this configuration under any playbook project, for example, review the data set example configuration documentation.
If you are testing a configuration, it can be helpful to set the environment variables in a playbook, an example of that can be reviewed here.
To learn more about the ZOAU Python wheel installation method, review the documentation.
If the wheel is installed using the --target option, it will install the package into the specified target directory. The environment variable PYTHONPATH will have to be configured to where the packages is installed, e.g; PYTHONPATH: /usr/zoau/wheels. Using --target is recommended, else the wheel will be installed in Python's home directory which may not have write permissions or persist
after an update.
If the wheel is installed using the --user option, it will install the package into the user directory. The environment variable PYTHONPATH will have to be configured to where the packages is installed, e.g; PYTHONPATH: /u/user.
Environment variables:
PYZ: "path_to_python_installation_on_zos_target"
ZOAU: "path_to_zoau_installation_on_zos_target"
ZOAU_PYTHON_LIBRARY_PATH: "path_to_zoau_wheel_installation_directory"
ansible_python_interpreter: "{{ PYZ }}/bin/python3"
environment_vars:
_BPXK_AUTOCVT: "ON"
ZOAU_HOME: "{{ ZOAU }}"
PYTHONPATH: "{{ ZOAU_PYTHONPATH }}"
LIBPATH: "{{ ZOAU }}/lib:{{ PYZ }}/lib:/lib:/usr/lib:."
PATH: "{{ ZOAU }}/bin:{{ PYZ }}/bin:/bin:/var/bin"
_CEE_RUNOPTS: "FILETAG(AUTOCVT,AUTOTAG) POSIX(ON)"
_TAG_REDIR_ERR: "txt"
_TAG_REDIR_IN: "txt"
_TAG_REDIR_OUT: "txt"
LANG: "C"
PYTHONSTDINENCODING: "cp1047"- Use Case Name: Add a new z/OS User
- Actors:
- Application Developer
- Description:
- An application developer can submit a new user request for the system admin to approve.
- Flow:
- Verify user does not exist; create home directory, password, and passphrase
- Create home directory and the user to the system
- Provide access to resource, add to system groups, and define an alias
- Create the users ISPROF data set
- Create user private data set, mount with persistence
- Generate email with login credentials
- Actors:
- Use Case Name: Automate certificate renewals
- Actors:
- System Admin
- Description:
- The system administrator can automate certificate renewals
- Flow:
- Setup, configure and run z/OS Health Checker to generate a report
- Search the Health Checker report for expiring certificates
- Renew expiring certificates
- Collect expiring certificate attributes and backup certificate
- Replicate certificate with a new label
- Generate signing request and sign new certificate
- Supersede the old with the new certificate
- Delete old certificate and relabel new certificate with previous certificate name
- Actors:
- Use Case Name: Provision a Liberty Profile Instance
- Actors:
- Application Developer
- Description:
- An application developer can provision an application runtime that accelerates the delivery of cloud-native applications.
- Flow:
- Create and mount a file system for the Liberty profile.
- Create a Liberty Profile instance with optional configurations.
- Enable z/OS authorized services for the Liberty profile.
- Start an angel process or a server process
- Actors:
All releases will meet the following test criteria.
- 100% success for Functional tests.
- 100% success for Unit tests.
- 100% success for Sanity tests as part ofansible-test.
- 100% success for pyflakes.
- 100% success for ansible-lint allowing only false positives.
This release of the collection was tested with following dependencies.
- ansible-core v2.15.x
- Python 3.11.x
- IBM Open Enterprise SDK for Python 3.12.x
- IBM Z Open Automation Utilities (ZOAU) 1.3.2.x
- z/OS V2R5
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.
If you would like to communicate with this community, you can do so through the following options.
- GitHub discussions.
- GitHub issues.
- Ansible Forum, please use the
zostag to ensure proper awareness. - Discord System Z Enthusiasts room
ansible. - Matrix general usage questions room.
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 GitHub, 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, IBM Z Open Automation Utilities, IBM Open Enterprise SDK for Python or ansible-core.
The current supported versions of this collection can be found listed under the release section.
The collection's cumulative release notes can be reviewed here. Note, some collections 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 | Changelogs |
|---|---|---|---|
| 1.13.x | In development | unreleased | unreleased |
| 1.12.x | Current | Release notes | Changelogs |
| 1.11.x | Released | Release notes | Changelogs |
| 1.10.x | Released | Release notes | Changelogs |
| 1.9.x | Released | Release notes | Changelogs |
| 1.8.x | Released | Release notes | Changelogs |
| 1.7.x | Released | Release notes | Changelogs |
| 1.6.x | Released | Release notes | Changelogs |
| 1.5.x | Released | Release notes | Changelogs |
Example playbooks and use cases can be be found in the z/OS playbook repository. Supplemental content on getting started with Ansible, architecture and use cases is available here.
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.
