Ansible for IBM Z - Group home

IBM z/OS Ansible Core 1.5.0 has released to Automation Hub,  Galaxy and is available in GitHub and wow, what a list of changes. For starters, the entire collection been updated to no longer depend on System Display and Search Facility (SDSF), a new module zos_gather_facts has been included while more than half the collections modules have updates and the latest Z Open Automation Utilities (ZOAU) and IBM Enterprise Python dependencies are now supported. This comes with optional support and service for Automation Hub users and community support for Galaxy users. 

Major changes

The collection no longer requires the SDSF dependency. In prior versions, the collection would interact with SDSF to access job logs. Now, the collection interacts directly with the job entry subsystem (JES) to access job logs. Not only does this reduce the collections requirements but also performance has been improved. 

A new module zos_gather_facts, is included in this release that can discover z/OS facts. Much like the community ansible.builtin.gather_facts module, that can gather facts about Unix System Services (USS), zos_gather_facts focuses on collecting z/OS operating system facts that can be used in playbook development. This module has been in the making for quite some time to ensure the proper design was in place that would allow for continued facts to be added. If you would like to see more facts that will help with playbook development, please request an enhancement. If you are unfamiliar with the term facts, think of them as initialized variables you can access from a playbook. Although there is more to facts than this blog will discuss, some additional points are that you can store facts in a JSON or Redis cache such that they persist between playbook executions to avoid the overhead of having to discover them repeatedly. 

Enhancements

Many of the modules were  enhanced with a new option named tmp_hlq, that when configured, will instruct the module to use this value for the  high level qualifier (HLQ)  for any  temporary data sets that are created during the modules execution.  Prior to this, you could append the environment variable TMPHLQ to the configuration, but this value would be applied for all modules where now its configured for each module. When no value is provided, the user executing the playbooks username will be used as the HLQ. Modules zos_apf, zos_blockinfile, zos_copy, zos_data_set, zos_encode, zos_fetch, zos_lineinfile, zos_mount and zos_mvs_raw all support option tmp_hlq.

Module zos_blockinfile content blocks can now have spaces prepended to every line of the content block. While the YAML block indicator is still supported, that has a maximum indentation of 9 spaces. Another new option is the force option, that will instruct the module to write to a data set that is simultaneously being accessed by other tasks. This is helpful when a data set is being used in a long running process such as a started task and you are wanting to update the data setm. For example, 

- name: Add content to a data set member using a predefined indentation and force.
  zos_blockinfile:
    path: SYS1.PARMLIB(BPXPRM00)
    block: |
          DSN SYSTEM(DB2SSID)
          RUN  PROGRAM(DSNTEP2) PLAN(DSNTEP12) -
          LIB('DB2RUN.RUNLIB.LOAD')
    indentation: 16
    force: true

   - name: Submit a job and wait up to 30 seconds for completion allowing for a maximum return code of 16.
     zos_job_submit:
       src: HLQ.DATA.LLQ(LONGRUN)
       location: DATA_SET
       wait_time_s: 30
       max_rc: 16

Managed node perquisites
In our recent release of Ansible z/OS Core of version 1.4.1 we briefly discussed the requirements and recommended users prepare for a migration to ZOAU 1.2.2 or later. In this release, the minimum ZOAU supported is version 1.2.2 and IBM Enterprise Python version 3.9.x or later. 

Another important note regarding dependencies and configurations. If you have enabled Ansible pipelining where in ansible.cfg pipelining is set as true and are using either IBM Enterprise Python 3.10 or 3.11, you will want to ensure you have the latest IBM Enterprise Python PTF applied and add a new environment variable PYTHONSTDINENCODING. Property PYTHONSTDINENCODING should be set to the encoding Unix System Services is configured as, supported encodings are ASCII or EBCDIC. This environment variable is used to instruct Ansible which encoding it will pipe content to Python's STDIN (standard in) when pipelining=true is set in ansible.cfg. This environment variable will only apply when using IBM Enterprise Python 3.10 or later, otherwise, it is ignored.

For  IBM Open Enterprise SDK for Python 3.10:

PTF: UI91082
APAR: PH53438

For IBM Open Enterprise SDK for Python 3.11:

PTF: UI91094
APAR: PH53470

environment_vars:
  _BPXK_AUTOCVT: "ON"
  ZOAU_HOME: "{{ ZOAU }}"
  PYTHONPATH: "{{ ZOAU }}/lib"
  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"

Resources

IBM Ansible z/OS core on Galaxy
IBM Ansible Core Collection Repository on GitHub
IBM Ansible Core Collection on Automation Hub
Red Hat® Ansible Certified Content for IBM Z documentation