-
Notifications
You must be signed in to change notification settings - Fork 134
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.
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
Add a v3 migration page #3889
Open
skurnevich
wants to merge
27
commits into
master
Choose a base branch
from
feature/v3-migration
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Add a v3 migration page #3889
Changes from 16 commits
Commits
Show all changes
27 commits
Select commit
Hold shift + click to select a range
d99087a
Add a v3 migration page
skurnevich cdeff39
Minor fixes, jwtAutoconfiguration details
skurnevich a41735c
Minor change in the pre-req around z/OSMF
balhar-jakub e5276c1
Fixing the line breaks for the build to pass
skurnevich 3b4e4f0
minor langugage refactor
janan07 a182729
Merge branch 'master' into feature/v3-migration
janan07 f07f348
Merge branch 'master' into feature/v3-migration
skurnevich d4f7827
Prereq Updates
1000TurquoisePogs 3d18fa9
Merge pull request #3900 from zowe/fix/v3/prereq-migrate
skurnevich 531c4bc
Adding a workspace note
skurnevich baae293
Put v2 upgrade instructions at top of v3 migrate guide
1000TurquoisePogs 2378acc
Add System Changes section to migrate guide
1000TurquoisePogs 432f19b
Merge pull request #3902 from zowe/doc/v3/v2-old-upgrade
skurnevich 4dc18b5
Merge pull request #3903 from zowe/doc/v3/migrate-system-changes
skurnevich 03b6152
merged removed components details into network changes table, minor f…
skurnevich 9449d52
fix a typo
skurnevich 116fab0
Update zowe-v3-migration.md
1000TurquoisePogs 1205672
Update zowe-v3-migration.md
1000TurquoisePogs 051f0fc
Merge pull request #3913 from zowe/feature/v3-v1-migration
skurnevich 982d9e1
Revert cloud gateway details
skurnevich b847036
Move v1 migration section, added a link to v1 migration page
skurnevich 4764c13
create dropdowns for migrating from previous versions
janan07 a7de88a
minor language refactoring
janan07 12c3276
Merge branch 'master' into feature/v3-migration
janan07 3d90efe
Add sidebars location
skurnevich a4d136e
Fix the details tag for the build
skurnevich 0c4fc9d
Merge branch 'master' into feature/v3-migration
janan07 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,172 @@ | ||
# Zowe V3 Migration Guide | ||
|
||
This guide outlines the steps and changes required to migrate from Zowe v2 to Zowe v3. While the migration process is similar to a Zowe v2 minor release upgrade, there are several new and updated configuration parameters to consider. The workspace directory should be re-created only if you are using the app-server component. | ||
Follow the steps described in this article to ensure a smooth migration. | ||
|
||
|
||
## Upgrading to the latest version of Zowe v2 (v2.18) | ||
|
||
Before upgrading to Zowe v3.0.0, first upgrade to Zowe v2.18, as the rest of the migration instructions are based upon Zowe v2.18. | ||
Please follow the instructions from the version of Zowe you have and newer in order to prepare to upgrade from Zowe v2 to v3.0.0. | ||
|
||
### Migrating from Zowe v2.16.0 or Lower | ||
|
||
If you are migrating from Zowe **v2.16.0** or a lower version, perform the following tasks: | ||
|
||
1) Ensure the following `zowe.network` section is added to your configuration: | ||
|
||
```yaml | ||
network: | ||
server: | ||
tls: | ||
attls: false | ||
# TLS settings only apply when attls=false | ||
# Else you must use AT-TLS configuration for TLS customization. | ||
minTls: "TLSv1.2" | ||
maxTls: "TLSv1.3" | ||
client: | ||
tls: | ||
attls: false | ||
``` | ||
|
||
2) Update your PROCLIB entries for Zowe, as enhancements and default parameters have changed throughout Zowe v2. | ||
This can be performed with the unix command `zwe init stc`, by running the job ZWEISTC, or by copying the SZWESAMP members ZWESLSTC, ZWESISTC, and ZWESASTC into your desired PROCLIB. | ||
|
||
|
||
### Migrating from Zowe v2.15.0 or Lower | ||
|
||
|
||
If you are migrating from Zowe **v2.15.0** or a lower version, ensure that Zowe configurations using keyrings do not have the section `zowe.certificate.pem`. | ||
This section is no longer needed and can cause startup error in newer versions of Zowe. | ||
|
||
### Migrating from Zowe v2.10.0 or Lower | ||
|
||
If you are migrating from Zowe **v2.10.0** or a lower version, consider taking advantage of the new **sysMessages** feature. | ||
|
||
The `zowe.sysMessages` is a new array that allows you to select messages that, when found by the launcher, will be duplicated into the system's log. | ||
|
||
### Migrating from Zowe v2.9.0 or Lower | ||
|
||
If you are migrating from Zowe **v2.9.0** or a lower version, it is recommended to delete the `<zowe.workspaceDirectory>/app-server/plugins` directory so that it can be regenerated on the next run of Zowe. | ||
In this version and prior there were old and no longer used Application Framework plugins and references to them will complicate logs with harmless errors. | ||
|
||
### Migrating from Zowe v2.3.0 or Lower | ||
|
||
If you are running Zowe **v2.3.0** or a lower version, a **clean install** of Zowe v3 is highly recommended to avoid potential issues during the migration process. | ||
|
||
|
||
## V3 Prerequisite Changes | ||
|
||
Before starting the migration, ensure the following system requirements are met: | ||
|
||
- **z/OSMF** | ||
Version V2R5 with APAR PH12143 or V3R1 is required. JWT support for z/OSMF must be enabled, [as seen in their documentation.](https://www.ibm.com/docs/en/zos/3.1.0?topic=configurations-enabling-json-web-token-support) | ||
- **Java** | ||
Java 17 is required. The Zowe YAML parameter `java.home` value should be a **Java 17** home location. If an administrator uses `zwe init` to set up Zowe, ensure the `java` for that user is v17 by including it in the `PATH` environment variable. | ||
- **Node.js** | ||
The Zowe YAML parameter `node.home` value should be a **Node.js 18 or 20** home location, as Node 16 and below are no longer supported. | ||
|
||
|
||
## System and Security Changes | ||
|
||
- Existing SAF settings for Zowe do not need to be changed for v3, so install steps such as `zwe init security`, the job or workflow ZWESECUR, and the jobs ZWEIRAC, ZWEITSS, and ZWEIACF are not required to be re-run. | ||
|
||
- Existing keyrings and keystores do not need to be changed for v3, so install steps such as `zwe init certificate`, the job or workflow ZWEKRING or jobs starting with ZWEIKR* are not required to be re-run. | ||
|
||
- The following network changes are needed for added or removed servers: | ||
|
||
| Component name | Change | Default Port | Default Jobname | Details | | ||
|----------------|--------|--------------|-----------------|---------| | ||
| zaas | Added | 7558 | ZWE1AZ | This component is responsible for authentication and is now required when using the API Mediation Layer | | ||
| metrics-service | Removed | 7551 | ZWE1MS | This service has been deprecated and removed. Currently, no replacement is available. The Open Telemetry standard will be implemented later, which will serve as a replacement | | ||
| jobs-api | Removed | 7558 | ZWE1EJ | This component was deprecated in Zowe v2 and is now removed. Ensure that you switch to using equivalent z/OSMF endpoints | | ||
| files-api | Removed | 7559 | ZWE1EF | This component was deprecated in Zowe v2 and is now removed. Ensure that you switch to using equivalent z/OSMF endpoints | | ||
| cloud-gateway | Removed | 7563 | ZWE1CG | The cloud-gateway has replaced the main gateway component in v3 and is now accessible on 7554 as ZWE1AG | | ||
|
||
|
||
## Configuration changes | ||
|
||
Review the following changes to configuration and updated configuration parameters. | ||
|
||
### New Configuration | ||
|
||
**components.zaas** | ||
Previously part of the `components.gateway` component, zaas in Zowe v3 is a separate component responsible for authentication. | ||
If you do not explicitly configure this section, zaas will still be enabled by default and will use **port 7558**. | ||
|
||
```yaml | ||
components: | ||
zaas: | ||
enabled: true | ||
port: 7558 | ||
debug: false | ||
``` | ||
|
||
### Updated Configuration Parameters | ||
--- | ||
|
||
#### Keyrings | ||
|
||
If you are using keyrings, verify that Zowe YAML references to `safkeyring` uses 2 slashes, not 4, such as `safkeyring://` instead of `safkeyring:////`. | ||
|
||
#### Gateway z/OSMF service configuration | ||
|
||
The service ID for gateway zosmf has changed to **ibmzosmf**. <br/> | ||
Set `jwtAutoconfiguration` to **jwt** (default) or **ltpa**. Note that **auto** is no longer supported.<br/> | ||
If you are using zosmf as your auth service, ensure that you update this z/OSMF service configuration. | ||
|
||
```yaml | ||
components: | ||
gateway: | ||
apiml: | ||
security: | ||
auth: | ||
zosmf: | ||
jwtAutoconfiguration: jwt | ||
skurnevich marked this conversation as resolved.
Show resolved
Hide resolved
|
||
serviceId: ibmzosmf | ||
``` | ||
|
||
#### Caching Service | ||
|
||
The Caching service now defaults to **Infinispan** mode instead of **VSAM**. | ||
While **VSAM** is still supported, this storage method is being deprecated and is not recommended. | ||
A new parameter for the key exchange port has been added to the default configuraion. | ||
|
||
```yaml | ||
components: | ||
caching-service: | ||
storage: | ||
mode: infinispan | ||
infinispan: | ||
jgroups: | ||
port: 7600 | ||
keyExchange: | ||
port: 7601 | ||
``` | ||
#### ZSS Server | ||
|
||
The ZSS server now runs in **64-bit** mode by default. | ||
|
||
```yaml | ||
components: | ||
zss: | ||
agent: | ||
64bit: true | ||
``` | ||
|
||
### Deprecated Settings: | ||
|
||
The following configuration parameters have been deprecated in Zowe v3. Ensure that these parameters are removed from your configuration. | ||
|
||
**zowe.useConfigmgr** | ||
The parameter `zowe.useConfigmgr=false` is no longer supported. | ||
|
||
**components.gateway.server.internal** | ||
The internal gateway server has been removed due to limited usage. | ||
|
||
```yaml | ||
components: | ||
gateway: | ||
server: | ||
internal: | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this detail about cloud-gateway replaces gateway yet takes on the same name and port as gateway is perhaps too much technical information for users - I shared this document with users and they didn't know what it meant.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Then we should just mention that it is removed here
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Reverted it to the previous phrase "The cloud-gateway has been removed as a standalone component and merged into the gateway", looks ok?