Simplify example-zowe.yaml based on system symbols and internal references to avoid duplication of data

[Joe-Winchester]

• Tests for the changes have been added (for bug fixes / features)
• Necessary documentation (if appropriate) have been added / updated
• DCO signoffs have been added to all commits, including this PR

PR type

What type of changes does your PR introduce to Zowe? Put an x in the box that applies to this PR. If you're unsure about any of them, don't hesitate to ask.

• Bugfix
• Feature
• Other... Please describe:

Relevant issues

Fixes #4600

Does this PR introduce a breaking change?

• Yes
• No

Does this PR add or change a YAML parameter?

• Yes
• No

[github-actions]

build 9264 SUCCEEDED.
Link to workflow run: https://github.com/zowe/zowe-install-packaging/actions/runs/19679757936

[github-actions]

Test workflow 7868 is started.
Running install test: Convenience Pax
The zowe artifact being used by this test workflow: libs-snapshot-local/org/zowe/3.4.0-PR-4601/zowe-3.4.0-pr-4601-9264-20251125182213.pax
Running on machine: zzow09
Result: FAILURE
Link to workflow run: https://github.com/zowe/zowe-install-packaging/actions/runs/19679902995

[Andrew-J-Metzger]

@Joe-Winchester I think this references the wrong value, e.g., "7554SV".

Let's use the zowe job prefix:

name: "${{ std.getenv('ZWE_zowe_job_prefix') }}SV"

[MarkAckert]

In general we've kept templated variables and template logic in the defaults.yaml file so the example-zowe.yaml can remain as straightforward and readable as possible. While I don't have any issues with templates like getenv(&SYSNAME), it could add some confusion. I don't think there's a hard rule on keeping templates out of example-zowe.yaml, but with that in mind, should some of these changes be moved to the defaults.yaml file, with the paired values in example-zowe.yaml commented out? Thinking zowe.job.name, externalPort, client.tls.attls fit in this category.

For the values which users must supply and there's no advantage to defaults (externalHost, zosmf.host), I'm a little mixed. Out of the box the values as-written are invalid and have to be replaced anyway, but they point the user towards &SYSNAME. Maybe we can call out the SYSNAME support in line-comments and setup doc?

Last item, configmgr supports symbol resolution via zos.resolveSymbol() and imo we should prefer that to getenv for clarity reasons...e.g. ${{ zos.resolveSymbol('&SYSNAME').

Interested in others' opinions cc @1000TurquoisePogs @Martin-Zeithaml

[Joe-Winchester]

I thought I'd tested these changes, but just re-started the STC I was testing with and are getting some errors on the network port and ttls values, that seem to enforce integers and bools respectively, so they don't like the yaml lookups.

I'm thinking of maybe setting the attls client to false by default, but having the external port match the gateway port seems like a good idea so I'll add to the PR to relax the integer enforcement.

I hadn't thought about the defaults.yaml, that's a good idea I'll noodle on.

Validity Exceptions(s) with object at
  Validity Exceptions(s) with object at /zowe
    type 'object' not permitted at /zowe/externalPort; expecting type 'integer'
    Validity Exceptions(s) with object at /zowe/network
      Validity Exceptions(s) with object at /zowe/network/client
        Schema at '/zowe/network/client/tls' invalid
          not anyOf schemas at '/zowe/network/client/tls' are valid
            Validity Exceptions(s) with object at /zowe/network/client/tls
              unequal constant value at /zowe/network/client/tls/attls
            Validity Exceptions(s) with object at /zowe/network/client/tls
              Schema at '/zowe/network/client/tls/attls' invalid
                not anyOf schemas at '/zowe/network/client/tls/attls' are valid
                  no matching enum value at /zowe/network/client/tls/attls; expecting one of values '[true, false]' of type 'string'
                  unequal constant value at /zowe/network/client/tls/attls

[Martin-Zeithaml]

Bulletproof definition

Any embedded value must be written in bulletproof form, like what if nothing is defined, is returned value valid etc.
This is wrong, beacuse

• (typo) ZWE_network_server_tls_attls should be ZWE_zowe_network_server_tls_attls
• What will be set, if zowe.network.server.tls.attls is not defined at all? It will return nothing, which is not valid boolean value.

attls: "${{ std.getenv('ZWE_network_server_tls_attls')}}"

Readability

Let's consider the previous example should be like this:

attls: "${{ zowe.network?.server?.tls?.attls ? false : true }}"

Is this easy to read for every customer?

Accessibility

Is every zwe command configmgr based? This requires small research, there were some PRs recently to remove "old" code, but I am not sure about this.

[1000TurquoisePogs]

This is incompatible with containers and thus some consideration for containers is needed, such as to take an old example and shove it into files/examples/containers/zowe.yaml

[1000TurquoisePogs]

the easiest solution for 'client' is just to get rid of it from the example.
it's an advanced option, and, allowing attls to be toggled on just client was a mistake so i think our code doesnt even respect it now.

[1000TurquoisePogs]

this has little effect in staging since it's forced on within apiml modulith.
a better simplification would be to remove attributes of apiml components which arent used in modulith, such as port. i would leave that to APIML devs to determine how best to refine.

[1000TurquoisePogs]

use of templates, and certain templates, are not backward compatible for certain zwe phases. That is, you can't use this file on an older version of zowe when doing an install, but you probably could at runtime.

some people may have v2 and v3, or various v3 versions, or want to do a downgrade, and encounter errors.

i would like to improve things, but we must be careful of what should wait for v4 and what can be done now. we need to know what impact changes will have.

[1000TurquoisePogs]

Also see #4605

[Joe-Winchester]

Lots of great feedback - thank you !
I'm going to convert this to draft, as I think it needs more thought especially if this will break containers and also the zwe commands that don't respect symbols.
I think I'll work instead of the troubleshooting section to add some more docs.
The only thing I was thinking about was whether the

externalPort: "${{ std.getenv('ZWE_components_gateway_port') }}"

is worth keeping, as I don't see why anyone would not want the two values to be in sync ?