Simplified zowe.yaml examples

[achmelo]

Customer content

Is your feature request related to a problem? Please describe.
Zowe example configuration file is too complex for many installations. Many parameters are usualy not changed and it is not easy to do in ISPF.

Describe the solution you'd like
Provide multiple zowe.yaml examples that would be focused on specific installation, e.g. keyring-zowe.yaml that contains predefined values for case when users have existing keyring and ask users to specify only the necessary details we can't know - hostname, system. Put any detail that needs to be specified at the beginning.

[balhar-jakub]

I support this one deeply. The standard installation should require as little information as possible to be provided.

[MarkAckert]

Related: #4238 and #4600

[1000TurquoisePogs]

There's a few changes that seem obvious but in reality introduce limitations or user experience complications, requiring code changes to pull off well.

PR #4238 combines cleanup of the yaml's certificate content with defaulting to bring-your-own-keyring.

PR #4601 relies upon configmgr templates which do not work on containers meaning that containers could not use such exmaples.

Further improvement of zosmf requires knowing which components depend upon zosmf such as by having a manifest declare dependencies.

Rolling all the APIML properties under 1 component might be good but requires some code changes?

If we say that the main example can have templates, then we can do #4601. We could put a container example in a folder since its rarer, and that one just would not use templates.

[1000TurquoisePogs]

Also see #4605

[achmelo]

I am not sure if I understand the goal of templates in example-zowe.yaml. Any parameter in this file should be for users to configure. Why not move templates to default yaml? Do we expect users to override these?
We can potentialy move API ML properties under single component in the next release, it doesn't require any code change as mappings are already in the start scripts.

[MarkAckert]

We generally agree that templates should reside in defaults.yaml. There are some cases where using templates or variables in example-zowe.yaml could actually help users make the YAML more portable across systems, but it would be an advanced use case and would require vendor support + advanced docs.

I think in all these linked issues we're talking about the same thing (simplifying config), and they show there's multiple ways to tackle it as well as the tradeoffs of the different approaches. Nothing from those PRs is locked in.

[achmelo]

I agree that all these are improvements that simplifies yaml configuration. Would it be possible to reuse templating and allow users to define parameters in a format that is more suitable for ISPF? e.g. parmlib with environment variables EXTERNAL_HOST=dvipa.com
would translate to default.yaml ->
zowe:
externalDomains: {EXTERNAL_HOST}

More things we can remove from example-zowe.yaml are those mentioned already in defaults.yaml like cookieIdentifier: "1" or rbacProfileIdentifier: "1" . How ofter are these changed in the initial installation?

[MarkAckert]

Would it be possible to reuse templating and allow users to define parameters in a format that is more suitable for ISPF? e.g. parmlib with environment variables

This is sort of supported today through zowe.yaml concatenation, though it's in the zowe.yaml format, not key/value pairs. A user can run zwe ... -c "PARMLIB(ZOWE.SHARED.PARMLIB(SYSA)):FILE(/path/to/example-zowe.yaml)", or generalize it like -c "PARMLIB(ZOWE.SHARED.PARMLIB(`sysvar SYSNAME`)):FILE(/path/to/example-zowe.yaml)"

ZOWE.SHARED.PARMLIB(SYSA):

zowe:
  externalHost:
  - sysa.example.com

Assuming this PARMLIB has members matching the SYSNAME... this isn't exactly what you're asking for, but it's a similar option that's available for consideration. We're moving around where templating happens, optionally avoiding it altogether if users hard-code their zwe start commands with their system names. IDK if in practice users would set their installations up this way.

[1000TurquoisePogs]

zowe.environments is a section of the yaml that will never have a strict schema so it is possible to define interesting variables there that can be used in templates elsewhere.
Someone could have a parmlib that is just

zowe:
  environments:
    a: b
    c: "${{ interesting logic }}"

and then in other yaml files, make use of them.
it also shows up as an env var, so that can be valuable too.

@achmelo your mention of cookieIdentifier and rbacProfileIdentifier could use this.

zowe:
  environments:
    instance_nickname: prod1
    uss_root: "/zowe/${{ zowe.environments.instance_nickname }}"
  setup:
    datasets:
      prefix: "ZOWE.${{ zowe.environments.instance_nickname }}"
  cookieIdentifier: ${{ zowe.environments.instance_nickname }}
  rbacProfileIdentifier: ${{ zowe.environments.instance_nickname }}
  logDirectory: "${{ zowe.environments.uss_root }}/logs"
  workspaceDirectory: "${{ zowe.environments.uss_root }}/workspace"

we had and lost the notion of an INSTANCE_DIR in v1, but i've been structuring my environments in this way.