Playbooks

An Ansible Playbook consists of organized instructions that define work for a managed node (hosts) to be managed with Ansible.

Playbook Documentation

IBM z/OSMF collection provides a playbooks directory, which contains various sample playbooks to demonstrate the use of modules and roles.

You can find the playbook content that is included with the collection where the collection was installed, please refer back to the section Installation to obtain the installation path for the collection. In the following examples, this document will refer to the installation path as ~/.ansible/collections/ansible_collections/ibm/ibm_zos_zosmf.

Ansible Config

Ansible config file ansible.cfg can override nearly all ansible-playbook configurations.

Included in the playbooks directory is a sample ansible.cfg that with little modification can supplement ansible-playbook.

You can modify the following configuration statement to refer to your own installation path for the collection:

collections_paths = ~/.ansible/collections:/usr/share/ansible/collections

For more information about available configurations for ansible.cfg, see Ansible Configuration Settings.

Inventory

Ansible works with multiple managed nodes (hosts) at the same time, using a list or group of lists know as an inventory. Once the inventory is defined, you can use patterns to select the hosts, or groups, you want Ansible to run against.

Included in the playbooks directory is a sample inventory file hosts that with little modification can be used to manage the target z/OS systems. This inventory file should be included when running the sample playbook.

[job]
jobHost1 zmf_host=zosmf1.ibm.com zmf_port=443
jobHost2 zmf_host=zosmf2.ibm.com zmf_port=443

[console]
consoleHost1
consoleHost2

[dataset]
datasetHost1 zmf_host=zosmf1.ibm.com zmf_port=443
datasetHost2 zmf_host=zosmf2.ibm.com zmf_port=443

[file]
fileHost1 zmf_host=zosmf1.ibm.com zmf_port=443
fileHost2 zmf_host=zosmf2.ibm.com zmf_port=443

  • job: Host grouping for z/OS Jobs.

    • jobHost1: Nickname for the target z/OS system. You can modify it to refer to your own z/OS system. When the nickname is modified, make sure host specific variables file is defined as described in Host Vars.

    • zmf_host: The value of this property identifies the hostname of the z/OS system on which z/OSMF server is running on. For example: zmf_host=pev076.pok.ibm.com.

    • zmf_port: The value of this property identifies the port number of z/OSMF server.

  • console: Host grouping for z/OS Consoles.

    • consoleHost1: Nickname for the target z/OS system. You can modify it to refer to your own z/OS system. It is configured in z/OSMF Systems plugin.

  • dataset: Host grouping for z/OS Data Sets.

    • datasetHost1: Nickname for the target z/OS system. You can modify it to refer to your own z/OS system. When the nickname is modified, make sure host specific variables file is defined as described in Host Vars.

    • zmf_host: The value of this property identifies the hostname of the z/OS system on which z/OSMF server is running on. For example: zmf_host=pev076.pok.ibm.com.

    • zmf_port: The value of this property identifies the port number of z/OSMF server.

  • file: Host grouping for z/OS USS File.

    • datasetHost1: Nickname for the target z/OS system. You can modify it to refer to your own z/OS system. When the nickname is modified, make sure host specific variables file is defined as described in Host Vars.

    • zmf_host: The value of this property identifies the hostname of the z/OS system on which z/OSMF server is running on. For example: zmf_host=pev076.pok.ibm.com.

    • zmf_port: The value of this property identifies the port number of z/OSMF server.

Host Vars

You can supply host variables in either the inventory file or the separate variable file. Storing separate host and group variables files may help you organize your variable values more easily.

Included in the playbooks directory is some sample variables files in the directory host_vars.

  • jobHost1.yml: It contains the variables for host jobHost1 in group job:

    # zmf_user:
# zmf_password:
# zmf_crt:
# zmf_key:
job_name: JCLSAMP1
job_id: JOB00000

    • zmf_user: The value of this property identifies the username to be used for authenticating with z/OSMF server.

    • zmf_password: The value of this property identifies the password to be used for authenticating with z/OSMF server.

    • zmf_crt: The value of this property identifies the location of the PEM-formatted certificate chain file to be used for HTTPS client authentication with z/OSMF server.

    • zmf_key: The value of this property identifies the location of the PEM-formatted file with private key to be used for HTTPS client authentication with z/OSMF server.

    • job_name: The value of this property identifies the job name to be used for role zmf_job_query to query a job running on different z/OS.

    • job_id: The value of this property identifies the job ID to be used for role zmf_job_query to query a job running on different z/OS.

  • datasetHost1.yml: It contains the variables for host datasetHost1 in group dataset:

    # zmf_user:
# zmf_password:
# zmf_crt:
# zmf_key:

    • zmf_user: The value of this property identifies the username to be used for authenticating with z/OSMF server.

    • zmf_password: The value of this property identifies the password to be used for authenticating with z/OSMF server.

    • zmf_crt: The value of this property identifies the location of the PEM-formatted certificate chain file to be used for HTTPS client authentication with z/OSMF server.

    • zmf_key: The value of this property identifies the location of the PEM-formatted file with private key to be used for HTTPS client authentication with z/OSMF server.

  • fileHost1.yml: It contains the variables for host fileHost1 in group file:

    # zmf_user:
# zmf_password:
# zmf_crt:
# zmf_key:

    • zmf_user: The value of this property identifies the username to be used for authenticating with z/OSMF server.

    • zmf_password: The value of this property identifies the password to be used for authenticating with z/OSMF server.

    • zmf_crt: The value of this property identifies the location of the PEM-formatted certificate chain file to be used for HTTPS client authentication with z/OSMF server.

    • zmf_key: The value of this property identifies the location of the PEM-formatted file with private key to be used for HTTPS client authentication with z/OSMF server.

Note

This is an easy example to use username and password for authenticating with z/OSMF server. zmf_user and zmf_password will be prompted to input when running the sample playbooks. Actually, client-certificate authorization is recommended. You can use zmf_crt and zmf_key to specify the client-certificate authorization. If both methods are specified, the system attempts to use client-certificate authentication.

Group Vars

You can supply group variables in either the inventory file or the separate variable file. Storing separate host and group variables files may help you organize your variable values more easily.

Included in the playbooks directory is some sample variables files in the directory group_vars.

  • console.yml: It contains the variables for group console:

    zmf_host: your.host.name
zmf_port: port_number
# zmf_user:
# zmf_password:
# zmf_crt:
# zmf_key:

    • zmf_host: The value of this property identifies the hostname of the z/OS system on which z/OSMF server is running on. For example: zmf_host=pev076.pok.ibm.com.

    • zmf_port: The value of this property identifies the port number of z/OSMF server.

    • zmf_user: The value of this property identifies the username to be used for authenticating with z/OSMF server.

    • zmf_password: The value of this property identifies the password to be used for authenticating with z/OSMF server.

    • zmf_crt: The value of this property identifies the location of the PEM-formatted certificate chain file to be used for HTTPS client authentication with z/OSMF server.

    • zmf_key: The value of this property identifies the location of the PEM-formatted file with private key to be used for HTTPS client authentication with z/OSMF server.

Note

This is an easy example to use username and password for authenticating with z/OSMF server. zmf_user and zmf_password will be prompted to input when running the sample playbooks. Actually, client-certificate authorization is recommended. You can use zmf_crt and zmf_key to specify the client-certificate authorization. If both methods are specified, the system attempts to use client-certificate authentication.

Run the Playbooks

The sample playbooks must be run from the playbooks directory of the installed collection: ~/.ansible/collections/ansible_collections/ibm/ibm_zos_zosmf/playbooks/

You can use the ansible-playbook command to run the sample playbooks as follows:

$ ansible-playbook [-i hosts] sample_role_*.yml [-e zmf_user=<username> -e zmf_password=<password>]

To adjust the logging verbosity, include the -v option with ansible-playbook command. You can append more letter v’s, for example, -v, -vv, -vvv, or -vvvv, to obtain more details in case a connection failed. Each letter v increases the logging verbosity similar to the traditional logging levels, such as INFO, WARN, ERROR, or DEBUG.