Introduce a new section for managing z/OS UNIX mainframe hosts with Ansible. #2424

ketankelkar · 2025-02-24T23:19:35Z

This is a recreate of draft PR #2387 with a clean commit log.

From #2387 description:

While still a niche, there has been a noticeable uptick in users targeting z/OS mainframe systems with Ansible.

Unfortunately, there are some specific and non-obvious steps required to establish a successful and sensible connection between the Ansible control node and a z/OS mainframe host.
Currently, there is no central and organized place for users to get all the necessary information. Some of the information is available on an external docsite, but a user has to know to go look there. And still the information available there is not complete, as the docsite is meant for the Red Hat Ansible Certified Content for IBM Z offering, which is a set of Ansible collections -- which is not the most obvious or ideal place to go looking for setting up Ansible. That would be the Ansible docsite.

This PR introduces a new section going over key details in managing z/OS mainframe target nodes. This includes some of the ambiguous configs required to get up and running, including getting readable content back from the z/OS host, and also goes over some of the limitations and work-arounds when using ansible-core "out of the box" with z/OS mainframes -- as the available functionality is not exactly on par with say a Linux host.

This PR also includes updates to the (now 5 year old) z/OS section in the FAQs page.

A discussion in the Ansible Community Forum on this topic can be found: here

Signed-off-by: Ketan Kelkar <[email protected]>

ansible-documentation-bot · 2025-02-24T23:20:00Z

Thanks for your Ansible docs contribution! We talk about Ansible documentation on Matrix at #docs:ansible.im if you ever want to join us and chat about the docs! We meet on Matrix every Tuesday. See the Ansible calendar for meeting details. We welcome additions to our weekly agenda items too. You can add the dawgs-meeting tag to a forum topic to bring it up at the next meeting.

ddimatos

Thanks @ketankelkar for pulling this into a new PR. Looks good to me.

felixfontein · 2025-02-25T06:35:50Z

docs/docsite/rst/os_guide/index.rst

-Using Ansible on Windows and BSD
-################################
+#######################################
+Using Ansible on Windows, BSD, and z/OS


Shouldn't it explicitly say z/OS UNIX here? Confusing z/OS with z/OS UNIX was one of the big issues in https://forum.ansible.com/t/40091 after all.

felixfontein · 2025-02-25T06:35:57Z

docs/docsite/rst/os_guide/intro_zos.rst

+.. _working_with_zos:
+
+
+Managing z/OS hosts with Ansible


felixfontein · 2025-02-25T06:37:36Z

docs/docsite/rst/reference_appendices/faq.rst

@@ -316,41 +316,69 @@ is likely the problem. There are several workarounds:
 Running on z/OS
 ---------------

-There are a few common errors that one might run into when trying to execute Ansible on z/OS as a target.
+* Generally speaking, z/OS cannot be used as an Ansible control node. For more details, see :ref:`zos_as_control_node`.


Also in this section, shouldn't it explicitly say z/OS UNIX?

For this one, I actually wanted to capture the broader "z/OS" umbrella as being overall ineligible as a control node. This is our (ibm_zos_core collection team's) most frequently asked question.

That being said, I'm ok changing this to z/OS UNIX.

Both is fine for me, as long as using z/OS here instead of z/OS UNIX is intentional :)

felixfontein · 2025-02-25T06:39:13Z

docs/docsite/rst/os_guide/intro_zos.rst

+Configure the Remote Python Interpreter
+---------------------------------------
+
+Ansible requires a Python interpreter to run most modules on the remote host, and it checks for python at the 'default' path ``/usr/bin/python``.


It should be either (if you mean Python, the programming language)

Suggested change

Ansible requires a Python interpreter to run most modules on the remote host, and it checks for python at the 'default' path ``/usr/bin/python``.

Ansible requires a Python interpreter to run most modules on the remote host, and it checks for Python at the 'default' path ``/usr/bin/python``.

or (if you mean python, the CLI program)

Suggested change

Ansible requires a Python interpreter to run most modules on the remote host, and it checks for python at the 'default' path ``/usr/bin/python``.

Ansible requires a Python interpreter to run most modules on the remote host, and it checks for ``python`` at the 'default' path ``/usr/bin/python``.

Same below in several other instances.

samccann

some documentation style guide edits and some questions...

docs/docsite/rst/os_guide/intro_zos.rst

samccann · 2025-02-25T19:28:33Z

docs/docsite/rst/os_guide/intro_zos.rst

+z/OS which are aware of tags will use them.
+
+
+Using Ansible Community Modules with z/OS


I'm unsure if this applies to all modules in the community package (aka community.general, etc etc) or only to the core ansible.builtin modules. if it's just the ansible.builtin modules, please change the heading to "Using ansible.buitlin moduels with z/OS UNIX" (note we use sentence case for headings in the Ansible docs)

good point, I was wrongly equating "community" with "builtin"

docs/docsite/rst/os_guide/intro_zos.rst

…ances of 'Python' Signed-off-by: Ketan Kelkar <[email protected]>

…ate section headers to use sentence-case Signed-off-by: Ketan Kelkar <[email protected]>

Signed-off-by: Ketan Kelkar <[email protected]>

ketankelkar · 2025-02-27T20:20:44Z

Thanks @felixfontein and @samccann for the reviews, I have updated the PR with the suggested changes, please have a look, which leads me to my next question:

What practice does the community follow for resolving comments? Would you prefer I mark them 'resolved' as I add changes or is it better to have the comment author resolve them after having a chance to verify the changes? From what I can see from other PRs, seems like it's a mix of both - the creator of the PR and the commenter resolves comments

samccann · 2025-02-27T20:54:37Z

Yeah it's a mix of both really. My preference - if the fix is obvious and you basically do it, I'm fine if you mark it resolved. Those of us who can merge will look for approvals and a quick scann of open comments to see if anything looks like it wasn't adressed before we hit the button.

To clarify here the debate a bit on the forum - after this PR merges, one of use will go in and exclude it from the core docs. It will show up where you expect to see it on docs.ansible.com, but not on the core versioned docs for now.

docs/docsite/rst/os_guide/intro_zos.rst

samccann

just one last nit to fix, but LGTM

Co-authored-by: Sandra McCann <[email protected]>

felixfontein · 2025-03-01T15:02:09Z

docs/docsite/rst/os_guide/intro_zos.rst

+Here are some notes / pro-tips when using the ``ansible.builtin`` modules with z/OS UNIX. This is by no means a comprehensive list.
+Before using any Ansible modules, you must first :ref:`configure_zos_remote_environment`.
+
+* ansible.builtin.command / ansible.builtin.shell


I'd link to the modules in question:

Suggested change

* ansible.builtin.command / ansible.builtin.shell

* :ansplugin:`ansible.builtin.command#module` / :ansplugin:`ansible.builtin.shell#module`

Then users can quickly navigate to the module docs by clicking on the names, instead of having to search for them.

felixfontein · 2025-03-01T15:02:19Z

docs/docsite/rst/os_guide/intro_zos.rst

+        ansible.builtin.shell: "some_pgm | iconv -f ibm-1047 -t iso8859-1"
+
+
+* ansible.builtin.raw


Suggested change

* ansible.builtin.raw

* :ansplugin:`ansible.builtin.raw#module`

felixfontein · 2025-03-01T15:02:54Z

docs/docsite/rst/os_guide/intro_zos.rst

+    which set up the configured remote environment for each task.
+
+
+* ansible.builtin.copy / ansible.builtin.fetch


Suggested change

* ansible.builtin.copy / ansible.builtin.fetch

* :ansplugin:`ansible.builtin.copy#module` / :ansplugin:`ansible.builtin.fetch#module`

felixfontein · 2025-03-01T15:03:08Z

docs/docsite/rst/os_guide/intro_zos.rst

+        - name: Tag my_file.txt as UTF-8.
+          ansible.builtin.command: chtag -tc iso8859-1 my_file.txt
+
+* ansible.builtin.blockinfile / ansible.builtin.lineinfile


Suggested change

* ansible.builtin.blockinfile / ansible.builtin.lineinfile

* :ansplugin:`ansible.builtin.blockinfile` / :ansplugin:`ansible.builtin.lineinfile`

felixfontein · 2025-03-01T15:03:16Z

docs/docsite/rst/os_guide/intro_zos.rst

+* ansible.builtin.blockinfile / ansible.builtin.lineinfile
+    These modules process all data in UTF-8. Ensure target files are UTF-8 encoded beforehand and re-tag the files afterwards.
+
+* ansible.builtin.script


Suggested change

* ansible.builtin.script

* :ansplugin:`ansible.builtin.script`

felixfontein · 2025-03-01T15:04:03Z

docs/docsite/rst/os_guide/intro_zos.rst

+    The LE environment variable configurations will correctly convert streams if they are tagged and return readable output to Ansible.
+    However, some command line programs may return output in UTF-8 and not tag the pipe.
+    In this case, the autoconversion may incorrectly assume output is in EBCDIC and attempt to convert it and yield unreadable data.
+    If the source encoding is known, you can use the ``ansible.builtin.shell`` module's capability to chain commands together through pipes,


Suggested change

If the source encoding is known, you can use the ``ansible.builtin.shell`` module's capability to chain commands together through pipes,

If the source encoding is known, you can use the :ansplugin:`ansible.builtin.shell#module` module's capability to chain commands together through pipes,

felixfontein · 2025-03-01T15:04:17Z

docs/docsite/rst/os_guide/intro_zos.rst

+
+Ansible modules will not read or recognize file tags. It is up to the user to determine the nature of remote data and tag it appropriately.
+Data sent to remote z/OS UNIX hosts through Ansible is, by default, encoded in UTF-8 and not tagged.
+Tagging a file is achievable with an additional task using the ``ansible.builtin.command`` module.


Suggested change

Tagging a file is achievable with an additional task using the ``ansible.builtin.command`` module.

Tagging a file is achievable with an additional task using the :ansplugin:`ansible.builtin.command#module` module.

felixfontein · 2025-03-01T15:05:19Z

docs/docsite/rst/os_guide/intro_zos.rst

+When Ansible pipelining is enabled but the ``PYTHONSTDINENCODING`` property is not correctly set, the following error may result.
+Note, the hex ``'\x81'`` below may vary depending on the source causing the error:
+
+.. code-block::


All code-blocks should have a language:

Suggested change

.. code-block::

.. code-block:: text

felixfontein · 2025-03-01T15:09:29Z

docs/docsite/rst/os_guide/intro_zos.rst

+    the script file, since the file does not get tagged as UTF-8 text, the shell assumes that the file is encoded in EBCDIC,
+    and fails to correctly read or run the script.
+    One work-around is to manually copy local files to managed nodes (``ansible.builtin.copy`` ) and convert or tag files (with the ``ansible.builtin.command`` module).
+    With this work-around, some of the conveniences of the script module are lost, such as automatically cleaning up the script file once it's run,


Suggested change

With this work-around, some of the conveniences of the script module are lost, such as automatically cleaning up the script file once it's run,

With this work-around, some of the conveniences of the script module are lost, such as automatically cleaning up the script file once it is run,

(https://docs.ansible.com/ansible/devel/dev_guide/style_guide/grammar_punctuation.html#contractions)

felixfontein · 2025-03-01T15:09:46Z

docs/docsite/rst/os_guide/intro_zos.rst

+``ansible.builtin`` modules will assume all textual data is UTF-8 encoded, while z/OS UNIX may be using EBCDIC.
+On many z/OS UNIX systems, the default encoding for untagged files is EBCDIC.
+This variation in default settings can easily lead to data being misinterpreted with the wrong encoding,
+whether that's failing to auto convert EBCDIC to UTF-8 or erroneously attempting to convert data that is already in UTF-8.


Suggested change

whether that's failing to auto convert EBCDIC to UTF-8 or erroneously attempting to convert data that is already in UTF-8.

whether that is failing to auto convert EBCDIC to UTF-8 or erroneously attempting to convert data that is already in UTF-8.

Signed-off-by: Ketan Kelkar <[email protected]>

ketankelkar · 2025-03-04T17:10:16Z

@felixfontein - thanks for the suggestion to add links to the modules! this will def make things more convenient for users / readers, plus it was very cool to learn about the ansplugin feature, i didn't know about it 😄

ketankelkar added 2 commits February 24, 2025 14:31

add a new page for managing unix(zos) hosts

3514e75

Signed-off-by: Ketan Kelkar <[email protected]>

update unix(zos) faq section

9da4207

Signed-off-by: Ketan Kelkar <[email protected]>

ketankelkar temporarily deployed to github-bot February 24, 2025 23:19 — with GitHub Actions Inactive

ansible-documentation-bot bot added the new_contributor This PR is the first contribution by a new community member. label Feb 24, 2025

ketankelkar mentioned this pull request Feb 24, 2025

Introduce a new section for managing z/OS mainframe hosts with Ansible. #2387

Closed

ddimatos approved these changes Feb 24, 2025

View reviewed changes

felixfontein reviewed Feb 25, 2025

View reviewed changes

samccann reviewed Feb 25, 2025

View reviewed changes

ketankelkar added 3 commits February 25, 2025 14:14

update references from z/OS to z/OS UNIX for clarity; capitalize inst…

b406608

…ances of 'Python' Signed-off-by: Ketan Kelkar <[email protected]>

specify 'ansible.builtin modules' instead of 'community modules', upd…

8e50950

…ate section headers to use sentence-case Signed-off-by: Ketan Kelkar <[email protected]>

missed a few 'community' where 'ansible.builtin' belongs

a8f7309

Signed-off-by: Ketan Kelkar <[email protected]>

ketankelkar temporarily deployed to github-bot February 25, 2025 23:00 — with GitHub Actions Inactive

ketankelkar requested review from samccann and felixfontein February 25, 2025 23:05

samccann reviewed Feb 27, 2025

View reviewed changes

docs/docsite/rst/os_guide/intro_zos.rst Outdated Show resolved Hide resolved

samccann approved these changes Feb 27, 2025

View reviewed changes

update to correct terminology

5fdd48d

Co-authored-by: Sandra McCann <[email protected]>

ketankelkar temporarily deployed to github-bot February 27, 2025 22:12 — with GitHub Actions Inactive

felixfontein reviewed Mar 1, 2025

View reviewed changes

ketankelkar added 2 commits March 3, 2025 17:56

add links to builtin modules

2a1f12f

Signed-off-by: Ketan Kelkar <[email protected]>

sytax and punctation edits

ae2594d

Signed-off-by: Ketan Kelkar <[email protected]>

ketankelkar temporarily deployed to github-bot March 4, 2025 01:58 — with GitHub Actions Inactive

fix a bad link

b9d1616

Signed-off-by: Ketan Kelkar <[email protected]>

ketankelkar temporarily deployed to github-bot March 4, 2025 02:06 — with GitHub Actions Inactive

ketankelkar requested a review from felixfontein March 4, 2025 17:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Introduce a new section for managing z/OS UNIX mainframe hosts with Ansible. #2424

Introduce a new section for managing z/OS UNIX mainframe hosts with Ansible. #2424

ketankelkar commented Feb 24, 2025

ansible-documentation-bot bot commented Feb 24, 2025

ddimatos left a comment

felixfontein Feb 25, 2025

felixfontein Feb 25, 2025

felixfontein Feb 25, 2025

ketankelkar Feb 25, 2025

felixfontein Mar 1, 2025

felixfontein Feb 25, 2025

samccann left a comment

samccann Feb 25, 2025

ketankelkar Feb 25, 2025

ketankelkar commented Feb 27, 2025

samccann commented Feb 27, 2025

samccann left a comment

felixfontein Mar 1, 2025

felixfontein Mar 1, 2025

felixfontein Mar 1, 2025

felixfontein Mar 1, 2025

felixfontein Mar 1, 2025

felixfontein Mar 1, 2025

felixfontein Mar 1, 2025

felixfontein Mar 1, 2025

felixfontein Mar 1, 2025

felixfontein Mar 1, 2025

ketankelkar commented Mar 4, 2025

	Ansible requires a Python interpreter to run most modules on the remote host, and it checks for python at the 'default' path ``/usr/bin/python``.
	Ansible requires a Python interpreter to run most modules on the remote host, and it checks for Python at the 'default' path ``/usr/bin/python``.

		z/OS which are aware of tags will use them.


		Using Ansible Community Modules with z/OS

	* ansible.builtin.command / ansible.builtin.shell
	* :ansplugin:`ansible.builtin.command#module` / :ansplugin:`ansible.builtin.shell#module`

		ansible.builtin.shell: "some_pgm \| iconv -f ibm-1047 -t iso8859-1"


		* ansible.builtin.raw

	* ansible.builtin.raw
	* :ansplugin:`ansible.builtin.raw#module`

		which set up the configured remote environment for each task.


		* ansible.builtin.copy / ansible.builtin.fetch

	* ansible.builtin.copy / ansible.builtin.fetch
	* :ansplugin:`ansible.builtin.copy#module` / :ansplugin:`ansible.builtin.fetch#module`

	* ansible.builtin.blockinfile / ansible.builtin.lineinfile
	* :ansplugin:`ansible.builtin.blockinfile` / :ansplugin:`ansible.builtin.lineinfile`

	* ansible.builtin.script
	* :ansplugin:`ansible.builtin.script`

	If the source encoding is known, you can use the ``ansible.builtin.shell`` module's capability to chain commands together through pipes,
	If the source encoding is known, you can use the :ansplugin:`ansible.builtin.shell#module` module's capability to chain commands together through pipes,

	Tagging a file is achievable with an additional task using the ``ansible.builtin.command`` module.
	Tagging a file is achievable with an additional task using the :ansplugin:`ansible.builtin.command#module` module.

	With this work-around, some of the conveniences of the script module are lost, such as automatically cleaning up the script file once it's run,
	With this work-around, some of the conveniences of the script module are lost, such as automatically cleaning up the script file once it is run,

	whether that's failing to auto convert EBCDIC to UTF-8 or erroneously attempting to convert data that is already in UTF-8.
	whether that is failing to auto convert EBCDIC to UTF-8 or erroneously attempting to convert data that is already in UTF-8.

Introduce a new section for managing z/OS UNIX mainframe hosts with Ansible. #2424

Are you sure you want to change the base?

Introduce a new section for managing z/OS UNIX mainframe hosts with Ansible. #2424

Conversation

ketankelkar commented Feb 24, 2025

ansible-documentation-bot bot commented Feb 24, 2025

ddimatos left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

samccann left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ketankelkar commented Feb 27, 2025

samccann commented Feb 27, 2025

samccann left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ketankelkar commented Mar 4, 2025