diff --git a/README.md b/README.md index b796f106..dbfdc770 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,7 @@ often repeated and in need of automation. - [Dump, Archive, Fetch, Copy and Unarchive Data Sets](zos_concepts/data_transfer/archive_copy_unarchive_restore) - [Transfer, Dump and Unpack Data Sets](zos_concepts/data_transfer/dump_pack_ftp_unpack_restore) - [Grow ZFS aggregates](zos_concepts/zfsadm/zfs_grow_aggr) + - [Grow ZFS fetch full trace back](zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back) - [Copy templates to z/OS](zos_concepts/templates/copy_template) - [Use templated job cards and JCL to submit jobs](zos_concepts/templates/submit_job_template) - [Use templates for compiling and linking libraries](zos_concepts/templates/loadlib) @@ -113,6 +114,7 @@ often repeated and in need of automation. - [Security validation](zos_management/zosmf_security_configuration_assistant) - [Security audit](zos_management/zosmf_security_configuration_assistant) - [Security provision](zos_management/zosmf_security_configuration_assistant) + - [Shrink on different size and see full verbose](zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose) ## Blogs diff --git a/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/README.md b/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/README.md new file mode 100644 index 00000000..a5843427 --- /dev/null +++ b/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/README.md @@ -0,0 +1,66 @@ +# Create, grow ZFS aggregate with trace back and fetch the trace member. +This playbook demonstrates how to grow a ZFS aggregate on z/OS using Red Hat +Ansible Certified Content for IBM Z. + +This playbook uses: + - collection: + - ibm.ibm_zos_core + - modules: + - zos_data_set + - zos_mount + - zos_zfs_resize + - zos_fetch + +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. + +## Playbook Requirements +This playbook requires: + +- [IBM® z/OS® core collection 1.13.0 or later](https://galaxy.ansible.com/ibm/ibm_zos_core) +- [Ansible® 2.16 or later](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) + +## Configuration +- Configure the included [inventory.yml](inventories/inventory.yml) with the + information from the managed z/OS host. + - Review [inventory documentation](../../../docs/share/zos_core/configure_inventory.md) +- Configure the included **host_vars** [zos_host.yml](inventories/host_vars/zos_host.yml) + with the information from your z/OS system. + - Review [host_vars documentation](../../../docs/share/zos_core/configure_host_vars.md) + and any additional noted variables in the configuration. + +## Run the playbook +This project has included a `site.yml` playbook that serves as the primary playbook +that provides additional prerequisite checks then it invokes the `grow_zfs_fetch_trace_back.yml` +playbook. + +If you want to run the primary playbook `site.yml` it will check that your environment +has the correct version of Ansible as well as the collection needed to execute +correctly. To run the primary playbook, use command: + +```bash +ansible-playbook -i inventories site.yml +``` + +You can skip the prerequisite check and run the `grow_zfs_fetch_trace_back.yml` with +command: + +```bash +ansible-playbook -i inventories grow_zfs_fetch_trace_back.yml +``` + +# Changelog +All changes are maintained chronologically by date found in the +[changelog](changelog.yml). + +# Copyright +© Copyright IBM Corporation 2022 + +# License +Licensed under [Apache License, +Version 2.0](https://opensource.org/licenses/Apache-2.0). + +# Support +Please refer to the [support section](../../../README.md#support) for more +details. diff --git a/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/ansible.cfg b/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/ansible.cfg new file mode 100644 index 00000000..157184a9 --- /dev/null +++ b/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/ansible.cfg @@ -0,0 +1,18 @@ +################################################################################ +# Copyright (c) IBM Corporation 2025 +################################################################################ + +################################################################################ +# Minimum required configuration for this playbook. +# For additional `ansible.cfg` configuration options, review: +# https://docs.ansible.com/ansible/latest/reference_appendices/config.html +# https://github.com/ansible/ansible/blob/devel/examples/ansible.cfg +################################################################################ + +[defaults] +forks = 25 +roles_path = ../../../roles:.. + +[ssh_connection] +pipelining = True + diff --git a/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/changelog.yml b/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/changelog.yml new file mode 100644 index 00000000..44d57036 --- /dev/null +++ b/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/changelog.yml @@ -0,0 +1,33 @@ +################################################################################ +# Copyright (c) IBM Corporation 2025 +# +# 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 +# repository. +# +# releases: +# 2025.01.06: +# date: 2025-01-06 +# changes: +# added: +# - new features are added +# deprecated: +# - features being removed in the future +# fixed: +# - bug fixes +# minor: +# - changes in existing functionality +# removed: +# - features removed no longer available +# security: +# - vulnerabilities fixed +# summary: +# - summary of changes or link to Git issue, pull request +################################################################################ + +releases: + 2025.01.06: + date: 2025-01-01 + changes: + added: + - Released initial version diff --git a/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/grow_zfs_fetch_trace_back.yml b/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/grow_zfs_fetch_trace_back.yml new file mode 100644 index 00000000..41c26594 --- /dev/null +++ b/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/grow_zfs_fetch_trace_back.yml @@ -0,0 +1,160 @@ +############################################################################### +# © Copyright IBM Corporation 2025 +############################################################################### + +############################################################################### +# This sample playbook demonstrates how to create a new Generation Data Group(GDG), +# add text content to a Generation Data Set(GDS), copy to another +# Generation Data Group(GDG), edit the copy and fetch the content. +# +# Usage: +# ansible-playbook -i +# +# Example: +# ansible-playbook -i inventories copy_edit_submit.yml +# +# When running this playbook, review the comments on how ths sample will +# interact with your target, ensure you have the required authority and +# permissions such as writing the the target directories or creating data sets. +# +# Requirements: +# - IBM z/OS core collection 1.13.0 or later +# +############################################################################### + +--- +- hosts: zos_host + collections: + - ibm.ibm_zos_core + gather_facts: false + environment: "{{ environment_vars }}" + vars: + mount_point: "/tmp/zfs_aggr" + aggr_growth_size: 2000 + + tasks: + # ########################################################################## + # Generate a temporary data set names + # ########################################################################## + - name: Create temp data set name + command: "mvstmp {{ ansible_user | upper }}" + register: tmp_ds1 + + - name: Create temp data set name + command: "mvstmp {{ ansible_user | upper }}" + register: tmp_ds2 + + - set_fact: + zfs_data_set: "{{ tmp_ds1.stdout }}" + trace_back_data_set: "{{ tmp_ds2.stdout }}" + trace_back_data_set_mem: "{{ tmp_ds2.stdout }}(MEM)" + + # ########################################################################## + # Modules: zos_data_set, zos_zfs_resize, zos_fetch + # ########################################################################## + # +------------------------------------------------------------------------- + # | - Using zos_data_set, create zfs data set {{ zfs_data_set }}. + # | - Using zos_mount, mount zfs {{ zfs_data_set }} on {{ mount_point }}. + # | - Using zos_data_set, create pds data set to generate a member. + # | - Using zos_data_set, create a member to get the full trace back. + # | - Using zos_zfs_resize, resize data set {{ zfs_data_set }}. + # | - Using zos_fetch, to fetch the trace back member of the grow operation. + # +------------------------------------------------------------------------- + + # ########################################################################## + # Create and Mount ZFS data set. + # ########################################################################## + + - name: "Create ZFS." + zos_data_set: + name: "{{ zfs_data_set }}" + type: zfs + space_primary: 1 + space_type: m + replace: true + + - name: "Create mount dir on z/OS USS." + file: + path: "{{ mount_point }}" + state: directory + + - name: "Mount ZFS data set." + zos_mount: + src: "{{ zfs_data_set | upper }}" + path: "{{ mount_point }}" + fs_type: zfs + state: mounted + + - name: "Confirm mount point." + command: "df /{{ mount_point }}" + register: df_output + + - name: "Echo df output." + debug: + msg: "{{ df_output.stdout_lines }}" + + # ########################################################################## + # Create PDS data set and member for get the full trace back. + # ########################################################################## + + - name: "Create data set to trace." + zos_data_set: + name: "{{ trace_back_data_set }}" + record_length: 200 + type: pds + + - name: "Create member of data set to trace." + zos_data_set: + name: "{{ trace_back_data_set_mem }}" + type: member + + # ########################################################################## + # Fill up ZFS aggregate with random data. + # ########################################################################## + + - name: "Write 1 million bytes to ZFS." + shell: head -c 1000000 /dev/urandom > {{ mount_point }}/test.txt + + # ########################################################################## + # Grow ZFS aggregate. + # See the full stdout. + # Fetch the full trace back + # ########################################################################## + + - name: "Grow ZFS aggregate and get trace back on data set {{ trace_back_data_set }}." + zos_zfs_resize: + target: "{{ zfs_data_set }}" + size: "{{ aggr_growth_size }}" + trace_destination: "{{ trace_back_data_set_mem }}" + register: grow_output + + - name: Echo grow_output. + debug: + msg: "{{ grow_output }}" + + - name: "Fetch {{ trace_back_data_set }} to the local controller." + zos_fetch: + src: "{{ trace_back_data_set_mem }}" + dest: "{{ playbook_dir }}/" + register: fetch_result + + - name: "Result of Fetch {{ trace_back_data_set_mem }} to the local machine." + debug: + msg: "{{ fetch_result }}" + + # ########################################################################## + # clean up - unmount and delete ZFS data sets + # ########################################################################## + + - name: Unmount ZFS data set. + command: "/usr/sbin/unmount {{ mount_point }}" + + - name: Delete ZFS data set. + zos_data_set: + name: "{{ zfs_data_set }}" + state: absent + + - name: Delete trace_dataset. + zos_data_set: + name: "{{ trace_back_data_set }}" + state: absent \ No newline at end of file diff --git a/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/inventories/group_vars/all.yml b/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/inventories/group_vars/all.yml new file mode 100644 index 00000000..95b24492 --- /dev/null +++ b/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/inventories/group_vars/all.yml @@ -0,0 +1,52 @@ +################################################################################ +# Copyright (c) IBM Corporation 2025 +################################################################################ + +################################################################################ +# Enviroment variables for all z/OS managed nodes (target) that do not need +# further configuration. +################################################################################ +environment_vars: + _BPXK_AUTOCVT: "ON" + ZOAU_HOME: "{{ ZOAU }}" + PYTHONPATH: "{{ ZOAU_PYTHON_LIBRARY_PATH }}" + LIBPATH: "{{ ZOAU }}/lib:{{ PYZ }}/lib:/lib:/usr/lib:." + PATH: "{{ ZOAU }}/bin:{{ PYZ }}/bin:/bin:/var/bin" + _CEE_RUNOPTS: "FILETAG(AUTOCVT,AUTOTAG) POSIX(ON)" + _TAG_REDIR_ERR: "txt" + _TAG_REDIR_IN: "txt" + _TAG_REDIR_OUT: "txt" + LANG: "C" + PYTHONSTDINENCODING: "cp1047" + +################################################################################ +# Description of the properties used in this configuration: +################################################################################ +# - Property BPXK_AUTOCVT must be configured to "ON"; e.g., _BPXK_AUTOCVT: "ON" +# - Property ZOAU_HOME is the Z Open Automation Utilities (ZOAU) install root path; +# e.g., ZOAU_HOME: "/usr/lpp/IBM/zoautil" +# - Property PYTHONPATH is the Z Open Automation Utilities (ZOAU) Python library path; +# e.g., PYTHONPATH: "/usr/lpp/IBM/zoautil/lib" +# - Property LIBPATH is both the path to the Python libraries on the target +# and the Z Open Automation Utilities (ZOAU) Python library path separated by semi-colons; e.g., +# LIBPATH: "/usr/lpp/IBM/zoautil/lib/:/usr/lpp/IBM/cyp/v3r8/pyz/lib:/usr/lib:/lib:." +# - Property PATH is the ZOA utilities BIN path and Python interpreter path, e.g., +# PATH: "/usr/lpp/IBM/zoautil/bin:/usr/lpp/IBM/cyp/v3r8/pyz/bin:/bin" +# - Property _CEE_RUNOPTS is the invocation Language Environment® runtime +# options for programs and used by Python. e.g., +# _CEE_RUNOPTS: "FILETAG(AUTOCVT,AUTOTAG) POSIX(ON)" +# - Properties __TAG_REDIR_ERR, _TAG_REDIR_IN, _TAG_REDIR_OUT are txt and used +# by the shell; e.g., +# _TAG_REDIR_ERR: "txt" +# _TAG_REDIR_IN: "txt" +# _TAG_REDIR_OUT: "txt" +# - Property LANG is the name of the default locale; value +# C specifies the POSIX locale; for example: ``LANG: "C"``. +# - Property `PYTHONSTDINENCODING` should be set to the encoding Unix System Services +# is configured as, supported encodings are ASCII or EBCDIC. This environment +# variable is used to instruct Ansible which encoding it will *pipe* content to +# Python's STDIN (standard in) when `pipelining=true` is set in `ansible.cfg` . +# This environment variable will only apply when using IBM Enterprise Python +# 3.10 or later, otherwise, it is ignored. +# For example:`PYTHONSTDINENCODING: "cp1047"`. +################################################################################ diff --git a/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/inventories/host_vars/zos_host.yml b/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/inventories/host_vars/zos_host.yml new file mode 100644 index 00000000..2e6c0df0 --- /dev/null +++ b/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/inventories/host_vars/zos_host.yml @@ -0,0 +1,64 @@ +--- +################################################################################ +# Copyright (c) IBM Corporation 2025 +################################################################################ + +################################################################################ +# Description of the properties used in this configuration: +# - Property `PYZ` is the python installation home path on the z/OS managed +# (target) node e.g, PYZ: "/usr/lpp/IBM/cyp/v3r12/pyz" +# - Property `PYZ_VERSION` is the version of python on the z/OS managed +# (target) node e.g, PYZ_VERSION: "3.12". +# - Property `ZOAU` is the ZOAU installation home on the z/OS managed (target) +# node, e.g, ZOAU: "/usr/lpp/IBM/zoautil". +# - Property `ZOAU_PYTHON_LIBRARY_PATH` is the path to the Z Open Automation +# Utilities (ZOAU) python library. Specifically, the path points to the +# directory containing 'zoautil_py'. Packages installed using 'pip' generally +# default to the 'site-packages' directory within the python installation, +# eg "/usr/lpp/IBM/cyp/v3r12/pyz/lib/python3.12/site-packages/". +# If the installation uses options such as '--user' or '--target', the module +# is installed to a non-default location which must be configured in +# `ZOAU_PYTHON_LIBRARY_PATH`. +# If the wheel installation method is used with the '--target' or '--user' +# option, `ZOAU_PYTHON_LIBRARY_PATH` should point to the directory the wheel +# file was installed to. e.g ZOAU_PYTHON_LIBRARY_PATH: "/usr/zoau-wheel/". +# Else 'ZOAU_PYTHON_LIBRARY_PATH' should point to the directory containing +# the pre-compiled binary. +# For ZOAU v1.2.x, the pre-compiled binary is located in the 'lib' directory. +# e.g "/usr/lpp/IBM/zoautil/lib" or "{{ ZOAU }}/lib". +# For ZOAU v1.3.x, the pre-compiled binary is located in a sub-directory +# corresponding to the `PYZ_VERSION` inside the 'lib' directory, +# e.g "/usr/lpp/IBM/zoautil/lib/3.12" or "{{ ZOAU }}/lib/{{ PYZ_VERSION }}". +# - 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, PYZ_VERSION, and ZOAU environment variables must be configured. +################################################################################ + +PYZ: "path_to_python_installation_on_zos_target" +PYZ_VERSION: "3.xx" + +ZOAU: "path_to_zoau_installation_on_zos_target" + +# Configuring the `ZOAU_PYTHON_LIBRARY_PATH` property is required. + +# If the ZOAU python package, zoautil_py, has been installed as a wheel (*.whl) +# with the '--target' or '--user' option, uncomment the following line: +# ZOAU_PYTHON_LIBRARY_PATH: "{{ path_to_wheel_installation_directory }}" + +# If the ZOAU python zoautil_py package has been installed in the default location +# that is part of Python's search path, the `ZOAU_PYTHON_LIBRARY_PATH` environment +# variable must be set as an empty string. Uncomment the following line: +# ZOAU_PYTHON_LIBRARY_PATH: "" + +# If using pre-compiled binaries for ZOAU v1.3.x, uncomment the following line: +# ZOAU_PYTHON_LIBRARY_PATH: "{{ ZOAU }}/lib/{{ PYZ_VERSION }}" + +# If using pre-compiled binaries for ZOAU v1.2.x, uncomment the following line: +# ZOAU_PYTHON_LIBRARY_PATH: "{{ ZOAU }}/lib" + +################################################################################ +# Do not configure, variable substitution will correctly set the +# variable `ansible_python_interpreter` +################################################################################ +ansible_python_interpreter: "{{ PYZ }}/bin/python3" diff --git a/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/inventories/inventory.yml b/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/inventories/inventory.yml new file mode 100644 index 00000000..7ce7a4d0 --- /dev/null +++ b/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/inventories/inventory.yml @@ -0,0 +1,17 @@ +################################################################################ +# © Copyright IBM Corporation 2025 +################################################################################ + +################################################################################ +# Description of the properties used in this configuration: +# - Property `ansible_host` is the z/OS managed node (target), +# e.g, ansible_host: "zvm1.vmec.svl.ibm.com" +# - Property `ansible_user` is the z/OS managed user to connect and run as over SSH, +# e.g, ansible_user: "zosadm" +################################################################################ + +source_system: + hosts: + zos_host: + ansible_host: zos_target_address + ansible_user: zos_target_username diff --git a/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/runtime-requirements.yml b/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/runtime-requirements.yml new file mode 100644 index 00000000..e6cbec03 --- /dev/null +++ b/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/runtime-requirements.yml @@ -0,0 +1,30 @@ +################################################################################ +# Copyright (c) IBM Corporation 2025 +################################################################################ + +################################################################################ +# List `requires_ansible_version` contains Ansible version entries that this +# playbook requires. It can be one more then one Ansible version +# e.g, `- 2.9` would be interpreted as 2.9 - 2.9.n where n is >= 0. Where `- 2.9.0` +# would be require an exact match, just like 2.9.12 would be an exact match. +# +# Dictionary `requires_collection` can include more than one collection such as +# in the case a playbook depends on other IBM z collections. +# e.g, +# requires_collection: +# - ibm_zos_core: +# name: "ibm_zos_core" +# version: "1.4.0-beta.1" +# - ibm_zos_ims: +# name: "ibm_zos_ims" +# version: "1.4.0-beta.1" +################################################################################ + +requires_ansible_version: + - "2.16" + - "2.17" + +requires_collection: + - ibm_zos_core: + name: "ibm_zos_core" + version: "1.13.0" diff --git a/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/site.yml b/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/site.yml new file mode 100644 index 00000000..ff4fa2f8 --- /dev/null +++ b/zos_concepts/zfsadm/grow_zfs_fetch_full_trace_back/site.yml @@ -0,0 +1,34 @@ +############################################################################### +# © Copyright IBM Corporation 2025 +############################################################################### + +############################################################################### +# This playbook (`site.yml`) is the master playbook for this project. Based on +# the playbooks requirments, `site.yml` playbook will evalute the requirements +# and report when the minimum requirements are not configured and fail playbook +# execution. +# +# Upon successful dependency analyais, the z/OS playbook will be executed. +# +# Usage: +# ansible-playbook -i +# +# Example: +# ansible-playbook -i inventories site.yml +# ansible-playbook -i inventories site.yml -v +############################################################################### + + +--- +- hosts: localhost + + tasks: + - name: Parse the registry for collection entries + include_vars: runtime-requirements.yml + + - name: Display the registered collections and properites in `registry.yml`. + include_role: + name: requirements-check + +- name: Executing the z/OS Ansible playbook + import_playbook: grow_zfs_aggregate_fetch_trace_back.yml diff --git a/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/README.md b/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/README.md new file mode 100644 index 00000000..76abcbb8 --- /dev/null +++ b/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/README.md @@ -0,0 +1,65 @@ +# Create, shrink ZFS aggregate with different size and see verbose. +This playbook demonstrates how to grow a ZFS aggregate on z/OS using Red Hat +Ansible Certified Content for IBM Z. + +This playbook uses: + - collection: + - ibm.ibm_zos_core + - modules: + - zos_data_set + - zos_mount + - zos_zfs_resize + +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. + +## Playbook Requirements +This playbook requires: + +- [IBM® z/OS® core collection 1.13.0 or later](https://galaxy.ansible.com/ibm/ibm_zos_core) +- [Ansible® 2.16 or later](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) + +## Configuration +- Configure the included [inventory.yml](inventories/inventory.yml) with the + information from the managed z/OS host. + - Review [inventory documentation](../../../docs/share/zos_core/configure_inventory.md) +- Configure the included **host_vars** [zos_host.yml](inventories/host_vars/zos_host.yml) + with the information from your z/OS system. + - Review [host_vars documentation](../../../docs/share/zos_core/configure_host_vars.md) + and any additional noted variables in the configuration. + +## Run the playbook +This project has included a `site.yml` playbook that serves as the primary playbook +that provides additional prerequisite checks then it invokes the `shrink_zfs_different_size_and_verbose.yml` +playbook. + +If you want to run the primary playbook `site.yml` it will check that your environment +has the correct version of Ansible as well as the collection needed to execute +correctly. To run the primary playbook, use command: + +```bash +ansible-playbook -i inventories site.yml +``` + +You can skip the prerequisite check and run the `shrink_zfs_different_size_and_verbose.yml` with +command: + +```bash +ansible-playbook -i inventories shrink_zfs_different_size_and_verbose.yml +``` + +# Changelog +All changes are maintained chronologically by date found in the +[changelog](changelog.yml). + +# Copyright +© Copyright IBM Corporation 2022 + +# License +Licensed under [Apache License, +Version 2.0](https://opensource.org/licenses/Apache-2.0). + +# Support +Please refer to the [support section](../../../README.md#support) for more +details. diff --git a/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/ansible.cfg b/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/ansible.cfg new file mode 100644 index 00000000..157184a9 --- /dev/null +++ b/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/ansible.cfg @@ -0,0 +1,18 @@ +################################################################################ +# Copyright (c) IBM Corporation 2025 +################################################################################ + +################################################################################ +# Minimum required configuration for this playbook. +# For additional `ansible.cfg` configuration options, review: +# https://docs.ansible.com/ansible/latest/reference_appendices/config.html +# https://github.com/ansible/ansible/blob/devel/examples/ansible.cfg +################################################################################ + +[defaults] +forks = 25 +roles_path = ../../../roles:.. + +[ssh_connection] +pipelining = True + diff --git a/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/changelog.yml b/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/changelog.yml new file mode 100644 index 00000000..44d57036 --- /dev/null +++ b/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/changelog.yml @@ -0,0 +1,33 @@ +################################################################################ +# Copyright (c) IBM Corporation 2025 +# +# 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 +# repository. +# +# releases: +# 2025.01.06: +# date: 2025-01-06 +# changes: +# added: +# - new features are added +# deprecated: +# - features being removed in the future +# fixed: +# - bug fixes +# minor: +# - changes in existing functionality +# removed: +# - features removed no longer available +# security: +# - vulnerabilities fixed +# summary: +# - summary of changes or link to Git issue, pull request +################################################################################ + +releases: + 2025.01.06: + date: 2025-01-01 + changes: + added: + - Released initial version diff --git a/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/inventories/group_vars/all.yml b/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/inventories/group_vars/all.yml new file mode 100644 index 00000000..95b24492 --- /dev/null +++ b/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/inventories/group_vars/all.yml @@ -0,0 +1,52 @@ +################################################################################ +# Copyright (c) IBM Corporation 2025 +################################################################################ + +################################################################################ +# Enviroment variables for all z/OS managed nodes (target) that do not need +# further configuration. +################################################################################ +environment_vars: + _BPXK_AUTOCVT: "ON" + ZOAU_HOME: "{{ ZOAU }}" + PYTHONPATH: "{{ ZOAU_PYTHON_LIBRARY_PATH }}" + LIBPATH: "{{ ZOAU }}/lib:{{ PYZ }}/lib:/lib:/usr/lib:." + PATH: "{{ ZOAU }}/bin:{{ PYZ }}/bin:/bin:/var/bin" + _CEE_RUNOPTS: "FILETAG(AUTOCVT,AUTOTAG) POSIX(ON)" + _TAG_REDIR_ERR: "txt" + _TAG_REDIR_IN: "txt" + _TAG_REDIR_OUT: "txt" + LANG: "C" + PYTHONSTDINENCODING: "cp1047" + +################################################################################ +# Description of the properties used in this configuration: +################################################################################ +# - Property BPXK_AUTOCVT must be configured to "ON"; e.g., _BPXK_AUTOCVT: "ON" +# - Property ZOAU_HOME is the Z Open Automation Utilities (ZOAU) install root path; +# e.g., ZOAU_HOME: "/usr/lpp/IBM/zoautil" +# - Property PYTHONPATH is the Z Open Automation Utilities (ZOAU) Python library path; +# e.g., PYTHONPATH: "/usr/lpp/IBM/zoautil/lib" +# - Property LIBPATH is both the path to the Python libraries on the target +# and the Z Open Automation Utilities (ZOAU) Python library path separated by semi-colons; e.g., +# LIBPATH: "/usr/lpp/IBM/zoautil/lib/:/usr/lpp/IBM/cyp/v3r8/pyz/lib:/usr/lib:/lib:." +# - Property PATH is the ZOA utilities BIN path and Python interpreter path, e.g., +# PATH: "/usr/lpp/IBM/zoautil/bin:/usr/lpp/IBM/cyp/v3r8/pyz/bin:/bin" +# - Property _CEE_RUNOPTS is the invocation Language Environment® runtime +# options for programs and used by Python. e.g., +# _CEE_RUNOPTS: "FILETAG(AUTOCVT,AUTOTAG) POSIX(ON)" +# - Properties __TAG_REDIR_ERR, _TAG_REDIR_IN, _TAG_REDIR_OUT are txt and used +# by the shell; e.g., +# _TAG_REDIR_ERR: "txt" +# _TAG_REDIR_IN: "txt" +# _TAG_REDIR_OUT: "txt" +# - Property LANG is the name of the default locale; value +# C specifies the POSIX locale; for example: ``LANG: "C"``. +# - Property `PYTHONSTDINENCODING` should be set to the encoding Unix System Services +# is configured as, supported encodings are ASCII or EBCDIC. This environment +# variable is used to instruct Ansible which encoding it will *pipe* content to +# Python's STDIN (standard in) when `pipelining=true` is set in `ansible.cfg` . +# This environment variable will only apply when using IBM Enterprise Python +# 3.10 or later, otherwise, it is ignored. +# For example:`PYTHONSTDINENCODING: "cp1047"`. +################################################################################ diff --git a/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/inventories/host_vars/zos_host.yml b/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/inventories/host_vars/zos_host.yml new file mode 100644 index 00000000..2e6c0df0 --- /dev/null +++ b/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/inventories/host_vars/zos_host.yml @@ -0,0 +1,64 @@ +--- +################################################################################ +# Copyright (c) IBM Corporation 2025 +################################################################################ + +################################################################################ +# Description of the properties used in this configuration: +# - Property `PYZ` is the python installation home path on the z/OS managed +# (target) node e.g, PYZ: "/usr/lpp/IBM/cyp/v3r12/pyz" +# - Property `PYZ_VERSION` is the version of python on the z/OS managed +# (target) node e.g, PYZ_VERSION: "3.12". +# - Property `ZOAU` is the ZOAU installation home on the z/OS managed (target) +# node, e.g, ZOAU: "/usr/lpp/IBM/zoautil". +# - Property `ZOAU_PYTHON_LIBRARY_PATH` is the path to the Z Open Automation +# Utilities (ZOAU) python library. Specifically, the path points to the +# directory containing 'zoautil_py'. Packages installed using 'pip' generally +# default to the 'site-packages' directory within the python installation, +# eg "/usr/lpp/IBM/cyp/v3r12/pyz/lib/python3.12/site-packages/". +# If the installation uses options such as '--user' or '--target', the module +# is installed to a non-default location which must be configured in +# `ZOAU_PYTHON_LIBRARY_PATH`. +# If the wheel installation method is used with the '--target' or '--user' +# option, `ZOAU_PYTHON_LIBRARY_PATH` should point to the directory the wheel +# file was installed to. e.g ZOAU_PYTHON_LIBRARY_PATH: "/usr/zoau-wheel/". +# Else 'ZOAU_PYTHON_LIBRARY_PATH' should point to the directory containing +# the pre-compiled binary. +# For ZOAU v1.2.x, the pre-compiled binary is located in the 'lib' directory. +# e.g "/usr/lpp/IBM/zoautil/lib" or "{{ ZOAU }}/lib". +# For ZOAU v1.3.x, the pre-compiled binary is located in a sub-directory +# corresponding to the `PYZ_VERSION` inside the 'lib' directory, +# e.g "/usr/lpp/IBM/zoautil/lib/3.12" or "{{ ZOAU }}/lib/{{ PYZ_VERSION }}". +# - 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, PYZ_VERSION, and ZOAU environment variables must be configured. +################################################################################ + +PYZ: "path_to_python_installation_on_zos_target" +PYZ_VERSION: "3.xx" + +ZOAU: "path_to_zoau_installation_on_zos_target" + +# Configuring the `ZOAU_PYTHON_LIBRARY_PATH` property is required. + +# If the ZOAU python package, zoautil_py, has been installed as a wheel (*.whl) +# with the '--target' or '--user' option, uncomment the following line: +# ZOAU_PYTHON_LIBRARY_PATH: "{{ path_to_wheel_installation_directory }}" + +# If the ZOAU python zoautil_py package has been installed in the default location +# that is part of Python's search path, the `ZOAU_PYTHON_LIBRARY_PATH` environment +# variable must be set as an empty string. Uncomment the following line: +# ZOAU_PYTHON_LIBRARY_PATH: "" + +# If using pre-compiled binaries for ZOAU v1.3.x, uncomment the following line: +# ZOAU_PYTHON_LIBRARY_PATH: "{{ ZOAU }}/lib/{{ PYZ_VERSION }}" + +# If using pre-compiled binaries for ZOAU v1.2.x, uncomment the following line: +# ZOAU_PYTHON_LIBRARY_PATH: "{{ ZOAU }}/lib" + +################################################################################ +# Do not configure, variable substitution will correctly set the +# variable `ansible_python_interpreter` +################################################################################ +ansible_python_interpreter: "{{ PYZ }}/bin/python3" diff --git a/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/inventories/inventory.yml b/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/inventories/inventory.yml new file mode 100644 index 00000000..7ce7a4d0 --- /dev/null +++ b/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/inventories/inventory.yml @@ -0,0 +1,17 @@ +################################################################################ +# © Copyright IBM Corporation 2025 +################################################################################ + +################################################################################ +# Description of the properties used in this configuration: +# - Property `ansible_host` is the z/OS managed node (target), +# e.g, ansible_host: "zvm1.vmec.svl.ibm.com" +# - Property `ansible_user` is the z/OS managed user to connect and run as over SSH, +# e.g, ansible_user: "zosadm" +################################################################################ + +source_system: + hosts: + zos_host: + ansible_host: zos_target_address + ansible_user: zos_target_username diff --git a/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/runtime-requirements.yml b/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/runtime-requirements.yml new file mode 100644 index 00000000..e6cbec03 --- /dev/null +++ b/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/runtime-requirements.yml @@ -0,0 +1,30 @@ +################################################################################ +# Copyright (c) IBM Corporation 2025 +################################################################################ + +################################################################################ +# List `requires_ansible_version` contains Ansible version entries that this +# playbook requires. It can be one more then one Ansible version +# e.g, `- 2.9` would be interpreted as 2.9 - 2.9.n where n is >= 0. Where `- 2.9.0` +# would be require an exact match, just like 2.9.12 would be an exact match. +# +# Dictionary `requires_collection` can include more than one collection such as +# in the case a playbook depends on other IBM z collections. +# e.g, +# requires_collection: +# - ibm_zos_core: +# name: "ibm_zos_core" +# version: "1.4.0-beta.1" +# - ibm_zos_ims: +# name: "ibm_zos_ims" +# version: "1.4.0-beta.1" +################################################################################ + +requires_ansible_version: + - "2.16" + - "2.17" + +requires_collection: + - ibm_zos_core: + name: "ibm_zos_core" + version: "1.13.0" diff --git a/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/shrink_zfs_different_size_and_verbose.yml b/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/shrink_zfs_different_size_and_verbose.yml new file mode 100644 index 00000000..9b2d8426 --- /dev/null +++ b/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/shrink_zfs_different_size_and_verbose.yml @@ -0,0 +1,134 @@ +############################################################################### +# © Copyright IBM Corporation 2025 +############################################################################### + +############################################################################### +# This sample playbook demonstrates how to create a new Generation Data Group(GDG), +# add text content to a Generation Data Set(GDS), copy to another +# Generation Data Group(GDG), edit the copy and fetch the content. +# +# Usage: +# ansible-playbook -i +# +# Example: +# ansible-playbook -i inventories copy_edit_submit.yml +# +# When running this playbook, review the comments on how ths sample will +# interact with your target, ensure you have the required authority and +# permissions such as writing the the target directories or creating data sets. +# +# Requirements: +# - IBM z/OS core collection 1.13.0 or later +# +############################################################################### + +--- +- hosts: zos_host + collections: + - ibm.ibm_zos_core + gather_facts: false + environment: "{{ environment_vars }}" + vars: + mount_point: "/tmp/zfs_aggr" + aggr_shrink_size: 1400 + aggr_shrink_size_on_m: 2 + + tasks: + # ########################################################################## + # Generate a temporary data set name + # ########################################################################## + - name: Create temp data set name + command: "mvstmp {{ ansible_user | upper }}" + register: tmp_ds1 + + - set_fact: + zfs_data_set: "{{ tmp_ds1.stdout }}" + + # ########################################################################## + # Modules: zos_data_set, zos_zfs_resize + # ########################################################################## + # +------------------------------------------------------------------------- + # | - Using zos_data_set, create zfs data set {{ zfs_data_set }}. + # | - Using zos_mount, mount zfs {{ zfs_data_set }} on {{ mount_point }}. + # | - Using zos_zfs_resize, resize data set {{ zfs_data_set }} on m size. + # | - Using zos_zfs_resize, resize data set {{ zfs_data_set }}. + # +------------------------------------------------------------------------- + + # ########################################################################## + # Create and Mount ZFS data set. + # ########################################################################## + + - name: "Create ZFS." + zos_data_set: + name: "{{ zfs_data_set }}" + type: zfs + space_primary: 2 + space_type: m + replace: true + + - name: "Create mount dir on z/OS USS." + file: + path: "{{ mount_point }}" + state: directory + + - name: "Mount ZFS data set." + zos_mount: + src: "{{ zfs_data_set | upper }}" + path: "{{ mount_point }}" + fs_type: zfs + state: mounted + + - name: "Confirm mount point." + command: "df /{{ mount_point }}" + register: df_output + + - name: "Echo df output." + debug: + msg: "{{ df_output.stdout_lines }}" + + # ########################################################################## + # Fill up ZFS aggregate with random data. + # ########################################################################## + + - name: "Write 1 million bytes to ZFS." + shell: head -c 1000000 /dev/urandom > {{ mount_point }}/test.txt + + # ########################################################################## + # Shrink ZFS aggregate on tracks size. + # Shrink ZFS aggregate with verbose mode. + # ########################################################################## + + - name: "Shrink ZFS aggregate data set {{ zfs_data_set }} on track size." + zos_zfs_resize: + target: "{{ zfs_data_set }}" + size: "{{ aggr_shrink_size_on_m }}" + space_type: m + register: shrink_output + + - name: Echo shrink_output. + debug: + msg: "{{ shrink_output }}" + + - name: "Shrink ZFS aggregate data set {{ zfs_data_set }} and verbose mode." + zos_zfs_resize: + target: "{{ zfs_data_set }}" + size: "{{ aggr_shrink_size }}" + verbose: True + register: shrink_output + + - name: Echo shrink_output. + debug: + msg: "{{ shrink_output }}" + + # ########################################################################## + # clean up - unmount and delete ZFS data sets + # ########################################################################## + + - name: Unmount ZFS data set. + command: "/usr/sbin/unmount {{ mount_point }}" + + - name: Delete ZFS data set. + zos_data_set: + name: "{{ zfs_data_set }}" + state: absent + diff --git a/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/site.yml b/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/site.yml new file mode 100644 index 00000000..3cafbf8f --- /dev/null +++ b/zos_concepts/zfsadm/shrink_zfs_different_size_and_verbose/site.yml @@ -0,0 +1,34 @@ +############################################################################### +# © Copyright IBM Corporation 2025 +############################################################################### + +############################################################################### +# This playbook (`site.yml`) is the master playbook for this project. Based on +# the playbooks requirments, `site.yml` playbook will evalute the requirements +# and report when the minimum requirements are not configured and fail playbook +# execution. +# +# Upon successful dependency analyais, the z/OS playbook will be executed. +# +# Usage: +# ansible-playbook -i +# +# Example: +# ansible-playbook -i inventories site.yml +# ansible-playbook -i inventories site.yml -v +############################################################################### + + +--- +- hosts: localhost + + tasks: + - name: Parse the registry for collection entries + include_vars: runtime-requirements.yml + + - name: Display the registered collections and properites in `registry.yml`. + include_role: + name: requirements-check + +- name: Executing the z/OS Ansible playbook + import_playbook: shrink_zfs_different_size_and_verbose.yml