From 317775601d1141e73adfb3fd4d1f00c2ae910209 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pavel=20Jare=C5=A1?= Date: Tue, 15 Oct 2024 09:40:26 +0200 Subject: [PATCH 1/7] fixes and notes to explain examples --- .../api-mediation-multi-tenancy.md | 34 ++++++++++++++++--- .../configuration-multi-tenancy-routing.md | 30 ++++++++++------ 2 files changed, 49 insertions(+), 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 index 9e51f00d83..f33a9c1ce7 100644 --- 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,21 @@ 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 + The value `discoveryServiceUrls` should contain all instances of Discovery services for a specific API ML instance. + + Do not provide multiple API ML instance in one `discoveryServiceUrls`. Always provide the direct address to the + system, do not use DVIPA address. It could lead to unexpected behaviour. + + Hostname `sys1` and `sys2` are names of LPAR in the sysplex. +::: + ``` components.gateway.apiml.security.x509: # cloud gateway port @@ -119,12 +128,21 @@ 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 + The value `discoveryServiceUrls` should contain all instances of Discovery services for a specific API ML instance. + + Do not provide multiple API ML instance in one `discoveryServiceUrls`. Always provide the direct address to the + system, do not use DVIPA address. It could lead to unexpected behaviour. + + Hostnames `sys1` and `sys2` are names of 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 +155,14 @@ ZWE_CONFIGS_APIML_SERVICE_ADDITIONALREGISTRATION_0_ROUTES_0_GATEWAYURL=/ ZWE_CONFIGS_APIML_SERVICE_ADDITIONALREGISTRATION_0_ROUTES_0_SERVICEURL=/ ``` +:::note + Value `#` in the properties name `ZWE_CONFIGS_APIML_SERVICE_ADDITIONALREGISTRATION_#_*` defines ID of APIML instance. + For HA is necessary to provide all address of Discovery service instances. Always provide the direct address to the + system, do not use DVIPA address. It could lead to unexpected behaviour. + + Hostnames `sys1` and `sys2` are names of 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 index a9db5054e1..c0d9967bcc 100644 --- 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,26 @@ Follow these steps to register with additional Discovery Services: components.gateway.apiml.service.additionalRegistration: - discoveryServiceUrls: https://sys1:10011/eureka/,https://sys1:10021/eureka/ - routes: - gatewayUrl: / - serviceUrl: / - + routes: + - gatewayUrl: / + serviceUrl: / + - discoveryServiceUrls: https://sys2:10011/eureka/,https://sys2:10021/eureka/ - routes: - gatewayUrl: / - serviceUrl: / - + routes: + - gatewayUrl: / + serviceUrl: / + - discoveryServiceUrls: https://sys3:10011/eureka/,https://sys3:10021/eureka/ - routes: - gatewayUrl: / - serviceUrl: / + routes: + - gatewayUrl: / + serviceUrl: / ``` + + :::note + The value `discoveryServiceUrls` should contain all instances of Discovery services for a specific API ML instance. + + Do not provide multiple API ML instance in one `discoveryServiceUrls`. Always provide the direct address to the + system, do not use DVIPA address. It could lead to unexpected behaviour. + ::: + 3. Restart Zowe. From ce8ad65f3882ba6bfed344d81cdf252bfb406cd1 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Wed, 16 Oct 2024 16:10:43 +0200 Subject: [PATCH 2/7] initial language refactor Signed-off-by: Andrew Jandacek --- .../user-guide/api-mediation/api-mediation-multi-tenancy.md | 6 +++--- 1 file changed, 3 insertions(+), 3 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 index f33a9c1ce7..88db3042a5 100644 --- a/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md +++ b/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md @@ -74,10 +74,10 @@ components.gateway.apiml.service.additionalRegistration: ``` :::note - The value `discoveryServiceUrls` should contain all instances of Discovery services for a specific API ML instance. + Ensure that the value of `discoveryServiceUrls` contains all instances of Discovery services for a specific API ML instance. - Do not provide multiple API ML instance in one `discoveryServiceUrls`. Always provide the direct address to the - system, do not use DVIPA address. It could lead to unexpected behaviour. + Do not provide multiple API ML instances in one `discoveryServiceUrls`. Always provide the direct address to the + system, and not the DVIPA address. Using the DVIPA address could result in unexpected behaviour. Hostname `sys1` and `sys2` are names of LPAR in the sysplex. ::: From 6042f10dd6ed627a69f73937aff276865fbb7cf9 Mon Sep 17 00:00:00 2001 From: Pavel Jares Date: Wed, 16 Oct 2024 16:51:25 +0200 Subject: [PATCH 3/7] code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Pavel Jareš --- .../api-mediation-multi-tenancy.md | 27 ++++++++++++------- .../configuration-multi-tenancy-routing.md | 9 ++++--- 2 files changed, 22 insertions(+), 14 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 index 88db3042a5..2ec9e4fa39 100644 --- a/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md +++ b/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md @@ -74,10 +74,11 @@ components.gateway.apiml.service.additionalRegistration: ``` :::note - Ensure that the value of `discoveryServiceUrls` contains all instances of Discovery services for a specific API ML instance. + Each API ML instance should be defined in a separated record. Do not mix different API ML instance in one record. + The value `discoveryServiceUrls` could contain multiple URLs in case of HA setup. We highly recommend to provide all + available Discovery URLs in there. - Do not provide multiple API ML instances in one `discoveryServiceUrls`. Always provide the direct address to the - system, and not the DVIPA address. Using the DVIPA address could result in unexpected behaviour. + Always provide the direct address to the system, do not use DVIPA address. It could lead to unexpected behaviour. Hostname `sys1` and `sys2` are names of LPAR in the sysplex. ::: @@ -135,10 +136,11 @@ components.gateway.apiml.service.additionalRegistration: ``` :::note - The value `discoveryServiceUrls` should contain all instances of Discovery services for a specific API ML instance. - - Do not provide multiple API ML instance in one `discoveryServiceUrls`. Always provide the direct address to the - system, do not use DVIPA address. It could lead to unexpected behaviour. + Each API ML instance should be defined in a separated record. Do not mix different API ML instance in one record. + The value `discoveryServiceUrls` could contain multiple URLs in case of HA setup. We highly recommend to provide all + available Discovery URLs in there. + + Always provide the direct address to the system, do not use DVIPA address. It could lead to unexpected behaviour. Hostnames `sys1` and `sys2` are names of LPAR in the sysplex. ::: @@ -156,9 +158,14 @@ ZWE_CONFIGS_APIML_SERVICE_ADDITIONALREGISTRATION_0_ROUTES_0_SERVICEURL=/ ``` :::note - Value `#` in the properties name `ZWE_CONFIGS_APIML_SERVICE_ADDITIONALREGISTRATION_#_*` defines ID of APIML instance. - For HA is necessary to provide all address of Discovery service instances. Always provide the direct address to the - system, do not use DVIPA address. It could lead to unexpected behaviour. + The number in the properties names (see position of `#` in `ZWE_CONFIGS_APIML_SERVICE_ADDITIONALREGISTRATION_#_*`) + defines ID of API ML instance. + + Each API ML instance should be defined in a separated record. Do not mix different API ML instance in one record. + The value `discoveryServiceUrls` could contain multiple URLs in case of HA setup. We highly recommend to provide all + available Discovery URLs in there. + + Always provide the direct address to the system, do not use DVIPA address. It could lead to unexpected behaviour. Hostnames `sys1` and `sys2` are names of LPAR in the sysplex. ::: diff --git a/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md b/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md index c0d9967bcc..4fb681f402 100644 --- a/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md +++ b/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md @@ -29,10 +29,11 @@ Follow these steps to register with additional Discovery Services: ``` :::note - The value `discoveryServiceUrls` should contain all instances of Discovery services for a specific API ML instance. - - Do not provide multiple API ML instance in one `discoveryServiceUrls`. Always provide the direct address to the - system, do not use DVIPA address. It could lead to unexpected behaviour. + Each API ML instance should be defined in a separated record. Do not mix different API ML instance in one record. + The value `discoveryServiceUrls` could contain multiple URLs in case of HA setup. We highly recommend to provide + all available Discovery URLs in there. + + Always provide the direct address to the system, do not use DVIPA address. It could lead to unexpected behaviour. ::: 3. Restart Zowe. From 3c54bec6914b5f6b2466b23d929577360dc360bf Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Thu, 17 Oct 2024 10:08:08 +0200 Subject: [PATCH 4/7] refactor note Signed-off-by: Andrew Jandacek --- .../api-mediation/api-mediation-multi-tenancy.md | 8 +++----- 1 file changed, 3 insertions(+), 5 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 index 2ec9e4fa39..0e88c3df29 100644 --- a/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md +++ b/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md @@ -74,13 +74,11 @@ components.gateway.apiml.service.additionalRegistration: ``` :::note - Each API ML instance should be defined in a separated record. Do not mix different API ML instance in one record. - The value `discoveryServiceUrls` could contain multiple URLs in case of HA setup. We highly recommend to provide all - available Discovery URLs in there. + 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 DVIPA address. It could lead to unexpected behaviour. + Always provide the direct address to the system. Do not use the DVIPA address. Using this address could lead to unexpected behaviour. - Hostname `sys1` and `sys2` are names of LPAR in the sysplex. + Use hostnames `sys1` and `sys2` for the LPAR in the sysplex. ::: ``` From 4ec396dbce005655faae6ea02800e12a21ff3d5f Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Thu, 17 Oct 2024 10:55:42 +0200 Subject: [PATCH 5/7] propogate refactored note Signed-off-by: Andrew Jandacek --- .../api-mediation/api-mediation-multi-tenancy.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 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 index 0e88c3df29..e4d6e39102 100644 --- a/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md +++ b/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md @@ -74,7 +74,7 @@ components.gateway.apiml.service.additionalRegistration: ``` :::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`. + Ensure that each API ML instance is defined in a separate 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. @@ -133,14 +133,12 @@ components.gateway.apiml.service.additionalRegistration: serviceUrl: / ``` -:::note - Each API ML instance should be defined in a separated record. Do not mix different API ML instance in one record. - The value `discoveryServiceUrls` could contain multiple URLs in case of HA setup. We highly recommend to provide all - available Discovery URLs in there. +:::note + Ensure that each API ML instance is defined in a separate 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 DVIPA address. It could lead to unexpected behaviour. - - Hostnames `sys1` and `sys2` are names of LPAR in the sysplex. + 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 From f43668fde9ddb5c42efe4c36206e270a0417ec3c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pavel=20Jare=C5=A1?= Date: Thu, 17 Oct 2024 10:56:57 +0200 Subject: [PATCH 6/7] refactor rollout MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Pavel Jareš --- .../api-mediation-multi-tenancy.md | 28 ++++++++++--------- .../configuration-multi-tenancy-routing.md | 8 +++--- 2 files changed, 19 insertions(+), 17 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 index 0e88c3df29..5911461857 100644 --- a/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md +++ b/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md @@ -73,8 +73,10 @@ components.gateway.apiml.service.additionalRegistration: 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`. +:::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. @@ -134,13 +136,13 @@ components.gateway.apiml.service.additionalRegistration: ``` :::note - Each API ML instance should be defined in a separated record. Do not mix different API ML instance in one record. - The value `discoveryServiceUrls` could contain multiple URLs in case of HA setup. We highly recommend to provide all - available Discovery URLs in there. + 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 DVIPA address. It could lead to unexpected behaviour. - - Hostnames `sys1` and `sys2` are names of LPAR in the sysplex. + 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 @@ -159,13 +161,13 @@ ZWE_CONFIGS_APIML_SERVICE_ADDITIONALREGISTRATION_0_ROUTES_0_SERVICEURL=/ The number in the properties names (see position of `#` in `ZWE_CONFIGS_APIML_SERVICE_ADDITIONALREGISTRATION_#_*`) defines ID of API ML instance. - Each API ML instance should be defined in a separated record. Do not mix different API ML instance in one record. - The value `discoveryServiceUrls` could contain multiple URLs in case of HA setup. We highly recommend to provide all - available Discovery URLs in there. + 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 DVIPA address. It could lead to unexpected behaviour. + Always provide the direct address to the system. Do not use the DVIPA address. Using this address could lead to unexpected behaviour. - Hostnames `sys1` and `sys2` are names of LPAR in the sysplex. + 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. diff --git a/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md b/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md index 4fb681f402..b0910aa7e1 100644 --- a/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md +++ b/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md @@ -29,11 +29,11 @@ Follow these steps to register with additional Discovery Services: ``` :::note - Each API ML instance should be defined in a separated record. Do not mix different API ML instance in one record. - The value `discoveryServiceUrls` could contain multiple URLs in case of HA setup. We highly recommend to provide - all available Discovery URLs in there. + 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 DVIPA address. It could lead to unexpected behaviour. + 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. From b7784cdf2521b08894e0632660e793cb1877c091 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Thu, 17 Oct 2024 10:58:26 +0200 Subject: [PATCH 7/7] propogate refctored note Signed-off-by: Andrew Jandacek --- .../configuration-multi-tenancy-routing.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md b/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md index 4fb681f402..e396b6eba3 100644 --- a/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md +++ b/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md @@ -28,12 +28,11 @@ Follow these steps to register with additional Discovery Services: serviceUrl: / ``` - :::note - Each API ML instance should be defined in a separated record. Do not mix different API ML instance in one record. - The value `discoveryServiceUrls` could contain multiple URLs in case of HA setup. We highly recommend to provide - all available Discovery URLs in there. + :::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 DVIPA address. It could lead to unexpected behaviour. - ::: + 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.