Ansible for z/OS
IBM's certified Ansible collection for z/OS, ibm.ibm_zos_core, lets the same playbooks manage datasets, submit jobs, copy files and issue operator commands on z/OS. Ansible connects over SSH to z/OS UNIX, and the z/OS system needs IBM Open Enterprise SDK for Python and IBM Z Open Automation Utilities (ZOAU) installed.
Same Ansible, z/OS modules
z/OS is managed like any other node, through Red Hat Ansible Certified Content for IBM Z. The core collection, ibm.ibm_zos_core, provides modules for everyday z/OS work. Other IBM collections cover areas such as IMS, CICS and z/OSMF.
| Module | What it does |
|---|---|
zos_data_set | Create, delete or catalog datasets and members |
zos_copy | Copy files and datasets, converting the code page where needed |
zos_job_submit | Submit JCL from a dataset, a z/OS UNIX file or the control node |
zos_job_output | Fetch a job's output from the spool |
zos_operator | Issue a z/OS operator command and return the response |
zos_tso_command | Run TSO commands |
What the z/OS system needs
- z/OS OpenSSH, so the control node can connect to z/OS UNIX System Services.
- IBM Open Enterprise SDK for Python, because the modules run as Python on z/OS.
- IBM Z Open Automation Utilities (ZOAU), which the modules call to work with datasets, jobs and the console.
- A user ID with the RACF access the tasks need. Ansible can only do what that user is allowed to do.
Each version of the collection supports particular versions of z/OS, ZOAU and Python, so check IBM's requirements table before you upgrade any of them.
A small z/OS playbook
- name: Prepare a library and run the nightly job hosts: zos_test tasks: - name: Make sure the JCL library exists ibm.ibm_zos_core.zos_data_set: name: PAYROLL.TEST.JCL type: pds state: present record_format: fb record_length: 80 - name: Copy the JCL from the repository to a member ibm.ibm_zos_core.zos_copy: src: jcl/nightly.jcl dest: PAYROLL.TEST.JCL(NIGHTLY) - name: Submit it and fail if any step ends above RC 4 ibm.ibm_zos_core.zos_job_submit: src: PAYROLL.TEST.JCL(NIGHTLY) remote_src: true wait_time: 600 max_rc: 4 register: job
remote_src: true tells zos_job_submit that the JCL is already on z/OS. wait_time: 600 lets the task wait up to ten minutes for the job to finish (the default is only a few seconds). max_rc: 4 makes the task fail if any step ends with a return code above 4, which brings back the familiar z/OS rule from the JCL world. register: job keeps the result, including the job ID and step return codes, for later tasks to use. zos_copy converts text such as JCL from the control node's character set to EBCDIC on the way in, unless you mark the file as binary.
What is the name of IBM's core Ansible collection for z/OS? (namespace.collection)
Show a hint
ibm dot ibm underscore ...
Show the solution
ibm.ibm_zos_core.
Examples are for learning. Run commands and jobs only on a system you are authorised to use, such as a training or test system, and never on production without approval.
Common mistakes
Without Python and ZOAU on z/OS, the modules cannot run. Check them before blaming the playbook.
Use a dedicated user ID with only the RACF access the automation needs, so every change can be traced.
A job that ends with RC 12 is still 'submitted'. Use max_rc or check the registered result.
What you will see at work
- System programmers use these modules for routine tasks such as allocating datasets, running health-check jobs and issuing operator commands.
- Application teams use them in pipelines to deploy load modules and refresh CICS and Db2 consistently.
- IBM publishes sample playbooks for z/OS on GitHub, which are a good way to learn by example.
Key terms
Check your understanding.
Take this lesson's quiz and save your progress. Free.