[Role][2167] A role that automatically scans the playbooks in the directory and advises of migration actions #2399

surendrababuravella · 2025-11-10T07:21:24Z

SUMMARY

A role that automatically scans the playbooks in the directory and advises of migration actions

ISSUE TYPE

Role Pull Request

COMPONENT NAME

ADDITIONAL INFORMATION

surendrababuravella · 2025-11-10T08:34:02Z

SPS pipeline results:

rexemin

It looks pretty good, this will be really useful for users migrating to v2.0.0, but I have another question: does this really need to be a new module? Everything will always run locally and you are breaking the naming convention for modules by not starting the module name with zos_, this looks more like a different type of plugin or a module utility

rexemin · 2025-11-10T16:29:17Z

plugins/modules/playbook_upgrade_validator.py

+DOCUMENTATION = r'''
+---
+module: playbook_upgrade_validator
+version_added: "1.0.0"


This should say "2.0.0"

rexemin · 2025-11-10T16:29:41Z

plugins/modules/playbook_upgrade_validator.py

+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright (c) IBM Corporation 2023, 2025


If it's a new file, the copyright should just say 2025, I think

rexemin · 2025-11-10T16:30:03Z

plugins/modules/playbook_upgrade_validator.py

+version_added: "1.0.0"
+author:
+  - "Ravella Surendra Babu (@surendrababuravella)"
+short_description: Validates playbooks against ibm_zos_core 2.0 and provides migration actions.


Suggested change

short_description: Validates playbooks against ibm_zos_core 2.0 and provides migration actions.

short_description: Validates playbooks against ibm_zos_core 2.0.0 and provides migration actions.

rexemin · 2025-11-10T16:30:42Z

plugins/modules/playbook_upgrade_validator.py

+short_description: Validates playbooks against ibm_zos_core 2.0 and provides migration actions.
+description:
+  - Scans one or more Ansible playbooks to identify deprecated or renamed parameters
+    based on migration rules for IBM z/OS core collection version 2.0.


Suggested change

based on migration rules for IBM z/OS core collection version 2.0.

based on migration rules for IBM z/OS Core collection version 2.0.0.

rexemin · 2025-11-10T16:31:45Z

plugins/modules/playbook_upgrade_validator.py

+  migration_map:
+    description:
+      - A structured set of migration rules that specifies deprecated, renamed, and modified parameters
+        to help upgrade playbooks from ibm_zos_core 1.x to 2.0.


Suggested change

to help upgrade playbooks from ibm_zos_core 1.x to 2.0.

to help upgrade playbooks from ibm_zos_core 1.x.x to 2.0.0.

rexemin · 2025-11-10T16:44:21Z

roles/playbook_upgrade_validator/tasks/main.yml

+  register: result
+  delegate_to: localhost
+
+- name: print debug data


Suggested change

- name: print debug data

- name: Print migration validation results

rexemin · 2025-11-10T16:44:34Z

roles/playbook_upgrade_validator/README.md

@@ -0,0 +1,11 @@
+# ibm.ibm_zos_core.playbook_upgrade_validator
+
+This role validates playbooks against ibm_zos_core 2.0 and provides migration actions.


Suggested change

This role validates playbooks against ibm_zos_core 2.0 and provides migration actions.

This role validates playbooks against ibm_zos_core 2.0.0 and provides migration actions.

rexemin · 2025-11-10T16:44:55Z

roles/playbook_upgrade_validator/README.md

+
+## Role Variables
+
+The only variable required is:


Suggested change

The only variable required is:

The following variables are required:

rexemin · 2025-11-10T16:45:01Z

roles/playbook_upgrade_validator/README.md

+
+The only variable required is:
+
+- `playbook_path`: The path to the directory containing one or more Ansible playbooks.


Suggested change

- `playbook_path`: The path to the directory containing one or more Ansible playbooks.

- `playbook_path`: The path to a directory containing one or more Ansible playbooks.

rexemin · 2025-11-10T16:45:10Z

roles/playbook_upgrade_validator/README.md

+The only variable required is:
+
+- `playbook_path`: The path to the directory containing one or more Ansible playbooks.
+- `output_path`: File path where validation results should be written in JSON format.


Suggested change

- `output_path`: File path where validation results should be written in JSON format.

- `output_path`: File path where validation results should be written to in JSON format.

fernandofloresg · 2025-11-10T17:30:55Z

It looks pretty good, this will be really useful for users migrating to v2.0.0, but I have another question: does this really need to be a new module? Everything will always run locally and you are breaking the naming convention for modules by not starting the module name with zos_, this looks more like a different type of plugin or a module utility

Agree with Alex on this one, this doc mentions how to add custom modules to be used in a role https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html#embedding-modules-and-plugins-in-roles

Basically, you can add them under library given the project tree:

roles/
    common/               # this hierarchy represents a "role"
        tasks/            #
            main.yml      #  <-- tasks file can include smaller files if warranted
        handlers/         #
            main.yml      #  <-- handlers file
        templates/        #  <-- files for use with the template resource
            ntp.conf.j2   #  <------- templates end in .j2
        files/            #
            bar.txt       #  <-- files for use with the copy resource
            foo.sh        #  <-- script files for use with the script resource
        vars/             #
            main.yml      #  <-- variables associated with this role
        defaults/         #
            main.yml      #  <-- default lower priority variables for this role
        meta/             #
            main.yml      #  <-- role dependencies
        library/          # roles can also include custom modules
        module_utils/     # roles can also include custom module_utils
        lookup_plugins/   # or other types of plugins, like lookup in this case

    webtier/              # same kind of structure as "common" was above, done for the webtier role
    monitoring/           # ""
    fooapp/               # ""

fernandofloresg

Asked few questions and requested a couple of tests

fernandofloresg · 2025-11-10T17:31:52Z

changelogs/fragments/2167_playbook_upgrade_validator_role.yml

@@ -0,0 +1,3 @@
+minor_changes:
+   - playbook_upgrade_validator - Adding a role that automatically scans the playbooks in the directory and advises of migration actions.


Would recommend to add this

playbook_upgrade_validator - Adding a role that automatically scans the playbooks in the directory and advises of migration actions from v1.x.x to v2.0.0.

fernandofloresg · 2025-11-10T17:34:33Z

plugins/modules/playbook_upgrade_validator.py

+    type: str
+  playbook_path:
+    description:
+      - The path to the directory containing one or more Ansible playbooks.


Question, will it analyze the playbooks recursively?

fernandofloresg · 2025-11-10T17:39:05Z

roles/playbook_upgrade_validator/files/playbook_upgrade_validator.py

+def load_playbook(path):
+    """Load playbook YAML and preserve line numbers."""
+    try:
+        from ruamel.yaml import YAML


Question, is this package included in the Red Hat Universal Base Image for Execution Environments? How complex would be for the user to install it in a EE given that this could be executed in a AAP instance?

Just saw in the role playbook that you make sure that it is installed locally, thanks

fernandofloresg · 2025-11-10T18:50:03Z

roles/playbook_upgrade_validator/tasks/main.yml

@@ -0,0 +1,30 @@
+---
+- name: Ensure ruamel.yaml is installed


Could you also uninstall it only if it was installed by this role?

fernandofloresg · 2025-11-10T18:51:43Z

tests/functional/roles/test_role_playbook_upgrade_validator.py

Could you also test with a playbook that does not include any zos_core collection tasks ? another one that calls the modules like ibm.ibm_zos_core.zos_archive too?

Tested with multiple combinations

tested a playbook containing below task:

- name: Archive data set into a terse, specify pack algorithm and use adrdssu zos_archive: src: "USER.ARCHIVE.TEST" dest: "USER.ARCHIVE.RESULT.TRS" format: name: terse format_options: terse_pack: "spack" use_adrdssu: true

Results:

{ "playbook": "/Users/surendra/Documents/GitHub/ansible/test/dataset.yml", "play_name": "executing zos_script module", "task_name": "Archive data set into a terse, specify pack algorithm and use adrdssu", "module": "zos_archive", "line": 40, "migration_actions": [ "[MUST_FIX] Param 'format.format_options' is renamed to 'format.options' in zos_archive", "[MUST_FIX] Param 'format.format_options.terse_pack' is renamed to 'format.options.spack' in zos_archive", "[MUST_FIX] Param 'format.format_options.use_adrdssu' is renamed to 'format.options.adrdssu' in zos_archive", "[MUST_FIX] Param 'format.format_options.terse_pack' type changed from 'string' to 'boolean' in zos_archive" ] }

Thanks a lot!

fernandofloresg

Looks good to me thanks!

surendrababuravella added 4 commits November 4, 2025 23:24

Adding playbook_upgrade_validator role

965ea6e

fixing sanity issues

ab87f16

Merge branch 'dev' into Enhancement/2167

ebd1e8c

add doc changes

6d8f492

surendrababuravella marked this pull request as ready for review November 10, 2025 08:30

surendrababuravella requested review from AndreMarcel99, fernandofloresg, rexemin and richp405 November 10, 2025 08:34

richp405 previously approved these changes Nov 10, 2025

View reviewed changes

rexemin requested changes Nov 10, 2025

View reviewed changes

fernandofloresg reviewed Nov 10, 2025

View reviewed changes

resolving PR comments

b4b21a8

surendrababuravella dismissed richp405’s stale review via b4b21a8 November 11, 2025 20:08

surendrababuravella added 2 commits November 12, 2025 10:04

removing extra license details

36cecdf

Merge branch 'dev' into Enhancement/2167

d56aa14

surendrababuravella requested review from fernandofloresg, rexemin and richp405 November 12, 2025 10:24

richp405 approved these changes Nov 12, 2025

View reviewed changes

fernandofloresg approved these changes Nov 12, 2025

View reviewed changes

rexemin approved these changes Nov 13, 2025

View reviewed changes

	short_description: Validates playbooks against ibm_zos_core 2.0 and provides migration actions.
	short_description: Validates playbooks against ibm_zos_core 2.0.0 and provides migration actions.

	based on migration rules for IBM z/OS core collection version 2.0.
	based on migration rules for IBM z/OS Core collection version 2.0.0.

	to help upgrade playbooks from ibm_zos_core 1.x to 2.0.
	to help upgrade playbooks from ibm_zos_core 1.x.x to 2.0.0.

	- name: print debug data
	- name: Print migration validation results

		@@ -0,0 +1,11 @@
		# ibm.ibm_zos_core.playbook_upgrade_validator

		This role validates playbooks against ibm_zos_core 2.0 and provides migration actions.

	The only variable required is:
	The following variables are required:


		The only variable required is:

		- `playbook_path`: The path to the directory containing one or more Ansible playbooks.

	- `playbook_path`: The path to the directory containing one or more Ansible playbooks.
	- `playbook_path`: The path to a directory containing one or more Ansible playbooks.

	- `output_path`: File path where validation results should be written in JSON format.
	- `output_path`: File path where validation results should be written to in JSON format.

		@@ -0,0 +1,3 @@
		minor_changes:
		- playbook_upgrade_validator - Adding a role that automatically scans the playbooks in the directory and advises of migration actions.

[Role][2167] A role that automatically scans the playbooks in the directory and advises of migration actions #2399

Are you sure you want to change the base?

[Role][2167] A role that automatically scans the playbooks in the directory and advises of migration actions #2399

Uh oh!

Conversation

surendrababuravella commented Nov 10, 2025

SUMMARY

ISSUE TYPE

COMPONENT NAME

ADDITIONAL INFORMATION

Uh oh!

surendrababuravella commented Nov 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rexemin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fernandofloresg commented Nov 10, 2025

Uh oh!

fernandofloresg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

surendrababuravella commented Nov 10, 2025 •

edited

Loading