Create Version-specific API ML installation checklists - POC #4764
Conversation
Signed-off-by: Andrew Jandacek <[email protected]>
Signed-off-by: Andrew Jandacek <[email protected]>
|
😺 Thank you for creating this PR! To publish your content to Zowe Docs, follow these required steps.
Need help? Contact the Doc Squad in the #zowe-doc Slack channel. |
|
📁 The PR description is missing the file name(s) for the updated content. List all the files included in this PR so this information displays in our Zowe Docs GitHub Slack channel. If you have addressed this issue already, refresh this page in your browser to remove this comment. |
|
If you have addressed this issue already, refresh this page in your browser to remove this comment. |
|
📌 The subject area label is missing. Add an If you have addressed this issue already, refresh this page in your browser to remove this comment. |
|
💾 The release label is missing. Add a If you have addressed this issue already, refresh this page in your browser to remove this comment. |
|
🔍 The review label is missing. Add a If you have addressed this issue already, refresh this page in your browser to remove this comment. |
Signed-off-by: Andrew Jandacek <[email protected]>
Signed-off-by: Andrew Jandacek <[email protected]>
| | 4 | Verify access to SAF keyrings or keystore directories. | Required for TLS setup in API ML. | | ||
|
|
||
|
|
||
| ## Installing the Zowe z/OS Runtime |
There was a problem hiding this comment.
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
Signed-off-by: Andrew Jandacek <[email protected]>
Signed-off-by: Andrew Jandacek <[email protected]>
Signed-off-by: Andrew Jandacek <[email protected]>
Signed-off-by: Andrew Jandacek <[email protected]>
|
|
||
|
|
||
| ## Installing the Zowe z/OS Runtime | ||
| Okay, here's the table with the requested formatting changes applied: |
There was a problem hiding this comment.
I suggest renaming to docs/user-guide/api-mediation/api-ml-installation-checklist-v2.18.x.md to match the links below.
There was a problem hiding this comment.
I don't quite understand the comment, but in any case, these file names will be different when the tables are converted from markdown to xml.
| @@ -0,0 +1,57 @@ | |||
| # Zowe v3.0 – API ML Installation and Configuration Checklist | |||
There was a problem hiding this comment.
I suggest renaming to docs/user-guide/api-mediation/api-ml-installation-checklist-v.3.0.x.md to match the links below.
| @@ -0,0 +1,57 @@ | |||
| # API Mediation Layer (API ML) Installation and Configuration Checklist | |||
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
Sure. The links will be updated when we role out v3.4.
| # Zowe version-specific Install/Config Tasks | ||
|
|
||
| ## Preparing for Installation | ||
| | Task | Zowe v2.18 | Zowe v3.0 | Zowe v3.3 | |
There was a problem hiding this comment.
Should be v2.18.x, v3.0.x, v3.4.x I feel.
There was a problem hiding this comment.
That is a good question, so far we were really focused on the minor versions. The patch versions were more or less ignored unless it was a maintenance phase.
| | **Gateway architecture** | **Zuul Gateway** with Discovery and Catalog JVMs. | Migrated to **Spring Cloud Gateway**. | Uses **Spring Gateway Modulith** (optional single JVM). | | ||
| | **Port planning** | Separate ports for Gateway, Discovery, Catalog. | Modular services with distinct ports. | **Single port** possible in modulith mode. | | ||
| | **Keyring syntax** | `safkeyring:////<keyring_name>`. | Updated to `safkeyring://<keyring_name>`. | Same as v3.0. | | ||
| | **Deployment planning** | Multi-JVM only. | Modular runtime deployment: same microservice-based API ML (Gateway, Discovery, Catalog) | Choice of **modulith** (_recomended_) or microservice-based deployment. | |
There was a problem hiding this comment.
I don't think it's a great idea to use the term modulith anywhere other than in docs/user-guide/api-mediation/api-mediation-modulith.md. I would say "Choice of single-service (default and recommended) or microservice-based deployment."
There was a problem hiding this comment.
single-service is the term that we are using generally, but I want to hear from Andrej as we need to agree on whether and how we want to refer to this going forward.
| ## Configuring High Availability | ||
| | Task | Zowe v2.18 | Zowe v3.0 | Zowe v3.3 | | ||
| | ------------------------ | ---------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------- | | ||
| | **HA topology** | Multiple Gateway/Discovery/Catalog JVMs. | Modular microservices; external load balancer. | Modulith supports HA via **external clustering**. | |
There was a problem hiding this comment.
...single-service deployment mode...
| | ------------------------ | ---------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------- | | ||
| | **HA topology** | Multiple Gateway/Discovery/Catalog JVMs. | Modular microservices; external load balancer. | Modulith supports HA via **external clustering**. | | ||
| | **Service registration** | Internal Discovery synchronization. | Uses Spring-based Eureka registry. | Adds new timeout parameters (`connectTimeout`, `readTimeout`). | | ||
| | **Failover management** | Manual restart of JVMs. | Automatic via Spring Gateway and LB. | Modulith HA must be handled externally. | |
There was a problem hiding this comment.
...single-service deployment mode...
| ## Starting and Stopping Zowe | ||
| | Task | Zowe v2.18 | Zowe v3.0 | Zowe v3.3 | | ||
| | ----------------- | -------------------------------------------------------- | ------------------------------------------ | -------------------------------------------- | | ||
| | **Start command** | `zwe start` per component (Gateway, Discovery, Catalog). | `zwe start all` for all API ML components. | `zwe start apiml` for modulith (single JVM). | |
There was a problem hiding this comment.
...single-service deployment mode...
| | ----------------- | -------------------------------------------------------- | ------------------------------------------ | -------------------------------------------- | | ||
| | **Start command** | `zwe start` per component (Gateway, Discovery, Catalog). | `zwe start all` for all API ML components. | `zwe start apiml` for modulith (single JVM). | | ||
| | **Stop command** | `zwe stop` per service. | `zwe stop all` for modular runtime. | `zwe stop apiml` or `zwe stop all`. | | ||
| | **Startup logs** | Separate logs per JVM. | Combined logs for modular runtime. | Unified log stream in modulith. | |
There was a problem hiding this comment.
...single-service deployment mode...
| ## Verifying Installation | ||
| | Task | Zowe v2.18 | Zowe v3.0 | Zowe v3.3 | | ||
| | --------------------------- | --------------------------------------- | ----------------------------------------- | -------------------------------------------------- | | ||
| | **API Catalog access** | Verify via Zuul `/apicatalog` endpoint. | Verify via Spring Gateway endpoint. | Same endpoint; check “modulith mode enabled” log. | |
There was a problem hiding this comment.
I don't think that anyone would know where to look for the 'modulith mode enabled' log. After Pablo's previous comments, I suggest check gateway log.
Signed-off-by: Andrew Jandacek <[email protected]>
Signed-off-by: Andrew Jandacek <[email protected]>
Signed-off-by: Andrew Jandacek <[email protected]>
Signed-off-by: Andrew Jandacek <[email protected]>
Signed-off-by: Andrew Jandacek <[email protected]>
Signed-off-by: Andrew Jandacek <[email protected]>
Signed-off-by: Andrew Jandacek <[email protected]>
| | 1 | Identify and reserve necessary network ports for the API Gateway, Discovery Service, and API Catalog. | [Addressing network requirements](https://docs.zowe.org/v2.18.x/user-guide/address-network-requirements) | Required ports (e.g., 7551 for Gateway, 7552 for Discovery, 7553 for Catalog) are identified and confirmed as available and open through any firewalls. | N/A | Network Administrator / Zowe Administrator | | ||
| | 2 | Run `zwe init security` to create SAF security profiles and ensure that the Zowe runtime user (typically `ZWESVUSR`) has permissions to utilize Zowe resources. | [Generate Zowe security configurations](https://docs.zowe.org/v2.18.x/user-guide/initialize-zos-system#generate-zowe-security-configurations) | SAF profiles for Zowe and its components (including API ML) are created, and `ZWESVUSR` is defined with necessary permissions for Zowe started tasks and USS access. | N/A | Security Administrator / Zowe Administrator | | ||
| | 3 | Configure Zowe security group IDs for API ML users and services, ensuring proper access control. | [Assigning security permissions to users](https://docs.zowe.org/v2.18.x/user-guide/assign-security-permissions-to-users/) | Zowe security group IDs are assigned to relevant API ML users and services, adhering to organizational security policies. | N/A | Security Administrator | | ||
| | 4 | **Understand Zowe Certificate Requirements:** Review the basics of Zowe's certificate architecture, including the need for TLS/SSL and mTLS for secure communication between components. | [Configuring certificates](https://docs.zowe.org/v2.18.x/user-guide/configure-certificates) | Clear understanding of Zowe's certificate requirements, the types of certificates needed (server, CA), and their role in securing the API ML. | N/A | Zowe Administrator / Security Administrator | |
There was a problem hiding this comment.
I suggest that you expand 'CA' to 'certificate authority (CA)' on first use, especially given the former name of the company. Traditional mainframe staff sometimes don't know as much as we expect about certificate management, so we should spell out all but the most obvious terms.
I had to look up 'mTLS', so I was going to say to expand it - but the referenced document doesn't mention mTLS. Better removed?
Signed-off-by: Andrew Jandacek <[email protected]>
Signed-off-by: Andrew Jandacek <[email protected]>
Signed-off-by: Andrew Jandacek <[email protected]>
Signed-off-by: Andrew Jandacek <[email protected]>
Signed-off-by: Andrew Jandacek <[email protected]>
Signed-off-by: Andrew Jandacek <[email protected]>
Signed-off-by: Andrew Jandacek <[email protected]>
Signed-off-by: Andrew Jandacek <[email protected]>
Describe your pull request here: This is a POC for API ML installation checklists
List the file(s) included in this PR:
After creating the PR, follow the instructions in the comments.