Ansible on z/OS 3.1 Automation Complete Guide

IBM z/OS 3.1 (released September 2023) is the modern mainframe OS for IBM z16/z17 with AI on Z, container support via zCX, and OpenSSH/Python integrations through z/OS OMVS. Ansible automates z/OS through the ibm.ibm_zos_core collection (and friends ibm.ibm_zos_cics, ibm.ibm_zos_ims, ibm.ibm_zosmf), driving JCL submission, dataset management, USS files, and z/OSMF workflows. This is the master Ansible guide for z/OS 3.1.

z/OS 3.1 release facts

| Item | Value | |---|---| | Released | 2023-09-29 | | Hardware | IBM z15 / z16 / z17 | | Key features | AI on Z, zCX containers, modern OpenSSH/Python in OMVS | | Ansible APIs | Z Open Automation Utilities (ZOAU), z/OSMF REST |

See also: Ansible AWS: Complete Guide to Cloud Automation (2026)

Ansible-core compatibility

Use ansible-core 2.18 LTS. The collection requires: • IBM Open Enterprise SDK for Python in OMVS • Z Open Automation Utilities (ZOAU) ≥ 1.3 • SSH access to USS

[zos:vars]
ansible_python_interpreter=/usr/lpp/IBM/cyp/v3r10/pyz/bin/python3
ansible_zoau_path=/usr/lpp/IBM/zoautil

Collection:

collections:
  - name: ibm.ibm_zos_core
    version: ">=1.10.0"
  - name: ibm.ibm_zosmf
    version: ">=1.5.0"

Inventory

[zos]
zos01 ansible_host=mvs01.lab.example.com
[zos:vars]
ansible_user=ANSUSR
ansible_password='{{ vault_zos_password }}'
ansible_connection=ssh

See also: Ansible Become: Privilege Escalation with sudo, su & runas (Complete Guide)

Submit JCL

- name: Submit a JCL job
  hosts: zos
  gather_facts: false
  tasks:
    - name: Submit JCL
      ibm.ibm_zos_core.zos_job_submit:
        src: /u/ansusr/jcl/HELLOJOB.jcl
        location: USS
        wait_time_s: 120
      register: job
- name: Show job status
      ansible.builtin.debug:
        msg: "Job {{ job.jobs[0].job_name }} RC={{ job.jobs[0].ret_code.code }}"

Manage a sequential dataset

- name: Create a PS dataset
  hosts: zos
  gather_facts: false
  tasks:
    - name: Allocate
      ibm.ibm_zos_core.zos_data_set:
        name: ANSUSR.APP.CONFIG
        type: SEQ
        space_primary: 5
        space_secondary: 1
        space_type: TRK
        record_format: FB
        record_length: 80
        state: present
- name: Push content from USS
      ibm.ibm_zos_core.zos_copy:
        src: /u/ansusr/config/app.cfg
        dest: ANSUSR.APP.CONFIG
        remote_src: true

See also: Ansible check_mode: Dry Run & Test Playbooks Without Making Changes

z/OSMF workflow

- name: Run z/OSMF workflow
  hosts: localhost
  gather_facts: false
  tasks:
    - name: Create + start workflow
      ibm.ibm_zosmf.zmf_workflow:
        zmf_host: zosmf.lab.example.com
        zmf_port: 443
        zmf_user: ANSUSR
        zmf_password: "{{ vault_zos_password }}"
        workflow_name: ApplyAPAR
        workflow_file: /usr/lpp/zosmf/samples/sampleworkflow.xml
        system_name: SY1
        owner: ANSUSR
        state: started

RACF user

- name: Add user via TSO command
  hosts: zos
  gather_facts: false
  tasks:
    - name: ADDUSER through zos_tso_command
      ibm.ibm_zos_core.zos_tso_command:
        commands:
          - "ADDUSER APPUSR1 PASSWORD(P@ssw0rd1) DFLTGRP(USERS) NAME('APP USER')"
          - "PERMIT ANSUSR.APP.* ID(APPUSR1) ACCESS(READ)"
          - "SETROPTS REFRESH RACLIST(DATASET)"

Best practices

• Use z/OSMF workflows for installer-style operations and JCL chains; use ZOAU/Ansible for fleet management. • Store JCL templates as Jinja2 in the Git repo, render and push to USS before submission. • Pin ZOAU and Python locations explicitly per LPAR; don't rely on PATH. • Use a RACF service ID with surrogate authority instead of the operator ID.

Conclusion

z/OS 3.1 + ibm.ibm_zos_core and ibm.ibm_zosmf make the mainframe a first-class Ansible target. Combine JCL submission, dataset modules, USS file ops, and z/OSMF workflows to bring the z platform into modern enterprise automation pipelines.