diff --git a/collections/requirements.yml b/collections/requirements.yml index 6fc8490e0..993330f12 100644 --- a/collections/requirements.yml +++ b/collections/requirements.yml @@ -9,7 +9,7 @@ collections: - name: ibm.ibm_zhmc version: 1.2.1 - name: ibm.ibm_zos_cics - version: 1.1.0-beta.5 + version: 2.1.0 - name: ibm.ibm_zos_core version: 1.8.0-beta.1 - name: ibm.ibm_zos_ims diff --git a/z_infra_provisioning/cloud_infra_center/ocp_upi/README.md b/z_infra_provisioning/cloud_infra_center/ocp_upi/README.md index a41dd8e02..48a690100 100644 --- a/z_infra_provisioning/cloud_infra_center/ocp_upi/README.md +++ b/z_infra_provisioning/cloud_infra_center/ocp_upi/README.md @@ -310,9 +310,12 @@ Update your settings based on the samples. The following propeties are **require | `pullsecret` | \ | Get from [cloud.redhat.com](https://console.redhat.com/openshift/install/ibmz/user-provisioned) | | `sshkey` | \ | The SSH public key for the core user in RHEL CoreOS | | `os_dns_domain` | \ or \ | If you want to use your external or existing DNS server set `os_dns_domain` to use it, others set bastion machine ip address | -| `cluster_name` | \ | The name of the cluster, such as `openshift`. | +| `cluster_name` | \ | The name of the cluster, such as `openshift`. | | `base_domain` | \ | The base domain of the cluster, the base domain is used to create routes to your OpenShift Container Platform cluster components, such as `example.com`
| - | `use_internal_bastion` | true | (Boolean) true or false, if true then nodes information under /var/named/\\.zone and /etc/haproxy/haproxy.cfg will update and remove automatically | +| `bootstrap_name_prefix` | \ | The name and hostname of the bootstrap node, such as `ocp4zkboot`. If specific name is not required, leave the default value `` here. | +| `master_name_prefix` | \ | The name and hostname of the master nodes, such as `ocp4zkm`. If specific name is not required, leave the default value `` here. | +| `worker_name_prefix` | \ | The name and hostname of the worker nodes, such as `ocp4zkw`. If specific name is not required, leave the default value `` here. | +| `use_internal_bastion` | true | (Boolean) true or false, if true then nodes information under /var/named/\\.zone and /etc/haproxy/haproxy.cfg will update and remove automatically | If you need the Ansible playbook to help configure DNS server or HAProxy server on bastion server, you need to configure correct bastion properties: diff --git a/z_infra_provisioning/cloud_infra_center/ocp_upi/common.yaml b/z_infra_provisioning/cloud_infra_center/ocp_upi/common.yaml index 214beded5..1d12dd0c3 100644 --- a/z_infra_provisioning/cloud_infra_center/ocp_upi/common.yaml +++ b/z_infra_provisioning/cloud_infra_center/ocp_upi/common.yaml @@ -35,14 +35,43 @@ # Security groups names os_sg_master: "{{ infra_id.stdout_lines[0] }}-master" os_sg_worker: "{{ infra_id.stdout_lines[0] }}-worker" - # Server names + # Ignition files + os_bootstrap_ignition: "{{ infra_id.stdout_lines[0] }}-bootstrap-ignition.json" + +- name: 'Bootstrap server names with prefix' + ansible.builtin.set_fact: + os_bootstrap_server_name: "{{ bootstrap_name_prefix }}" + when: + - bootstrap_name_prefix is defined + +- name: 'Bootstrap server names without prefix' + ansible.builtin.set_fact: os_bootstrap_server_name: "{{ infra_id.stdout_lines[0] }}-bootstrap" + when: + - bootstrap_name_prefix is not defined + +- name: 'Master server names with prefix' + ansible.builtin.set_fact: + os_cp_server_name: "{{ master_name_prefix }}" + os_cp_server_group_name: "{{ master_name_prefix }}" + when: + - master_name_prefix is defined + +- name: 'Master server names without prefix' + ansible.builtin.set_fact: os_cp_server_name: "{{ infra_id.stdout_lines[0] }}-master" os_cp_server_group_name: "{{ infra_id.stdout_lines[0] }}-master" + when: + - master_name_prefix is not defined + +- name: 'Worker server names without prefix' + ansible.builtin.set_fact: os_compute_server_name: "{{ infra_id.stdout_lines[0] }}-worker" - # Ignition files - os_bootstrap_ignition: "{{ infra_id.stdout_lines[0] }}-bootstrap-ignition.json" - # BFV volume names - os_bootstrap_bfv_name: "{{ infra_id.stdout_lines[0] }}-bootstrap-boot" - os_master_bfv_name: "{{ infra_id.stdout_lines[0] }}-master-boot" - os_worker_bfv_name: "{{ infra_id.stdout_lines[0] }}-worker-boot" + when: + - worker_name_prefix is not defined + +- name: 'Worker server names without prefix' + ansible.builtin.set_fact: + os_compute_server_name: "{{ worker_name_prefix }}" + when: + - worker_name_prefix is defined \ No newline at end of file diff --git a/z_infra_provisioning/cloud_infra_center/ocp_upi/inventory.yaml b/z_infra_provisioning/cloud_infra_center/ocp_upi/inventory.yaml index ed4fd82e9..bbd517333 100644 --- a/z_infra_provisioning/cloud_infra_center/ocp_upi/inventory.yaml +++ b/z_infra_provisioning/cloud_infra_center/ocp_upi/inventory.yaml @@ -99,5 +99,8 @@ all: os_dns_domain: '' cluster_name: '' base_domain: '' + # bootstrap_name_prefix: '' + # master_name_prefix: '' + # worker_name_prefix: '' pullsecret: '' sshkey: '' \ No newline at end of file diff --git a/z_infra_provisioning/cloud_infra_center/ocp_upi/roles/configure-install-ignition/tasks/main.yaml b/z_infra_provisioning/cloud_infra_center/ocp_upi/roles/configure-install-ignition/tasks/main.yaml index 7f6bb8e7a..0f3cad3e8 100644 --- a/z_infra_provisioning/cloud_infra_center/ocp_upi/roles/configure-install-ignition/tasks/main.yaml +++ b/z_infra_provisioning/cloud_infra_center/ocp_upi/roles/configure-install-ignition/tasks/main.yaml @@ -39,13 +39,36 @@ cmd: openstack token issue -c id -f value register: glance_token +- name: Generate bootstrap ignition shim + ansible.builtin.script: tools/generate-bootstrap-ignitionshim.py {{ image_url.stdout_lines[0] }} {{ glance_token.stdout }} {{ infra_id.stdout_lines[0] }} {{ bootstrap_name_prefix }} + args: + executable: python3 + when: + - bootstrap_name_prefix is defined + - name: Generate bootstrap ignition shim ansible.builtin.script: tools/generate-bootstrap-ignitionshim.py {{ image_url.stdout_lines[0] }} {{ glance_token.stdout }} {{ infra_id.stdout_lines[0] }} args: executable: python3 + when: + - bootstrap_name_prefix is not defined + +- name: Generate master ignition + ansible.builtin.script: tools/generate-master-ignition.sh {{ infra_id.stdout_lines[0] }} {{ os_control_nodes_number }} {{ master_name_prefix }} + when: + - master_name_prefix is defined - name: Generate master ignition ansible.builtin.script: tools/generate-master-ignition.sh {{ infra_id.stdout_lines[0] }} {{ os_control_nodes_number }} + when: + - master_name_prefix is not defined + +- name: Generate worker ignition + ansible.builtin.script: tools/generate-worker-ignition.sh {{ infra_id.stdout_lines[0] }} {{ os_compute_nodes_number }} {{ worker_name_prefix }} + when: + - worker_name_prefix is defined - name: Generate worker ignition ansible.builtin.script: tools/generate-worker-ignition.sh {{ infra_id.stdout_lines[0] }} {{ os_compute_nodes_number }} + when: + - worker_name_prefix is not defined diff --git a/z_infra_provisioning/cloud_infra_center/ocp_upi/tools/generate-bootstrap-ignitionshim.py b/z_infra_provisioning/cloud_infra_center/ocp_upi/tools/generate-bootstrap-ignitionshim.py index a615f5495..a2d7e0ef7 100755 --- a/z_infra_provisioning/cloud_infra_center/ocp_upi/tools/generate-bootstrap-ignitionshim.py +++ b/z_infra_provisioning/cloud_infra_center/ocp_upi/tools/generate-bootstrap-ignitionshim.py @@ -54,6 +54,26 @@ } }) +if len(sys.argv) > 4: + name_prefix = sys.argv[4] +else: + name_prefix = '' + +if name_prefix: + name_prefix_byte = name_prefix.encode() + bootstrap_hostname = base64.standard_b64encode(name_prefix_byte).decode().strip() + files.update( + { + "storage": { + "files": { + "path": "/etc/hostname", + "mode": 420, + "contents": { + "source": "data:text/plain;charset=utf-8;base64," + bootstrap_hostname + } + } + } + }) infra_id = sys.argv[3] if infra_id: with open(infra_id+'-bootstrap-ignition.json', 'a') as f: diff --git a/z_infra_provisioning/cloud_infra_center/ocp_upi/tools/generate-master-ignition.sh b/z_infra_provisioning/cloud_infra_center/ocp_upi/tools/generate-master-ignition.sh index 968a796f4..f3f57234c 100755 --- a/z_infra_provisioning/cloud_infra_center/ocp_upi/tools/generate-master-ignition.sh +++ b/z_infra_provisioning/cloud_infra_center/ocp_upi/tools/generate-master-ignition.sh @@ -12,7 +12,13 @@ infra_id=$1 master_end=$(($2 - 1)) for index in $( seq 0 $master_end); do - MASTER_HOSTNAME="$infra_id-master-$index\n" + if [ -n "$3" ]; then + MASTER_HOSTNAME="$3-$index\n" + IGNITION_NAME="$3-$index" + else + MASTER_HOSTNAME="$infra_id-master-$index\n" + IGNITION_NAME="$infra_id-master-$index" + fi python -c "import base64, json, sys ignition = json.load(sys.stdin) storage = ignition.get('storage', {}) @@ -20,5 +26,5 @@ files = storage.get('files', []) files.append({'path': '/etc/hostname', 'mode': 420, 'contents': {'source': 'data:text/plain;charset=utf-8;base64,' + base64.standard_b64encode(b'$MASTER_HOSTNAME').decode().strip()},'filesystem': 'root'}) storage['files'] = files ignition['storage'] = storage -json.dump(ignition, sys.stdout)" < master.ign > "$infra_id-master-$index-ignition.json" +json.dump(ignition, sys.stdout)" < master.ign > "$IGNITION_NAME-ignition.json" done \ No newline at end of file diff --git a/z_infra_provisioning/cloud_infra_center/ocp_upi/tools/generate-worker-ignition.sh b/z_infra_provisioning/cloud_infra_center/ocp_upi/tools/generate-worker-ignition.sh index 479f0370f..694d81a05 100755 --- a/z_infra_provisioning/cloud_infra_center/ocp_upi/tools/generate-worker-ignition.sh +++ b/z_infra_provisioning/cloud_infra_center/ocp_upi/tools/generate-worker-ignition.sh @@ -11,7 +11,13 @@ infra_id=$1 worker_end=$(($2 - 1)) for index in $( seq 0 $worker_end); do - WORKER_HOSTNAME="$infra_id-worker-$index\n" + if [ -n "$3" ]; then + WORKER_HOSTNAME="$3-$index\n" + IGNITION_NAME="$3-$index" + else + WORKER_HOSTNAME="$infra_id-worker-$index\n" + IGNITION_NAME="$infra_id-worker-$index" + fi python -c "import base64, json, sys ignition = json.load(sys.stdin) storage = ignition.get('storage', {}) @@ -19,5 +25,5 @@ files = storage.get('files', []) files.append({'path': '/etc/hostname', 'mode': 420, 'contents': {'source': 'data:text/plain;charset=utf-8;base64,' + base64.standard_b64encode(b'$WORKER_HOSTNAME').decode().strip()},'filesystem': 'root'}) storage['files'] = files ignition['storage'] = storage -json.dump(ignition, sys.stdout)" < worker.ign > "$infra_id-worker-$index-ignition.json" +json.dump(ignition, sys.stdout)" < worker.ign > "$IGNITION_NAME-ignition.json" done \ No newline at end of file diff --git a/zos_basics/constructs/README.md b/zos_basics/constructs/README.md index 589a5daa5..3ae10acbd 100644 --- a/zos_basics/constructs/README.md +++ b/zos_basics/constructs/README.md @@ -22,6 +22,27 @@ configuration, flexibility is written into the samples because it can't always be determined if a sample has access to the host’s resources. Review the playbook for additional details and configuration. +> [!IMPORTANT] +> The release of `ibm_zos_core` collection version 1.10.0 introduced case-sensitive +> changes to modules, specifically that module choices must be lower case. See the porting +> guide in the release notes +> ([here](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#porting-guide)) +> to understand the full scope of these changes. +> +> These changes are not compatible with earlier versions of the `ibm_zos_core` collection, +> and since the earlier versions do not reach their end of life until April 2025, +> the sample playbook compatible with the older versions will remain available. +> +> To support both the latest and prior versions of the collection: +> * The `main` branch will reflect playbooks compatible with `ibm_zos_core` version 1.10.0 or later. +> * Find this playbook on the `main` branch: [here](https://github.com/IBM/z_ansible_collections_samples/tree/main/zos_basics/constructs). +> * The `ibm_zos_core-v1.9.x-samples` branch will reflect playbooks compatible with `ibm_zos_core` version 1.9.x or earlier. +> * Find this playbook on the `ibm_zos_core-v1.9.x-samples` branch: [here](https://github.com/IBM/z_ansible_collections_samples/tree/ibm_zos_core-v1.9.x-samples/zos_basics/constructs). +> +> The `ibm_zos_core-v1.9.x-samples` branch will remain available until April 2025 but will not receive updates. +> +> + ## Playbook Requirements - [IBM® z/OS® core collection 1.0.0 or later](https://galaxy.ansible.com/ibm/ibm_zos_core) - [Ansible® 2.11 or later](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) diff --git a/zos_basics/constructs/changelog.yml b/zos_basics/constructs/changelog.yml index c697c5b01..437937a94 100644 --- a/zos_basics/constructs/changelog.yml +++ b/zos_basics/constructs/changelog.yml @@ -1,5 +1,5 @@ ################################################################################ -# Copyright (c) IBM Corporation 2021 +# Copyright (c) IBM Corporation 2021, 2024 # # All notable changes to this project will be documented in this file. Following # releases is a decimal based date since playbooks have no version in this @@ -40,3 +40,10 @@ releases: - Added runtime-requirements.txt that lists the requirements needed for this playbook to execute minor: - Changed dependency from Ansible 2.10 to 2.11 to align with the collections supported Ansible + 2024.04.11: + date: 2024-04-11 + changes: + fixed: + - Lower case zos_job_submit module option 'location' per ibm.ibm_zos_core:1.10.0 requirements. + removed: + - Remove deprecated zos_job_submit module option 'wait'. diff --git a/zos_basics/constructs/zos_job_submit_ansible_constructs.yml b/zos_basics/constructs/zos_job_submit_ansible_constructs.yml index 37917727b..6df317aef 100644 --- a/zos_basics/constructs/zos_job_submit_ansible_constructs.yml +++ b/zos_basics/constructs/zos_job_submit_ansible_constructs.yml @@ -1,5 +1,5 @@ ############################################################################### -# Copyright (c) IBM Corporation 2021 +# Copyright (c) IBM Corporation 2021, 2024 ############################################################################### ############################################################################### @@ -382,8 +382,7 @@ - name: Convert a local JCL file to IBM-037 and submit the job zos_job_submit: src: "{{playbook_dir}}/files/HELLO.jcl" - location: LOCAL - wait: false + location: local encoding: from: ISO8859-1 to: IBM-037 diff --git a/zos_concepts/data_sets/copy_edit_submit/README.md b/zos_concepts/data_sets/copy_edit_submit/README.md index c9d1d4c6d..852c88fd4 100644 --- a/zos_concepts/data_sets/copy_edit_submit/README.md +++ b/zos_concepts/data_sets/copy_edit_submit/README.md @@ -14,6 +14,27 @@ It is a good practice to review the playbook contents before executing them. It will help you understand the requirements in terms of space, location, names, authority, and the artifacts that will be created and cleaned up. +> [!IMPORTANT] +> The release of `ibm_zos_core` collection version 1.10.0 introduced case-sensitive +> changes to modules, specifically that module choices must be lower case. See the porting +> guide in the release notes +> ([here](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#porting-guide)) +> to understand the full scope of these changes. +> +> These changes are not compatible with earlier versions of the `ibm_zos_core` collection, +> and since the earlier versions do not reach their end of life until April 2025, +> the sample playbook compatible with the older versions will remain available. +> +> To support both the latest and prior versions of the collection: +> * The `main` branch will reflect playbooks compatible with `ibm_zos_core` version 1.10.0 or later. +> * Find this playbook on the `main` branch: [here](https://github.com/IBM/z_ansible_collections_samples/tree/main/zos_concepts/data_sets/copy_edit_submit). +> * The `ibm_zos_core-v1.9.x-samples` branch will reflect playbooks compatible with `ibm_zos_core` version 1.9.x or earlier. +> * Find this playbook on the `ibm_zos_core-v1.9.x-samples` branch: [here](https://github.com/IBM/z_ansible_collections_samples/tree/ibm_zos_core-v1.9.x-samples/zos_concepts/data_sets/copy_edit_submit). +> +> The `ibm_zos_core-v1.9.x-samples` branch will remain available until April 2025 but will not receive updates. +> +> + ## Playbook Requirements This playbook requires: diff --git a/zos_concepts/data_sets/copy_edit_submit/changelog.yml b/zos_concepts/data_sets/copy_edit_submit/changelog.yml index 7d9704716..9a8c4baad 100644 --- a/zos_concepts/data_sets/copy_edit_submit/changelog.yml +++ b/zos_concepts/data_sets/copy_edit_submit/changelog.yml @@ -1,5 +1,5 @@ ################################################################################ -# Copyright (c) IBM Corporation 2021 +# Copyright (c) IBM Corporation 2021, 2024 # # All notable changes to this project will be documented in this file. Following # releases is a decimal based date since playbooks have no version in this @@ -43,3 +43,10 @@ releases: - Renamed `copy_edit_submit.yaml` to `copy_edit_submit.yml` to standardize all playbooks with the same extension removed: - Removed the zos_ssh connection plugin, it is no longer included in the ibm_zos_core collection. + 2024.04.09: + date: 2024-04-09 + changes: + fixed: + - Lower case zos_job_submit module option 'location' per ibm.ibm_zos_core:1.10.0 requirements. + removed: + - Remove deprecated zos_job_submit module option 'wait'. \ No newline at end of file diff --git a/zos_concepts/data_sets/copy_edit_submit/copy_edit_submit.yml b/zos_concepts/data_sets/copy_edit_submit/copy_edit_submit.yml index 878a70a4b..958ca0aee 100644 --- a/zos_concepts/data_sets/copy_edit_submit/copy_edit_submit.yml +++ b/zos_concepts/data_sets/copy_edit_submit/copy_edit_submit.yml @@ -1,5 +1,5 @@ ############################################################################### -# © Copyright IBM Corporation 2020, 2021 +# © Copyright IBM Corporation 2020, 2024 ############################################################################### ############################################################################### @@ -93,8 +93,7 @@ - name: "Submit the JCL {{ tmp_data_set }}(PSA)" zos_job_submit: src: "{{ tmp_data_set }}(PSA)" - location: DATA_SET - wait: true + location: data_set register: result_submit_psa - name: "Response for submitting JCL {{ tmp_data_set }}(PSA)" @@ -104,8 +103,7 @@ - name: "Submit the JCL {{ tmp_data_set }}(UPTIME)" zos_job_submit: src: "{{ tmp_data_set }}(UPTIME)" - location: DATA_SET - wait: true + location: data_set register: result_submit_uptime - name: "Response for submitting JCL {{ tmp_data_set }}(UPTIME)" diff --git a/zos_concepts/data_sets/data_set_basics/changelog.yml b/zos_concepts/data_sets/data_set_basics/changelog.yml index c7dee58d5..7fc957c9c 100644 --- a/zos_concepts/data_sets/data_set_basics/changelog.yml +++ b/zos_concepts/data_sets/data_set_basics/changelog.yml @@ -1,5 +1,5 @@ ################################################################################ -# Copyright (c) IBM Corporation 2021 +# Copyright (c) IBM Corporation 2021, 2024 # # All notable changes to this project will be documented in this file. Following # releases is a decimal based date since playbooks have no version in this @@ -44,3 +44,9 @@ releases: - Renamed `data_set_basics.yaml` to `data_set_basics.yml` with a `yml` extenstion to follow standardize on the extension removed: - Removed the zos_ssh connection plugin, it is no longer included in the ibm_zos_core collection. + 2024.04.09: + date: 2024-04-09 + changes: + fixed: + - Replace deprecated zos_data_set module option 'size' with new module options 'space_primary' and 'space_type'. + - Lower case zos_data_set module option 'type' per ibm.ibm_zos_core:1.10.0 requirements. diff --git a/zos_concepts/data_sets/data_set_basics/data_set_basics.yml b/zos_concepts/data_sets/data_set_basics/data_set_basics.yml index 3110db22f..03f3bdba0 100644 --- a/zos_concepts/data_sets/data_set_basics/data_set_basics.yml +++ b/zos_concepts/data_sets/data_set_basics/data_set_basics.yml @@ -1,5 +1,5 @@ ############################################################################### -# © Copyright IBM Corporation 2020, 2021 +# © Copyright IBM Corporation 2020, 2024 ############################################################################### # This sample playbook demonstrates basic data set operations using modules # included in the Red Hat Ansible Certified Content for IBM Z core collection. @@ -85,7 +85,8 @@ replace: true format: fb record_length: 100 - size: 5M + space_primary: 5 + space_type: m register: result - name: Response for data set creation @@ -106,7 +107,6 @@ zos_copy: src: "{{ playbook_dir }}/files/HELLO.jcl" dest: "{{ tgt_tmp_dir }}/HELLO" - # remote_src: yes register: result - name: Response for populating USS file {{ tgt_tmp_dir }}/HELLO @@ -129,7 +129,8 @@ zos_data_set: name: "{{ pds_name }}" type: pds - size: 5M + space_primary: 5 + space_type: m format: fba record_length: 100 register: result @@ -141,7 +142,7 @@ - name: Remove the target PDS member if it exists, for idempotency. zos_data_set: name: "{{ pds_name }}(HELLO)" - type: MEMBER + type: member state: absent register: result diff --git a/zos_concepts/data_transfer/archive_copy_unarchive_restore/README.md b/zos_concepts/data_transfer/archive_copy_unarchive_restore/README.md index 13cb82b49..f18db489c 100644 --- a/zos_concepts/data_transfer/archive_copy_unarchive_restore/README.md +++ b/zos_concepts/data_transfer/archive_copy_unarchive_restore/README.md @@ -21,6 +21,27 @@ names, authority, and the artifacts that will be created and cleaned up. - [**archive_fetch_data_sets.yml**](archive_fetch_data_sets.yml) - Dumps and archive of data sets. - [**unarchive_data_sets.yml**](unarchive_data_sets.yml) - Transfers, unarchives, and restores the target data set archive. +> [!IMPORTANT] +> The release of `ibm_zos_core` collection version 1.10.0 introduced case-sensitive +> changes to modules, specifically that module choices must be lower case. See the porting +> guide in the release notes +> ([here](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#porting-guide)) +> to understand the full scope of these changes. +> +> These changes are not compatible with earlier versions of the `ibm_zos_core` collection, +> and since the earlier versions do not reach their end of life until April 2025, +> the sample playbook compatible with the older versions will remain available. +> +> To support both the latest and prior versions of the collection: +> * The `main` branch will reflect playbooks compatible with `ibm_zos_core` version 1.10.0 or later. +> * Find this playbook on the `main` branch: [here](https://github.com/IBM/z_ansible_collections_samples/tree/main/zos_concepts/data_transfer/archive_copy_unarchive_restore). +> * The `ibm_zos_core-v1.9.x-samples` branch will reflect playbooks compatible with `ibm_zos_core` version 1.9.x or earlier. +> * Find this playbook on the `ibm_zos_core-v1.9.x-samples` branch: [here](https://github.com/IBM/z_ansible_collections_samples/tree/ibm_zos_core-v1.9.x-samples/zos_concepts/data_transfer/archive_copy_unarchive_restore). +> +> The `ibm_zos_core-v1.9.x-samples` branch will remain available until April 2025 but will not receive updates. +> +> + ## Playbook Requirements This playbook requires: diff --git a/zos_concepts/data_transfer/archive_copy_unarchive_restore/archive_fetch_data_sets.yml b/zos_concepts/data_transfer/archive_copy_unarchive_restore/archive_fetch_data_sets.yml index 4a8105246..d4fd6763c 100644 --- a/zos_concepts/data_transfer/archive_copy_unarchive_restore/archive_fetch_data_sets.yml +++ b/zos_concepts/data_transfer/archive_copy_unarchive_restore/archive_fetch_data_sets.yml @@ -1,5 +1,5 @@ ############################################################################### -# © Copyright IBM Corporation 2023 +# © Copyright IBM Corporation 2023, 2024 ############################################################################### ############################################################################### @@ -18,11 +18,10 @@ # IBM z/OS core collection 1.7.0 or later. # Ansible Community General Collection # -# Configure: +# Configure (optional): # data_sets_to_archive - A list of data sets contained in an archive you wish to include in dump. -# archive_data_set - The name to use for the data set archive, -# if not provided, module-generated name will be used. -# delete - Indicates if terse and archive data sets should be deleted upon successful transfer. +# archive_data_set - The name to use for the data set archive. +# remove_data_sets - Indicates if terse and archive data sets should be deleted upon successful transfer. # ############################################################################### @@ -30,20 +29,26 @@ collections : - "ibm.ibm_zos_core" gather_facts: false + vars: - data_sets_to_archive: ["USER.PRIVATE.TEST"] - archive_data_set: "" - delete: true + data_sets_to_archive: + - "{{ ansible_user | upper }}.ANSIBLE.SAMPLE.ONE" + - "{{ ansible_user | upper }}.ANSIBLE.SAMPLE.TWO" + archive_data_set: "{{ ansible_user | upper }}.ANSIBLE.SAMPLE.ARCHIVE" + remove_data_sets: true + environment: '{{ environment_vars }}' tasks: - - name: Create a temporary data set - zos_data_set: - type: seq - space_primary: 5 - space_secondary: 1 - space_type: cyl - name: "{{ item }}" + - name: Create and copy content into data sets to archive. + zos_copy: + content: "HELLO WORLD - {{ item }}" + dest: "{{ item }}" + dest_data_set: + type: seq + space_primary: 5 + space_secondary: 1 + space_type: cyl loop: "{{ data_sets_to_archive }}" ######################################################################### @@ -76,18 +81,18 @@ - name: Create a dump with adrdssu of the data sets and archive using terse. ibm.ibm_zos_core.zos_archive: src: "{{ data_sets_to_archive }}" - dest: "{{ dest_archive }}" + dest: "{{ archive_data_set }}" force: True format: name: terse format_options: - terse_pack: SPACK + terse_pack: spack use_adrdssu: True - remove: "{{ delete }}" + remove: "{{ remove_data_sets }}" dest_data_set: space_primary: "{{ size_in_cyls.primary }}" space_secondary: "{{ size_in_cyls.secondary }}" - space_type: CYL + space_type: cyl register: archive_result - debug: @@ -103,12 +108,20 @@ ######################################################################### - name: Fetch the data set into the controller ibm.ibm_zos_core.zos_fetch: - src: "{{ dest_archive }}" + src: "{{ archive_data_set }}" dest: "{{ playbook_dir }}/" is_binary: True flat: True register: result - - name: "Result of fetching {{ dest_archive }} to controller node" + - name: "Result of fetching {{ archive_data_set }} to controller node" debug: msg: "{{ result }}" + + ######################################################################### + # Remove archive data set from remote system. + ######################################################################### + - name: Delete archive data set from remote system. + zos_data_set: + name: "{{ archive_data_set }}" + state: absent \ No newline at end of file diff --git a/zos_concepts/data_transfer/archive_copy_unarchive_restore/changelog.yml b/zos_concepts/data_transfer/archive_copy_unarchive_restore/changelog.yml index ffae0f964..72eda92ea 100644 --- a/zos_concepts/data_transfer/archive_copy_unarchive_restore/changelog.yml +++ b/zos_concepts/data_transfer/archive_copy_unarchive_restore/changelog.yml @@ -1,5 +1,5 @@ ################################################################################ -# Copyright (c) IBM Corporation 2023 +# Copyright (c) IBM Corporation 2023, 2024 # # All notable changes to this project will be documented in this file. Following # releases is a decimal based date since playbooks have no version in this @@ -31,3 +31,13 @@ releases: changes: added: - Released initial version + 2024.04.11: + date: 2024-04-11 + changes: + added: + - Update description of optional configurations. + - Update vars section to use more generic data set names. + - Add new host_vars files for 'source' and 'destination' target nodes. + fixed: + - Lower case zos_archive module option 'terse_pack' per ibm.ibm_zos_core:1.10.0 requirements. + - Lower case zos_archive module option 'space_type' per ibm.ibm_zos_core:1.10.0 requirements. \ No newline at end of file diff --git a/zos_concepts/data_transfer/archive_copy_unarchive_restore/inventories/host_vars/zos_host.yml b/zos_concepts/data_transfer/archive_copy_unarchive_restore/inventories/host_vars/destination.yml similarity index 100% rename from zos_concepts/data_transfer/archive_copy_unarchive_restore/inventories/host_vars/zos_host.yml rename to zos_concepts/data_transfer/archive_copy_unarchive_restore/inventories/host_vars/destination.yml diff --git a/zos_concepts/data_transfer/archive_copy_unarchive_restore/inventories/host_vars/source.yml b/zos_concepts/data_transfer/archive_copy_unarchive_restore/inventories/host_vars/source.yml new file mode 100644 index 000000000..ee6a0e7d8 --- /dev/null +++ b/zos_concepts/data_transfer/archive_copy_unarchive_restore/inventories/host_vars/source.yml @@ -0,0 +1,24 @@ +################################################################################ +# Copyright (c) IBM Corporation 2024 +################################################################################ + +################################################################################ +# Description of the properties used in this configuration: +# - Property `PYZ` is the python installation home path on the z/OS managed node (target), +# e.g, pyz: "/usr/lpp/IBM/cyp/v3r11/pyz" +# - Property `ZOAU` is the ZOAU installation home on the z/OS managed node (target), +# e.g, zoau: "/usr/lpp/IBM/zoautil" +# - property `ansible_python_interpreter` is the z/OS managed node (target) Python +# binary installation path, e.g, ansible_python_interpreter: "{{PYZ}}/bin/python3" +# +# Note, PYZ and ZOAU environment variables must be configured. +################################################################################ + +PYZ: "path_to_python_installation_on_zos_target" +ZOAU: "path_to_zoau_installation_on_zos_target" + +################################################################################ +# Do not configure, variable substituion will correctly set the +# variable`ansible_python_interpreter` +################################################################################ +ansible_python_interpreter: "{{ PYZ }}/bin/python3" \ No newline at end of file diff --git a/zos_concepts/data_transfer/archive_copy_unarchive_restore/unarchive_data_sets.yml b/zos_concepts/data_transfer/archive_copy_unarchive_restore/unarchive_data_sets.yml index e6e5dc3ea..7a56b171c 100644 --- a/zos_concepts/data_transfer/archive_copy_unarchive_restore/unarchive_data_sets.yml +++ b/zos_concepts/data_transfer/archive_copy_unarchive_restore/unarchive_data_sets.yml @@ -1,5 +1,5 @@ ############################################################################### -# © Copyright IBM Corporation 2023 +# © Copyright IBM Corporation 2023, 2024 ############################################################################### ############################################################################### @@ -17,10 +17,10 @@ # IBM z/OS core collection 1.7.0 or later. # Ansible Community General Collection # -# Configure: +# Configure (optional): # archive_data_set - The name to use for the data set archive. -# delete - Indicates if terse and archive data sets should be deleted upon -# successful restore. +# remove_data_sets - Indicates if terse and archive data sets should be deleted +# upon successful restore. # replace - Indicates if existing data sets should be overwritten during restore. # ############################################################################### @@ -29,31 +29,33 @@ collections : - "ibm.ibm_zos_core" gather_facts: false + vars: - archive_data_set: "" - delete: False + archive_data_set: "{{ ansible_user | upper }}.ANSIBLE.SAMPLE.ARCHIVE" + remove_local_archive: True replace: True + environment: '{{ environment_vars }}' tasks: - block: - name: Unarchive the dump using terse and restore the data sets. ibm.ibm_zos_core.zos_unarchive: - src: "{{ playbook_dir }}/{{ dest_archive }}" - force: True + src: "{{ playbook_dir }}/{{ archive_data_set }}" + force: "{{ replace }}" format: name: terse format_options: use_adrdssu: True - force: "{{ replace }}" register: unarchive_result - debug: msg: "{{ unarchive_result }}" always: - - name: Clean up archive data set - ibm.ibm_zos_core.zos_data_set: - name: "{{ dest_archive }}" + - name: Clean up local archive. + ansible.builtin.file: + name: "{{ playbook_dir }}/{{ archive_data_set }}" state: absent - when: delete and dest_archive is defined + when: remove_local_archive + delegate_to: localhost diff --git a/zos_concepts/data_transfer/copy_fetch_data_set/changelog.yml b/zos_concepts/data_transfer/copy_fetch_data_set/changelog.yml index 0e1e97889..635272a61 100644 --- a/zos_concepts/data_transfer/copy_fetch_data_set/changelog.yml +++ b/zos_concepts/data_transfer/copy_fetch_data_set/changelog.yml @@ -1,5 +1,5 @@ ################################################################################ -# Copyright (c) IBM Corporation 2021 +# Copyright (c) IBM Corporation 2021, 2024 # # All notable changes to this project will be documented in this file. Following # releases is a decimal based date since playbooks have no version in this @@ -44,3 +44,10 @@ releases: - Renamed `copy_fetch_data_set.yaml` to `copy_fetch_data_set.yml` with a `yml` extenstion to follow standardize on the extension removed: - Removed the zos_ssh connection plugin, it is no longer included in the ibm_zos_core collection. + 2024.04.10: + date: 2024-04-10 + changes: + fixed: + - Replace deprecated zos_data_set module option 'size' with new module options 'space_primary' and 'space_type'. + - Modify playbook task to force the copy operation when writing the directory back to host to ensure + uninterrupted playbook execution. \ No newline at end of file diff --git a/zos_concepts/data_transfer/copy_fetch_data_set/copy_fetch_data_set.yml b/zos_concepts/data_transfer/copy_fetch_data_set/copy_fetch_data_set.yml index d33afe4eb..5dd35724b 100644 --- a/zos_concepts/data_transfer/copy_fetch_data_set/copy_fetch_data_set.yml +++ b/zos_concepts/data_transfer/copy_fetch_data_set/copy_fetch_data_set.yml @@ -1,5 +1,5 @@ ############################################################################### -# © Copyright IBM Corporation 2020, 2021 +# © Copyright IBM Corporation 2020, 2024 ############################################################################### ############################################################################### @@ -107,7 +107,8 @@ type: pds format: fba record_length: 100 - size: 5M + space_primary: 5 + space_type: m register: result - name: Response for creating the PDS @@ -153,13 +154,14 @@ debug: msg: "{{ result }}" - - name: Copy the updated directory back to the remote host + - name: Copy the updated directory back to the remote host overwriting previous content. zos_copy: src: "{{ ctl_tmp_dir }}/{{ data_set_name }}" dest: "{{ data_set_name }}" encoding: from: ISO8859-1 to: "{{ target_charset }}" + force: true register: result - name: Response for copying diff --git a/zos_concepts/data_transfer/copy_sort_fetch/changelog.yml b/zos_concepts/data_transfer/copy_sort_fetch/changelog.yml index 9474a88e8..9168c1ea9 100644 --- a/zos_concepts/data_transfer/copy_sort_fetch/changelog.yml +++ b/zos_concepts/data_transfer/copy_sort_fetch/changelog.yml @@ -1,5 +1,5 @@ ################################################################################ -# Copyright (c) IBM Corporation 2021 +# Copyright (c) IBM Corporation 2021, 2024 # # All notable changes to this project will be documented in this file. Following # releases is a decimal based date since playbooks have no version in this @@ -43,3 +43,8 @@ releases: - Renamed `copy-sort-fetch.yaml` to `copy-sort-fetch.yml` with a `yml` extenstion to follow standardize on the extension removed: - Removed the zos_ssh connection plugin, it is no longer included in the ibm_zos_core collection. + 2024.04.10: + date: 2024-04-10 + changes: + fixed: + - Replace deprecated zos_data_set module option 'size' with new module options 'space_primary' and 'space_type'. \ No newline at end of file diff --git a/zos_concepts/data_transfer/copy_sort_fetch/roles/copy-local-data/tasks/main.yml b/zos_concepts/data_transfer/copy_sort_fetch/roles/copy-local-data/tasks/main.yml index aa89a458f..3a2a61cea 100644 --- a/zos_concepts/data_transfer/copy_sort_fetch/roles/copy-local-data/tasks/main.yml +++ b/zos_concepts/data_transfer/copy_sort_fetch/roles/copy-local-data/tasks/main.yml @@ -1,6 +1,6 @@ --- ################################################################################ -# © Copyright IBM Corporation 2020 +# © Copyright IBM Corporation 2020, 2024 # Apache License, Version 2.0 (see https://opensource.org/licenses/Apache-2.0) ################################################################################ @@ -41,8 +41,8 @@ - name: Create the temporary data set ibm.ibm_zos_core.zos_data_set: name: "{{ dest_tmp_data_set }}" - type: "SEQ" - record_format: "FB" + type: seq + record_format: fb - name: Copy local data file to remote z/OS temporary data set ibm.ibm_zos_core.zos_copy: @@ -58,6 +58,6 @@ - ansible.builtin.assert: that: - - "{{ result.data_sets | valid_list }}" - - "'{{ result.data_sets[0]['name'] }}' == '{{ dest_tmp_data_set }}'" + - "result.data_sets | valid_list" + - "result.data_sets[0]['name'] == dest_tmp_data_set" fail_msg: "The destination data set does not exist" diff --git a/zos_concepts/encoding/convert_encoding/changelog.yml b/zos_concepts/encoding/convert_encoding/changelog.yml index 0ce60cf55..acd4f4c48 100644 --- a/zos_concepts/encoding/convert_encoding/changelog.yml +++ b/zos_concepts/encoding/convert_encoding/changelog.yml @@ -1,5 +1,5 @@ ################################################################################ -# Copyright (c) IBM Corporation 2021 +# Copyright (c) IBM Corporation 2021, 2024 # # All notable changes to this project will be documented in this file. Following # releases is a decimal based date since playbooks have no version in this @@ -48,3 +48,9 @@ releases: - Renamed `convert_encoding.yaml` to `convert_encoding.yml` with a `yml` extenstion to follow standardize on the extension removed: - Removed the zos_ssh connection plugin, it is no longer included in the ibm_zos_core collection. + 2024.04.09: + date: 2024-04-09 + changes: + fixed: + - Replace deprecated zos_encode module options 'from_encoding' and 'to_encoding' with new module option + 'encoding' with sub-options 'to' and from' \ No newline at end of file diff --git a/zos_concepts/encoding/convert_encoding/convert_encoding.yml b/zos_concepts/encoding/convert_encoding/convert_encoding.yml index 27f638905..eef7a9021 100644 --- a/zos_concepts/encoding/convert_encoding/convert_encoding.yml +++ b/zos_concepts/encoding/convert_encoding/convert_encoding.yml @@ -1,5 +1,5 @@ ############################################################################### -# © Copyright IBM Corporation 2020, 2021 +# © Copyright IBM Corporation 2020, 2024 ############################################################################### ############################################################################### @@ -96,8 +96,9 @@ zos_encode: src: "{{ tgt_tmp_dir }}/date.sh" dest: "{{ tgt_tmp_dir }}/date.sh" - from_encoding: ISO8859-1 - to_encoding: "{{ target_charset }}" + encoding: + from: ISO8859-1 + to: "{{ target_charset }}" backup: false register: result @@ -196,8 +197,9 @@ zos_encode: src: "{{ tgt_tmp_dir }}/encode/" dest: "{{ tgt_tmp_dir }}/encode/" - from_encoding: ISO8859-1 - to_encoding: "{{ target_charset }}" + encoding: + from: ISO8859-1 + to: "{{ target_charset }}" register: result - name: Response for encode files in {{ tgt_tmp_dir }}/encode/` from diff --git a/zos_concepts/jobs/submit_query_retrieve/README.md b/zos_concepts/jobs/submit_query_retrieve/README.md index 65801cfef..6f0b9713c 100644 --- a/zos_concepts/jobs/submit_query_retrieve/README.md +++ b/zos_concepts/jobs/submit_query_retrieve/README.md @@ -19,6 +19,27 @@ It is a good practice to review the playbook contents before executing them. It will help you understand the requirements in terms of space, location, names, authority, and the artifacts that will be created and cleaned up. +> [!IMPORTANT] +> The release of `ibm_zos_core` collection version 1.10.0 introduced case-sensitive +> changes to modules, specifically that module choices must be lower case. See the porting +> guide in the release notes +> ([here](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#porting-guide)) +> to understand the full scope of these changes. +> +> These changes are not compatible with earlier versions of the `ibm_zos_core` collection, +> and since the earlier versions do not reach their end of life until April 2025, +> the sample playbook compatible with the older versions will remain available. +> +> To support both the latest and prior versions of the collection: +> * The `main` branch will reflect playbooks compatible with `ibm_zos_core` version 1.10.0 or later. +> * Find this playbook on the `main` branch: [here](https://github.com/IBM/z_ansible_collections_samples/tree/main/zos_concepts/jobs/submit_query_retrieve). +> * The `ibm_zos_core-v1.9.x-samples` branch will reflect playbooks compatible with `ibm_zos_core` version 1.9.x or earlier. +> * Find this playbook on the `ibm_zos_core-v1.9.x-samples` branch: [here](https://github.com/IBM/z_ansible_collections_samples/tree/ibm_zos_core-v1.9.x-samples/zos_concepts/jobs/submit_query_retrieve). +> +> The `ibm_zos_core-v1.9.x-samples` branch will remain available until April 2025 but will not receive updates. +> +> + ## Playbook Requirements This playbook requires: diff --git a/zos_concepts/jobs/submit_query_retrieve/changelog.yml b/zos_concepts/jobs/submit_query_retrieve/changelog.yml index ddbb7df05..cd6b09cf2 100644 --- a/zos_concepts/jobs/submit_query_retrieve/changelog.yml +++ b/zos_concepts/jobs/submit_query_retrieve/changelog.yml @@ -1,5 +1,5 @@ ################################################################################ -# Copyright (c) IBM Corporation 2021 +# Copyright (c) IBM Corporation 2021, 2024 # # All notable changes to this project will be documented in this file. Following # releases is a decimal based date since playbooks have no version in this @@ -40,3 +40,10 @@ releases: - Updated host_vars, group_vars and inventory removed: - Removed the zos_ssh connection plugin, it is no longer included in the ibm_zos_core collection. + 2024.04.09: + date: 2024-04-09 + changes: + fixed: + - Replace deprecated zos_data_set module option 'size' with new module options 'space_primary' and 'space_type'. + removed: + - Remove playbook task creating members to avoid using 'force' module option in the zos_copy playbook task. \ No newline at end of file diff --git a/zos_concepts/jobs/submit_query_retrieve/submit_query_retrieve.yml b/zos_concepts/jobs/submit_query_retrieve/submit_query_retrieve.yml index 5236107af..a1c5c46c5 100644 --- a/zos_concepts/jobs/submit_query_retrieve/submit_query_retrieve.yml +++ b/zos_concepts/jobs/submit_query_retrieve/submit_query_retrieve.yml @@ -1,5 +1,5 @@ ############################################################################### -# © Copyright IBM Corporation 2020, 2021, 2022 +# © Copyright IBM Corporation 2020, 2024 ############################################################################### ############################################################################### @@ -74,7 +74,8 @@ zos_data_set: name: "{{ data_set_name }}" type: pds - size: 5M + space_primary: 5 + space_type: m format: fb record_length: 80 replace: true @@ -84,25 +85,6 @@ debug: msg: "{{ result }}" - # +------------------------------------------------------------------------- - # | "with_sequence" is a type of conditional Ansible loop. The loop here - # | only runs for a single iteration and is included solely to demonstrate - # | how easy it is to perform the operation for multiple members. The result - # | is that single member 'MEM1' is created. - # +------------------------------------------------------------------------- - - - name: Create a PDS member and replace if member exist - zos_data_set: - name: "{{ data_set_name }}(MEM{{ item }})" - type: MEMBER - replace: true - with_sequence: count=1 - register: result - - - name: Response for create a PDS member and replace if member exist - debug: - msg: "{{ result }}" - - name: Ensure JCL folder exists in USS to manage JCL file: path: "{{ tgt_tmp_dir }}/ansible/jcl" @@ -139,16 +121,16 @@ msg: "{{ result }}" # +------------------------------------------------------------------------- - # | Similar to how the PDS member was created earlier, this is another - # | Ansible loop with a single iteration designed to showcase how multiple - # | jobs could be submitted under a single task for members of a single PDS + # | "with_sequence" is a type of conditional Ansible loop. The loop here + # | only runs for a single iteration and is included solely to demonstrate + # | how multiple jobs could be submitted under a single task for members of + # | a single PDS. # +------------------------------------------------------------------------- - name: Submit the JCL {{ data_set_name }}(MEM1) zos_job_submit: src: "{{ data_set_name }}(MEM{{ item }})" - location: DATA_SET - wait: true + location: data_set register: result with_sequence: count=1 @@ -165,8 +147,7 @@ - name: Setting fact `job_id_pds` for id of job submitted above set_fact: - job_id_pds: "{{ result.results[0].job_id }}" - + job_id_pds: "{{ result.results[0].jobs[0].job_id }}" - name: Fact `job_id_pds` set with value debug: msg: "{{ job_id_pds }}" @@ -199,8 +180,7 @@ in {{ tgt_tmp_dir }}/ansible/jcl/{{ job_name }} zos_job_submit: src: "{{ tgt_tmp_dir }}/ansible/jcl/{{ job_name }}" - location: USS - wait: true + location: uss register: result - name: Response for submit {{ job_name }} JCL located on target @@ -211,7 +191,7 @@ - name: Setting fact `job_id_uss` for id of job submitted above set_fact: - job_id_uss: "{{ result.job_id }}" + job_id_uss: "{{ result.jobs[0].job_id }}" - name: Fact `job_id_uss` set with value debug: diff --git a/zos_concepts/templates/copy_template/changelog.yml b/zos_concepts/templates/copy_template/changelog.yml index 572e5c6e3..8ba0f73ae 100644 --- a/zos_concepts/templates/copy_template/changelog.yml +++ b/zos_concepts/templates/copy_template/changelog.yml @@ -1,5 +1,5 @@ ################################################################################ -# Copyright (c) IBM Corporation 2023 +# Copyright (c) IBM Corporation 2023, 2024 # # All notable changes to this project will be documented in this file. Following # releases is a decimal based date since playbooks have no version in this @@ -31,3 +31,8 @@ releases: changes: added: - Released initial version + 2024.04.11: + date: 2024-04-11 + changes: + fixed: + - Prefix paths with 'playbook_dir' Ansible global variable. \ No newline at end of file diff --git a/zos_concepts/templates/copy_template/zos_copy_template.yml b/zos_concepts/templates/copy_template/zos_copy_template.yml index 1573bae82..dad4080c6 100644 --- a/zos_concepts/templates/copy_template/zos_copy_template.yml +++ b/zos_concepts/templates/copy_template/zos_copy_template.yml @@ -1,5 +1,5 @@ ############################################################################### -# © Copyright IBM Corporation 2023 +# © Copyright IBM Corporation 2023, 2024 ############################################################################### ############################################################################### @@ -89,7 +89,7 @@ # be copied over to the host. - name: Copy a template to a remote file. ibm.ibm_zos_core.zos_copy: - src: ./files/template.j2 + src: "{{ playbook_dir }}/files/template.j2" dest: "{{ json_path }}" use_template: true @@ -115,7 +115,7 @@ # to make use of Jinja. - name: Copy a template to a dataset. ibm.ibm_zos_core.zos_copy: - src: ./files/records.j2 + src: "{{ playbook_dir }}/files/records.j2" dest: "{{ default_dataset_name }}" use_template: true @@ -137,7 +137,7 @@ # "{{" and "}}", to "((" and "))". - name: Copy a template to a dataset while changing the markers used. ibm.ibm_zos_core.zos_copy: - src: ./files/records_custom_markers.j2 + src: "{{ playbook_dir }}/files/records_custom_markers.j2" dest: "{{ custom_dataset_name }}" use_template: true template_parameters: @@ -154,7 +154,7 @@ # after rendering blocks. - name: Copy a template to a dataset without trimming whitespace. ibm.ibm_zos_core.zos_copy: - src: ./files/records.j2 + src: "{{ playbook_dir }}/files/records.j2" dest: "{{ default_dataset_name }}" force: true use_template: true diff --git a/zos_concepts/templates/loadlib/README.md b/zos_concepts/templates/loadlib/README.md index 008b9a406..d0907ca01 100644 --- a/zos_concepts/templates/loadlib/README.md +++ b/zos_concepts/templates/loadlib/README.md @@ -16,6 +16,27 @@ It is a good practice to review the playbook contents before executing them. It will help you understand the requirements in terms of space, location, names, authority, and the artifacts that will be created and cleaned up. +> [!IMPORTANT] +> The release of `ibm_zos_core` collection version 1.10.0 introduced case-sensitive +> changes to modules, specifically that module choices must be lower case. See the porting +> guide in the release notes +> ([here](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#porting-guide)) +> to understand the full scope of these changes. +> +> These changes are not compatible with earlier versions of the `ibm_zos_core` collection, +> and since the earlier versions do not reach their end of life until April 2025, +> the sample playbook compatible with the older versions will remain available. +> +> To support both the latest and prior versions of the collection: +> * The `main` branch will reflect playbooks compatible with `ibm_zos_core` version 1.10.0 or later. +> * Find this playbook on the `main` branch: [here](https://github.com/IBM/z_ansible_collections_samples/tree/main/zos_concepts/templates/loadlib). +> * The `ibm_zos_core-v1.9.x-samples` branch will reflect playbooks compatible with `ibm_zos_core` version 1.9.x or earlier. +> * Find this playbook on the `ibm_zos_core-v1.9.x-samples` branch: [here](https://github.com/IBM/z_ansible_collections_samples/tree/ibm_zos_core-v1.9.x-samples/zos_concepts/templates/loadlib). +> +> The `ibm_zos_core-v1.9.x-samples` branch will remain available until April 2025 but will not receive updates. +> +> + ## Playbook Requirements This playbook requires: diff --git a/zos_concepts/templates/loadlib/changelog.yml b/zos_concepts/templates/loadlib/changelog.yml index afc95fa0a..882a74281 100644 --- a/zos_concepts/templates/loadlib/changelog.yml +++ b/zos_concepts/templates/loadlib/changelog.yml @@ -1,5 +1,5 @@ ################################################################################ -# Copyright (c) IBM Corporation 2023 +# Copyright (c) IBM Corporation 2023, 2024 # # All notable changes to this project will be documented in this file. Following # releases is a decimal based date since playbooks have no version in this @@ -31,3 +31,11 @@ releases: changes: added: - Released initial version + 2024.04.11: + date: 2024-04-11 + changes: + fixed: + - Lower case zos_data_set module option 'type' per ibm.ibm_zos_core:1.10.0 requirements. + - Lower case zos_data_set module option 'space_type' per ibm.ibm_zos_core:1.10.0 requirements. + - Lower case zos_data_set module option 'record_format' per ibm.ibm_zos_core:1.10.0 requirements. + - Lower case zos_job_submit module option 'location' per ibm.ibm_zos_core:1.10.0 requirements. \ No newline at end of file diff --git a/zos_concepts/templates/loadlib/compile_link_loadlib.yml b/zos_concepts/templates/loadlib/compile_link_loadlib.yml index fb3c28432..71237036a 100644 --- a/zos_concepts/templates/loadlib/compile_link_loadlib.yml +++ b/zos_concepts/templates/loadlib/compile_link_loadlib.yml @@ -1,5 +1,5 @@ ############################################################################### -# © Copyright IBM Corporation 2023 +# © Copyright IBM Corporation 2023, 2024 ############################################################################### ############################################################################### @@ -43,10 +43,10 @@ - name: Create {{ pgm_dataset }} for the COBOL program. ibm.ibm_zos_core.zos_data_set: name: "{{ pgm_dataset }}" - type: PDS + type: pds space_primary: 2 - space_type: M - record_format: FB + space_type: m + record_format: fb record_length: 80 block_size: 3120 @@ -58,17 +58,17 @@ - name: Create {{ loadlib_dataset }} where the compiled source will be linked. ibm.ibm_zos_core.zos_data_set: name: "{{ loadlib_dataset }}" - type: PDSE + type: pdse space_primary: 2 - space_type: M - record_format: U + space_type: m + record_format: u record_length: 0 block_size: 32760 - name: Compile and link the COBOL code. ibm.ibm_zos_core.zos_job_submit: src: "{{playbook_dir}}/files/COMPLINK.j2" - location: LOCAL + location: local wait_time_s: 60 use_template: true register: comp_result diff --git a/zos_concepts/templates/submit_job_template/README.md b/zos_concepts/templates/submit_job_template/README.md index cfaf47d45..08f4202f6 100644 --- a/zos_concepts/templates/submit_job_template/README.md +++ b/zos_concepts/templates/submit_job_template/README.md @@ -12,6 +12,27 @@ It is a good practice to review the playbook contents before executing them. It will help you understand the requirements in terms of space, location, names, authority, and the artifacts that will be created and cleaned up. +> [!IMPORTANT] +> The release of `ibm_zos_core` collection version 1.10.0 introduced case-sensitive +> changes to modules, specifically that module choices must be lower case. See the porting +> guide in the release notes +> ([here](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#porting-guide)) +> to understand the full scope of these changes. +> +> These changes are not compatible with earlier versions of the `ibm_zos_core` collection, +> and since the earlier versions do not reach their end of life until April 2025, +> the sample playbook compatible with the older versions will remain available. +> +> To support both the latest and prior versions of the collection: +> * The `main` branch will reflect playbooks compatible with `ibm_zos_core` version 1.10.0 or later. +> * Find this playbook on the `main` branch: [here](https://github.com/IBM/z_ansible_collections_samples/tree/main/zos_concepts/templates/submit_job_template). +> * The `ibm_zos_core-v1.9.x-samples` branch will reflect playbooks compatible with `ibm_zos_core` version 1.9.x or earlier. +> * Find this playbook on the `ibm_zos_core-v1.9.x-samples` branch: [here](https://github.com/IBM/z_ansible_collections_samples/tree/ibm_zos_core-v1.9.x-samples/zos_concepts/templates/submit_job_template). +> +> The `ibm_zos_core-v1.9.x-samples` branch will remain available until April 2025 but will not receive updates. +> +> + ## Playbook Requirements This playbook requires: diff --git a/zos_concepts/templates/submit_job_template/changelog.yml b/zos_concepts/templates/submit_job_template/changelog.yml index afc95fa0a..f71a67f9b 100644 --- a/zos_concepts/templates/submit_job_template/changelog.yml +++ b/zos_concepts/templates/submit_job_template/changelog.yml @@ -1,5 +1,5 @@ ################################################################################ -# Copyright (c) IBM Corporation 2023 +# Copyright (c) IBM Corporation 2023, 2024 # # All notable changes to this project will be documented in this file. Following # releases is a decimal based date since playbooks have no version in this @@ -31,3 +31,8 @@ releases: changes: added: - Released initial version + 2024.04.11: + date: 2024-04-11 + changes: + fixed: + - Lower case zos_job_submit module option 'location' per ibm.ibm_zos_core:1.10.0 requirements. diff --git a/zos_concepts/templates/submit_job_template/submit_templates.yml b/zos_concepts/templates/submit_job_template/submit_templates.yml index a556c5a2b..1ce03b24d 100644 --- a/zos_concepts/templates/submit_job_template/submit_templates.yml +++ b/zos_concepts/templates/submit_job_template/submit_templates.yml @@ -1,5 +1,5 @@ ############################################################################### -# © Copyright IBM Corporation 2023 +# © Copyright IBM Corporation 2023, 2024 ############################################################################### ############################################################################### @@ -75,7 +75,7 @@ - name: Submit shell command job using a local template. ibm.ibm_zos_core.zos_job_submit: src: "{{ playbook_dir }}/files/CMD.j2" - location: LOCAL + location: local use_template: true register: job_output @@ -103,7 +103,7 @@ - name: Submit IEFBR14 job using a local template. ibm.ibm_zos_core.zos_job_submit: src: "{{ playbook_dir }}/files/LOOP.j2" - location: LOCAL + location: local use_template: true template_parameters: trim_blocks: true diff --git a/zos_concepts/tso_commands/scripts/changelog.yml b/zos_concepts/tso_commands/scripts/changelog.yml index 69edf768c..f50a3810c 100644 --- a/zos_concepts/tso_commands/scripts/changelog.yml +++ b/zos_concepts/tso_commands/scripts/changelog.yml @@ -1,5 +1,5 @@ ################################################################################ -# Copyright (c) IBM Corporation 2023 +# Copyright (c) IBM Corporation 2023, 2024 # # All notable changes to this project will be documented in this file. Following # releases is a decimal based date since playbooks have no version in this @@ -31,3 +31,8 @@ releases: changes: added: - Released initial version + 2024.04.09: + date: 2024-04-09 + changes: + fixed: + - Prefix paths with 'playbook_dir' Ansible global variable. \ No newline at end of file diff --git a/zos_concepts/tso_commands/scripts/run_rexx_and_clist.yml b/zos_concepts/tso_commands/scripts/run_rexx_and_clist.yml index 997f8a924..ab89e827b 100644 --- a/zos_concepts/tso_commands/scripts/run_rexx_and_clist.yml +++ b/zos_concepts/tso_commands/scripts/run_rexx_and_clist.yml @@ -1,5 +1,5 @@ ############################################################################### -# © Copyright IBM Corporation 2023 +# © Copyright IBM Corporation 2023, 2024 ############################################################################### ############################################################################### @@ -40,7 +40,7 @@ block: - name: Copy file to a new data set. ibm.ibm_zos_core.zos_copy: - src: ./files/DSINFO + src: "{{ playbook_dir }}/files/DSINFO" dest: "{{ script_data_set }}" remote_src: false @@ -58,7 +58,7 @@ block: - name: Copy file to a new data set. ibm.ibm_zos_core.zos_copy: - src: ./files/CLIST + src: "{{ playbook_dir }}/files/CLIST" dest: "{{ clist_data_set }}" remote_src: false diff --git a/zos_concepts/volume_management/volume_initialization/init_dasd_vol_and_run_sample_jcl/README.md b/zos_concepts/volume_management/volume_initialization/init_dasd_vol_and_run_sample_jcl/README.md index f8b5de837..3b50b7c1f 100644 --- a/zos_concepts/volume_management/volume_initialization/init_dasd_vol_and_run_sample_jcl/README.md +++ b/zos_concepts/volume_management/volume_initialization/init_dasd_vol_and_run_sample_jcl/README.md @@ -20,6 +20,27 @@ It is a good practice to review the playbook contents before executing them. It will help you understand the requirements in terms of space, location, names, authority, and the artifacts that will be created and cleaned up. +> [!IMPORTANT] +> The release of `ibm_zos_core` collection version 1.10.0 introduced case-sensitive +> changes to modules, specifically that module choices must be lower case. See the porting +> guide in the release notes +> ([here](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#porting-guide)) +> to understand the full scope of these changes. +> +> These changes are not compatible with earlier versions of the `ibm_zos_core` collection, +> and since the earlier versions do not reach their end of life until April 2025, +> the sample playbook compatible with the older versions will remain available. +> +> To support both the latest and prior versions of the collection: +> * The `main` branch will reflect playbooks compatible with `ibm_zos_core` version 1.10.0 or later. +> * Find this playbook on the `main` branch: [here](https://github.com/IBM/z_ansible_collections_samples/tree/main/zos_concepts/volume_management/volume_initialization/init_dasd_vol_and_run_sample_jcl). +> * The `ibm_zos_core-v1.9.x-samples` branch will reflect playbooks compatible with `ibm_zos_core` version 1.9.x or earlier. +> * Find this playbook on the `ibm_zos_core-v1.9.x-samples` branch: [here](https://github.com/IBM/z_ansible_collections_samples/tree/ibm_zos_core-v1.9.x-samples/zos_concepts/volume_management/volume_initialization/init_dasd_vol_and_run_sample_jcl). +> +> The `ibm_zos_core-v1.9.x-samples` branch will remain available until April 2025 but will not receive updates. +> +> + ## Playbook Requirements This playbook requires: diff --git a/zos_concepts/volume_management/volume_initialization/init_dasd_vol_and_run_sample_jcl/changelog.yml b/zos_concepts/volume_management/volume_initialization/init_dasd_vol_and_run_sample_jcl/changelog.yml index 19a1b9272..66a3e69fc 100644 --- a/zos_concepts/volume_management/volume_initialization/init_dasd_vol_and_run_sample_jcl/changelog.yml +++ b/zos_concepts/volume_management/volume_initialization/init_dasd_vol_and_run_sample_jcl/changelog.yml @@ -1,5 +1,5 @@ ################################################################################ -# Copyright (c) IBM Corporation 2023 +# Copyright (c) IBM Corporation 2023, 2024 # # All notable changes to this project will be documented in this file. Following # releases is a decimal based date since playbooks have no version in this @@ -31,3 +31,10 @@ releases: changes: added: - Released initial version + 2024.04.10: + date: 2024-04-10 + changes: + fixed: + - Lower case zos_data_set module option 'space_type' per ibm.ibm_zos_core:1.10.0 requirements. + - Lower case zos_mount module option 'fs_type' per ibm.ibm_zos_core:1.10.0 requirements. + - Lower case zos_job_submit module option 'location' per ibm.ibm_zos_core:1.10.0 requirements. diff --git a/zos_concepts/volume_management/volume_initialization/init_dasd_vol_and_run_sample_jcl/init_dasd_vol_and_run_sample_jcl.yml b/zos_concepts/volume_management/volume_initialization/init_dasd_vol_and_run_sample_jcl/init_dasd_vol_and_run_sample_jcl.yml index fc8466d0a..43fcd2983 100644 --- a/zos_concepts/volume_management/volume_initialization/init_dasd_vol_and_run_sample_jcl/init_dasd_vol_and_run_sample_jcl.yml +++ b/zos_concepts/volume_management/volume_initialization/init_dasd_vol_and_run_sample_jcl/init_dasd_vol_and_run_sample_jcl.yml @@ -1,5 +1,5 @@ ############################################################################### -# © Copyright IBM Corporation 2023 +# © Copyright IBM Corporation 2023, 2024 ############################################################################### ############################################################################### @@ -80,11 +80,11 @@ not be SMS managed. zos_volume_init: address: "{{ vol_unit }}" - verify_offline: true + verify_offline: no volid: "{{ new_volser }}" index: true sms_managed: false - verify_volume_empty: true + verify_volume_empty: no register: output - name: Response for intialize target volume. @@ -100,7 +100,7 @@ name: "{{ zfs_dsname }}" type: zfs space_primary: 50 - space_type: M + space_type: m replace: true volumes: "{{ new_volser }}" @@ -113,7 +113,7 @@ zos_mount: src: "{{ zfs_dsname }}" path: "{{ mount_point }}" - fs_type: ZFS + fs_type: zfs state: mounted - name: Copy JCL to data set. @@ -124,7 +124,7 @@ - name: Submit the JCL at {{ mount_point}}/HELLO.jcl. zos_job_submit: src: "{{ mount_point }}/HELLO.jcl" - location: USS + location: uss register: result - name: Setting fact `job_id` for id of job submitted above. @@ -155,7 +155,7 @@ zos_mount: src: "{{ zfs_dsname }}" path: "{{ mount_point }}" - fs_type: ZFS + fs_type: zfs state: absent - name: Delete ZFS data set {{ zfs_dsname }}. diff --git a/zos_concepts/zfsadm/zfs_grow_aggr/changelog.yml b/zos_concepts/zfsadm/zfs_grow_aggr/changelog.yml index 30857c2ed..f845bcd56 100644 --- a/zos_concepts/zfsadm/zfs_grow_aggr/changelog.yml +++ b/zos_concepts/zfsadm/zfs_grow_aggr/changelog.yml @@ -1,5 +1,5 @@ ################################################################################ -# Copyright (c) IBM Corporation 2022 +# Copyright (c) IBM Corporation 2022, 2024 # # All notable changes to this project will be documented in this file. Following # releases is a decimal based date since playbooks have no version in this @@ -31,3 +31,8 @@ releases: changes: added: - Released initial version (pending) + 2024.04.10: + date: 2024-04-10 + changes: + fixed: + - Update data set space configurations for clearer threshold variations in output. diff --git a/zos_concepts/zfsadm/zfs_grow_aggr/scan_and_grow_zfs_aggr.yml b/zos_concepts/zfsadm/zfs_grow_aggr/scan_and_grow_zfs_aggr.yml index 45258a4e3..46e58fe8f 100644 --- a/zos_concepts/zfsadm/zfs_grow_aggr/scan_and_grow_zfs_aggr.yml +++ b/zos_concepts/zfsadm/zfs_grow_aggr/scan_and_grow_zfs_aggr.yml @@ -1,5 +1,5 @@ ############################################################################### -# © Copyright IBM Corporation 2022 +# © Copyright IBM Corporation 2022, 2024 ############################################################################### ############################################################################### @@ -60,8 +60,8 @@ zos_data_set: name: "{{ item | upper }}" type: zfs - space_primary: 1 - space_type: M + space_primary: 950 + space_type: k replace: true loop: "{{ zfs_data_sets }}" @@ -119,7 +119,7 @@ - name: Build grow_list set_fact: grow_list: "{{ grow_list | default([]) + [item[0]] }}" - when: "{{ item[1] | int }} > {{ threshold_limit }}" + when: item[1] | int > threshold_limit | int loop: "{{ dsn_per_util_list }}" - name: Echo grow_list diff --git a/zos_concepts/zos_script/changelog.yml b/zos_concepts/zos_script/changelog.yml index 69edf768c..f50a3810c 100644 --- a/zos_concepts/zos_script/changelog.yml +++ b/zos_concepts/zos_script/changelog.yml @@ -1,5 +1,5 @@ ################################################################################ -# Copyright (c) IBM Corporation 2023 +# Copyright (c) IBM Corporation 2023, 2024 # # All notable changes to this project will be documented in this file. Following # releases is a decimal based date since playbooks have no version in this @@ -31,3 +31,8 @@ releases: changes: added: - Released initial version + 2024.04.09: + date: 2024-04-09 + changes: + fixed: + - Prefix paths with 'playbook_dir' Ansible global variable. \ No newline at end of file diff --git a/zos_concepts/zos_script/zos_script.yml b/zos_concepts/zos_script/zos_script.yml index 02453d892..e0acbefe3 100644 --- a/zos_concepts/zos_script/zos_script.yml +++ b/zos_concepts/zos_script/zos_script.yml @@ -1,5 +1,5 @@ ############################################################################### -# © Copyright IBM Corporation 2023 +# © Copyright IBM Corporation 2023, 2024 ############################################################################### ############################################################################### @@ -45,7 +45,7 @@ # node. Make sure to replace the values of the arguments. - name: Run REXX script to get a job's information. ibm.ibm_zos_core.zos_script: - cmd: ./files/JOB_INFO JOBID=ID OWNER=OWNER JOBNAME=NAME + cmd: "{{ playbook_dir }}/files/JOB_INFO JOBID=ID OWNER=OWNER JOBNAME=NAME" remote_src: false register: job_output @@ -57,7 +57,7 @@ # control over the way a script is run. - name: Run Python script in a given directory. ibm.ibm_zos_core.zos_script: - cmd: ./files/list_dir.py + cmd: "{{ playbook_dir }}/files/list_dir.py" chdir: "{{ python_script_dir }}" executable: "{{ ansible_python_interpreter }}" remote_src: false @@ -71,7 +71,7 @@ # the variables defined above. - name: Run template of a REXX script. ibm.ibm_zos_core.zos_script: - cmd: ./files/CATALOG + cmd: "{{ playbook_dir }}/files/CATALOG" remote_src: false use_template: true template_parameters: diff --git a/zos_subsystems/cics/README.md b/zos_subsystems/cics/README.md index 8e19c0576..91959b3a8 100644 --- a/zos_subsystems/cics/README.md +++ b/zos_subsystems/cics/README.md @@ -32,6 +32,19 @@ This repository provides a number of samples that show how to use the CICS colle The `set_ca` sample shows how to use the CMCI modules with a custom CA bundle, typically useful when you have an internal CA. +1. [Refresh tags](cmci/refresh_tags) + + The `refresh_tags` sample shows how to instruct a CICS region to refresh + its tags by re-reading the tags file on USS. This is achieved by using + the `cmci_action` module. This sample also documents how to determine + the appropriate parameters for the `cmci_action` module for the action + you're trying to run. + +1. [Provisioning](provisioning/) + + The `provisioning` sample shows how use the modules in the CICS collection + to provision a CICS region from scratch. + --- These CICS samples are just some of the samples available for the Red Hat Ansible Certified Content for IBM Z. You can find samples covering other aspects at the [root of the repository](https://github.com/IBM/z_ansible_collections_samples). diff --git a/zos_subsystems/cics/cmci/deploy_program/deploy_program.yml b/zos_subsystems/cics/cmci/deploy_program/deploy_program.yml index dc6789d43..d866ab65c 100644 --- a/zos_subsystems/cics/cmci/deploy_program/deploy_program.yml +++ b/zos_subsystems/cics/cmci/deploy_program/deploy_program.yml @@ -29,7 +29,7 @@ - typing;python_version<"3.5" ############################################################################ - # Install module dependencies + # NEWCOPY PROGRAM in CICS ############################################################################ - name: NEWCOPY PROGRAM in CICS delegate_to: localhost diff --git a/zos_subsystems/cics/cmci/refresh_tags/README.md b/zos_subsystems/cics/cmci/refresh_tags/README.md new file mode 100644 index 000000000..a9f383c6f --- /dev/null +++ b/zos_subsystems/cics/cmci/refresh_tags/README.md @@ -0,0 +1,54 @@ +# Using the CICS collection to refresh a region's tags + +This sample playbook demonstrates how to use the `cmci_action` module from the `ibm_zos_cics` collection to run an action against a CICS resource. +Additionally, this readme documents how to determine the appropriate Ansible +module configuration, if you're trying to automate something you know how +to do in CICS Explorer + +## Requirements + +- Python 3.5+ +- Ansible 2.15+ +- IBM z/OS CICS Ansible collection 2.1.0+ + +## Getting Started + +As this sample only uses the `cmci_action` module, no inventory is required, as +it can execute directly on the Ansible control node. + +Variables must be supplied for the CMCI connection details. Dummy variables are +provided in `group_vars/all.yml`, which you must edit to supply the CMCI +connection details: + +- `cmci_host` - Target CMCI hostname +- `cmci_port` - Target CMCI port +- `cmci_scheme` - CMCI scheme (http or https) +- `context` - Target CICSplex SM context +- `scope` - Target CICSplex SM scope + +The playbook will prompt for the CMCI user name and password when it executes. + +## Usage +```bash +ansible-playbook refresh_tags.yml +``` + +## How to determine CMCI module parameters + +You can use CICS Explorer to tell a CICS region to re-read its tags file +by right-clicking on a row in the "Regions" view and selecting "Refresh tags". + +From this, we can determine that CMCI request runs against a CICS Region. +In order to use the `cmci_action` module to execute the same request we +need to determine the CMCI resource name, and the action name. + +The Regions view corresponds to the `CICSRGN` resource table. Consulting the +[documentation](https://www.ibm.com/docs/en/cics-ts/latest?topic=tables-cicsrgn-resource-table) for that table, we can find the +"External resource name (CMCI)" information, which is `CICSRegion`. This is +the value we've filled in for the `type` parameter of the `cmci_action` module. + +The action names can be found on the same page. By looking at the available +actions we can identify that `TAGSREFR` is the name of the action we're looking +to run. We've filled that in for the `action_name` parameter of the module. + +As this action has no further parameters, we're done! If the action did have parameters, they're also documented on the same page. \ No newline at end of file diff --git a/zos_subsystems/cics/cmci/refresh_tags/group_vars/all.yml b/zos_subsystems/cics/cmci/refresh_tags/group_vars/all.yml new file mode 100644 index 000000000..ccf537a66 --- /dev/null +++ b/zos_subsystems/cics/cmci/refresh_tags/group_vars/all.yml @@ -0,0 +1,14 @@ +# Target CMCI hostname +cmci_host: example.com + +# Target CMCI port +cmci_port: 12345 + +# CMCI scheme (http or https) +scheme: https + +# Target CICSplex SM context +context: MYPLEX + +# Target CICSplex SM scope +scope: MYRGN \ No newline at end of file diff --git a/zos_subsystems/cics/cmci/refresh_tags/refresh_tags.yml b/zos_subsystems/cics/cmci/refresh_tags/refresh_tags.yml new file mode 100644 index 000000000..9b0718d61 --- /dev/null +++ b/zos_subsystems/cics/cmci/refresh_tags/refresh_tags.yml @@ -0,0 +1,40 @@ +# (c) Copyright IBM Corporation 2024 +# Apache License, Version 2.0 (see https://opensource.org/licenses/Apache-2.0) +--- +- name: Refresh region tags + + hosts: localhost + gather_facts: false + + vars_prompt: + - name: cmci_user + prompt: CMCI user name (leave blank for unauthenticated) + private: false + - name: cmci_password + prompt: CMCI password (leave blank for unauthenticated) + + tasks: + ############################################################################ + # Install cmci_action module dependencies + ############################################################################ + - name: Make sure CMCI module dependencies are installed + ansible.builtin.pip: + name: + - requests + - xmltodict + - typing;python_version<"3.5" + + ############################################################################ + # Use cmci_action to tell region to refresh tags + ############################################################################ + - name: Refresh tags from tag file on USS + ibm.ibm_zos_cics.cmci_action: + context: "{{ context }}" + scope: "{{ scope }}" + cmci_host: "{{ cmci_host }}" + cmci_port: "{{ cmci_port | int }}" + cmci_user: "{{ cmci_user | default(omit) }}" + cmci_password: "{{ cmci_password | default(omit) }}" + scheme: "{{ scheme }}" + action_name: TAGSREFR + type: CICSRegion diff --git a/zos_subsystems/cics/cmci/reporting/README.md b/zos_subsystems/cics/cmci/reporting/README.md index 2b9caeaf7..2ad500490 100644 --- a/zos_subsystems/cics/cmci/reporting/README.md +++ b/zos_subsystems/cics/cmci/reporting/README.md @@ -55,7 +55,7 @@ You can run the playbook without modification: ```bash ansible-playbook report.yml -```` +``` The playbook will prompt for required parameters. After parameters have been supplied, the playbook installs the CMCI module dependencies to the python environment. The playbook makes a CMCI GET request to regions in the supplied diff --git a/zos_subsystems/cics/provisioning/README.md b/zos_subsystems/cics/provisioning/README.md index 587563ac0..47cad18a0 100644 --- a/zos_subsystems/cics/provisioning/README.md +++ b/zos_subsystems/cics/provisioning/README.md @@ -1,17 +1,17 @@ # CICS Provisioning -The CICS provisioning playbook samples demonstrate how to configure and allocate the required data sets to provision and start a CICS region (with or without SMSS support), using the [latest Beta](https://galaxy.ansible.com/ui/repo/published/ibm/ibm_zos_cics/?version=1.1.0-beta.5) of the CICS Ansible collection. The deprovisioning sample, shows how to stop a running region and delete all the associated data sets. +The CICS provisioning playbook samples demonstrate how to configure and allocate the required data sets to provision and start a CICS region (with or without SMSS support), using the [latest version](https://galaxy.ansible.com/ui/repo/published/ibm/ibm_zos_cics/?version=2.1.0) of the CICS Ansible collection. The deprovisioning sample, shows how to stop a running region and delete all the associated data sets. -It is a recommended you review the playbook contents and the [Beta documentation](https://galaxy.ansible.com/ui/repo/published/ibm/ibm_zos_cics/docs/?version=1.1.0-beta.5) before executing them. +It is a recommended you review the playbook contents and the [documentation](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_cics/docs/ansible_content.html) before executing them. ## Playbook Summary -[full_provision.yml](./full_provision.yml) contains an Ansible playbook that can create all the required data sets and start a CICS region. Specify the `applid` using the vars at the top of the playbook, and check the CICS data sets in module defaults and start match those in your system. For more information on the different overrides and options available, see the [Beta documentation](https://galaxy.ansible.com/ui/repo/published/ibm/ibm_zos_cics/docs/?version=1.1.0-beta.5) +[full_provision.yml](./full_provision.yml) contains an Ansible playbook that can create all the required data sets and start a CICS region. Specify the `applid` using the vars at the top of the playbook, and check the CICS data sets in module defaults and start match those in your system. For more information on the different overrides and options available, see the [documentation](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_cics/docs/ansible_content.html) -[full_provision_smss.yml](./full_provision_smss.yml) contains an Ansible playbook that can create all the required data sets and start a CICS region with CMCI support. Specify the applid and port using the vars at the top of the playbook and check the CICS data sets in module defaults and start match those in your system. For more information on the different overrides and options available, see the [Beta documentation](https://galaxy.ansible.com/ui/repo/published/ibm/ibm_zos_cics/docs/?version=1.1.0-beta.5) +[full_provision_smss.yml](./full_provision_smss.yml) contains an Ansible playbook that can create all the required data sets and start a CICS region with CMCI support. Specify the applid and port using the vars at the top of the playbook and check the CICS data sets in module defaults and start match those in your system. For more information on the different overrides and options available, see the [documentation](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_cics/docs/ansible_content.html)) -[deprovision.yml](./deprovision.yml) contains an Ansible playbook that stops a running CICS region and removes all its data sets. Specify the `applid` and `job_id` (as output by the provisioning script) belonging to the running CICS region using the vars at the top of the playbook, and check the CICS data sets in module defaults match those in your provisioning playbook. For more information on the different overrides and options available, see the [Beta documentation](https://galaxy.ansible.com/ui/repo/published/ibm/ibm_zos_cics/docs/?version=1.1.0-beta.5) +[deprovision.yml](./deprovision.yml) contains an Ansible playbook that stops a running CICS region and removes all its data sets. Specify the `applid` belonging to the running CICS region using the vars at the top of the playbook, and check the CICS data sets in module defaults match those in your provisioning playbook. For more information on the different overrides and options available, see the [documentation](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_cics/docs/ansible_content.html) [inventory.yml](./inventories/inventory.yml) contains an ansible inventory for your provisioning. Change the ansible_host to your own LPAR/system to provision a CICS region on. It also contains the user which Ansible connects over SSH to that lpar as. Therefore change this to the user you wish to connect as, and ensure you have already setup ssh key authentication for this user on the machine you run the `ansible-playbook` command from. @@ -21,9 +21,9 @@ It is a recommended you review the playbook contents and the [Beta documentation ## Requirements - Python 3.9 or later - Ansible 2.15 or later -- ZOAU 1.3 or later +- ZOAU 1.2.X - IBM z/OS Core Ansible collection 1.9.0 or later -- IBM z/OS CICS Ansible collection 1.1.0-beta.5 +- IBM z/OS CICS Ansible collection 2.1.0 @@ -33,7 +33,7 @@ Before running the playbooks you must: - Ensure you have Ansible installed already locally - Ensure you have Python and [ZOAU](https://www.ibm.com/docs/en/zoau/1.3.x?topic=installing-zoau) installed on z/OS -- Install the latest beta version of the [CICS ansible collection](https://galaxy.ansible.com/ui/repo/published/ibm/ibm_zos_cics/) +- Install the latest version of the [CICS ansible collection](https://galaxy.ansible.com/ui/repo/published/ibm/ibm_zos_cics/) - Install the latest version of the [z/OS Core collection](https://galaxy.ansible.com/ui/repo/published/ibm/ibm_zos_core/) - Ensure all steps you normally undertake before provisioning a CICS region, such as setting up RACF permissions and activating VTAM nodes for the region have been completed - Update the `inventories/inventory.yml` and `host_var/variables.yml` to match the values for your system diff --git a/zos_subsystems/cics/provisioning/deprovision.yml b/zos_subsystems/cics/provisioning/deprovision.yml index f0277c5f2..96f58c8ce 100644 --- a/zos_subsystems/cics/provisioning/deprovision.yml +++ b/zos_subsystems/cics/provisioning/deprovision.yml @@ -7,10 +7,9 @@ vars: applid: APPLID - job_id: JOB12345 module_defaults: - group/ibm.ibm_zos_cics.region_group: + group/ibm.ibm_zos_cics.region: state: absent cics_data_sets: template: "CTS610.CICS740.<< lib_name >>" @@ -22,22 +21,22 @@ tasks: - name: Stop CICS Region - ibm.ibm_zos_cics.stop_cics: - job_id: "{{ job_id }}" + ibm.ibm_zos_cics.stop_region: + job_name: "{{ applid }}" register: result - + - name: Log output of stop ansible.builtin.debug: msg: "{{ result }}" - name: Delete the auxiliary temporary storage data set (DFHTEMP) - ibm.ibm_zos_cics.auxiliary_temp: + ibm.ibm_zos_cics.aux_temp_storage: - name: Delete the auxiliary trace data set (DFHAUXT) - ibm.ibm_zos_cics.trace: + ibm.ibm_zos_cics.aux_trace: - name: Delete the second auxiliary trace data set (DFHBUXT) - ibm.ibm_zos_cics.trace: + ibm.ibm_zos_cics.aux_trace: destination: B - name: Delete the transaction dump data set (DFHDMPA) @@ -51,7 +50,7 @@ ibm.ibm_zos_cics.csd: - name: Delete the transient data intrapartition data set (DFHINTRA) - ibm.ibm_zos_cics.intrapartition: + ibm.ibm_zos_cics.td_intrapartition: - name: Delete the local request queue data set (DFHLRQ) ibm.ibm_zos_cics.local_request_queue: @@ -61,3 +60,7 @@ - name: Delete the local catalog data set (DFHLCD) ibm.ibm_zos_cics.local_catalog: + + - name: Delete the CICS startup JCL data set (DFHSTART) + ibm.ibm_zos_cics.region_jcl: + applid: "{{ applid }}" diff --git a/zos_subsystems/cics/provisioning/files/CSDUP_script b/zos_subsystems/cics/provisioning/files/CSDUP_script index b33f94d97..fad86feca 100644 --- a/zos_subsystems/cics/provisioning/files/CSDUP_script +++ b/zos_subsystems/cics/provisioning/files/CSDUP_script @@ -1 +1,9 @@ -ADD GROUP(DFHTERMC) LIST(DFHLIST1) \ No newline at end of file +ADD GROUP(DFHTERMC) LIST(DFHLIST1) + +COPY GROUP(DFH$WU) TO(WUIGRP) + +ALTER TCPIPSERVICE(DFH$WUTC) + GROUP(WUIGRP) + PORT({{ cmci_port }}) + +ADD GROUP(WUIGRP) LIST(DFHLIST1) \ No newline at end of file diff --git a/zos_subsystems/cics/provisioning/files/CSDUP_script_smss b/zos_subsystems/cics/provisioning/files/CSDUP_script_smss deleted file mode 100644 index fad86feca..000000000 --- a/zos_subsystems/cics/provisioning/files/CSDUP_script_smss +++ /dev/null @@ -1,9 +0,0 @@ -ADD GROUP(DFHTERMC) LIST(DFHLIST1) - -COPY GROUP(DFH$WU) TO(WUIGRP) - -ALTER TCPIPSERVICE(DFH$WUTC) - GROUP(WUIGRP) - PORT({{ cmci_port }}) - -ADD GROUP(WUIGRP) LIST(DFHLIST1) \ No newline at end of file diff --git a/zos_subsystems/cics/provisioning/full_provision.yml b/zos_subsystems/cics/provisioning/full_provision.yml index 9b8aa0905..0ba266986 100644 --- a/zos_subsystems/cics/provisioning/full_provision.yml +++ b/zos_subsystems/cics/provisioning/full_provision.yml @@ -9,7 +9,7 @@ applid: APPLID module_defaults: - group/ibm.ibm_zos_cics.region_group: + group/ibm.ibm_zos_cics.region: state: initial cics_data_sets: template: "CTS610.CICS740.<< lib_name >>" @@ -21,13 +21,13 @@ tasks: - name: Create the auxiliary temporary storage data set (DFHTEMP) - ibm.ibm_zos_cics.auxiliary_temp: + ibm.ibm_zos_cics.aux_temp_storage: - name: Create the auxiliary trace data set (DFHAUXT) - ibm.ibm_zos_cics.trace: + ibm.ibm_zos_cics.aux_trace: - name: Create the second auxiliary trace data set (DFHBUXT) - ibm.ibm_zos_cics.trace: + ibm.ibm_zos_cics.aux_trace: destination: B - name: Create the transaction dump data set (DFHDMPA) @@ -40,25 +40,14 @@ - name: Create the CSD data set (DFHCSD) ibm.ibm_zos_cics.csd: - - name: Create a CSDUP script on z/OS Unix - ibm.ibm_zos_core.zos_copy: - src: "{{ playbook_dir }}/files/CSDUP_script" - dest: "/u/{{ ansible_user | lower }}/csdup_script/script" - use_template: true - - name: Update the CSD data set with the CSDUP script ibm.ibm_zos_cics.csd: - state: script - script_location: USS - script_src: "/u/{{ ansible_user | lower }}/csdup_script/script" - - - name: Remove CSDUP script directory and file - ansible.builtin.file: - path: "/u/{{ ansible_user | lower }}/csdup_script" - state: absent + state: changed + input_location: INLINE + input_content: ADD GROUP(DFHTERMC) LIST(DFHLIST1) - name: Create the transient data intrapartition data set (DFHINTRA) - ibm.ibm_zos_cics.intrapartition: + ibm.ibm_zos_cics.td_intrapartition: - name: Create the local request queue data set (DFHLRQ) ibm.ibm_zos_cics.local_request_queue: @@ -69,9 +58,8 @@ - name: Create the local catalog data set (DFHLCD) ibm.ibm_zos_cics.local_catalog: - - name: Start CICS Region - ibm.ibm_zos_cics.start_cics: - submit_jcl: true + - name: Create CICS startup JCL data set (DFHSTART) + ibm.ibm_zos_cics.region_jcl: applid: "{{ applid }}" job_parameters: region: 0M @@ -82,13 +70,14 @@ cicssvc: 217 edsalim: 500M grplist: (DFHLIST*) - gmtext: '''Region provisioned with Ansible''' + gmtext: Region provisioned with Ansible srbsvc: 218 tcpip: "NO" usshome: /cics/cics740 sysidnt: ZPY1 register: result - - name: Output start CICS JCL - ansible.builtin.debug: - msg: "{{ result }}" \ No newline at end of file + - name: Submit region JCL + ansible.builtin.command: + cmd: jsub "{{ ansible_user }}.REGIONS.{{ applid }}.DFHSTART" + changed_when: true diff --git a/zos_subsystems/cics/provisioning/full_provision_smss.yml b/zos_subsystems/cics/provisioning/full_provision_smss.yml index 5d47bbf56..b3411ae05 100644 --- a/zos_subsystems/cics/provisioning/full_provision_smss.yml +++ b/zos_subsystems/cics/provisioning/full_provision_smss.yml @@ -10,25 +10,27 @@ cmci_port: 27000 module_defaults: - group/ibm.ibm_zos_cics.region_group: + group/ibm.ibm_zos_cics.region: state: initial cics_data_sets: - template: "CTS610.CICS740.<< lib_name >>" - sdfhlic: "CTS610.CICS740.LIC.SDFHLIC" + template: CTS610.CICS740.<< lib_name >> + sdfhlic: CTS610.CICS740.LIC.SDFHLIC region_data_sets: template: "{{ ansible_user }}.REGIONS.{{ applid }}.<< data_set_name >>" le_data_sets: template: "CEE.<< lib_name >>" + cpsm_data_sets: + template: CTS610.CPSM610.<< lib_name >> tasks: - name: Create the auxiliary temporary storage data set (DFHTEMP) - ibm.ibm_zos_cics.auxiliary_temp: + ibm.ibm_zos_cics.aux_temp_storage: - name: Create the auxiliary trace data set (DFHAUXT) - ibm.ibm_zos_cics.trace: + ibm.ibm_zos_cics.aux_trace: - name: Create the second auxiliary trace data set (DFHBUXT) - ibm.ibm_zos_cics.trace: + ibm.ibm_zos_cics.aux_trace: destination: B - name: Create the transaction dump data set (DFHDMPA) @@ -41,26 +43,27 @@ - name: Create the CSD data set (DFHCSD) ibm.ibm_zos_cics.csd: - - name: Create a CSDUP script on z/OS Unix - ibm.ibm_zos_core.zos_copy: - src: "{{ playbook_dir }}/files/CSDUP_script_smss" - dest: "/u/{{ ansible_user | lower }}/csdup_script/script" - use_template: true + - name: Template the port into CSDUP script + ansible.builtin.template: + src: "{{ playbook_dir }}/files/CSDUP_script" + dest: "{{ playbook_dir }}/files/CSDUP_script_templated" + mode: "644" + delegate_to: localhost - name: Update the CSD data set with the CSDUP script ibm.ibm_zos_cics.csd: - state: script - script_location: USS - script_src: "/u/{{ ansible_user | lower }}/csdup_script/script" - ignore_errors: true + state: changed + input_location: LOCAL + input_src: "{{ playbook_dir }}/files/CSDUP_script_templated" - - name: Remove CSDUP script directory and file + - name: Delete the templated CSDUP script ansible.builtin.file: - path: "/u/{{ ansible_user | lower }}/csdup_script" + path: "{{ playbook_dir }}/files/CSDUP_script_templated" state: absent + delegate_to: localhost - name: Create the transient data intrapartition data set (DFHINTRA) - ibm.ibm_zos_cics.intrapartition: + ibm.ibm_zos_cics.td_intrapartition: - name: Create the local request queue data set (DFHLRQ) ibm.ibm_zos_cics.local_request_queue: @@ -71,16 +74,9 @@ - name: Create the local catalog data set (DFHLCD) ibm.ibm_zos_cics.local_catalog: - - name: Start CICS Region - ibm.ibm_zos_cics.start_cics: - submit_jcl: true + - name: Create CICS startup JCL data set (DFHSTART) + ibm.ibm_zos_cics.region_jcl: applid: "{{ applid }}" - steplib: - top_libraries: - - CTS610.CPSM610.SEYUAUTH - dfhrpl: - top_libraries: - - CTS610.CPSM610.SEYULOAD job_parameters: region: 0M sit_parameters: @@ -88,9 +84,10 @@ sit: 6$ aicons: AUTO cicssvc: 217 + csdrecov: "NONE" edsalim: 500M grplist: (DFHLIST*) - gmtext: '''Region provisioned with Ansible''' + gmtext: Region provisioned with Ansible srbsvc: 218 tcpip: "YES" usshome: /cics/cics740 @@ -99,6 +96,7 @@ sec: "NO" register: result - - name: Output start CICS JCL - ansible.builtin.debug: - msg: "{{ result }}" \ No newline at end of file + - name: Submit region JCL + ansible.builtin.command: + cmd: jsub "{{ ansible_user }}.REGIONS.{{ applid }}.DFHSTART" + changed_when: true