Merge pull request #3951 from zowe/reboot/additional-ds-registration-fix

Extended information about additional registration of APIML
zowe · Oct 17, 2024 · b0f8221 · b0f8221
2 parents c97c67f + ca04a9f
commit b0f8221
Show file tree

Hide file tree

Showing 2 changed files with 57 additions and 15 deletions.
diff --git a/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md b/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md
@@ -67,12 +67,22 @@ Use the following example as a template for how to set the value for this proper
 ```
 components.gateway.apiml.service.additionalRegistration:
     # central API ML (in HA, for non-HA mode use only 1 hostname)
-       - discoveryServiceUrls:      https://sys1:{discoveryServicePort}/eureka/,https://sys2:{discoveryServicePort}/eureka/
- 	    routes:
+       - discoveryServiceUrls: https://sys1:{discoveryServicePort}/eureka/,https://sys2:{discoveryServicePort}/eureka/
+ 	     routes:
               - gatewayUrl: /
                 serviceUrl: /
 ```
 
+:::note
+  Ensure that each API ML instance is defined in a separated record. Do not combine multiple API ML instances in a
+  single record. In the case of a high availability setup, the value `discoveryServiceUrls` may contain multiple URLs.
+  We highly recommend to provide all available Discovery URLs in the value `discoveryServiceUrls`.
+
+  Always provide the direct address to the system. Do not use the DVIPA address. Using this address could lead to unexpected behaviour.
+
+  Use hostnames `sys1` and `sys2` for the LPAR in the sysplex.
+:::
+
 ```
 components.gateway.apiml.security.x509:
     #  cloud gateway port 
@@ -119,12 +129,22 @@ Use the following example as a template for how to set the value of this propert
 ```
 components.gateway.apiml.service.additionalRegistration:
     # central API ML (in HA, for non-HA mode use only 1 hostname)
-       - discoveryServiceUrls:      https://sys1:{discoveryServicePort}/eureka/,https://sys2:{discoveryServicePort}/eureka/
- 	    routes:
+       - discoveryServiceUrls: https://sys1:{discoveryServicePort}/eureka/,https://sys2:{discoveryServicePort}/eureka/
+ 	     routes:
               - gatewayUrl: /
                 serviceUrl: /
 ```
 
+:::note
+  Ensure that each API ML instance is defined in a separated record. Do not combine multiple API ML instances in a
+  single record. In the case of a high availability setup, the value `discoveryServiceUrls` may contain multiple URLs.
+  We highly recommend to provide all available Discovery URLs in the value `discoveryServiceUrls`.
+
+  Always provide the direct address to the system. Do not use the DVIPA address. Using this address could lead to unexpected behaviour.
+
+  Use hostnames `sys1` and `sys2` for the LPAR in the sysplex.
+:::
+
 #### Dynamic configuration: Environment variables
 
 The list of additional registrations is extracted from environment variables. You can define a list of objects by following YML -> Environment translation rules. 
@@ -137,6 +157,19 @@ ZWE_CONFIGS_APIML_SERVICE_ADDITIONALREGISTRATION_0_ROUTES_0_GATEWAYURL=/
 ZWE_CONFIGS_APIML_SERVICE_ADDITIONALREGISTRATION_0_ROUTES_0_SERVICEURL=/
 ```
 
+:::note
+  The number in the properties names (see position of `#` in `ZWE_CONFIGS_APIML_SERVICE_ADDITIONALREGISTRATION_#_*`)
+  defines ID of API ML instance.
+
+  Ensure that each API ML instance is defined in a separated record. Do not combine multiple API ML instances in a 
+  single record. In the case of a high availability setup, the value `discoveryServiceUrls` may contain multiple URLs. 
+  We highly recommend to provide all available Discovery URLs in the value `discoveryServiceUrls`.
+
+  Always provide the direct address to the system. Do not use the DVIPA address. Using this address could lead to unexpected behaviour.
+
+  Use hostnames `sys1` and `sys2` for the LPAR in the sysplex.
+:::
+
 This Zowe configuration transforms the zowe.yaml configuration file into the environment variables described previously. 
 
 ### Validating successful configuration

diff --git a/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md b/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md
@@ -13,18 +13,27 @@ Follow these steps to register with additional Discovery Services:
    components.gateway.apiml.service.additionalRegistration: 
        <!-- central APIML -->
        - discoveryServiceUrls: https://sys1:10011/eureka/,https://sys1:10021/eureka/ 
-                    routes:
-                            gatewayUrl: /
-                            serviceUrl: /
-     <!-- APIML on System 2 -->
+         routes:
+              - gatewayUrl: /
+                serviceUrl: /
+       <!-- APIML on System 2 -->
        - discoveryServiceUrls: https://sys2:10011/eureka/,https://sys2:10021/eureka/
-                    routes:
-                            gatewayUrl: /
-                            serviceUrl: /
-      <!-- APIML on System 3 -->
+         routes:
+              - gatewayUrl: /
+                serviceUrl: /
+       <!-- APIML on System 3 -->
        - discoveryServiceUrls: https://sys3:10011/eureka/,https://sys3:10021/eureka/ 
-                    routes:
-                            gatewayUrl: /
-                            serviceUrl: /
+         routes:
+              - gatewayUrl: /
+                serviceUrl: /
     ```
+
+   :::note
+     Ensure that each API ML instance is defined in a separated record. Do not combine multiple API ML instances in a
+     single record. In the case of a high availability setup, the value `discoveryServiceUrls` may contain multiple URLs.
+     We highly recommend to provide all available Discovery URLs in the value `discoveryServiceUrls`.
+
+     Always provide the direct address to the system. Do not use the DVIPA address. Using this address could lead to unexpected behaviour.
+   :::
+
 3. Restart Zowe.