Skip to content

Commit

Permalink
Merge branch 'master' into reboot/docs/v2-attls
Browse files Browse the repository at this point in the history
  • Loading branch information
@pablocarle
pablocarle authored Oct 22, 2024
2 parents 78276c3 + a24e9ad commit 96807c1
Show file tree
Hide file tree
Showing 2 changed files with 1,594 additions and 64 deletions.
121 changes: 58 additions & 63 deletions docs/user-guide/api-mediation/api-mediation-multi-tenancy.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,24 +4,26 @@ Zowe supports management of multiple tenants, whereby different tenants can serv

* [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)
* [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 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)
* [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 Cloud Gateway](#using-the-registry-endpoint-in-the-central-gateway)
* [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 for `/registry`](#authorization-with-registry)
* [Authorization with `/registry`](#authorization-with-registry)
* [Requests with `/registry`](#requests-with-registry)
* [Response with `/registry`](#response-with-registry)
* [Validating successful configuration with `/registry`](#validating-successful-configuration-with-registry)
* [Gateway static definition example](#gateway-static-definition-example-deprecated)
* [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)
Expand All @@ -39,21 +41,11 @@ Domain-1 to Domain-N are z/OS systems with the standard Zowe API ML running eith

## 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. As such, different setups are required for the V2 version of the API ML on the central domain and on the specific customer environments.

When using a multitenancy environment, ensure that the following Zowe components are either enabled or disabled:

- **Domain API ML**
- Gateway and Discovery Service: **enabled**
- Cloud Gateway: **disabled**

- **Central API ML**
- Cloud Gateway and Discovery Service: **enabled**
- Gateway: **disabled**
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.

## Onboarding Domain Gateways to the Central Gateway

The Central Cloud 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).
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).

### Dynamic Onboarding (recommended) for Domain Gateways

Expand Down Expand Up @@ -85,8 +77,8 @@ components.gateway.apiml.service.additionalRegistration:

```
components.gateway.apiml.security.x509:
# cloud gateway port
certificatesUrl: https://sys1:{cloudGatewayPort}/gateway/certificates
# central gateway port
certificatesUrl: https://{centralGatewayHost}:{centralGatewayPort}/gateway/certificates
```

:::note
Expand All @@ -110,7 +102,7 @@ For static onboarding, use the [Gateway static definition example (deprecated)](

## Onboarding a Domain Gateway service to the Central Discovery service

The Central Cloud Gateway can onboard Cloud 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.
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
Expand All @@ -119,7 +111,7 @@ The Central Cloud Gateway can onboard Cloud Gateways of all domains. This servic

#### Dynamic configuration: YML

Users must set the following property for the Domain Cloud Gateway to dynamically onboard to the Central Discovery service.
Users must set the following property for the Domain Gateway to dynamically onboard to the Central Discovery service.

`components.gateway.apiml.service.additionalRegistration`

Expand All @@ -128,7 +120,7 @@ Use the following example as a template for how to set the value of this propert
**Example:**
```
components.gateway.apiml.service.additionalRegistration:
# central API ML (in HA, for non-HA mode use only 1 hostname)
# central API ML (in HA, for non-HA mode use only 1 hostname)
- discoveryServiceUrls: https://sys1:{discoveryServicePort}/eureka/,https://sys2:{discoveryServicePort}/eureka/
routes:
- gatewayUrl: /
Expand Down Expand Up @@ -174,7 +166,7 @@ This Zowe configuration transforms the zowe.yaml configuration file into the env

### Validating successful configuration

The corresponding Cloud Gateway service should appear in the Eureka console of the Central Discovery service.
The corresponding Gateway service should appear in the Eureka console 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 Central Discovery service:

Expand Down Expand Up @@ -338,17 +330,16 @@ You completed certificates setup for multitenancy configuration, whereby Domain

## Using the `/registry` endpoint in the Central Gateway

The `/registry` endpoint provides information about services onboarded to all Domain Gateways and the Central Cloud Gateway. 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 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.

### Configuration for `/registry`

The `/registry` endpoint is disabled by default. Use the following environment variable to enable this feature:

`APIML_CLOUDGATEWAY_REGISTRY_ENABLED=TRUE`
The `/registry` endpoint is disabled by default. Use the configuration property `apiml.gateway.registry.enabled=true` or
environment variable `APIML_GATEWAY_REGISTRY_ENABLED=TRUE` to enable this feature.

### Authentication for `/registry`

The `/registry` endpoint is authenticated by the client certificate. The Central Cloud 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 Central 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.

Expand Down Expand Up @@ -387,12 +378,12 @@ This request lists services in the apimlId domain.
{
"status": "UP",
"customMetadata": {
"zos.sysname": "sys1",
"zos.sysplex": "sysplex"
"zos.sysname": "sys1",
"zos.sysplex": "sysplex"
},
"apiId": [
"zowe.apiml.gateway"
],
"zowe.apiml.gateway"
],
"serviceId": "gateway"
}
]
Expand All @@ -402,26 +393,28 @@ This request lists services in the apimlId domain.
"services": [
{
"status": "UP",
"customMetadata": {
"zos.sysname": "sys2",
"zos.sysplex": "sysplex"
},
"customMetadata": {
"zos.sysname": "sys2",
"zos.sysplex": "sysplex"
},
"apiId": [
"zowe.apiml.gateway"
],
"zowe.apiml.gateway"
],
"serviceId": "gateway"
},
{
"status": "UP",
"status": "UP",
"customMetadata": {
"zos.sysname": "sys2",
"zos.sysplex": "sysplex"},
"zos.sysname": "sys2",
"zos.sysplex": "sysplex"
},
"apiId": [
"zowe.apiml.catalog"
],
"zowe.apiml.catalog"
],
"serviceId": "catalog"
}
]
}
]
```

Expand All @@ -441,26 +434,27 @@ Should contain information about all services in a specific domain
{
"status": "UP",
"customMetadata": {
"zos.sysname": "sys2",
"zos.sysplex": "sysplex"
"zos.sysname": "sys2",
"zos.sysplex": "sysplex"
},
"apiId": [
"zowe.apiml.gateway"
],
"zowe.apiml.gateway"
],
"serviceId": "gateway"
},
{
"status": "UP",
"customMetadata": {
"zos.sysname": "sys2",
"zos.sysplex": "sysplex"
"zos.sysname": "sys2",
"zos.sysplex": "sysplex"
},
"apiId": [
"zowe.apiml.catalog"
],
"zowe.apiml.catalog"
],
"serviceId": "catalog"
}
]
}
]
```

Expand All @@ -480,15 +474,16 @@ Should contain information about a specific service in a specific domain
{
"status": "UP",
"customMetadata": {
"zos.sysname": "sys2",
"zos.sysplex": "sysplex"
"zos.sysname": "sys2",
"zos.sysplex": "sysplex"
},
"apiId": [
"zowe.apiml.catalog"
],
"zowe.apiml.catalog"
],
"serviceId": "catalog"
}
]
}
]
```

Expand Down Expand Up @@ -526,7 +521,7 @@ services:
serviceRelativeUrl: /
- gatewayUrl: ws/v1
serviceRelativeUrl: /ws
# List of APIs provided by the service (currently only one is supported):
# List of APIs provided by the service (currently only one is supported):
apiInfo:
- apiId: zowe.apiml.gateway
gatewayUrl: api/v1
Expand All @@ -553,7 +548,7 @@ services:
serviceRelativeUrl: /
- gatewayUrl: ws/v1
serviceRelativeUrl: /ws
# List of APIs provided by the service (currently only one is supported):
# List of APIs provided by the service (currently only one is supported):
apiInfo:
- apiId: zowe.apiml.gateway
gatewayUrl: api/v1
Expand All @@ -578,7 +573,7 @@ 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 Cloud Gateway was not established.
The trust between the domain and the central Gateway was not established.

**Action**
Review your certificate configuration.
Expand Down
1,537 changes: 1,536 additions & 1 deletion docs/user-guide/api-mediation/diagrams/multi-domain_architecture_V2.svg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 96807c1

Please sign in to comment.