Skip to main content
Version: v3.0.x LTS

Migrating Zowe server component from V1 to V2

Migrating Zowe server component from V1 to V2

This doc guides you through migrating an existing Zowe server component from version 1 to version 2.

To make Zowe server component compatible with Zowe version 2, you must update the following configurations.

Component manifest

In Zowe v2, the component must define a manifest file and package it into the extension's root directory. This manifest file is used by Zowe to understand how this component should be installed, configured, and started. For detailed information of this file, see Server Component Manifest File Reference.

Lifecycle scripts

In Zowe v2, lifecycle scripts can be located anywhere in your component directory. However, you must explicitly define them in the commands section of the component manifest file.

Environment variables

Zowe v1 and v2 environment variables are not exact match. There are the following differences:

  • Some variables in Zowe v1 are removed in v2.
  • Some are separated into two or more variables.
  • Zowe v2 defines more configuration options than v1.

Review the following table for a detailed mapping of Zowe v1 and v2 variables.

Zowe v1 VariableZowe v2 YAML ConfigurationZowe v2 VariableNotes
APIML_ALLOW_ENCODED_SLASHEScomponents.gateway.apiml.service.allowEncodedSlashesZWE_components_gateway_apiml_service_allowEncodedSlashes
APIML_CORS_ENABLEDcomponents.gateway.apiml.service.corsEnabledZWE_components_gateway_apiml_service_corsEnabled
APIML_DEBUG_MODE_ENABLEDcomponents.gateway.debug, etcZWE_components_gateway_debug, etcIn v2, you can enable debug mode for APIML components separately. The gateway placeholder can be discovery, api-catalog, and so on.
APIML_ENABLE_SSORemoved in v2Removed in v2
APIML_GATEWAY_EXTERNAL_MAPPERcomponents.gateway.apiml.security.x509.externalMapperUrlZWE_components_gateway_apiml_security_x509_externalMapperUrl
APIML_GATEWAY_INTERNAL_HOSTNot configurable in v2Not configurable in v2
APIML_GATEWAY_INTERNAL_PORTcomponents.gateway.server.internal.portZWE_components_gateway_server_internal_port
APIML_GATEWAY_TIMEOUT_MILLIScomponents.gateway.apiml.gateway.timeoutMillisZWE_components_gateway_apiml_gateway_timeoutMillis
APIML_MAX_CONNECTIONS_PER_ROUTEcomponents.gateway.server.maxConnectionsPerRouteZWE_components_gateway_server_maxConnectionsPerRoute
APIML_MAX_TOTAL_CONNECTIONScomponents.gateway.server.maxTotalConnectionsZWE_components_gateway_server_maxTotalConnections
APIML_PREFER_IP_ADDRESSRemoved in v2Removed in v2
APIML_SECURITY_AUTH_PROVIDERcomponents.gateway.apiml.security.auth.providerZWE_components_gateway_apiml_security_auth_provider
APIML_SECURITY_AUTHORIZATION_ENDPOINT_URLcomponents.gateway.apiml.security.authorization.endpoint.urlZWE_components_gateway_apiml_security_authorization_endpoint_url
APIML_SECURITY_X509_ENABLEDcomponents.gateway.apiml.security.x509.enabledZWE_components_gateway_apiml_security_x509_enabled
APIML_SECURITY_ZOSMF_APPLIDzOSMF.applIdZOSMF_APPLID
CATALOG_PORTcomponents.api-catalog.portZWE_components_api_catalog_port
DISCOVERY_PORTcomponents.discovery.portZWE_components_discovery_port
EXTERNAL_CERTIFICATE_AUTHORITIESzowe.certificate.pem.certificateAuthoritiesZWE_zowe_certificate_pem_certificateAuthorities
EXTERNAL_COMPONENTSRemoved in v2Removed in v2Zowe v2 configuration does not distinguish core components and extensions on how to enable them. They use the same components.<component>.enabled configuration.
GATEWAY_PORTcomponents.gateway.portZWE_components_gateway_port
INSTANCE_DIRRemoved in v2ZWE_zowe_workspaceDirectory or ZWE_zowe_logDirectoryThe instance directory is split into workspace and logs directory in v2.
JAVA_HOMEjava.homeJAVA_HOME
JES_EXPLORER_UI_PORTRemoved in v2Removed in v2In v2, explorer-jes reuses the web server provided by App Server. It does not start independent web server.
KEY_ALIASzowe.certificate.keystore.aliasZWE_zowe_certificate_keystore_alias
KEYSTORE_CERTIFICATE_AUTHORITYzowe.certificate.pem.certificateAuthoritiesZWE_zowe_certificate_pem_certificateAuthorities
KEYSTORE_CERTIFICATEzowe.certificate.pem.certificateZWE_zowe_certificate_pem_certificate
KEYSTORE_DIRECTORYzowe.setup.certificate.pkcs12.directoryZWE_zowe_setup_certificate_pkcs12_directoryThis is a setup variable in v2. It is optional and may not have a value if you manually prepare keystores by yourself.
KEYSTORE_KEYzowe.certificate.pem.keyZWE_zowe_certificate_pem_key
KEYSTORE_PASSWORDzowe.certificate.keystore.password and zowe.certificate.truststore.passwordZWE_zowe_certificate_keystore_password and ZWE_zowe_certificate_truststore_password
KEYSTORE_TYPEzowe.certificate.keystore.type and zowe.certificate.truststore.typeZWE_zowe_certificate_keystore_type and ZWE_zowe_certificate_truststore_type
KEYSTOREzowe.certificate.keystore.fileZWE_zowe_certificate_keystore_file
LAUNCH_COMPONENT_GROUPSRemoved in v2Removed in v2Zowe v2 doesn't group several components together. It us suggested that you enable or disable component individually.
MVS_EXPLORER_UI_PORTRemoved in v2Removed in v2In v2, explorer-mvs reuses web server provided by App Server. It will not start independent web server.
PKCS11_TOKEN_LABELRemoved in v2Removed in v2
PKCS11_TOKEN_NAMERemoved in v2Removed in v2
ROOT_DIRzowe.runtimeDirectoryZWE_zowe_runtimeDirectory
SKIP_NODERemoved in v2Removed in v2
STATIC_DEF_CONFIG_DIR-ZWE_STATIC_DEFINITIONS_DIRValue is always ${ZWE_zowe_workspaceDirectory}/api-mediation/api-defs.
TRUSTSTOREzowe.certificate.truststore.fileZWE_zowe_certificate_truststore_file
USS_EXPLORER_UI_PORTRemoved in v2Removed in v2In v2, explorer-uss reuses web server provided by App Server. It does not start independent web server.
ZOSMF_HOSTzOSMF.hostZOSMF_HOST
ZOSMF_PORTzOSMF.portZOSMF_PORT
ZOWE_APIM_NONSTRICT_VERIFY_CERTIFICATESzowe.verifyCertificatesZWE_zowe_verifyCertificateszowe.verifyCertificates has 3 options: STRICT, NONSTRICT, and DISABLED.
ZOWE_APIM_VERIFY_CERTIFICATESzowe.verifyCertificatesZWE_zowe_verifyCertificateszowe.verifyCertificates has 3 options: STRICT, NONSTRICT, and DISABLED.
ZOWE_EXPLORER_FRAME_ANCESTORSRemoved in v2Removed in v2
ZOWE_EXPLORER_HOSTzowe.externalDomains or haInstances.<ha-instance>.hostnameZWE_zowe_externalDomains, ZWE_zowe_externalDomains_0, ZWE_haInstance_hostname or ZWE_haInstances_<ha-instance>_hostnameZowe v2 separates external domain name from internal host name. Choose the appropriate variable by northbound or southbound facing.
ZOWE_INSTANCERemoved in v2Removed in v2Use ZWE_zowe_job_prefix or ZWE_zowe_job_name instead.
ZOWE_IP_ADDRESSRemoved in v2Removed in v2If you don't have a hostname but use IP to access Zowe, you can put IP into zowe.externalDomains
ZOWE_PREFIXzowe.job.prefixZWE_zowe_job_prefixThe meaning of this variable is changed in v2. In v1, this combines with ZOWE_INSTANCE as the job prefix. In v2, ZOWE_INSTANCE is removed and this affects only the address space names under Zowe job. V2 variable ZWE_zowe_job_name defines the full job name for Zowe.
ZOWE_ZLUX_SECURITY_TYPE--(Coming soon)
ZOWE_ZLUX_SERVER_HTTPS_PORT--(Coming soon)
ZOWE_ZLUX_SSH_PORT--(Coming soon)
ZOWE_ZLUX_TELNET_PORT--(Coming soon)
ZOWE_ZSS_SERVER_PORT--(Coming soon)
ZOWE_ZSS_SERVER_TLS--(Coming soon)
ZOWE_ZSS_XMEM_SERVER_NAME--(Coming soon)
ZWE_CACHING_EVICTION_STRATEGYcomponents.caching-service.storage.evictionStrategyZWE_components_caching_service_storage_evictionStrategy
ZWE_CACHING_SERVICE_PERSISTENTcomponents.caching-service.storage.modeZWE_components_caching_service_storage_mode
ZWE_CACHING_SERVICE_PORTcomponents.caching-service.portZWE_components_caching_service_port
ZWE_CACHING_SERVICE_VSAM_DATASETcomponents.caching-service.storage.vsam.nameZWE_components_caching_service_storage_vsam_name
ZWE_CACHING_STORAGE_SIZEcomponents.caching-service.storage.sizeZWE_components_caching_service_storage_size
ZWE_DISCOVERY_SERVICES_LIST-ZWE_DISCOVERY_SERVICES_LIST
ZWE_DISCOVERY_SERVICES_REPLICAScomponents.discovery.replicasZWE_components_discovery_replicasThis is only available for Zowe Kubernetes deployment.
ZWE_EXTENSION_DIRzowe.extensionDirectoryZWE_zowe_extensionDirectory
ZWE_EXTERNAL_HOSTSzowe.externalDomainsZWE_zowe_externalDomains
ZWE_EXTERNAL_PORTzowe.externalPortZWE_zowe_externalPort
ZWE_LAUNCH_COMPONENTSCombined information of components.<component>.enabled with value of trueZWE_ENABLED_COMPONENTS or ZWE_LAUNCH_COMPONENTSDepends on the purpose, in v2, ZWE_ENABLED_COMPONENTS are list of components with enabled status true. ZWE_LAUNCH_COMPONENTS in v2 is a subset of ZWE_ENABLED_COMPONENTS which components also have commands.start lifecycle script.
ZWE_LOG_LEVEL_ZWELSzowe.launchScript.logLevelZWE_zowe_launchScript_logLevel
ZWEAD_EXTERNAL_STATIC_DEF_DIRECTORIESRemoved in v2Removed in v2Use ZWE_STATIC_DEFINITIONS_DIR instead.
ZWES_ZIS_LOADLIBzowe.setup.dataset.authLoadlibZWE_zowe_setup_dataset_authLoadlib
ZWES_ZIS_PARMLIB_MEMBER--
ZWES_ZIS_PARMLIBzowe.setup.dataset.parmlibZWE_zowe_setup_dataset_parmlib
ZWES_ZIS_PLUGINLIBzowe.setup.dataset.authPluginLibZWE_zowe_setup_dataset_authPluginLib

Packaging one component deliverable for both Zowe v1 and v2

It is recommended that you create a dedicated package of extensions for Zowe v2, which is the most straight-forward way to address all of the breaking changes introduced in v2. We understand that this method presents the challenge of maintaining two sets of packages. If you prefer not to maintain two sets of packages, it's still possible to maintain one version of an extension which works for both Zowe v1 and v2. However, the lifecycle code will be complicated and in this case, comprehensive testing should be performed.

caution

The Zowe v2 App Framework desktop is upgraded from Angular version 6 to angular version 12 for support and security - websites have a "1 version of a library" limitation. This means that plug-ins dependent upon Angular must be coded for either v6 or v12 [not both] thus the single version approach is not applicable.

If the lifecycle scripts are the main concern, the following steps outline requirements and recommendations for the single version approach:

  • Packaging manifest.yaml is required. This is a hard requirement for Zowe v2. If you define lifecycle scripts with default names, for example, use bin/start.sh as commands.start, it should work for v1.
  • Revisit all environment variables used in the lifecycle scripts and apply fallback variables. For example, if you use $ROOT_DIR in Zowe v1, this should be changed to ${ZWE_zowe_runtimeDirectory:-${ROOT_DIR}} to make it compatible with both versions. Other variables like $EXPLORER_HOST should be changed to ${ZWE_haInstance_hostname:-${EXPLORER_HOST}} or ${ZWE_externalDomains_0:-${EXPLORER_HOST}} based on purpose.
  • In Zowe v2, we recommend you to define extension configurations in the manifest.yaml configs section and use ${ZWE_configs_*} variables to access them. This feature does not exist in Zowe v1. So if you use ${ZWE_configs_*} variables, it should fall back to the matching environment variable used in v1.
  • In Zowe v2, we recommend you to define a commands.install lifecycle script to handle extension installation. This lifecycle script will be executed by zwe components install. In v1, this also exists if you use the zowe-install-components.sh utility to install a Zowe extension. So if you want one extension package to work for both Zowe v1 and v2, this install lifecycle script should also be compatible with both v1 and v2.
  • A new v2 variable ${ZWE_VERSION} may help you determine the Zowe version number. This variable does not exist in Zowe v1. By knowing the Zowe version, the lifecycle scripts can implement logic to source v1 or v2 dedicated scripts to avoid handling fallbacks in the same script. This could help avoid complicated compatibility version checks, and it could be easier in the future if you decide to drop Zowe v1.