From d99087a0309cabb820fb863ba16c23e143c859aa Mon Sep 17 00:00:00 2001
From: Sergei Kurnevich <sergei.kurnevich@broadcom.com>
Date: Wed, 25 Sep 2024 23:29:45 +0200
Subject: [PATCH] Add a v3 migration page

Signed-off-by: Sergei Kurnevich <sergei.kurnevich@broadcom.com>
---
 docs/whats-new/zowe-v3-migration.md | 121 ++++++++++++++++++++++++++++
 sidebars.js                         |   1 +
 2 files changed, 122 insertions(+)
 create mode 100644 docs/whats-new/zowe-v3-migration.md

diff --git a/docs/whats-new/zowe-v3-migration.md b/docs/whats-new/zowe-v3-migration.md
new file mode 100644
index 0000000000..f4c4db0770
--- /dev/null
+++ b/docs/whats-new/zowe-v3-migration.md
@@ -0,0 +1,121 @@
+# 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 minor release upgrade, there are several new and updated configuration parameters to consider. Follow the steps below to ensure a smooth migration.
+
+
+## Prerequisites
+
+Before starting the migration, ensure the following system requirements are met:
+
+- **z/OSMF**: Version V2R5 with APAR PH12143 is required.
+- **Java**: Ensure java.home is set to **Java 17**.
+- **Node.js**: Ensure node.home is set to **Node.js 18+**.
+- **Keyrings**: If you are using keyrings, verify that you use safkeyring:// instead of safkeyring:////.
+
+
+
+## Configuration changes
+
+### New Configuration
+
+**components.zaas**:  
+  Previously part of the components.gateway component (used as the auth service), zaas has now been moved to a separate component.  
+  If you do not explicitly configure this section, zaas will still be enabled by default, using **port 7558**.
+
+### Updated Configuration Parameters
+
+#### Gateway z/OSMF Service ID
+
+The service ID for gateway zosmf has changed to **ibmzosmf**. If you are using zosmf as your auth service, this needs to be updated.
+
+```yaml
+components:
+  gateway:
+    apiml:
+      security:
+        auth:
+          zosmf:
+             jwtAutoconfiguration: jwt
+             serviceId: ibmzosmf
+```
+
+#### Caching Service
+
+The caching service now defaults to **Infinispan** mode instead of **VSAM**. **VSAM** is deprecated (still supported but 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
+```
+
+### Removed Configuration Parameters
+
+The following configuration parameters have been deprecated in Zowe v3, so should be removed from your configuraion
+
+#### 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.
+
+```yaml
+components:
+  gateway:
+    server:
+      internal:
+        enabled: false
+```
+
+#### Removed Components:
+
+**metrics-service**: This service has been deprecated and removed, currently there is no replacement. 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 components were deprecated in Zowe v2 and are now removed in v3. You should switch to using equivalent z/OSMF endpoints.
+
+
+
+## Special Considerations for Older Versions
+
+### Migrating from Zowe v2.16.0 or Lower
+
+If you are migrating from Zowe **v2.16.0** or lower, 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
+```
+
+### Migrating from Zowe v2.10.0 or Lower
+
+If you are migrating from Zowe **v2.10.0** or lower, consider taking advantage of the new **sysMessages** feature.
+
+### Migrating from Zowe v2.3.0 or Lower
+
+If you are running Zowe **v2.3.0** or lower, a **clean install** of Zowe v3 is highly recommended to avoid potential issues during the migration process.
\ No newline at end of file
diff --git a/sidebars.js b/sidebars.js
index 6b00e2f3c9..89f2bb1431 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -39,6 +39,7 @@ module.exports = {
         "whats-new/zowe-v3-office-hours",
         "whats-new/zowe-v3-conformance-criteria",
         "whats-new/zowe-v3-frequently-asked-questions",
+        "whats-new/zowe-v3-migration",
       ],
     },
   ],