Merge pull request #3853 from zowe/balhar-jakub/apiml/v3/yaml-fixes

Further fixes for V3 from API Mediation Layer

docs/getting-started/zowe-architecture.md

@@ -75,7 +75,16 @@ ZIS is a z/OS native, authorized cross-memory server that allows a secure and co
 
 Unlike all of the servers described above which run under the `ZWESLSTC` started task as address spaces for USS processes, the Cross Memory server has its own separate started task `ZWESISTC` and its own user ID `ZWESIUSR` that runs the program `ZWESIS01`.
 
-## API Gateway
+## API Mediation Layer
+
+The API Mediation Layer is a collection of services for management and administration of APIs, and is comprised of the following components that are described in detail below:
+
+* API Gateway
+* API Catalog
+* API Discovery
+* Caching service
+
+### API Gateway
 
 The API Gateway is a proxy server that routes requests from clients on its northbound or upstream edge, such as web browsers or the Zowe command line interface, to servers on its southbound (downstream) edge that are able to provide data to serve the request. The API Gateway is also responsible for generating the authentication token used to provide single sign-on (SSO) functionality. The API Gateway homepage is `https://<ZOWE_HOST_IP>:7554`. Following authentication, this URL enables users to navigate to the API Catalog.
 
@@ -84,31 +93,31 @@ The API Gateway is a proxy server that routes requests from clients on its north
 When the API Gateway is running, this server is accessible at `https://<ZOWE_HOST_IP>:7554/`.
 When running on z/OS, the server uses the jobname suffix of AG.
 
-## API Catalog
+### API Catalog
 
 The API Catalog provides a list of the API services that have registered themselves as catalog tiles. These tiles make it possible to view the available APIs from Zowe's southbound (downstream) servers, as well as test REST API calls.  
 
 ![Zowe API Catalog](../images/api-mediation/api-catalog.png)
 
 When the API Gateway is running, this server is accessible at `https://<ZOWE_HOST_IP>:7554/apicatalog/ui/v1`.
-When the API Catalog is running, this server's API documentation is accessible at the API Catalog tile `Zowe Applications` which can be viewed at `https://<ZOWE_HOST_IP>:7554/apicatalog/ui/v1/#/tile/apimediationlayer/apicatalog`
+When the API Catalog is running, the API documentation of this server is accessible at the API Catalog tile `Zowe Applications` which can be viewed at `https://<ZOWE_HOST_IP>:7554/apicatalog/ui/v1/#/tile/apimediationlayer/apicatalog`
 When running on z/OS, the server uses the jobname suffix of AC.
 
-## API Discovery
+### API Discovery
 
 The API Discovery server acts as the registration service broker between the API Gateway and its southbound (downstream) servers. This server can be accessed through the URL `https://<ZOWE_HOST_IP>:7552` making it possible to view a list of registered API services on the API discovery homepage.
 
 ![Zowe API Discovery](../images/api-mediation/api-discovery.png)
 
 When running on z/OS, the server uses the jobname suffix of AD.
 
-## Caching service
+### Caching service
 
 The Caching service aims to provide an API which offers the possibility to store, retrieve, and delete data associated with keys. The service is used only by internal Zowe applications and is not exposed to the internet. The Caching service URL is `https://<ZOWE_HOST_IP>:7555`.
 For more information about the Caching service, see [Using the Caching Service](../user-guide/api-mediation/api-mediation-caching-service).
 
 When the API Gateway is running, this server is accessible at `https://<ZOWE_HOST_IP>:7554/cachingservice/api/v1`.
-When the API Catalog is running, this server's API documentation is accessible at the API Catalog tile `Zowe Applications` which can be viewed at `https://<ZOWE_HOST_IP>:7554/apicatalog/ui/v1/#/tile/zowe/cachingservice`.
+When the API Catalog is running, the API documentation of this server is accessible at the API Catalog tile `Zowe Applications` which can be viewed at `https://<ZOWE_HOST_IP>:7554/apicatalog/ui/v1/#/tile/zowe/cachingservice`.
 When running on z/OS, the server uses the jobname suffix of CS.
 
 ## Desktop Apps

docs/user-guide/api-mediation/configuration-connection-limits.md

@@ -33,8 +33,7 @@ zowe:
 Use the following procedure to change the limits:
 
 1. Open the file `zowe.yaml`.
-2. Find or add the property `zowe.components.gateway.server.websocket.connectTimeout`, and set the value to an appropriate positive integer. This timeout limits how long the API Gateway waits until it drops connection if it cannot reach the target server. The default is 45 seconds (45000 milliseconds).
-3. Find or add the property `zowe.components.gateway.server.websocket.stopTimeout`, and set the value to an appropriate positive integer. This timeout handles how long the API Gateway will wait for the graceful stopping of the WebSocket connection. The default is 30 seconds (30000 milliseconds).
-4. Find or add the property `zowe.components.gateway.server.websocket.asyncWriteTimeout`, and set the value to an appropriate positive integer. This timeout handles how long it takes before the server fails with unsuccessful response when trying to write a message to the Websocket connection. The default is 60 seconds (60000 milliseconds).
-5. Find or add the property `zowe.components.gateway.server.websocket.maxIdleTimeout`, and set the value to an appropriate positive integer. This timeout handles how long the Websocket connection remains open if there is no communication happening over the open connection. The default is one hour (3600000 milliseconds).
-6. Find or add the property `zowe.components.gateway.server.websocket.requestBufferSize` and set the value to an appropriate positive integer. This property handles the max request size allowed in WebSocket handshake requests. The default is 8K.
+2. Find or add the property `components.gateway.server.websocket.connectTimeout`, and set the value to an appropriate positive integer. This timeout limits how long the API Gateway waits until it drops connection if it cannot reach the target server. The default is 45 seconds (45000 milliseconds).
+3. Find or add the property `components.gateway.server.websocket.asyncWriteTimeout`, and set the value to an appropriate positive integer. This timeout handles how long it takes before the server fails with unsuccessful response when trying to write a message to the Websocket connection. The default is 60 seconds (60000 milliseconds).
+4. Find or add the property `components.gateway.server.websocket.maxIdleTimeout`, and set the value to an appropriate positive integer. This timeout handles how long the Websocket connection remains open if there is no communication happening over the open connection. The default is one hour (3600000 milliseconds).
+5. Find or add the property `components.gateway.server.websocket.requestBufferSize` and set the value to an appropriate positive integer. This property handles the max request size allowed in WebSocket handshake requests. The default is 8K.

docs/user-guide/api-mediation/configuration-gateway-timeouts.md

@@ -8,35 +8,22 @@ Use the following procedure to change the global timeout value for an API Mediat
 1. Open the file `zowe.yaml`.
 2. Configure the following properties:
 
-  * **components.gateway.apiml.gateway.timeoutmillis**  
-   This property defines the global value for http/ws client timeout.
-
-  :::note
-  Ribbon configures the client that connects to the routed services.
-  :::
-  * **components.gateway.ribbon.connectTimeout**  
+  * **components.gateway.apiml.connectTimeout**  
   Specifies the value in milliseconds which corresponds to the period in which API ML should establish a single, non-managed connection with the service. If omitted, the default value specified in the API ML Gateway service configuration is used.
+  * **components.gateway.apiml.connection.idleConnectionTimeoutSeconds**
 
-  * **components.gateway.ribbon.readTimeout**  
-  Specifies the time in milliseconds of inactivity between two packets in response from this service to API ML. If omitted, the default value specified in the API ML Gateway service configuration is used.
-
-  * **components.gateway.ribbon.connectionManagerTimeout**  
-  The HttpClient employs a special entity to manage access to HTTP connections called by the HTTP connection manager. The purpose of an HTTP connection manager is to serve as a factory for new HTTP connections, to manage the life cycle of persistent connections, and to synchronize access to persistent connections. Internally, the connections that are managed serve as proxies for real connections. `ConnectionManagerTimeout` specifies a period during which managed connections with API ML should be established. The value is in milliseconds. If omitted, the default value specified in the API ML Gateway service configuration is used.
-
-  * **components.gateway.httpclient.requestConnectionTimeout**  
-  Specifies the HTTP Client Request Connection Timeout for southbound services from the API Gateway. This setting defines the period that the API Gateway waits for a response from the southbound server before issuing a connection refused response. The value is in milliseconds. An example value of a 30 second connection timeout would be 30000. 
+  * **components.gateway.apiml.connection.timeToLive**
 
 **Example:**
 
 ```yaml
 components:
     gateway:
-       ribbon:
+       apiml:
            connectTimeout: 30000
-           readTimeout: 60000
-           connectionManagerTimeout: 45000
-       httpclient:
-           requestConnectionTimeout: 60000
+           connection:
+              idleConnectionTimeoutSeconds:
+              timeToLive: 
 ```
 
 3. Restart Zowe.

docs/user-guide/api-mediation/configuration-health-endpoint-protection.md

@@ -1,43 +1,48 @@
-# Configuring API Gateway Health Check Protection
+# Configuring Health Check Protection
 
 :::info Role: system programmer
 ::: 
 
-As a system programmer, you can configure the security setting for the health check endpoint of the API Gateway. This setting determines whether the health check endpoint is accessible without authentication, or alternatively requires authentication. Enabling protection for the health check endpoint can enhance the security of the API Gateway by restricting access to sensitive status information about the Gateway.
+As a system programmer, you can disable the security setting for the health check endpoint of the API Gateway. This setting determines whether the health check endpoint is accessible without authentication, or alternatively requires authentication. In Zowe V2, authentication was not required. Disabling protection for the health check endpoint can limit the security of the API Gateway by allowing access to sensitive status information about the Gateway.
 
 Use the following procedure to set the value of the health check endpoint of the API Gateway:  
 
 1. Open the file `zowe.yaml`.
 2. Configure the following property:
 
-* `components.gateway.apiml.gateway.health.protected`  
+* `components.gateway.apiml.health.protected`  
 This property defines whether the health check endpoint is accessible with or without authentication.
 
 :::note
-The default value of this parameter is `false`. We recommend setting this parameter to `true` for production environments.
+The default value of this parameter is `true`.
 :::
 
 **Example:**
 ```yaml
-zowe:
-  components:
+components:
     gateway:
-      apiml:
-        gateway:
-            health:
-                protected: true
+        apiml:
+            gateway:
+                health:
+                    protected: true
 ```
 
-In this example, setting `protected` to `true` protects the health check endpoint by requiring authentication. Only authenticated users can access the health check endpoint. This ensures that sensitive information about the status of the Gateway is not exposed to unauthenticated users.
+In this example, setting `protected` to `true` protects the health check endpoint by requiring authentication. Only authenticated users can access the health check endpoint. Requiring authentication ensures that sensitive information about the status of the Gateway is not exposed to unauthenticated users.
 
 To allow open access to the health check endpoint, set the parameter to `false`. Setting this parameter to `false` permits access to this endpoint without authentication. In this case, anyone can access the health check endpoint and obtain information about the status of the Gateway.
 
+* `components.discovery.apiml.health.protected`  
+  This property defines whether the health check endpoint on Discovery service is accessible with or without authentication.
+* `components.apiCatalog.apiml.health.protected`  
+  This property defines whether the health check endpoint on API Catalog is accessible with or without authentication.
+
+
 ## Environment Recommendations
 
 When setting this parameter, we recommend applying the following values according to your environment:
 
 * **In Production Environments**  
-It is recommended to set `apiml.gateway.health.protected` to `true` to enhance security and protect sensitive information about the API Gateway's health status.
+It is recommended to set `components.*.apiml.health.protected` to `true` to enhance security and protect sensitive information about the API Gateway's health status. This is the default.
 
 * **In Development/Testing Environments**  
- setting `apiml.gateway.health.protected` to `false` can simplify the testing process, reduce development overhead, and assist with debugging.  
+ setting `components.*.apiml.health.protected` to `false` can simplify the testing process, reduce development overhead, and assist with debugging.  

docs/user-guide/api-mediation/configuration-personal-access-token.md

@@ -10,18 +10,17 @@ Review this article for steps that enable single sign on via Personal Access Tok
 
 To enable Personal Access Token support when using the Caching Service, **Infinispan** is the required storage solution. Infinispan is part of Zowe installation. No additional software or installation is required when using this storage solution.
 
-To enable this storage method, set the value of `zowe.components.caching-service.storage.mode` to `infinispan` in the `zowe.yaml` configuration file. Infinispan environment variables are not currently following the v2 naming convention, so they must be defined into `zowe.environments` section.  For more information on these properties and their values see [Infinispan configuration](../../extend/extend-apiml/api-mediation-infinispan.md#infinispan-configuration).
+To enable this storage method, set the value of `components.caching-service.storage.mode` to `infinispan` in the `zowe.yaml` configuration file. For more information on other properties for infinispan and their values see [Infinispan configuration](../../extend/extend-apiml/api-mediation-infinispan.md#infinispan-configuration).
 
 
   ``` yaml
-  zowe
-    components:
-          caching-service:
-            storage:
-              mode: infinispan
-              infinispan: 
-                jgroups:
-                  port: 7098
+  components:
+    caching-service:
+      storage:
+        mode: infinispan
+        infinispan: 
+          jgroups:
+            port: 7098
   ```
 
 ## Enabling Personal Access Tokens