From 6da09aa19f48e1b3151a7c350d29f02f5b1f6415 Mon Sep 17 00:00:00 2001 From: ShobhaJayanna <36433611+Shobhajayanna@users.noreply.github.com> Date: Fri, 20 Dec 2024 13:30:41 +0100 Subject: [PATCH 1/8] cherry pick from zowe/refactor-troubleshoot-cgw remove central gateway reference from the docs for v3 --- .../troubleshoot-apiml-error-codes.md | 52 ++-- .../api-mediation-multi-tenancy.md | 264 +++++++----------- .../configuration-multi-tenancy-routing.md | 6 +- .../diagrams/multi-domain_architecture_V3.svg | 1 + .../zowe-v3-frequently-asked-questions.md | 2 +- .../zowe-v3-frequently-asked-questions.md | 2 +- 6 files changed, 133 insertions(+), 194 deletions(-) create mode 100644 docs/user-guide/api-mediation/diagrams/multi-domain_architecture_V3.svg diff --git a/docs/troubleshoot/troubleshoot-apiml-error-codes.md b/docs/troubleshoot/troubleshoot-apiml-error-codes.md index ee2bc6ef5d..afc28f1444 100644 --- a/docs/troubleshoot/troubleshoot-apiml-error-codes.md +++ b/docs/troubleshoot/troubleshoot-apiml-error-codes.md @@ -599,44 +599,44 @@ The following error message codes may appear on logs or API responses. Use the f ### ZWEAT500E - Failed to parse the client certificate forwarded from the central Gateway. Error message %s. The client certificate was %s + Failed to parse the client certificate forwarded from the Gateway. Hostname is %s. Error message is %s. The client certificate was %s **Reason:** - The string sent by the central Gateway was not recognized as valid DER-encoded certificate in the Base64 printable form. + The string sent by the Gateway was not recognized as a valid DER-encoded certificate in the Base64 printable form. **Action:** - Ensure that the forwarding of client certificate is enabled also in the central Gateway. Check for any error messages from the central Gateway. + Ensure that forwarding of the client certificate is also enabled in the Gateway. Check for any error messages from the Gateway. ### ZWEAT501E - Failed to get trusted certificates from the central Gateway. Unexpected response from %s endpoint. Status code: %s. Response body: %s + Failed to get trusted certificates from the Gateway. Unexpected response from %s endpoint. Status code: %s. Response body: %s **Reason:** The response status code is different from expected 200 OK. **Action:** - - Ensure that the parameter apiml.security.x509.certificatesUrl is correctly configured with the complete URL to the central Gateway certificates endpoint. Test the URL manually. + + Ensure that the parameter apiml.security.x509.certificatesUrls is correctly configured with the complete URL to the Gateway certificates endpoint. Test the URL manually. ### ZWEAT502E - Invalid URL specified to get trusted certificates from the central Gateway. Error message: %s - + Invalid URL specified to get trusted certificates from the Gateway. URL is %s. Error message: %s + **Reason:** - - The parameter apiml.security.x509.certificatesUrl is not correctly configured with the complete URL to the central Gateway certificates endpoint. - + + The parameter apiml.security.x509.certificatesUrls is not correctly configured with the complete URL to the Gateway certificates endpoint. + **Action:** Ensure that the parameter apiml.security.x509.certificatesUrl is correctly configured. ### ZWEAT503E - An error occurred during retrieval of trusted certificates from the central Gateway. Error message: %s - + An error occurred during retrieval of trusted certificates from the Gateway. Certificate endpoint is %s. Error message: %s + **Reason:** The communication with the gateway got interrupted or an error occurred during processing the response. @@ -647,27 +647,15 @@ The following error message codes may appear on logs or API responses. Use the f ### ZWEAT504E - Failed to parse the trusted certificates provided by the central Gateway. Error message %s - + Failed to parse the trusted certificates provided by the Gateway. Certificate endpoint is %s. Error message %s + **Reason:** - - The string sent by the central Gateway was not recognized as valid DER-encoded certificates in the Base64 printable form. - + + The string sent by the Gateway was not recognized as valid DER-encoded certificates in the Base64 printable form. + **Action:** - - Check that the URL configured in apiml.security.x509.certificatesUrl responds with valid DER-encoded certificates in the Base64 printable form. - -### ZWEAT505E - - Incoming request certificate is not one of the trusted certificates provided by the central Gateway. - - **Reason:** - - The Gateway performs additional check of request certificates when the central Gateway forwards incoming client certificate to the domain Gateway. This check may fail when the certificatesUrl parameter does not point to proper central Gateway certificates endpoint. - - **Action:** - - Check that the URL configured in apiml.security.x509.certificatesUrl points to the central Gateway and it responds with valid DER-encoded certificates in the Base64 printable form. + + Check that the URL configured in apiml.security.x509.certificatesUrls responds with valid DER-encoded certificates in the Base64 printable form. ### ZWEAT601E 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 da10dd3469..bd1f54098f 100644 --- a/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md +++ b/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md @@ -2,142 +2,85 @@ Zowe supports management of multiple tenants, whereby different tenants can serve different purposes or different customers. The use case for multi-tenant support is when a service provider manages sysplexes/monoplexes for multiple customers. This configuration makes it possible to have a single access point for all customers, and properly route and authenticate across different domains. -* [Overview of Central and Domain API MLs](#overview-of-central-and-domain-api-mls) -* [Multitenancy component enablement settings](#multitenancy-component-enablement-settings) -* [Onboarding Domain Gateways to the Central Gateway](#onboarding-domain-gateways-to-the-central-gateway) - * [Dynamic Onboarding (recommended) for Domain Gateways](#dynamic-onboarding-recommended-for-domain-gateways) - * [Static Onboarding for Domain Gateways (deprecated)](#static-onboarding-for-domain-gateways-deprecated) -* [Onboarding a Domain Gateway service to the Central Discovery service](#onboarding-a-domain-gateway-service-to-the-central-discovery-service) - * [Dynamic Configurations to the Central Discovery service](#dynamic-configurations-to-the-central-discovery-service) - * [Dynamic configuration: YML](#dynamic-configuration-yml) - * [Dynamic configuration: Environment variables](#dynamic-configuration-environment-variables) - * [Validating successful configuration](#validating-successful-configuration) -* [Establishing a trust relationship between Domain API ML and Central API ML](#establishing-a-trust-relationship-between-domain-api-ml-and-central-api-ml) - * [Commands to establish trust between Domain and Central API MLs](#commands-to-establish-trust-between-domain-and-central-api-mls) -* [Using the `/registry` endpoint in the Central Gateway](#using-the-registry-endpoint-in-the-central-gateway) - * [Configuration for `/registry`](#configuration-for-registry) - * [Authentication for `/registry`](#authentication-for-registry) - * [Authorization with `/registry`](#authorization-with-registry) - * [Requests with `/registry`](#requests-with-registry) - * [Response with `/registry`](#response-with-registry) - * [Response with `/registry{apimlId}`](#response-with-registryapimlid) - * [Response with `GET /gateway/api/v1/registry/{apimlId}?apiId={apiId}&serviceId={serviceId}`](#response-with-get-gatewayapiv1registryapimlidapiidapiidserviceidserviceid) -* [Validating successful configuration with `/registry`](#validating-successful-configuration-with-registry) -* [Gateway static definition example (deprecated)](#gateway-static-definition-example-deprecated) -* [Troubleshooting multitenancy configuration](#troubleshooting-multitenancy-configuration) - * [ZWESG100W](#zwesg100w) - * [No debug messages similar to apiml1 completed with onComplete are produced](#no-debug-messages-similar-to-apiml1-completed-with-oncomplete-are-produced) - -## Overview of Central and Domain API MLs - -The following diagram illustrates communication between the "central" API Mediation Layer and Zowe in multiple domains. Note that some API MLs may be running in a sysplex (HA), while others may be in a monoplex (non-HA). - -![Multi-domain architecture diagram](./diagrams/multi-domain_architecture_V2.svg) - -Domain-Central is where the "central" API ML is running, and may be on z/OS, or off z/OS, for example in Kubernetes. This API ML is referred to as the Central API ML. -The Central API ML serves as a single point of access to all API Mediation Layers registered in it, and by extension, to all services registered in those secondary API MLs. - -Domain-1 to Domain-N are z/OS systems with the standard Zowe API ML running either in HA (sysplex) or non-HA (monoplex). These API MLs are referred to as Domain API MLs. +- [Multitenancy Configuration](#multitenancy-configuration) + - [Overview of API MLs](#overview-of-api-mls) + - [Multitenancy component enablement settings](#multitenancy-component-enablement-settings) + - [Onboarding a Gateway service in one domain to the Discovery service of API ML in another domain](#onboarding-a-gateway-service-in-one-domain-to-the-discovery-service-of-api-ml-in-another-domain) + - [Dynamic configuration via zowe.yaml](#dynamic-configuration-via-zoweyaml) + - [Dynamic configuration via Environment variables](#dynamic-configuration-via-environment-variables) + - [Validating successful configuration](#validating-successful-configuration) + - [Establishing a trust relationship between the API MLs](#establishing-a-trust-relationship-between-the-api-mls) + - [Commands to establish trust between the API MLs](#commands-to-establish-trust-between-the-api-mls) + - [Using the `/registry` endpoint in the Gateway](#using-the-registry-endpoint-in-the-gateway) + - [Configuration for `/registry`](#configuration-for-registry) + - [Authentication for `/registry`](#authentication-for-registry) + - [Authorization with `/registry`](#authorization-with-registry) + - [Requests with `/registry`](#requests-with-registry) + - [Response with `/registry`](#response-with-registry) + - [Response with `/registry{apimlId}`](#response-with-registryapimlid) + - [Response with `GET /gateway/api/v1/registry/{apimlId}?apiId={apiId}&serviceId={serviceId}`](#response-with-get-gatewayapiv1registryapimlidapiidapiidserviceidserviceid) + - [Validating successful configuration with `/registry`](#validating-successful-configuration-with-registry) + - [Troubleshooting multitenancy configuration](#troubleshooting-multitenancy-configuration) + - [ZWESG100W](#zwesg100w) + (#no-debug-messages-similar-to-apiml1-completed-with-oncomplete-are-produced) + +## Overview of API MLs + +The following diagram illustrates communication between the API Mediation Layers and Zowe in multiple domains. Note that some API MLs may be running in a sysplex (HA), while others may be in a monoplex (non-HA). + +![Multi-domain architecture diagram](./diagrams/multi-domain_architecture_V3.svg) + + As represented in the example diagram of Multitenacy environement where the APIMLs in Domain(2-N) are registered to APIML in Domain-1. The APIML in Domain-1 may be running on z/OS, or off z/OS, for example in Kubernetes, this API ML serves as a single point of access to all API Mediation Layers registered in this and, by extension, to all services registered in those API MLs. + +The APIMLs in Domain(2-N) are installed on z/OS systems with the standard Zowe API ML running either in HA (sysplex) or non-HA (monoplex). These API MLs are registered to APIML in Domain-1. ## Multitenancy component enablement settings -In the multitenancy environment, certain Zowe components may be enabled, while others may be disabled. The multitenancy environment expects one Central API ML that handles the discovery and registration as well as routing to the API ML installed in specific domains. +In the multitenancy environment, certain Zowe components may be enabled, while others may be disabled. The multitenancy environment expects one API ML (APIML in Domain-1 in our example diagram) that handles the discovery and registration as well as routing to the other API MLs (APIMLs in Domain(2-N) in our example diagram) installed in any other specific domains. -## Onboarding Domain Gateways to the Central Gateway +## Onboarding a Gateway service in one domain to the Discovery service of API ML in another domain -The Central Gateway must onboard all Domain Gateways. This can be done dynamically or by static definition. We strongly recommend using dynamic onboarding as this onboarding method adapts better to the potentially changing environments of the customer. Static onboarding does not provide the functionality to actively monitor the health of specific services (e.g. domain gateways). +A Gateway from any domain can onboard Gateways of any domains. This service onboarding can be achieved similar to additional registrations of the Gateway. This section describes the dynamic configuration of the yaml file and environment variables, and how to validate successful configuration. -### Dynamic Onboarding (recommended) for Domain Gateways +- [Dynamic configuration via zowe.yaml](#dynamic-configuration-via-zoweyaml) +- [Dynamic configuration via Environment variables](#dynamic-configuration-via-environment-variables) -To dynamically onboard to the Discovery service in the central cluster, set the following property for all Domain Gateways: +### Dynamic configuration via zowe.yaml -`components.gateway.apiml.service.additionalRegistration` - -Use the following example as a template for how to set the value for this property in zowe.yml. - -**Example:** -``` -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: - - 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: - # central gateway port - certificatesUrl: https://{centralGatewayHost}:{centralGatewayPort}/gateway/certificates -``` - -:::note -It is not necessary for the Gateway service to provide different routing patterns for the Central Discovery service. These metadata can be the same for every cluster. -::: - -### Static Onboarding for Domain Gateways (deprecated) - -Alternatively, you can statically onboard all Domain Gateways on the Central Discovery service. Note that dynamic onboarding is the preferred method. - -For static onboarding, make sure that the following parameters are correctly specified in the static definition file: - -- **services.serviceId** - Specify this parameter to GATEWAY -- **services.instanceBaseUrls** - Specifies the URL of the Domain Gateway -- **services.customMetadata.apiml.service.apimlId** - Specifies the id of the API ML environment - -For static onboarding, use the [Gateway static definition example (deprecated)](#gateway-static-definition-example-deprecated) presented later in this article. - -## Onboarding a Domain Gateway service to the Central Discovery service - -The Central API ML can onboard Gateways of all domains. This service onboarding can be achieved similar to additional registrations of the Gateway. This section describes the dynamic configuration of the yaml file and environment variables, and how to validate successful configuration. - -- Dynamic configuration via zowe.yaml -- Dynamic configuration via Environment variables - -### Dynamic Configurations to the Central Discovery service - -#### Dynamic configuration: YML - -Users must set the following property for the Domain Gateway to dynamically onboard to the Central Discovery service. +1. Set the following property for the Gateway of APIMLs in Domain(2-N) to dynamically onboard to the Discovery service of API ML in Domain-1. `components.gateway.apiml.service.additionalRegistration` Use the following example as a template for how to set the value of this property in zowe.yml. -**Example:** -``` -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: - - gatewayUrl: / - serviceUrl: / -``` + **Example:** + ``` + components.gateway.apiml.service.additionalRegistration: + # APIML in Domain-1 (in HA, for non-HA mode use only 1 hostname) + - discoveryServiceUrls: https://sys1:{discoveryServicePort}/eureka/,https://sys2:{discoveryServicePort}/eureka/ + ``` -:::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 Notes: + * 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 +2. (Optional) Configure the Gateway to forward client certificates. +Use this step to enable the domain(2-N) gateway to use this client certificate for authentication. . +Set the `certificatesUrl` property to ensure that only Gateway-forwarded certificates are used for client certificate authentication. This URL returns a certificate chain from the gateway. + + ``` + components.gateway.apiml.security.x509: + # gateway port in domain-1 + certificatesUrl: https://{gatewayHost}:{gatewayPort}/gateway/certificates + ``` + +### Dynamic configuration via 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. @@ -166,45 +109,45 @@ This Zowe configuration transforms the zowe.yaml configuration file into the env ### Validating successful configuration -The corresponding Gateway service should appear in the Eureka console of the Central Discovery service. +The corresponding Gateway service in domain(2-N) should appear in the Eureka console of the Discovery service in the domain-1 API ML. -To see details of all instances of the ‘GATEWAY’ application, perform a **GET** call on the following endpoint of the Central Discovery service: +To see details of all instances of the ‘GATEWAY’ application, perform a **GET** call on the following endpoint of the Discovery service in domain-1 API ML: ``` /eureka/apps ``` -## Establishing a trust relationship between Domain API ML and Central API ML +## Establishing a trust relationship between the API MLs -For routing to work in a multitenancy configuration, the Central API Mediation Layer must trust the Domain API Mediation Layers for a successful registration into the Discovery Service component. -The Domain API Mediation Layers must trust the Central API Mediation Layer Gateway to accept routed requests. -It is necessary that the root and, if applicable, intermediate public certificates be shared between the Central API Mediation Layer and Domain API Mediation Layers. +For routing to work in a multitenancy configuration, as represented in the example diagram above where "Domain APIML 2", "Domain APIML 3" are registered to "Domain APIML 1", the "Domain APIML 1" must trust the "Domain APIML 2", "Domain APIML 3" for successful registration into it's Discovery Service component. +The "Domain APIML 2", "Domain APIML 3" must trust the "Domain APIML 1" Gateway where they are registered to, to accept routed requests. +It is necessary that the root and, if applicable, intermediate public certificates be shared between these domain API Mediation Layers. -The following diagram is a visual description of the relationship between the Central API ML and Domain API MLs. +The following diagram shows the relationship between the API MLs. ![Trust relation diagram](./diagrams/mt-trust-relations.png) -As shown in this example diagram, the Central API ML is installed on system X. Domain API MLs are installed on systems Y and Z. +As presented in this example diagram, The API MLs are installed on systems X, Y and Z. -To establish secure communications, "Domain APIML 1" and "Domain APIML 2" are using different private keys signed with different public keys. These API MLs do not trust each other. +To establish secure communications, "Domain APIML 2" and "Domain APIML 3" are using different private keys signed with different public keys. These API MLs do not trust each other. -In order for all Domain API MLs to register with the Central API ML, it is necessary that the Central API ML have all public keys from the certificate chains of all Domain API MLs: +In order for all API MLs to register with an "Domain APIML 1" in multitenancy set up, it is necessary that the "Domain APIML 1" has all public keys from the certificate chains of all registered API MLs: * DigiCert Root CA * DigiCert Root CA1 * DigiCert CA -These public keys are required for the Central API ML to establish trust with "Domain APIML 1" and "Domain APIML 2". +These public keys are required for the "Domain APIML 1" to establish trust with "Domain APIML 2" and "Domain APIML 3". -The Central API ML uses a private key which is signed by the Local CA public key for secure communication. +The "Domain APIML 1" uses a private key which is signed by the Local CA public key for secure communication. -"Domain APIML 1" and "Domain APIML 2" require a Local CA public key in order to accept the routing requests from the Central API ML, otherwise the Central API ML requests will not be trusted by the Domain API MLs. +"Domain APIML 2" and "Domain APIML 3" require a Local CA public key in order to accept the routing requests from the "Domain APIML 1", otherwise the "Domain APIML 1" requests will not be trusted by the registered API MLs. The diagram indicates all of the added certificates inside the red dashed lines. -### Commands to establish trust between Domain and Central API MLs +### Commands to establish trust between the API MLs -The following commands are examples of establishing a trust relationship between a Domain API ML and the Central API ML for both PKCS12 certificates and when using keyrings. +The following commands are examples of establishing a trust relationship between API MLs in Multitenancy Configuration for both PKCS12 certificates and when using keyrings. -1. Import the root and, if applicable, the intermediate public key certificate of Domain API MLs running on systems Y and Z into the truststore of the Central API ML running on system X. +1. Import the root and, if applicable, the intermediate public key certificate of registered "Domain APIML 2" , "Domain APIML 3" API MLs running on systems Y and Z into the truststore of the "Domain APIML 1" running on system X. - **PKCS12** @@ -216,9 +159,12 @@ The following commands are examples of establishing a trust relationship between - **Keyring** - For keyrings, use the following examples of commands specific to your ESM to add certificates from the dataset and connect these certificates to the keyring used by the Central API ML: - - - **For RACF:** + For keyrings, use the following examples of commands specific to your ESM to add certificates from the dataset and connect these certificates to the keyring used by the "Domain APIML 1": + +
+ Click here for command details for RACF. + + - **For RACF:** ``` RACDCERT ADD('SHARE.SYSY.ROOTCA.CER') ID(ZWESVUSR) WITHLABEL('DigiCert Root CA') TRUST @@ -268,7 +214,7 @@ The following commands are examples of establishing a trust relationship between TSS LIST(ZWESVUSR) KEYRING(ZOWERING) ``` -2. Import root and, if applicable, intermediate public key certificates of the Central API ML running on system X into the truststore of the Domain API MLs running on systems Y and Z. +2. Import root and, if applicable, intermediate public key certificates of the API ML running on system X into the truststore of the API MLs running on systems Y and Z. - **PKCS12** @@ -280,7 +226,10 @@ The following commands are examples of establishing a trust relationship between - **Keyring** - For keyring certificates, use the following examples of commands specific to your ESM to add certificates from the dataset, and connect these certificates to the keyrings used by Domain API MLs: + For keyring certificates, use the following examples of commands specific to your ESM to add certificates from the dataset, and connect these certificates to the keyrings used by registered API MLs: + +
+ Click here for command details for RACF. - **For RACF:** @@ -326,11 +275,13 @@ The following commands are examples of establishing a trust relationship between TSS LIST(ZWESVUSR) KEYRING(ZOWERING) ``` -You completed certificates setup for multitenancy configuration, whereby Domain API MLs can trust the Central API ML and vice versa. +
+ +You completed certificates setup for multitenancy configuration, whereby registered API MLs can trust the API ML where they are registered and vice versa. -## Using the `/registry` endpoint in the Central Gateway +## Using the `/registry` endpoint in the Gateway -The `/registry` endpoint provides information about services onboarded to all Domain Gateways (all domains and the central one). This section describes the configuration, authentication, authorization, example of requests, and responses when using the `/registry` endpoint. +The `/registry` endpoint provides information about services onboarded to all registered Gateways. This section describes the configuration, authentication, authorization, example of requests, and responses when using the `/registry` endpoint. ### Configuration for `/registry` @@ -339,7 +290,7 @@ environment variable `APIML_GATEWAY_REGISTRY_ENABLED=TRUE` to enable this featur ### Authentication for `/registry` -The `/registry` endpoint is authenticated by the client certificate. The Central Gateway accepts certificates that are trusted. The username is obtained from the common name of the client certificate. +The `/registry` endpoint is authenticated by the client certificate. The Gateway accepts certificates that are trusted. The username is obtained from the common name of the client certificate. Unsuccessful authentication returns a 401 error code. @@ -355,16 +306,16 @@ Unsuccessful authorization returns a 403 error code. ### Requests with `/registry` -There are two endpoints that provide information about services registered to the API ML. One endpoint is for all domains, and the other endpoint is for the specific domain. Choose from the following **GET** calls: +There are two endpoints that provide information about services registered to the API ML. One endpoint is for all APIMLs, and the other endpoint is for the specific APIML. Choose from the following **GET** calls: * `GET /gateway/api/v1/registry` -This request lists services in all domains. +This request lists services in all APIMLs. * `GET /gateway/api/v1/registry/{apimlId}` -This request lists services in the apimlId domain. +This request lists services in the APIML of the specific apimlId given. * `GET /gateway/api/v1/registry/{apimlId}?apiId={apiId}&serviceId={serviceId}` - This request gets the specific service in the specific apimlId domain. + This request gets the specific service from the APIML in the specific apimlId. ### Response with `/registry` @@ -420,7 +371,10 @@ This request lists services in the apimlId domain. ### Response with `/registry{apimlId}` -Should contain information about all services in a specific domain +This response should contain information about all services in an APIML with the specific apimlId. + +
+Click here for an example response with `/registry{apimlId}`. **Example:** @@ -460,7 +414,10 @@ Should contain information about all services in a specific domain ### Response with `GET /gateway/api/v1/registry/{apimlId}?apiId={apiId}&serviceId={serviceId}` -Should contain information about a specific service in a specific domain +This response should contain information about a specific service in an APIML with the specific apimlId. + +
+Click here for an example of a response with `GET /gateway/api/v1/registry/{apimlId}?apiId={apiId}&serviceId={serviceId}`. **Example:** @@ -489,7 +446,7 @@ Should contain information about a specific service in a specific domain ## Validating successful configuration with `/registry` -Use the `/registry` endpoint to validate successful configuration. The response should contain all Domain API MLs represented by `apimlId`, and information about onboarded services. +Use the `/registry` endpoint to validate successful configuration. The response should contain all the API MLs represented by `apimlId`, and information about onboarded services. ## Gateway static definition example (deprecated) @@ -573,15 +530,8 @@ catalogUiTiles: Cannot receive information about services on API Gateway with apimlId 'apiml1' because: Received fatal alert: certificate_unknown; nested exception is javax.net.ssl.SSLHandshakeException: Received fatal alert: certificate_unknown **Reason** -The trust between the domain and the central Gateway was not established. +Cannot connect to the Gateway service. **Action** -Review your certificate configuration. - -### No debug messages similar to apiml1 completed with onComplete are produced +Make sure that the external Gateway service is running and the truststore of the both Gateways contains the corresponding certificate. - **Reason** - Domain Gateway is not correctly onboarded to Discovery Service in Central API ML. - - **Action** - Review Gateway static definition. Check the Central Discovery Service dashboard if the domain Gateway is displayed. 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 b0910aa7e1..538df00bbb 100644 --- a/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md +++ b/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md @@ -1,7 +1,7 @@ # Configuring routing in a multi-tenant environment -In addition to the domain-specific Discovery Service, which is typically in the same LPAR, in a multi-sysplex environment, the API Gateway may also need to register with a Central Discovery Service which gathers information about all installed API Gateways -in isolated sysplex environments. Data from the Central Discovery Service can then be used by the Central Gateway for routing to individual API Gateways. +In addition to the domain-specific Discovery Service, which is typically in the same LPAR, in a multi-sysplex environment, where the API Gateway in APIML in one domain lets say "Domain APIML 2", may also need to register with the Discovery Service in API ML in domain any lets say "Domain APIML 1", which gathers information about all installed API Gateways +in isolated sysplex environments. Data from the Discovery Service in the API ML "Domain APIML 1" can then be used by the Gateway in the APIML "Domain APIML 2" for routing to individual API Gateways. Follow these steps to register with additional Discovery Services: @@ -11,7 +11,7 @@ Follow these steps to register with additional Discovery Services: **Example:** ``` components.gateway.apiml.service.additionalRegistration: - + - discoveryServiceUrls: https://sys1:10011/eureka/,https://sys1:10021/eureka/ routes: - gatewayUrl: / diff --git a/docs/user-guide/api-mediation/diagrams/multi-domain_architecture_V3.svg b/docs/user-guide/api-mediation/diagrams/multi-domain_architecture_V3.svg new file mode 100644 index 0000000000..9f5880d49f --- /dev/null +++ b/docs/user-guide/api-mediation/diagrams/multi-domain_architecture_V3.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/whats-new/zowe-v3-frequently-asked-questions.md b/docs/whats-new/zowe-v3-frequently-asked-questions.md index 260e4aeba8..c88e86a125 100644 --- a/docs/whats-new/zowe-v3-frequently-asked-questions.md +++ b/docs/whats-new/zowe-v3-frequently-asked-questions.md @@ -84,7 +84,7 @@ 3. Can you speak about the migration from Zuul to Spring Cloud Gateway? Today there are two separate gateway services in API ML with separate configurations. - In Zowe V3, Spring Cloud Gateway has replaced Zuul as the technology to provide the API Gateway. The configuration for the API Gateway remains in the `components.gateway` namespace. If you were using Spring Cloud Gateway in V2 for the multi-tenancy scenario, you need to update the configuration for the central gateway and move this configuration from `components.cloud-gateway` to `components.gateway`. + Spring Cloud Gateway is replacing Zuul as the technology to provide the API Gateway. The configuration for the API Gateway remains in the `components.gateway` namespace. If you were using Spring Cloud Gateway in V2 for the multi-tenancy scenario, you need to update the configuration for the Central Gateway (referred as Gateway from v3 onwards) and move this configuration from `components.cloud-gateway` to `components.gateway`. 4. If I have a legacy gateway deployed, how will I migrate to the new gateway? Will the old gateway be removed? diff --git a/versioned_docs/version-v2.18.x/whats-new/zowe-v3-frequently-asked-questions.md b/versioned_docs/version-v2.18.x/whats-new/zowe-v3-frequently-asked-questions.md index 0247009e96..d7802c8fb2 100644 --- a/versioned_docs/version-v2.18.x/whats-new/zowe-v3-frequently-asked-questions.md +++ b/versioned_docs/version-v2.18.x/whats-new/zowe-v3-frequently-asked-questions.md @@ -94,7 +94,7 @@ 3. Can you speak about the migration from Zuul to Spring Cloud Gateway? Today there are two separate gateway services in API ML with separate configurations. - Spring Cloud Gateway is replacing Zuul as the technology to provide the API Gateway. The configuration for the API Gateway remains in the `components.gateway` namespace. If you were using Spring Cloud Gateway in V2 for the multi-tenancy scenario, you need to update the configuration for the central gateway and move this configuration from `components.cloud-gateway` to `components.gateway`. + Spring Cloud Gateway is replacing Zuul as the technology to provide the API Gateway. The configuration for the API Gateway remains in the `components.gateway` namespace. If you were using Spring Cloud Gateway in V2 for the multi-tenancy scenario, you need to update the configuration for the Central Gateway (referred as Gateway from v3 onwards) and move this configuration from `components.cloud-gateway` to `components.gateway`. 4. If I have a legacy gateway deployed, how will I migrate to the new gateway? Will the old gateway be removed? From 05d4cd01c3ee9b7a2c28a5ceb1927409c2ba1ac5 Mon Sep 17 00:00:00 2001 From: sj895092 Date: Fri, 20 Dec 2024 17:21:39 +0100 Subject: [PATCH 2/8] refactor --- docs/user-guide/api-mediation/api-mediation-multi-tenancy.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) 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 bd1f54098f..7c066ac8ed 100644 --- a/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md +++ b/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md @@ -213,7 +213,8 @@ The following commands are examples of establishing a trust relationship between ``` TSS LIST(ZWESVUSR) KEYRING(ZOWERING) ``` - +
+ 2. Import root and, if applicable, intermediate public key certificates of the API ML running on system X into the truststore of the API MLs running on systems Y and Z. - **PKCS12** @@ -411,6 +412,7 @@ This response should contain information about all services in an APIML with the } ] ``` +
### Response with `GET /gateway/api/v1/registry/{apimlId}?apiId={apiId}&serviceId={serviceId}` @@ -443,6 +445,7 @@ This response should contain information about a specific service in an APIML wi } ] ``` +
## Validating successful configuration with `/registry` From 13f502c99e4207a34f0b7db4593698c6fc318f67 Mon Sep 17 00:00:00 2001 From: sj895092 Date: Fri, 20 Dec 2024 18:32:42 +0100 Subject: [PATCH 3/8] refactor --- docs/user-guide/api-mediation/api-mediation-multi-tenancy.md | 3 +++ 1 file changed, 3 insertions(+) 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 7c066ac8ed..8ea09b8053 100644 --- a/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md +++ b/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md @@ -213,6 +213,7 @@ The following commands are examples of establishing a trust relationship between ``` TSS LIST(ZWESVUSR) KEYRING(ZOWERING) ``` + 2. Import root and, if applicable, intermediate public key certificates of the API ML running on system X into the truststore of the API MLs running on systems Y and Z. @@ -412,6 +413,7 @@ This response should contain information about all services in an APIML with the } ] ``` + ### Response with `GET /gateway/api/v1/registry/{apimlId}?apiId={apiId}&serviceId={serviceId}` @@ -445,6 +447,7 @@ This response should contain information about a specific service in an APIML wi } ] ``` + ## Validating successful configuration with `/registry` From 438ce734c06d5f6f58f654bd2c0a89ce72057358 Mon Sep 17 00:00:00 2001 From: ShobhaJayanna <36433611+Shobhajayanna@users.noreply.github.com> Date: Fri, 20 Dec 2024 20:25:27 +0100 Subject: [PATCH 4/8] Update api-mediation-multi-tenancy.md Signed-off-by: ShobhaJayanna <36433611+Shobhajayanna@users.noreply.github.com> --- .../api-mediation-multi-tenancy.md | 20 ------------------- 1 file changed, 20 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 8ea09b8053..d532b7784d 100644 --- a/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md +++ b/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md @@ -161,9 +161,6 @@ The following commands are examples of establishing a trust relationship between For keyrings, use the following examples of commands specific to your ESM to add certificates from the dataset and connect these certificates to the keyring used by the "Domain APIML 1": -
- Click here for command details for RACF. - - **For RACF:** ``` @@ -213,8 +210,6 @@ The following commands are examples of establishing a trust relationship between ``` TSS LIST(ZWESVUSR) KEYRING(ZOWERING) ``` - -
2. Import root and, if applicable, intermediate public key certificates of the API ML running on system X into the truststore of the API MLs running on systems Y and Z. @@ -229,9 +224,6 @@ The following commands are examples of establishing a trust relationship between - **Keyring** For keyring certificates, use the following examples of commands specific to your ESM to add certificates from the dataset, and connect these certificates to the keyrings used by registered API MLs: - -
- Click here for command details for RACF. - **For RACF:** @@ -277,8 +269,6 @@ The following commands are examples of establishing a trust relationship between TSS LIST(ZWESVUSR) KEYRING(ZOWERING) ``` -
- You completed certificates setup for multitenancy configuration, whereby registered API MLs can trust the API ML where they are registered and vice versa. ## Using the `/registry` endpoint in the Gateway @@ -375,9 +365,6 @@ This request lists services in the APIML of the specific apimlId given. This response should contain information about all services in an APIML with the specific apimlId. -
-Click here for an example response with `/registry{apimlId}`. - **Example:** * `GET /gateway/api/v1/registry/apiml2` @@ -414,15 +401,10 @@ This response should contain information about all services in an APIML with the ] ``` -
- ### Response with `GET /gateway/api/v1/registry/{apimlId}?apiId={apiId}&serviceId={serviceId}` This response should contain information about a specific service in an APIML with the specific apimlId. -
-Click here for an example of a response with `GET /gateway/api/v1/registry/{apimlId}?apiId={apiId}&serviceId={serviceId}`. - **Example:** * `GET /gateway/api/v1/registry/apiml2?apiId=zowe.apiml.gateway&serviceId=catalog` @@ -448,8 +430,6 @@ This response should contain information about a specific service in an APIML wi ] ``` -
- ## Validating successful configuration with `/registry` Use the `/registry` endpoint to validate successful configuration. The response should contain all the API MLs represented by `apimlId`, and information about onboarded services. From 6ccd9ef4ac92d81878f16f45a986c3f35b0d1287 Mon Sep 17 00:00:00 2001 From: ShobhaJayanna <36433611+Shobhajayanna@users.noreply.github.com> Date: Fri, 20 Dec 2024 21:02:03 +0100 Subject: [PATCH 5/8] Update openssl link zowe-api-mediation-layer-security-overview.md Signed-off-by: ShobhaJayanna <36433611+Shobhajayanna@users.noreply.github.com> --- .../extend-apiml/zowe-api-mediation-layer-security-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/extend/extend-apiml/zowe-api-mediation-layer-security-overview.md b/docs/extend/extend-apiml/zowe-api-mediation-layer-security-overview.md index 2a9593435a..6e5235afe5 100644 --- a/docs/extend/extend-apiml/zowe-api-mediation-layer-security-overview.md +++ b/docs/extend/extend-apiml/zowe-api-mediation-layer-security-overview.md @@ -140,7 +140,7 @@ The following list shows the default ciphers. API ML services use the following TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384 ``` -Only IANA ciphers names are supported. For more information, see [Cipher Suites](https://wiki.mozilla.org/Security/Server_Side_TLS#Cipher_suites) or [List of Ciphers](https://testssl.net/openssl-iana.mapping.html). +Only IANA ciphers names are supported. For more information, see [Cipher Suites](https://wiki.mozilla.org/Security/Server_Side_TLS#Cipher_suites) or [List of Ciphers](https://testssl.sh/openssl-iana.mapping.html). ## JSON Web Token (JWT) From 6b2d2c71008798356b43b338c8119ad14b50be8e Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Mon, 23 Dec 2024 10:36:33 +0100 Subject: [PATCH 6/8] refactor introduction Signed-off-by: Andrew Jandacek --- .../api-mediation/configuration-multi-tenancy-routing.md | 5 +++-- 1 file changed, 3 insertions(+), 2 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 538df00bbb..9218149274 100644 --- a/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md +++ b/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md @@ -1,7 +1,8 @@ # Configuring routing in a multi-tenant environment -In addition to the domain-specific Discovery Service, which is typically in the same LPAR, in a multi-sysplex environment, where the API Gateway in APIML in one domain lets say "Domain APIML 2", may also need to register with the Discovery Service in API ML in domain any lets say "Domain APIML 1", which gathers information about all installed API Gateways -in isolated sysplex environments. Data from the Discovery Service in the API ML "Domain APIML 1" can then be used by the Gateway in the APIML "Domain APIML 2" for routing to individual API Gateways. +In a multi-sysplex environment, both the domain-specific Discovery Service as well as an additional Discovery service may require registration with the Discovery Service in the domain which gathers information about all installed API Gateways in isolated sysplex environments. + +The domain-specific Discovery Service is typically in the same LPAR in a multi-sysplex environment. However, the API Gateway in API ML in one domain (for example in Domain API ML 2) may also need to register with the API ML Discovery Service in a separate domain (for example in Domain API ML 1), which gathers information about all installed API Gateways in isolated sysplex environments. After registration, data from the Discovery Service in Domain API ML 1 can be used by the Gateway in Domain API ML 2 for routing to individual API Gateways. Follow these steps to register with additional Discovery Services: From 1579bc4cfc488d0e9f09a36f3606b3f270ac514a Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Mon, 23 Dec 2024 11:38:25 +0100 Subject: [PATCH 7/8] add completion statement Signed-off-by: Andrew Jandacek --- .../api-mediation/configuration-multi-tenancy-routing.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 9218149274..a78a1152e0 100644 --- a/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md +++ b/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md @@ -1,6 +1,6 @@ # Configuring routing in a multi-tenant environment -In a multi-sysplex environment, both the domain-specific Discovery Service as well as an additional Discovery service may require registration with the Discovery Service in the domain which gathers information about all installed API Gateways in isolated sysplex environments. +In a multi-sysplex environment, both the domain-specific Discovery Service as well as one or more additional Discovery Services may require registration with the Discovery Service in the domain which gathers information about all installed API Gateways in isolated sysplex environments. The domain-specific Discovery Service is typically in the same LPAR in a multi-sysplex environment. However, the API Gateway in API ML in one domain (for example in Domain API ML 2) may also need to register with the API ML Discovery Service in a separate domain (for example in Domain API ML 1), which gathers information about all installed API Gateways in isolated sysplex environments. After registration, data from the Discovery Service in Domain API ML 1 can be used by the Gateway in Domain API ML 2 for routing to individual API Gateways. @@ -38,3 +38,5 @@ Follow these steps to register with additional Discovery Services: ::: 3. Restart Zowe. + +You completed the procedure to register with additional Discovery Services. \ No newline at end of file From 016b24f2eb3fcd8114c37baa45ef4c7f4581a23b Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Mon, 23 Dec 2024 12:28:12 +0100 Subject: [PATCH 8/8] langauge/format refactoring Signed-off-by: Andrew Jandacek --- .../api-mediation-multi-tenancy.md | 145 ++++++++++-------- 1 file changed, 80 insertions(+), 65 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 d532b7784d..f808ee756d 100644 --- a/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md +++ b/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md @@ -2,83 +2,61 @@ Zowe supports management of multiple tenants, whereby different tenants can serve different purposes or different customers. The use case for multi-tenant support is when a service provider manages sysplexes/monoplexes for multiple customers. This configuration makes it possible to have a single access point for all customers, and properly route and authenticate across different domains. -- [Multitenancy Configuration](#multitenancy-configuration) - - [Overview of API MLs](#overview-of-api-mls) - - [Multitenancy component enablement settings](#multitenancy-component-enablement-settings) - - [Onboarding a Gateway service in one domain to the Discovery service of API ML in another domain](#onboarding-a-gateway-service-in-one-domain-to-the-discovery-service-of-api-ml-in-another-domain) - - [Dynamic configuration via zowe.yaml](#dynamic-configuration-via-zoweyaml) - - [Dynamic configuration via Environment variables](#dynamic-configuration-via-environment-variables) - - [Validating successful configuration](#validating-successful-configuration) - - [Establishing a trust relationship between the API MLs](#establishing-a-trust-relationship-between-the-api-mls) - - [Commands to establish trust between the API MLs](#commands-to-establish-trust-between-the-api-mls) - - [Using the `/registry` endpoint in the Gateway](#using-the-registry-endpoint-in-the-gateway) - - [Configuration for `/registry`](#configuration-for-registry) - - [Authentication for `/registry`](#authentication-for-registry) - - [Authorization with `/registry`](#authorization-with-registry) - - [Requests with `/registry`](#requests-with-registry) - - [Response with `/registry`](#response-with-registry) - - [Response with `/registry{apimlId}`](#response-with-registryapimlid) - - [Response with `GET /gateway/api/v1/registry/{apimlId}?apiId={apiId}&serviceId={serviceId}`](#response-with-get-gatewayapiv1registryapimlidapiidapiidserviceidserviceid) - - [Validating successful configuration with `/registry`](#validating-successful-configuration-with-registry) - - [Troubleshooting multitenancy configuration](#troubleshooting-multitenancy-configuration) - - [ZWESG100W](#zwesg100w) - (#no-debug-messages-similar-to-apiml1-completed-with-oncomplete-are-produced) - ## Overview of API MLs The following diagram illustrates communication between the API Mediation Layers and Zowe in multiple domains. Note that some API MLs may be running in a sysplex (HA), while others may be in a monoplex (non-HA). ![Multi-domain architecture diagram](./diagrams/multi-domain_architecture_V3.svg) - As represented in the example diagram of Multitenacy environement where the APIMLs in Domain(2-N) are registered to APIML in Domain-1. The APIML in Domain-1 may be running on z/OS, or off z/OS, for example in Kubernetes, this API ML serves as a single point of access to all API Mediation Layers registered in this and, by extension, to all services registered in those API MLs. +As represented in the diagram of Multitenacy environement where the API MLs in Domain(2-N) are registered to API ML in Domain-1. The API ML in Domain-1 may be running on z/OS, or off z/OS, for example in Kubernetes. This API ML serves as a single point of access to all API Mediation Layers registered in this and, by extension, to all services registered in those API MLs. -The APIMLs in Domain(2-N) are installed on z/OS systems with the standard Zowe API ML running either in HA (sysplex) or non-HA (monoplex). These API MLs are registered to APIML in Domain-1. +The API MLs in Domain(2-N) are installed on z/OS systems with the standard Zowe API ML running either in HA (sysplex) or non-HA (monoplex). These API MLs are registered to API ML in Domain-1. ## Multitenancy component enablement settings -In the multitenancy environment, certain Zowe components may be enabled, while others may be disabled. The multitenancy environment expects one API ML (APIML in Domain-1 in our example diagram) that handles the discovery and registration as well as routing to the other API MLs (APIMLs in Domain(2-N) in our example diagram) installed in any other specific domains. +In the multitenancy environment, certain Zowe components may be enabled, while others may be disabled. The multitenancy environment expects one API ML (for example API ML in Domain-1) that handles the discovery and registration as well as routing to the other API MLs (API MLs in Domain(2-N)) installed in any other specific domains. ## Onboarding a Gateway service in one domain to the Discovery service of API ML in another domain -A Gateway from any domain can onboard Gateways of any domains. This service onboarding can be achieved similar to additional registrations of the Gateway. This section describes the dynamic configuration of the yaml file and environment variables, and how to validate successful configuration. +A Gateway from any domain can onboard Gateways of any other domains. This service onboarding can be achieved similar to additional registrations of the Gateway. This section describes the dynamic configuration of the yaml file and environment variables, and how to validate successful configuration. - [Dynamic configuration via zowe.yaml](#dynamic-configuration-via-zoweyaml) - [Dynamic configuration via Environment variables](#dynamic-configuration-via-environment-variables) ### Dynamic configuration via zowe.yaml -1. Set the following property for the Gateway of APIMLs in Domain(2-N) to dynamically onboard to the Discovery service of API ML in Domain-1. +1. In zowe.yml, set the following property for the Gateway of API MLs in Domain(2-N) to dynamically onboard to the Discovery service of API ML in Domain-1. `components.gateway.apiml.service.additionalRegistration` Use the following example as a template for how to set the value of this property in zowe.yml. - **Example:** - ``` - components.gateway.apiml.service.additionalRegistration: - # APIML in Domain-1 (in HA, for non-HA mode use only 1 hostname) - - discoveryServiceUrls: https://sys1:{discoveryServicePort}/eureka/,https://sys2:{discoveryServicePort}/eureka/ - ``` +**Example:** +``` +components.gateway.apiml.service.additionalRegistration: + # APIML in Domain-1 (in HA, for non-HA mode use only 1 hostname) + - discoveryServiceUrls: https://sys1:{discoveryServicePort}/eureka/,https://sys2:{discoveryServicePort}/eureka/ + ``` - :::note Notes: - * 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. +:::note Notes: + * 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`. + * 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. + * 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. + * Use hostnames `sys1` and `sys2` for the LPAR in the sysplex. ::: 2. (Optional) Configure the Gateway to forward client certificates. -Use this step to enable the domain(2-N) gateway to use this client certificate for authentication. . +Use this step to enable the domain(2-N) Gateway to use this client certificate for authentication. Set the `certificatesUrl` property to ensure that only Gateway-forwarded certificates are used for client certificate authentication. This URL returns a certificate chain from the gateway. - ``` - components.gateway.apiml.security.x509: - # gateway port in domain-1 - certificatesUrl: https://{gatewayHost}:{gatewayPort}/gateway/certificates - ``` +``` +components.gateway.apiml.security.x509: + # gateway port in domain-1 + certificatesUrl: https://{gatewayHost}:{gatewayPort}/gateway/certificates +``` ### Dynamic configuration via Environment variables @@ -92,17 +70,17 @@ 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_#_*`) +:::note Notes: + * 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 + * 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. + * 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. + * 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. @@ -119,9 +97,9 @@ To see details of all instances of the ‘GATEWAY’ application, perform a **GE ## Establishing a trust relationship between the API MLs -For routing to work in a multitenancy configuration, as represented in the example diagram above where "Domain APIML 2", "Domain APIML 3" are registered to "Domain APIML 1", the "Domain APIML 1" must trust the "Domain APIML 2", "Domain APIML 3" for successful registration into it's Discovery Service component. -The "Domain APIML 2", "Domain APIML 3" must trust the "Domain APIML 1" Gateway where they are registered to, to accept routed requests. -It is necessary that the root and, if applicable, intermediate public certificates be shared between these domain API Mediation Layers. +For routing to work in a multitenancy configuration, as represented in the previous diagram where "Domain API ML 2" and "Domain API ML 3" are registered to "Domain API ML 1", "Domain API ML 1" must trust "Domain API ML 2" and "Domain API ML 3". This trust is required for successful registration into the Discovery Service component of Domain API ML 1. +To accept routed requests, "Domain API ML 2" and "Domain API ML 3" must trust the "Domain API ML 1" Gateway where Domains API ML 2 and 3 are registered to. +It is necessary that the root and, if applicable, intermediate public certificates are shared between these domain API Mediation Layers. The following diagram shows the relationship between the API MLs. @@ -129,25 +107,25 @@ The following diagram shows the relationship between the API MLs. As presented in this example diagram, The API MLs are installed on systems X, Y and Z. -To establish secure communications, "Domain APIML 2" and "Domain APIML 3" are using different private keys signed with different public keys. These API MLs do not trust each other. +To establish secure communications, "Domain API ML 2" and "Domain API ML 3" use different private keys signed with different public keys. These API MLs do not trust each other. -In order for all API MLs to register with an "Domain APIML 1" in multitenancy set up, it is necessary that the "Domain APIML 1" has all public keys from the certificate chains of all registered API MLs: +In multitenancy set up, in order for all API MLs to register with "Domain API ML 1", it is necessary that "Domain API ML 1" has all public keys from the certificate chains of all registered API MLs: * DigiCert Root CA * DigiCert Root CA1 * DigiCert CA -These public keys are required for the "Domain APIML 1" to establish trust with "Domain APIML 2" and "Domain APIML 3". +These public keys are required for the "Domain API ML 1" to establish trust with "Domain API ML 2" and "Domain APIML 3". -The "Domain APIML 1" uses a private key which is signed by the Local CA public key for secure communication. +"Domain APIML 1" uses a private key which is signed by the local CA public key for secure communication. -"Domain APIML 2" and "Domain APIML 3" require a Local CA public key in order to accept the routing requests from the "Domain APIML 1", otherwise the "Domain APIML 1" requests will not be trusted by the registered API MLs. -The diagram indicates all of the added certificates inside the red dashed lines. +"Domain API ML 2" and "Domain API ML 3" require a local CA public key to accept routing requests from "Domain API ML 1". Without these local CA public keys "Domain API ML 1" requests will not be trusted by the registered API MLs. +All added certificates are indicated in the diagram inside the red dashed lines. ### Commands to establish trust between the API MLs The following commands are examples of establishing a trust relationship between API MLs in Multitenancy Configuration for both PKCS12 certificates and when using keyrings. -1. Import the root and, if applicable, the intermediate public key certificate of registered "Domain APIML 2" , "Domain APIML 3" API MLs running on systems Y and Z into the truststore of the "Domain APIML 1" running on system X. +1. Import the root and, if applicable, the intermediate public key certificate of registered "Domain API ML 2" and "Domain API ML 3" API MLs running on systems Y and Z into the truststore of the "Domain API ML 1" running on system X. - **PKCS12** @@ -159,9 +137,11 @@ The following commands are examples of establishing a trust relationship between - **Keyring** - For keyrings, use the following examples of commands specific to your ESM to add certificates from the dataset and connect these certificates to the keyring used by the "Domain APIML 1": + For keyrings, use the following examples of commands specific to your ESM to add certificates from the dataset and connect these certificates to the keyring used by the "Domain APIML 1": - - **For RACF:** +
+ Click here for command details for RACF. + - **For RACF:** ``` RACDCERT ADD('SHARE.SYSY.ROOTCA.CER') ID(ZWESVUSR) WITHLABEL('DigiCert Root CA') TRUST @@ -175,7 +155,10 @@ The following commands are examples of establishing a trust relationship between ``` RACDCERT LISTRING(ZoweKeyring) ID(ZWESVUSR) ``` +
+
+ Click here for command details for ACF2. - **For ACF2:** ``` @@ -196,8 +179,11 @@ The following commands are examples of establishing a trust relationship between SET PROFILE(USER) DIVISION(KEYRING) LIST LIKE(ZWESVUSR.-) ``` +
- - **For TopSecret:** +
+ Click here for command details for Top Secret. + - **For Top Secret:** ``` TSS ADD(CERTAUTH) DCDS(SHARE.SYSY.ROOTCA.CER) DIGICERT(SYSYROOT) LABLCERT('DigiCert Root CA') TRUST @@ -210,6 +196,7 @@ The following commands are examples of establishing a trust relationship between ``` TSS LIST(ZWESVUSR) KEYRING(ZOWERING) ``` +
2. Import root and, if applicable, intermediate public key certificates of the API ML running on system X into the truststore of the API MLs running on systems Y and Z. @@ -223,8 +210,10 @@ The following commands are examples of establishing a trust relationship between - **Keyring** - For keyring certificates, use the following examples of commands specific to your ESM to add certificates from the dataset, and connect these certificates to the keyrings used by registered API MLs: + For keyring certificates, use the following examples of commands specific to your ESM to add certificates from the dataset, and connect these certificates to the keyrings used by registered API MLs: +
+ Click here for command details for RACF. - **For RACF:** ``` @@ -237,7 +226,10 @@ The following commands are examples of establishing a trust relationship between ``` RACDCERT LISTRING(ZoweKeyring) ID(ZWESVUSR) ``` +
+
+ Click here for details for ACF2. - **For ACF2:** ``` @@ -256,8 +248,12 @@ The following commands are examples of establishing a trust relationship between SET PROFILE(USER) DIVISION(KEYRING) LIST LIKE(ZWESVUSR.-) ``` +
+ +
+ Click here for command details for Top Secret - - **For TopSecret:** + - **For Top Secret:** ``` TSS ADD(CERTAUTH) DCDS(SHARE.SYSX.ROOTCA.CER) DIGICERT(SYSXROOT) LABLCERT('Local CA') TRUST @@ -268,6 +264,7 @@ The following commands are examples of establishing a trust relationship between ``` TSS LIST(ZWESVUSR) KEYRING(ZOWERING) ``` +
You completed certificates setup for multitenancy configuration, whereby registered API MLs can trust the API ML where they are registered and vice versa. @@ -311,6 +308,9 @@ This request lists services in the APIML of the specific apimlId given. ### Response with `/registry` +
+Click here for an example of the response with /registry + **Example:** ``` @@ -360,10 +360,14 @@ This request lists services in the APIML of the specific apimlId given. } ] ``` +
### Response with `/registry{apimlId}` -This response should contain information about all services in an APIML with the specific apimlId. +This response should contain information about all services in an API ML with the specific apimlId. + +
+Click here for an example of a response with /registry{apimlId} **Example:** @@ -401,10 +405,15 @@ This response should contain information about all services in an APIML with the ] ``` +
+ ### Response with `GET /gateway/api/v1/registry/{apimlId}?apiId={apiId}&serviceId={serviceId}` This response should contain information about a specific service in an APIML with the specific apimlId. +
+Click here for an example response with GET /gateway/api/v1/registry/{apimlId}?apiId={apiId}&serviceId={serviceId} + **Example:** * `GET /gateway/api/v1/registry/apiml2?apiId=zowe.apiml.gateway&serviceId=catalog` @@ -429,6 +438,7 @@ This response should contain information about a specific service in an APIML wi } ] ``` +
## Validating successful configuration with `/registry` @@ -439,6 +449,9 @@ Use the `/registry` endpoint to validate successful configuration. The response The Gateway static definition file should be stored together with other statically onboarded services. The default location is `/zowe/runtime/instance/workspace/api-mediation/api-defs/`. There is no naming restriction of the filename, but the file extension must be `yml`. +
+Click here for a Gateway static definition example. + **Example:** ``` # @@ -509,6 +522,8 @@ catalogUiTiles: description: Services which demonstrate how to make an API service discoverable in the APIML ecosystem using YAML definitions ``` +
+ ## Troubleshooting multitenancy configuration ### ZWESG100W