Skip to content

Create Version-specific API ML installation checklists - POC #4764

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
janan07 wants to merge 24 commits into
base: master
Choose a base branch
from
Open

Create Version-specific API ML installation checklists - POC #4764

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
74578f7
initial commit
janan07 Oct 29, 2025
c8a19bf
second commit of version specific checklists for API ML
janan07 Oct 29, 2025
9c901f3
add zowe version-specific install/config task table
janan07 Oct 31, 2025
8caebd4
clarify modulith vs modular
janan07 Nov 3, 2025
67cb269
Merge branch 'master' into janan07/apiml-install-tables
janan07 Nov 3, 2025
c0bf79e
add links 1
janan07 Nov 14, 2025
0f24548
link fixes
janan07 Nov 14, 2025
af0628f
fix links
janan07 Nov 14, 2025
8695d3a
update v3.0 table
janan07 Nov 18, 2025
085623c
add required role column
janan07 Nov 18, 2025
caacdc9
update v3.4 table / replace modulthi with single-service
janan07 Nov 18, 2025
fb84c6a
add intro to v3.4 checklist
janan07 Nov 18, 2025
095c5b8
polish intro v3.4
janan07 Nov 18, 2025
d48dc0a
improve v2.18 checklist to security
janan07 Nov 18, 2025
794e445
add introductory paragraph
janan07 Nov 18, 2025
a50c36c
update v2.18 securioty and cert table
janan07 Nov 20, 2025
b84c930
update security and certificate config for v2.18 and 3.0
janan07 Nov 20, 2025
1a0942c
initial security and certificates config for v3.4 refactor
janan07 Nov 20, 2025
1c7772f
remove gibberish
janan07 Nov 20, 2025
73d3d78
remove estimated time
janan07 Nov 20, 2025
8f4c74c
remove time estimate
janan07 Nov 20, 2025
329e160
add meta-description
janan07 Nov 20, 2025
774b41d
update metadescription
janan07 Nov 20, 2025
ae4384f
fix comparison table
janan07 Nov 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions docs/user-guide/api-mediation/api-ml-installation-checklist-v2.18.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Zowe v2.18 – API ML Installation and Configuration Checklist

## Preparing for Installation
| Step | Task | Notes / References |
| ---- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| 1 | Verify z/OS prerequisites for Zowe (z/OS 2.4 +, Java 11 +, USS enabled). | [Zowe v2.18 Prerequisites](https://docs.zowe.org/v2.18.x/user-guide/installandconfig) |
| 2 | Ensure proper USS directory and zFS space for the API ML runtime. | Typical path: `/ZOWE/runtime/`. |
| 3 | Identify ports for Gateway, Discovery, and Catalog services. | Check for conflicts with existing ports. |
| 4 | Verify access to SAF keyrings or keystore directories. | Required for TLS setup in API ML. |


## Installing the Zowe z/OS Runtime
Copy link
Member

@balhar-jakub balhar-jakub Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sections below seems to be rather strange and a bit messy, particularly with respect to the z/OSMF workflow and the inforamtion about zwe install and obtaining the SMP/E or PAX

It should probably follow the structure from Techdocs, e.g. preparing the environment, then configuring via z/OSMF Workflows

| Step | Task | Notes / References |
| ---- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| 1 | Obtain and extract the Zowe v2.18 PAX or SMP/E package. | [Install Zowe on z/OS](https://docs.zowe.org/v2.18.x/user-guide/install-zos) |
| 2 | Run `zwe install` or equivalent setup job to deploy runtime. | Includes API ML by default. |
| 3 | Prepare and update the `zowe.yaml` configuration file. | Define API ML components (gateway, discovery, catalog). |
| 4 | Validate environment variables for the Zowe runtime user (e.g., `JAVA_HOME`, `ZOWE_ROOT_DIR`). | Verify via `env` command. |

## Configuring with a z/OSMF Workflow
| Step | Task | Notes / References |
| ---- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| 1 | Import and start the “Install Zowe Server Components” z/OSMF workflow. | [Zowe z/OSMF workflow](https://docs.zowe.org/v2.18.x/user-guide/install-zosmf) |
| 2 | Specify **“Install API ML and Zowe Server Components”** as the workflow option. | Ensures Gateway, Discovery, Catalog are configured. |
| 3 | Complete prompts for workspace, port assignments, and keyrings. | Auto-populates `zowe.yaml`. |

## Configuring Security
| Step | Task | Notes / References |
| ---- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| 1 | Run `zwe init mvs` and `zwe init security` to create required SAF profiles. | [Security Setup](https://docs.zowe.org/v2.18.x/user-guide/installandconfig#security) |
| 2 | Grant the Zowe runtime user access to SAF keyring or certificates. | Typically via RACF `RDEFINE DIGTCERT`. |
| 3 | Configure Zowe security group IDs for API ML users and services. | Assign IDs for API ML discovery/caching. |

## Configuring Certificates
| Step | Task | Notes / References |
| ---- | ---------------------------------------------------------------- | ---------------------------------------------------------------------- |
| 1 | Create or import certificates into SAF or PKCS12 keystore. | [Zowe Certificates](https://docs.zowe.org/v2.18.x/user-guide/keystore) |
| 2 | Update `zowe.yaml` with certificate locations and keyring names. | Example: `safkeyring:////ZOWE.KEYRING`. |
| 3 | Test certificate trust between Gateway, Discovery, and Catalog. | Use `openssl s_client` or Zowe logs. |

## Configuring High Availability
| Step | Task | Notes / References |
| ---- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| 1 | Configure multiple Gateway instances if needed. | Share Discovery and Catalog services. |
| 2 | Enable caching service for session consistency. | [API ML Caching Service](https://docs.zowe.org/v2.18.x/user-guide/api-mediation/api-mediation-overview) |
| 3 | Validate shared zFS directories or VSAM datasets for HA. | Required for cross-LPAR setups. |

## Starting and Stopping Zowe
| Step | Task | Notes / References |
| ---- | ---------------------------------------- | -------------------------------------- |
| 1 | Start the Zowe runtime with `zwe start`. | Includes API ML services. |
| 2 | Stop with `zwe stop` or JCL STOP job. | Use JES logs to verify clean shutdown. |

## Verifying Installation
| Step | Task | Notes / References |
| ---- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| 1 | Access the API Catalog UI: `https://<host>:<port>/apicatalog`. | Verify UI loads successfully. |
| 2 | Confirm Gateway and Discovery registration in logs. | Look for “Registered service” messages. |
| 3 | Onboard a sample service (e.g., z/OSMF API) and confirm routing. | [Onboarding APIs](https://docs.zowe.org/v2.18.x/user-guide/api-mediation/using-api-mediation-layer) |
57 changes: 57 additions & 0 deletions docs/user-guide/api-mediation/api-ml-installation-checklist-v3.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# Zowe v3.0 – API ML Installation and Configuration Checklist
Copy link
Collaborator

@iansergeant42 iansergeant42 Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest renaming to docs/user-guide/api-mediation/api-ml-installation-checklist-v.3.0.x.md to match the links below.


## Preparing for Installation
| Step | Task | Notes / References |
| ---- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| 1 | Verify Java 17 + and z/OS 2.4 + prerequisites. | See [Zowe v3 Prerequisites](https://docs.zowe.org/v3.0.x/user-guide/install-nodejs-zos) |
| 2 | Allocate workspace for the new modular API ML runtime. | Gateway now uses Spring Cloud Gateway. |
| 3 | Reserve updated ports for Gateway, Discovery, and Catalog. | Port defaults changed in v3. |
| 4 | Confirm SAF keyring access for new format (`safkeyring://`). | Updated URI syntax required. |

## Installing the Zowe z/OS Runtime
| Step | Task | Notes / References |
| ---- | ------------------------------------------------------- | ---------------------------------------------------------------------- |
| 1 | Install Zowe v3.0 using Zowe Server Install Wizard, Convenience Build, SMP/E build, or Portable Software Instance. | See **Zowe 3.0.0** in [All Zowe V3.x Releases](https://www.zowe.org/download#all-v3-releases) in Download Zowe on the zowe.org website|
| 2 | Use `zwe install` to deploy the runtime. | Installs API ML (Spring Gateway) components. |
| 3 | Update `zowe.yaml` for new service layout and defaults. | Gateway, Discovery, Catalog parameters changed. |

## Configuring with a z/OSMF Workflow

| Step | Task | Notes / References |
| ---- | ---------------------------------------------------------------- | ------------------------------------------------------------------------ |
| 1 | Import and start “Install Zowe Server Components v3.0” workflow. | See [Configuring Zowe with z/OSMF Workflows](https://docs.zowe.org/v3.0.x/user-guide/configure-zowe-zosmf-workflow) |
2 | Provide `safkeyring://` entries during prompts. | Replaces older keyring path format. |

## Configuring Security
| Step | Task | Notes / References |
| ---- | --------------------------------------------------------- | --------------------------------------------------------------------- |
| 1 | Run `zwe init security` for new group IDs. | See [Addressing security requirements](https://docs.zowe.org/v3.0.x/user-guide/address-security-requirements) |
| 2 | Verify security definitions for `ZWEUSER` and `ZWESVUSR`. | Needed for Spring Gateway startup. |
| 3 | Confirm RACF permissions for SAF keyrings and ports. | Use `PERMIT` command as needed. |

## Configuring Certificates
| Step | Task | Notes / References |
| ---- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| 1 | Create or import certificates for the new Gateway (Spring). | See [Configuring certificates](https://docs.zowe.org/v3.0.x/user-guide/configure-certificates/) |
| 2 | Update certificate properties to `verify_certificates: ENABLED`. | Required for production. |
| 3 | Validate trust chain across API ML services. | Check Gateway logs. |

## Configuring High Availability
| Step | Task | Notes / References |
| ---- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| 1 | Deploy multiple Gateway (Spring) instances for redundancy. | See [Configuring high availability](https://docs.zowe.org/v3.0.x/user-guide/zowe-ha-overview/) |
| 2 | Configure shared Discovery and Catalog with HA cache. | Ensure Eureka syncs correctly. |
| 3 | Use external load balancer for Gateway endpoints. | Recommended for production. |

## Starting and Stopping Zowe
| Step | Task | Notes / References |
| ---- | --------------------------- | ------------------------- |
| 1 | Start with `zwe start all`. | Verifies all services up. See [Starting and stopping Zowe](https://docs.zowe.org/v3.0.x/user-guide/start-zowe-zos) |
| 2 | Stop with `zwe stop all`. | Graceful shutdown. |

## Verifying Installation
| Step | Task | Notes / References |
| ---- | ----------------------------------------------------- | ----------------------------------- |
| 1 | Open API Catalog: `https://<host>:<port>/apicatalog`. | Confirm Spring Gateway response. |
| 2 | Verify Discovery Service logs show registered APIs. | Look for “registered successfully”. |
| 3 | Test CLI authentication via `zowe auth login apiml`. | Confirms token service operational. |
57 changes: 57 additions & 0 deletions docs/user-guide/api-mediation/api-ml-installation-checklist-v3.3.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# API Mediation Layer (API ML) Installation and Configuration Checklist
Copy link
Collaborator

@iansergeant42 iansergeant42 Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest renaming to docs/user-guide/api-mediation/api-ml-installation-checklist-v3.4.x.md. The links will go to https://docs.zowe.org/stable when we release Zowe v3.4.0, but I suggest that this should work on demo. Can we update the links to somewhere running the up-to-date site?

Copy link
Collaborator Author

@janan07 janan07 Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure. The links will be updated when we role out v3.4.


## Preparing for Installation
| Step | Task | Notes / References |
| ---- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| 1 | Verify Java 17+, z/OS 2.4+, and Zowe 3.3 runtime prerequisites. | See [Addressing Zowe server prerequisites](https://docs.zowe.org/stable/user-guide/install-nodejs-zos/) |
| 2 | Choose deployment type: **modulith** or **multi-component**. | Modulith consolidates all API ML components. |
| 3 | Update firewall and port settings if using modulith mode. | Single-port operation. |

## Installing the Zowe z/OS Runtime
| Step | Task | Notes / References |
| ---- | --------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| 1 | Install Zowe v3.0 using Zowe Server Install Wizard, Convenience Build, SMP/E build, or Portable Software Instance. | See **Zowe 3.3.0** in [All Zowe V3.x Releases](https://www.zowe.org/download#all-v3-releases) <br> Includes updated API ML modulith. |
| 2 | Run `zwe install` or `zwe generate --dry-run`. | See [zwe generate](https://docs.zowe.org/stable/user-guide/install-zos#zwe-install) |
| 3 | Define API ML settings under `components.apiml` in `zowe.yaml`. | Unified section replaces separate components. |

## Configuring API ML with a z/OSMF Workflow
| Step | Task | Notes / References |
| ---- | ------------------------------------------------------ | ------------------------------------------------------------------------ |
| 1 | Use the Stand-alone Zowe API ML Configuration workflow. | See [Configuring API ML with z/OSMF Workflow](https://docs.zowe.org/stable/user-guide/configure-apiml-zosmf-workflow) |
| 2 | We recommend you select “Modulith Deployment” as your deployment method. | Creates consolidated API ML service. |
| 3 | Specify trusted proxies and forward-header parameters. | New in v3.3. |

## Configuring Security
| Step | Task | Notes / References |
| ---- | ----------------------------------------------------- | --------------------------------------------------------------------- |
| 1 | Run `zwe init security` as standard. | See [Address security requirements](https://docs.zowe.org/stable/user-guide/address-security-requirements) |
| 2 | Perform Configuration tasks that apply to API Mediation Layer. | See API sepecific tasks in [Address security requirements](https://docs.zowe.org/stable/user-guide/address-security-requirements) |
| 3 | Define trusted proxy headers in `zowe.yaml`. | `apiml.security.forwardHeader.trustedProxies`. |
| 4 | Verify port and certificate access for runtime users. | Required for modulith start. |

## Configuring Certificates
| Step | Task | Notes / References |
| ---- | --------------------------------------------------------------------- | -------------------- |
| 1 | Create or import certificates for the new Gateway (Spring). | See [Configuring certificates](https://docs.zowe.org/stable/user-guide/configure-certificates/) |
| 2 | Update `zowe.yaml` with keyring references and modulith TLS settings. | Consolidated config. |
| 3 | Confirm TLS communication between clients and backend. | Check Gateway logs. |

## Configuring High Availability
| Step | Task | Notes / References |
| ---- | --------------------------------------------------------- | ------------------------------------------------------------------------------ |
| 1 | Configure HA mode by deploy multiple independent Zowe server component instances "moduliths", ideally be on different LPARs | See [Configuring high availability](https://docs.zowe.org/stable/user-guide/zowe-ha-overview) |
| 2 | Define Eureka timeouts (`connectTimeout`, `readTimeout`). | Added in v3.3. |
| 3 | For modulith, enable HA through external clustering. | Gateway and Discovery combined. |

## Starting and Stopping Zowe
| Step | Task | Notes / References |
| ---- | ----------------------------------------------------- | --------------------------- |
| 1 | Start Zowe with `zwe start apiml` or `zwe start all`. | Modulith starts as one JVM. <br>See [Starting and stopping Zowe](https://docs.zowe.org/stable/user-guide/start-zowe-zos) |
| 2 | Stop Zowe with `zwe stop apiml` or `zwe stop all`. | Confirm shutdown. |

## Verifying Installation
| Step | Task | Notes / References |
| ---- | ------------------------------------------------ | ---------------------------------------- |
| 1 | Access API Catalog and verify registered APIs. | `https://<host>:<port>/apicatalog` |
| 2 | Confirm “modulith mode enabled” in Gateway logs. | Indicates v3.3 deployment. |
| 3 | Test proxy header forwarding using REST client. | Validates trusted proxies configuration. |
Loading
Loading