Ansible for IBM Z - Group home

Oh summer, the sun is up and the days stretch long and golden. Get your fruity drinks ready and don't forget your sunscreen. This year, as we embrace the warmth and relaxation, there's exciting news on the horizon: the new IBM z/OS Core Ansible version 1.10.0 is now generally available on Galaxy, GitHub, and Automation Hub. Embrace the season of automation alongside your summer adventures.

Let's see what's new with this release.

Major changes

This release is the first GA version of the IBM z/OS core collection to support IBM Z Open Automation Utilities (ZOAU) version 1.3.x. Considerable effort was made in this release to adopt all the changes from the latest ZOAU release, benefiting the collection with enhancements and bug fixes.

The team focused on adopting new APIs, ensured performance and behaviors remained the same and met their goal of 100% regression success. Going forward, ZOAU 1.3.0 or later will be required for all subsequent releases.  

The other significant change was to adopt new certification requirements from Red Hat. To meet these standards, starting with this release, we have implemented a significant change to options in several modules, now all choices must be lowercase. For example, in the past, you might have used ‘location: DATA_SET’, now the option must be lower case, ‘location: data_set’.

Enhancements

Module zos_backup_restore added a tmp_hlq option to override the default high level qualifier (HLQ) for temporary and backup data sets that could result in an error if a user did not have permission for other HQL's.

Module zos_apf enhances error messages when an exception is caught providing more details to the user when a failure occurs.

Module zos_copy had options group and owner present for internal use and were undocumented, those are now documented and available to use.

Bugfixes

Module zos_apf fixes an issue where option list previously only returned one data set, now it returns a list of retrieved data sets.

Module zos_find fixes an issue that when option size was specified, it  would fail if a PDS/E matched the specified pattern. Now the module filters on utilized size for a PDS/E to correct the behavior.

Module zos_blockinfile fixes an issue where if option block contaied double quotation marks results in a task failure, now the module handles this case to avoid failure.

Module zos_job_submit did not take into consideration that if max_rc was configured, it meant that the user wanted this new return code to decide if a job submission is a success or failure, now the modules relies on this value, else defaults to zero.

Module zos_mvs_raw corrected the modules behavior when using option tmp_hlq that previously was ignored, now the option honors the HLQ for temporary data sets created during the module execution.

Documentation

Module zos_script has been updated with examples on how to use it to execute shell scripts.

Module zos_copy has added a notice, to use this module, you must define the RACF FACILITY class profile and allow READ access to RACF FACILITY profile MVS.MCSOPER.ZOAU. If your system uses a different security product, consult that product's documentation to configure the required security classes.

In case you missed it, in the last IBM z/OS Ansible Core v1.9.1 release blog we mention the new README and support matrix addition, this is an extract from it:

A new support matrix has been created to explain the various dependencies, versions and the end of life (EOL) dates.This clarifies when a collection will be out of service, when to start planning a migration and the requirements for each version.

The README has been updated to align to an upcoming certification requirement, more importantly, there is valuable information in here you don't want to miss. The updated document includes topics as requirements, installation, use cases, testing, support, roadmap and even how to communicate with us.

Important Notices

Use of special characters (#, @, $, - ) in module options like data set names and commands is not fully supported. For example, you can not escape a character in a data set name, yet the `zos_operator` module allows for escapes in the command.

zos_operator:
    cmd: "\\$PJ(*)"

Review each modules documentation for further details. Support for special characters in data set name will be available in the coming IBM Ansible Core v.1.11.0 release generally available later this year.

Porting guide

As previously mentioned, to maintain Red Hat certification, all options in the modules within the collection are now in lower case. Refer to the following porting guide to update your playbooks for this new release.

• zos_archive
  
  • option terse_pack no longer accepts uppercase choices, users should replace them with lowercase ones.
  • suboption record_format of dest_data_set no longer accepts uppercase choices, users should replace them with lowercase ones.
  • suboption space_type of dest_data_set no longer accepts uppercase choices, users should replace them with lowercase ones.
  • suboption type of dest_data_set no longer accepts uppercase choices, users should replace them with lowercase ones.
• zos_backup_restore
  • option space_type no longer accepts uppercase choices, users should replace them with lowercase ones.
• zos_copy
  
  • suboption record_format of dest_data_set no longer accepts uppercase choices, users should replace them with lowercase ones.
  • suboption space_type of dest_data_set no longer accepts uppercase choices, users should replace them with lowercase ones.
  • suboption type of dest_data_set no longer accepts uppercase choices, users should replace them with lowercase ones.
• zos_data_set
  
  • option record_format no longer accepts uppercase choices, users should replace them with lowercase ones.
  • option space_type no longer accepts uppercase choices, users should replace them with lowercase ones.
  • option type no longer accepts uppercase choices, users should replace them with lowercase ones.
  • options inside batch no longer accept uppercase choices, users should replace them with lowercase ones.
• zos_job_submit
  • option location no longer accepts uppercase choices, users should replace them with lowercase ones.
• zos_mount
  
  • option automove no longer accepts uppercase choices, users should replace them with lowercase ones.
  • option fs_type no longer accepts uppercase choices, users should replace them with lowercase ones.
  • option mount_opts no longer accepts uppercase choices, users should replace them with lowercase ones.
  • option tag_untagged no longer accepts uppercase choices, users should replace them with lowercase ones.
  • option unmount_opts no longer accepts uppercase choices, users should replace them with lowercase ones.
• zos_mvs_raw
  
  • options inside dd_concat no longer accept uppercase choices, users should replace them with lowercase ones.
  • suboption record_format of dd_data_set no longer accepts uppercase choices, users should replace them with lowercase ones.
  • suboption record_format of dd_unix no longer accepts uppercase choices, users should replace them with lowercase ones.
  • suboption space_type of dd_data_set no longer accepts uppercase choices, users should replace them with lowercase ones.
  • suboption type of dd_data_set no longer accepts uppercase choices, users should replace them with lowercase ones.
  • suboptions disposition_normal and disposition_abnormal of dd_data_set no longer accept catlg and uncatlg as choices. This also applies when defining a dd_data_set inside dd_concat.
• zos_unarchive
  
  • suboption record_format of dest_data_set no longer accepts uppercase choices, users should replace them with lowercase ones.
  • suboption space_type of dest_data_set no longer accepts uppercase choices, users should replace them with lowercase ones.
  • suboption type of dest_data_set no longer accepts uppercase choices, users should replace them with lowercase ones.

Known Issues

Module zos_job_submit has an issue that when submitting JCL, the response value returned for byte_count is incorrect.

Module zos_data_set has an issue when the module fails during data set creation step, exception can throw an import error instead of data set creation error.

Modules zos_job_submit, zos_job_output and zos_operator_action_query encounter JSON decoding (DecodeError, TypeError, KeyError) errors when interacting with results that contain non-printable UTF-8 characters in the response. This will be addressed in ZOAU version 1.3.2 and later.

Some options to work around this known issue are:

• Specify that the ASA assembler option be enabled to instruct the assembler to use ANSI control characters instead of machine code control characters.

• Ignore module errors by using ignore_errors:true for a specific playbook task.

• If the error is resulting from a batch job, add ignore_errors:true to the task and capture the output into a registered variable to extract the job ID with a regular expression. Then use zos_job_output to display the DD without the non-printable character such as the DD JESMSGLG.

• If the error is the result of a batch job, set option return_output to false so that no DDs are read which could contain the non-printable UTF-8 characters.

About the Authors

Oscar Fernando Flores Garcia is an IBM z/OS Ansible Core software engineer designing and developing many of the collections modules and responsible for many of the product releases. 

The Development Team

Without the development team, this would not be possible. I would like to thank the amazing team who work with passion and perseverance on this project. 

• Rich Parker
• Ketan Kelkar
• Oscar Fernando Flores Garcia
• Ivan Alejandro Moreno Soto
• Andre Marcel Gutierrez Benitez

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
IBM Z Open Automation Utilities