Ansible for IBM Z - Group home

IBM z/OS Ansible Core 1.7.0 has released to Automation Hub,  Galaxy and is available in GitHub.  This release includes new modules  zos_archive,  zos_unarchive, Jinja templating in both zos_copy and zos_job_submit modules, enhancements, bug fixes and deprecation notices. This release comes with optional support and service for Automation Hub users and community support for Galaxy and GitHub users. If you are wondering why I chose a spooky image, well besides releasing only weeks away from Halloween, this our 13th GA release, it includes 13 enhancements, 13 bug fixes and released on Friday the 13th, a tremendous accomplishment. 

New Modules

As you know, great things come in pairs, so we released modules zos_archive and zos_unarchive that can manage all your compression needs for both Unix System Services (USS) and z/OS. There are no additional dependencies, these modules are leveraging existing applications, native and python libraries. When used together, you can use them in several data in transit use cases such as software maintenance where you might need to unpack an archive, a backup strategy or even for selecting data to be put into cold storage; none the less, these modules will improve the Ansible automation experience.

You can choose from formats:

• bz2
• gz
• tar
• zip
• terse
• xmit
• pax

For example, imagine that some source files in an MVS data set needed to be archived into an existing data set and then unarchived, it would be as simple as this these 11 lines of code.

- name: Archive the contents of a data set with format terse.
   ibm.ibm_zos_core.zos_archive:
        src: "USER.DATA.SRC"
        dest: "USER.DATA.ARCHIVE.TRS"
        format:
          name: terse

- name: Unarchive a terse data set.
   ibm.ibm_zos_core.zos_unarchive:
     path: "USER.DATA.ARCHIVE.TRS"
     format:
       name: terse

Expanding on the prior example, let's assume the destination data set does not exist and want to specify the attributes of the new data set and should there be a duplicate data set, force deletion and when the module completes clean up and remove the source data set. This can be done with the following 12 lines of code.

- name: Archive the contents of a data set with format terse, create data set destination and remove the source data set on completion.
   ibm.ibm_zos_core.zos_archive:
        src: "USER.DATA.SRC"
        dest: "USER.DATA.ARCHIVE.TRS"
        force: True
        format:
          name: terse
        remove: True
        dest_data_set:
          space_primary: 10
          space_secondary: 3
          space_type: K

Jinja templating

Jinja templating is available natively in both zos_copy and zos_job_submit modules. In a previous blog, I discussed some use cases on how you might use templating to manage multiple configurations across various Logical Partitions (LPARs) with only one template . I also discussed how you can dynamically generate JCL specific to each system, it is important to note, all templating happens on the Ansible controller before the task is executed on z/OS. 

Jinja offers a powerful and reliable way to generate dynamic content, reduce redundancy and minimize both syntax, and source errors. With the Jinja templating enhancement , you can use all the standard Jinja filters and tests.  Filters allow for variables to be changed and are used in conjunction with a pipe symbol (|) and may have optional arguments in parentheses. Tests can be used to test a variable against a common expression. 

Some of the filters available are below, for a full list review here.

Some of the tests available are below, for a full list review here.

For example, you might want to dynamically generate job cards for JCL (Job Control Launguage). In the playbook snippet, the vars are statically defined in this example, but they can come from dynamic sources such as the zos_gather_facts module. The Jinja snippet is from a larger template JCL.j2 that will be later contributed to our playbook repository, and the zos_job_submit task is using the modules new use_template option to dynamically populate the template. 

Vars:

vars:
  sh_program_name: "UPTIME"
  programmer: "IBMUSER"

Jinja template snippet from 'JCL.j2':

//{{ sh_program_name }} JOB T043JM,JM00,1,0,0,0,'{{ programmer }}',

Playbook task:

- name: Submit JCL and populate job card using Jinja.
   ibm.ibm_zos_core.zos_job_submit:
      src: "{{ playbook_dir }}/files/JCL.j2"
      location: LOCAL
      use_template: true
   register: job_output

Enhancements

Of our substantial list of 22 modules, 7 were enhanced and we will discuss the most noteworthy changes.

zos_copy now displays the data set attributes for data sets that are created by the module. This is helpful when the expectation is that the module will compute the necessary data set attributes and create it. The module has also been updated to no longer perform automatic recovery backups during the module's life cycle. If data integrity is critical, please define the backup options provided in the module. 

zos_data_set introduced record format F (fixed) where one physical block on disk is one logical record and all the blocks and records are the same size.

 zos_job_output, zos_job_query, zos_job_submit now display job information 'asid', 'creation date', 'creation time', 'job class', 'priority', 'queue position', 'service class' and conditionally 'program name' (when ZOAU is v1.2.4 or later)

- fail:
    msg: 'Variable cmd_words not defined'
  when: cmd_words is defined

Then locate the 'Ansible Automation Platform Life Cycle' table and review the 'AAP version' and 'Maintenance support 2 ends' columns to determine when support ends.