Skip to main content
Version: v2.18.x LTS

Zowe V3 Migration Guide

Last updated
:  |
... min read
|
Edit this page
Print
Open doc issue

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:
  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
  1. 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.
  • 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.

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.

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.
Set jwtAutoconfiguration to jwt (default) or ltpa. Note that auto is no longer supported.
If you are using zosmf as your auth service, ensure that you update this z/OSMF service configuration.

components:
  gateway:
    apiml:
      security:
        auth:
          zosmf:
             jwtAutoconfiguration: jwt
             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.

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.

components:
  zss:
    agent:
      64bit: true

Removed Configuration Parameters​

The following configuration parameters have been deprecated in Zowe v3. Ensure that these parameters are removed from your configuration.

Deprecated Settings:​

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.

components:
  gateway:
    server:
      internal:

Removed Components:​

metrics-service
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.

cloud-gateway
The cloud-gateway component has been removed as a standalone component and merged into the gateway.

jobs-api and files-api
These two components were deprecated in Zowe v2 and are now removed in v3. Ensure that you switch to using equivalent z/OSMF endpoints.

On this page