From ed1a9831d37d6ad04436047365fc5672acb7b013 Mon Sep 17 00:00:00 2001 From: achmelo Date: Thu, 21 Dec 2023 10:32:47 +0100 Subject: [PATCH 1/8] configure infinispan with zowe yaml Signed-off-by: achmelo --- .../extend-apiml/api-mediation-infinispan.md | 44 +++++++++++-------- .../configure-caching-service-ha.md | 12 ++--- docs/user-guide/install-zos.md | 2 +- sidebars.js | 1 + 4 files changed, 35 insertions(+), 24 deletions(-) diff --git a/docs/extend/extend-apiml/api-mediation-infinispan.md b/docs/extend/extend-apiml/api-mediation-infinispan.md index 5d456d20cd..403db6a854 100644 --- a/docs/extend/extend-apiml/api-mediation-infinispan.md +++ b/docs/extend/extend-apiml/api-mediation-infinispan.md @@ -3,8 +3,10 @@ As an API developer, you can configure Infinispan as a storage solution through the Caching service. This article describes how to configure your storage solution for Infinispan. You can configure Infinispan for high availability as well as to replicate data to provide data durability and availability. -- [Understanding Infinispan](#understanding-infinispan) -- [Infinispan configuration](#infinispan-configuration) +- [Using Infinispan as a storage solution through the Caching service](#using-infinispan-as-a-storage-solution-through-the-caching-service) + - [Understanding Infinispan](#understanding-infinispan) + - [Infinispan replica instances](#infinispan-replica-instances) + - [Infinispan configuration](#infinispan-configuration) ## Understanding Infinispan @@ -16,38 +18,44 @@ For more information on Infinispan, see the [official Infinispan documentation]( ### Infinispan replica instances Infinispan can be used with both on standalone instance and High Availability mode. In case of multiple Caching Service instances, -you will have to specify all the cluster nodes (members). Each Infinispan node is bound to specific Caching Service instance and runs on a different port and host, which can be configured. See the [nfinispan configuration](#infinispan-configuration) to know how to configure multiple Infinispan nodes. +you will have to specify all the cluster nodes (members). Each Infinispan node is bound to specific Caching Service instance and runs on a different port and host, which can be configured. See the [infinispan configuration](#infinispan-configuration) to know how to configure multiple Infinispan nodes. For more information on Infinispan replication and how to configure a replica instance, see the [official Infinispan Cross-site Replication documentation](https://infinispan.org/docs/stable/titles/xsite/xsite.html). ## Infinispan configuration -Configure Infinispan as a storage solution through the Caching service by setting the following environment variables. Environment variables can be set by adding them to `instance.env`. +Configure Infinispan as a storage solution through the Caching service by setting the following configuration parameters in the `zowe.yaml`. -* **`CACHING_STORAGE_INFINISPAN_INITIALHOSTS`** +* **`zowe.components.caching-service.storage.infinispan.initialHosts`** This property specifies the list of cluster nodes (members). In case of multiple instances, the value for each Caching Service instance can be - either a list of all the members, separated by a comma, or just the replica. The format is `${JGROUPS_BIND_ADDRESS}[${JGROUPS_BIND_PORT}]`. + either a list of all the members, separated by a comma, or just the replica. The format is `${haInstance.hostname}[${zowe.components.caching-service.storage.infinispan.jgroups.port}]`. - **Example:** - `CACHING_STORAGE_INFINISPAN_INITIALHOST=caching-service[7600]` - -* **`CACHING_STORAGE_INFINISPAN_PERSISTENCE_DATALOCATION`** +* **`zowe.components.caching-service.storage.infinispan.persistence.dataLocation`** The path where the Soft-Index store will keep its data files for the Infinispan Soft-Index Cache Store. The default value is `data`. If you run the Caching Service in HA and the instances use the same filesystem, - you have to specify a different value of the `CACHING_STORAGE_INFINISPAN_PERSISTENCE_DATALOCATION` property for each + you have to specify a different value of the `zowe.components.caching-service.storage.infinispan.persistence.dataLocation` property for each instance. For more information, see [Soft-Index File Store](https://infinispan.org/blog/2014/10/31/soft-index-file-store). -* **`JGROUPS_BIND_PORT`** - - The Jgroups port used by Infinispan. - +* **`zowe.components.caching-service.storage.infinispan.jgroups.port`** -* **`JGROUPS_BIND_ADDRESS`** + The port number used by Infinispan to synchronise data among cahing-service instances. - The Jgroups address used by Infinispan. - + **Example of Caching service configuration using Infinispan:** + ``` + zowe + components: + caching-service: + storage: + mode: infinispan + infinispan: + initialHosts: lpar123[7099] + jgroups: + port: 7098 + persistence: + dataLocation: data01 + ``` \ No newline at end of file diff --git a/docs/user-guide/configure-caching-service-ha.md b/docs/user-guide/configure-caching-service-ha.md index 2703a65a82..78ac382808 100644 --- a/docs/user-guide/configure-caching-service-ha.md +++ b/docs/user-guide/configure-caching-service-ha.md @@ -38,11 +38,13 @@ The Infinispan storage method is recommended for production usage. ``` zowe - environments: - JGROUPS_BIND_PORT: - JGROUPS_BIND_ADDRESS: - CACHING_STORAGE_INFINISPAN_INITIALHOSTS: - CACHING_STORAGE_INFINISPAN_PERSISTENCE_DATALOCATION: + components: + caching-service: + storage: + mode: infinispan + infinispan: + jgroups: + port: 7098 ``` ## VSAM diff --git a/docs/user-guide/install-zos.md b/docs/user-guide/install-zos.md index e5ec5c842d..f9ccc9491b 100644 --- a/docs/user-guide/install-zos.md +++ b/docs/user-guide/install-zos.md @@ -50,7 +50,7 @@ In most cases, the system programmer performs the Zowe installation and configur The following diagram illustrates the full ecosystem for installing Zowe server-side components for z/OS. -![4 installation methods](../images/install/4-installation-methods(2).png) +![4 installation methods](../images/install/4-installation-methods.png) ## Stage 1: Prepare for installation diff --git a/sidebars.js b/sidebars.js index db18b6f788..ae49c7161e 100644 --- a/sidebars.js +++ b/sidebars.js @@ -651,6 +651,7 @@ module.exports = { "extend/extend-apiml/api-mediation-caching-service", "extend/extend-apiml/api-mediation-vsam", "extend/extend-apiml/api-mediation-redis", + "extend/extend-apiml/api-mediation-infinispan", ], } ], From 890f8fdb1cc967054afda1b02a71e9e5520c7421 Mon Sep 17 00:00:00 2001 From: achmelo Date: Fri, 17 May 2024 14:28:41 +0200 Subject: [PATCH 2/8] restructure AT-TLS conf to use global parameters Signed-off-by: achmelo --- .../api-mediation/configuration-at-tls.md | 38 ++----------------- docs/user-guide/at-tls-configuration.md | 32 ++++++++++++++++ sidebars.js | 1 + 3 files changed, 36 insertions(+), 35 deletions(-) create mode 100644 docs/user-guide/at-tls-configuration.md diff --git a/docs/user-guide/api-mediation/configuration-at-tls.md b/docs/user-guide/api-mediation/configuration-at-tls.md index ea5de0a577..7b16b2dd00 100644 --- a/docs/user-guide/api-mediation/configuration-at-tls.md +++ b/docs/user-guide/api-mediation/configuration-at-tls.md @@ -1,11 +1,10 @@ # Configuring AT-TLS for API Mediation Layer -The communication server on z/OS provides a functionality to encrypt HTTP communication for on-platform running jobs. This functionality is refered to as Application Transparent Transport Layer Security (AT-TLS). Review this article for descriptions of the configuration parameters required to make the Zowe API Mediation Layer work with AT-TLS, and security recommendations. :::info Role: security administrator -::: +::: - [AT-TLS configuration for Zowe](#at-tls-configuration-for-zowe) - [AT-TLS rules](#at-tls-rules) @@ -24,43 +23,12 @@ Review this article for descriptions of the configuration parameters required to Support for AT-TLS was introduced in Zowe v1.24. In this early version, startup was not possible in some versions of Zowe. For full support, we recommend that you upgrade to v2.13 or a later version of Zowe. ::: -Follow these steps to configure Zowe to support AT-TLS: - -1. Enable the AT-TLS profile and disable the TLS application in API ML. -Update `zowe.yaml` with the following values under `gateway`, `discovery`, `api-catalog`, `caching-service` and `metrics-service` in the `zowe.components` section. - -**Example:** - -```yaml -zowe: - components: - gateway: - spring: - profiles: - active: attls - server: - ssl: - enabled: false - server: - internal: - ssl: - enabled: false - - discovery: - spring: - profiles: - active: attls - server: - ssl: - enabled: false -``` - While API ML does not handle TLS on its own with AT-TLS enabled, API ML requires information about the server certificate that is defined in the AT-TLS rule. Esure that the server certificates provided by the AT-TLS layer are trusted in the configured Zowe keyring. Ideally, AT-TLS should be configured with the same Zowe keyring. -2. If there is an outbound AT-TLS rule configured for the link between the API Gateway and z/OSMF, set the `zowe.zOSMF.scheme` property to `http`. +If there is an outbound AT-TLS rule configured for the link between the API Gateway and z/OSMF, set the `zowe.zOSMF.scheme` property to `http`. :::note Notes -* Currently, AT-TLS is not supported in the API Cloud Gateway Mediation Layer component. +* AT-TLS is supported in the API Cloud Gateway Mediation Layer component since version 2.17. * As the Gateway is a core component of API ML, other components that need to interact with the Gateway, such as Zowe ZLUX App Server, also require AT-TLS configuration. ::: diff --git a/docs/user-guide/at-tls-configuration.md b/docs/user-guide/at-tls-configuration.md new file mode 100644 index 0000000000..22e9095f2e --- /dev/null +++ b/docs/user-guide/at-tls-configuration.md @@ -0,0 +1,32 @@ +# Configuring AT-TLS + +The communication server on z/OS provides functionality to encrypt HTTP communication for on-platform jobs. This functionality is referred to as Application Transparent Transport Layer Security (AT-TLS). + +## Configuration Parameters + +To enable AT-TLS for Zowe components, configure the following parameters: +```yaml +zowe: + network: + server: + attls: true +``` + +### High Availability Setup + +In a high availability setup where one LPAR (e.g., lpar1) is using AT-TLS and the second (e.g., lpar2) is also using AT-TLS, configure as follows: + +```yaml +zowe: + haInstances: + lpar1: + attls: true + lpar2: + attls: true +``` + +## Component-Specific Configuration + +For detailed configuration instructions specific to each component, refer to the following guides: +- [Configuring AT-TLS for API Mediation Layer](../user-guide/api-mediation/configuration-at-tls.md) +- [Using AT-TLS in the App Framework](../user-guide/mvd-configuration#using-at-tls-in-the-app-framework) \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index fb264ba854..ca3d84744d 100644 --- a/sidebars.js +++ b/sidebars.js @@ -200,6 +200,7 @@ module.exports = { "user-guide/generate-certificates", "user-guide/use-certificates", "user-guide/certificates-setup", + "user-guide/at-tls-configuration", ], }, { From d240e0d036783cb8d1e0e85727636acc81c8eeb6 Mon Sep 17 00:00:00 2001 From: achmelo Date: Fri, 17 May 2024 15:09:39 +0200 Subject: [PATCH 3/8] fix typo Signed-off-by: achmelo --- docs/user-guide/at-tls-configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/at-tls-configuration.md b/docs/user-guide/at-tls-configuration.md index 22e9095f2e..2eea36c0e8 100644 --- a/docs/user-guide/at-tls-configuration.md +++ b/docs/user-guide/at-tls-configuration.md @@ -14,7 +14,7 @@ zowe: ### High Availability Setup -In a high availability setup where one LPAR (e.g., lpar1) is using AT-TLS and the second (e.g., lpar2) is also using AT-TLS, configure as follows: +In a high availability setup where one LPAR (e.g., lpar1) is using AT-TLS and the second (e.g., lpar2) is not using AT-TLS, configure as follows: ```yaml zowe: @@ -22,7 +22,7 @@ zowe: lpar1: attls: true lpar2: - attls: true + attls: false ``` ## Component-Specific Configuration From a2d6c4c96fe07b96f6f3956ca3330f383ad7eb01 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Tue, 21 May 2024 11:58:48 +0200 Subject: [PATCH 4/8] minor language refactor Signed-off-by: Andrew Jandacek --- docs/extend/extend-apiml/api-mediation-infinispan.md | 2 -- docs/user-guide/api-mediation/configuration-at-tls.md | 7 +++++-- docs/user-guide/at-tls-configuration.md | 2 +- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/extend/extend-apiml/api-mediation-infinispan.md b/docs/extend/extend-apiml/api-mediation-infinispan.md index 763c882af0..15b69b37af 100644 --- a/docs/extend/extend-apiml/api-mediation-infinispan.md +++ b/docs/extend/extend-apiml/api-mediation-infinispan.md @@ -31,8 +31,6 @@ Configure Infinispan as a storage solution through the Caching service by settin This property specifies the list of cluster nodes (members). In case of multiple instances, the value for each Caching Service instance can be either a list of all the members, separated by a comma, or just the replica. The format is `${haInstance.hostname}[${zowe.components.caching-service.storage.infinispan.jgroups.port}]`. - either a list of all the members, separated by a comma, or just the replica. The format is `${haInstance.hostname}[${zowe.components.caching-service.storage.infinispan.jgroups.port}]`. - * **`zowe.components.caching-service.storage.infinispan.persistence.dataLocation`** The path where the Soft-Index store keeps its data files for the Infinispan Soft-Index Cache Store. diff --git a/docs/user-guide/api-mediation/configuration-at-tls.md b/docs/user-guide/api-mediation/configuration-at-tls.md index 7b16b2dd00..ede1f3867c 100644 --- a/docs/user-guide/api-mediation/configuration-at-tls.md +++ b/docs/user-guide/api-mediation/configuration-at-tls.md @@ -1,7 +1,7 @@ # Configuring AT-TLS for API Mediation Layer -Review this article for descriptions of the configuration parameters required to make the Zowe API Mediation Layer work with AT-TLS, and security recommendations. +Review this article for descriptions of the configuration parameters required to make Zowe API Mediation Layer work with AT-TLS, and security recommendations. :::info Role: security administrator ::: @@ -35,7 +35,7 @@ If there is an outbound AT-TLS rule configured for the link between the API Gate :::caution Important security consideration -Configuring AT-TLS for the Zowe API Mediation Layer requires careful consideration of security settings, specifically as these settings apply to the Client Certificate authentication feature in Zowe API Mediation Layer components, as well as for onboarded services that support the x.509 client certificates authentication scheme. +Configuring AT-TLS for the Zowe API Mediation Layer requires careful consideration of security settings. These security settings apply to the Client Certificate authentication feature in Zowe API Mediation Layer components, as well as for onboarded services that support the x.509 client certificates authentication scheme. Outbound AT-TLS rules (i.e. to make a transparent https call through http) that are configured to send the server certificate should be limited to the services that __require__ service to service authentication. If an API ML-onboarded southbound service needs to support x.509 client certificate authentication, we recommend to use the integrated TLS handshake capabilities of API ML. Do not configure an outbound AT-TLS rule for these services. @@ -92,7 +92,10 @@ The `PortRange` of this inbound rule is taken from the list of API Mediation Lay - API Catalog: default port 7552 - Metrics Service: default port 7551 +:::important + Replace `ApimlKeyring` with the keyring configured for your installation. Follow [the SAF keyring instructions](../../getting-started/zowe-certificates-overview.md#saf-keyring) in the article _Zowe Certificates overview_ to configure keyrings for your Zowe instance. +::: Note the setting `HandshakeRole`. This setting applies to core services which authenticate through certificates with each other. This setting allows the API Gateway to receive and accept X.509 client certificates from API Clients. diff --git a/docs/user-guide/at-tls-configuration.md b/docs/user-guide/at-tls-configuration.md index 2eea36c0e8..f2fac3ee18 100644 --- a/docs/user-guide/at-tls-configuration.md +++ b/docs/user-guide/at-tls-configuration.md @@ -14,7 +14,7 @@ zowe: ### High Availability Setup -In a high availability setup where one LPAR (e.g., lpar1) is using AT-TLS and the second (e.g., lpar2) is not using AT-TLS, configure as follows: +In a high availability setup where one LPAR (e.g., lpar1) is using AT-TLS and the second LPAR (e.g., lpar2) is not using AT-TLS, configure the following parameters: ```yaml zowe: From bacc57a82d7aa5feb392880be8b6f986fc083baf Mon Sep 17 00:00:00 2001 From: achmelo Date: Tue, 21 May 2024 13:38:09 +0200 Subject: [PATCH 5/8] required role Signed-off-by: achmelo --- docs/user-guide/at-tls-configuration.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/user-guide/at-tls-configuration.md b/docs/user-guide/at-tls-configuration.md index 2eea36c0e8..77b0a95267 100644 --- a/docs/user-guide/at-tls-configuration.md +++ b/docs/user-guide/at-tls-configuration.md @@ -2,6 +2,9 @@ The communication server on z/OS provides functionality to encrypt HTTP communication for on-platform jobs. This functionality is referred to as Application Transparent Transport Layer Security (AT-TLS). +:::info Required roles: security administrator +::: + ## Configuration Parameters To enable AT-TLS for Zowe components, configure the following parameters: From fff1e3c103070ca35eb4c4ef9bb7c898a2b65ac1 Mon Sep 17 00:00:00 2001 From: achmelo Date: Tue, 21 May 2024 13:39:22 +0200 Subject: [PATCH 6/8] align with config update Signed-off-by: achmelo --- docs/user-guide/at-tls-configuration.md | 16 ++-------------- 1 file changed, 2 insertions(+), 14 deletions(-) diff --git a/docs/user-guide/at-tls-configuration.md b/docs/user-guide/at-tls-configuration.md index 77b0a95267..3953ead3b7 100644 --- a/docs/user-guide/at-tls-configuration.md +++ b/docs/user-guide/at-tls-configuration.md @@ -12,20 +12,8 @@ To enable AT-TLS for Zowe components, configure the following parameters: zowe: network: server: - attls: true -``` - -### High Availability Setup - -In a high availability setup where one LPAR (e.g., lpar1) is using AT-TLS and the second (e.g., lpar2) is not using AT-TLS, configure as follows: - -```yaml -zowe: - haInstances: - lpar1: - attls: true - lpar2: - attls: false + tls: + attls: true ``` ## Component-Specific Configuration From d7e8a43c023e560e4bf0ab25eeb81ed33b2ab3dd Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Wed, 22 May 2024 14:34:04 +0200 Subject: [PATCH 7/8] minor language refactoring Signed-off-by: Andrew Jandacek --- docs/user-guide/api-mediation/configuration-at-tls.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/user-guide/api-mediation/configuration-at-tls.md b/docs/user-guide/api-mediation/configuration-at-tls.md index ede1f3867c..50f248515b 100644 --- a/docs/user-guide/api-mediation/configuration-at-tls.md +++ b/docs/user-guide/api-mediation/configuration-at-tls.md @@ -1,7 +1,6 @@ # Configuring AT-TLS for API Mediation Layer - -Review this article for descriptions of the configuration parameters required to make Zowe API Mediation Layer work with AT-TLS, and security recommendations. +Review this article for descriptions of the configuration parameters required to make Zowe API Mediation Layer work with AT-TLS, including AT-TLS inbound and outbound rules, Using AT-TLS in high availability, and troubleshooting. Security recommendations are also provided. :::info Role: security administrator ::: @@ -23,12 +22,12 @@ Review this article for descriptions of the configuration parameters required to Support for AT-TLS was introduced in Zowe v1.24. In this early version, startup was not possible in some versions of Zowe. For full support, we recommend that you upgrade to v2.13 or a later version of Zowe. ::: -While API ML does not handle TLS on its own with AT-TLS enabled, API ML requires information about the server certificate that is defined in the AT-TLS rule. Esure that the server certificates provided by the AT-TLS layer are trusted in the configured Zowe keyring. Ideally, AT-TLS should be configured with the same Zowe keyring. +While API ML does not handle TLS on its own with AT-TLS enabled, API ML requires information about the server certificate that is defined in the AT-TLS rule. Ensure that the server certificates provided by the AT-TLS layer are trusted in the configured Zowe keyring. Ideally, AT-TLS should be configured with the same Zowe keyring. If there is an outbound AT-TLS rule configured for the link between the API Gateway and z/OSMF, set the `zowe.zOSMF.scheme` property to `http`. :::note Notes -* AT-TLS is supported in the API Cloud Gateway Mediation Layer component since version 2.17. +* AT-TLS is supported in the API Cloud Gateway Mediation Layer component beginning with version 2.17. * As the Gateway is a core component of API ML, other components that need to interact with the Gateway, such as Zowe ZLUX App Server, also require AT-TLS configuration. ::: @@ -92,10 +91,9 @@ The `PortRange` of this inbound rule is taken from the list of API Mediation Lay - API Catalog: default port 7552 - Metrics Service: default port 7551 -:::important +**Follow this step:** Replace `ApimlKeyring` with the keyring configured for your installation. Follow [the SAF keyring instructions](../../getting-started/zowe-certificates-overview.md#saf-keyring) in the article _Zowe Certificates overview_ to configure keyrings for your Zowe instance. -::: Note the setting `HandshakeRole`. This setting applies to core services which authenticate through certificates with each other. This setting allows the API Gateway to receive and accept X.509 client certificates from API Clients. From 13515ac5761074668ad95639ad9da314b5af97d9 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Wed, 22 May 2024 15:04:01 +0200 Subject: [PATCH 8/8] change title Signed-off-by: Andrew Jandacek --- docs/user-guide/at-tls-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/at-tls-configuration.md b/docs/user-guide/at-tls-configuration.md index 3953ead3b7..ab36c09d92 100644 --- a/docs/user-guide/at-tls-configuration.md +++ b/docs/user-guide/at-tls-configuration.md @@ -1,4 +1,4 @@ -# Configuring AT-TLS +# Enabling AT-TLS across your Zowe environment The communication server on z/OS provides functionality to encrypt HTTP communication for on-platform jobs. This functionality is referred to as Application Transparent Transport Layer Security (AT-TLS).