From 6f9fb833a34e86de26d7416a642df1d5b52029ee Mon Sep 17 00:00:00 2001 From: Pasindu Yeshan Date: Sun, 2 Jun 2024 23:32:49 +0530 Subject: [PATCH 1/4] Update deployment guide with instructions for AWS EC2 and Kubernetes membership schemes --- .../5.10.0/docs/setup/deployment-guide.md | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) diff --git a/en/identity-server/5.10.0/docs/setup/deployment-guide.md b/en/identity-server/5.10.0/docs/setup/deployment-guide.md index 92ba25fb9c..332c3b3ff2 100644 --- a/en/identity-server/5.10.0/docs/setup/deployment-guide.md +++ b/en/identity-server/5.10.0/docs/setup/deployment-guide.md @@ -251,6 +251,104 @@ WSO2 supports the following membership schemes for clustering consume this docker image to create a `Task Definition` and run a new `Service` or a `Task` on the `AWS ECS cluster` that you created. + + ??? tip "Click to see the instructions for AWS EC2 membership scheme" + + When WSO2 products are deployed in clustered mode on Amazon EC2 instances, it is recommended to use the AWS clustering mode. Open the `deployment.toml` file (stored in the `/repository/conf/` directory) and + do the following changes. + + 1. Apply the following configuration parameters and update the values for the server to enable AWS + clustering. + ```toml + [clustering] + membership_scheme = "aws" + domain = "wso2.carbon.domain" + local_member_host = "10.0.21.80" + local_member_port = "5701" + ``` + The port used for communicating cluster messages has to be any port number between 5701 and 5800. The + local member host must be set to the IP address bound to the network interface used for communicating + with other members in the group (private IP address of EC2 instance). + + 2. Apply the following parameters to update the values to configure clustering properties. + ```toml + [clustering.properties] + accessKey = "***" + secretKey = "***" + securityGroup = "security_group_name" + region = "us-east-1" + tagKey = "a_tag_key" + tagValue = "a_tag_value" + ``` + It's recommended to add all the nodes to the same security group. The AWS credentials and security + group depend on your configurations in the Amazon EC2 instance. The `tagKey` and `tagValue` are + optional and the rest of the above parameters are mandatory. + + 3. To provide specific permissions for creating an access key and secret key for only this AWS clustering attempt, use the custom policy block given below. + See the [AWS documentation](http://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_managed-policies.html) for details on how to add the custom IAM policy. + Attach this to the user account that will operate AWS clustering in your WSO2 IS. The access key and secret key can only be used to list EC2 instance details in the AWS account. + ```json + { "Version": "2012-10-17", + "Statement": + [ + { + "Effect": "Allow", + "Action": + [ + "ec2:DescribeAvailabilityZones", + "ec2:DescribeInstances" + ], + "Resource": [ "*" ] + } + ] + } + ``` + + ??? tip "Click to see the instructions for Kubernetes membership scheme" + When WSO2 IS nodes are deployed in clustered mode on Kubernetes, the Kubernetes Membership Scheme enables automatically discovering these servers. The Kubernetes Membership Scheme supports finding the pod IP + addresses using the Kubernetes API. + + - Configure the `/repository/conf/deployment.toml` file with the following configurations. + + | Parameter | Description | Example | + |-----------|---------------|-----------| + | `membershipScheme` | This is the membership scheme that will be used to manage the membership of nodes in a cluster. | `kubernetes` | + | `local_member_host` | This is the member's hostname or IP address. Set it to the pod's local IP address. | `172.17.0.2` | + | `local_member_port` | This is the TCP port used by this member and through which other members will contact this member. | `4000` | + | `KUBERNETES_NAMESPACE` | This is the Kubernetes Namespace in which the pods are deployed. | `wso2-is` | + | `KUBERNETES_SERVICES` | These are the Kubernetes Services that belong in the cluster. | `wso2is-service` | + + ```toml + [clustering] + membership_scheme = "kubernetes" + local_member_host = "172.17.0.2" + local_member_port = "4000" + + [clustering.properties] + KUBERNETES_NAMESPACE = "wso2-is" + KUBERNETES_SERVICES = "wso2is-service" + ``` + + - In order to retrieve the pod IP address information from the Kubernetes api server, the Kubernetes + membership scheme uses the pod's service account. Hence, the pods need to be associated with a service + account that has permission to read the "endpoints" resource. Make sure the role you bind has the following permissions. + ```toml + rules: + - apiGroups: [""] + verbs: ["get", "list"] + resources: ["endpoints"] + ``` + + - Optionally, a Kubernetes token or basic authentication can be used to authenticate with the Kubernetes api server. + The following properties can be set under `[clustering.properties]` accordingly. + - `KUBERNETES_API_SERVER`: This is the Kubernetes API endpoint,e.g., `http://172.17.8.101:8080`. Alternatively, an https endpoint can be set via `KUBERNETES_SERVICE_HOST` and + `KUBERNETES_SERVICE_PORT_HTTPS`. + - `KUBERNETES_SERVICE_HOST`: This is the Kubernetes API hostname or IP address, e.g., + `kuberneteshostname`. + - `KUBERNETES_SERVICE_PORT_HTTPS`: This is the Kubernetes API https listening port. This must be an + integer value. + - `KUBERNETES_API_SERVER_TOKEN`: This is the Kubernetes Master token for authentication (optional), + e.g., `yourkubernetestoken`. 2. Configure caching. From 506a81b0f1e8cf10f269e9d3d1dc2b5a9348f2f9 Mon Sep 17 00:00:00 2001 From: Pasindu Yeshan Date: Sun, 2 Jun 2024 23:38:17 +0530 Subject: [PATCH 2/4] refactor --- en/identity-server/5.10.0/docs/setup/deployment-guide.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/en/identity-server/5.10.0/docs/setup/deployment-guide.md b/en/identity-server/5.10.0/docs/setup/deployment-guide.md index 332c3b3ff2..ec9855f204 100644 --- a/en/identity-server/5.10.0/docs/setup/deployment-guide.md +++ b/en/identity-server/5.10.0/docs/setup/deployment-guide.md @@ -348,8 +348,7 @@ WSO2 supports the following membership schemes for clustering - `KUBERNETES_SERVICE_PORT_HTTPS`: This is the Kubernetes API https listening port. This must be an integer value. - `KUBERNETES_API_SERVER_TOKEN`: This is the Kubernetes Master token for authentication (optional), - e.g., `yourkubernetestoken`. - + e.g., `yourkubernetestoken`. 2. Configure caching. From 55e2619cea885bce0bccb283eb62a0fc8a6b3fe3 Mon Sep 17 00:00:00 2001 From: Pasindu Yeshan Date: Mon, 3 Jun 2024 23:11:11 +0530 Subject: [PATCH 3/4] Add note about k8 jar --- en/identity-server/5.10.0/docs/setup/deployment-guide.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/en/identity-server/5.10.0/docs/setup/deployment-guide.md b/en/identity-server/5.10.0/docs/setup/deployment-guide.md index ec9855f204..d2fda9cf9f 100644 --- a/en/identity-server/5.10.0/docs/setup/deployment-guide.md +++ b/en/identity-server/5.10.0/docs/setup/deployment-guide.md @@ -285,7 +285,7 @@ WSO2 supports the following membership schemes for clustering optional and the rest of the above parameters are mandatory. 3. To provide specific permissions for creating an access key and secret key for only this AWS clustering attempt, use the custom policy block given below. - See the [AWS documentation](http://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_managed-policies.html) for details on how to add the custom IAM policy. + See the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_managed-policies.html) for details on how to add the custom IAM policy. Attach this to the user account that will operate AWS clustering in your WSO2 IS. The access key and secret key can only be used to list EC2 instance details in the AWS account. ```json { "Version": "2012-10-17", @@ -305,9 +305,14 @@ WSO2 supports the following membership schemes for clustering ``` ??? tip "Click to see the instructions for Kubernetes membership scheme" - When WSO2 IS nodes are deployed in clustered mode on Kubernetes, the Kubernetes Membership Scheme enables automatically discovering these servers. The Kubernetes Membership Scheme supports finding the pod IP + When WSO2 IS nodes are deployed in clustered mode on Kubernetes, the Kubernetes Membership Scheme enables automatic discovery of these servers. The Kubernetes Membership Scheme supports finding the pod IP addresses using the Kubernetes API. + !!! note + We have updated clustering and adding the `kubernetes-membership-scheme-1.x.x.jar` is not required from update level **5.10.0.302** onwards (Updates 2.0 model). Additionally the usage of `membershipSchemeClassName` and `KUBERNETES_MASTER_SKIP_SSL_VERIFICATION` parameters are removed from the same update level onwards. See the instructions on [updating WSO2 products](https://updates.docs.wso2.com/en/latest/). + + - If not already present, download and copy the [kubernetes-membership-scheme-1.x.x.jar](https://github.com/wso2/kubernetes-common/tags) to the `/repository/components/dropins/` directory. + - Configure the `/repository/conf/deployment.toml` file with the following configurations. | Parameter | Description | Example | From 64dba22028be36765f3ad0ae994667f466c2ade0 Mon Sep 17 00:00:00 2001 From: Pasindu Yeshan Date: Thu, 6 Jun 2024 10:54:10 +0530 Subject: [PATCH 4/4] Add parameters --- en/identity-server/5.10.0/docs/setup/deployment-guide.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/en/identity-server/5.10.0/docs/setup/deployment-guide.md b/en/identity-server/5.10.0/docs/setup/deployment-guide.md index d2fda9cf9f..243a62ae60 100644 --- a/en/identity-server/5.10.0/docs/setup/deployment-guide.md +++ b/en/identity-server/5.10.0/docs/setup/deployment-guide.md @@ -309,7 +309,7 @@ WSO2 supports the following membership schemes for clustering addresses using the Kubernetes API. !!! note - We have updated clustering and adding the `kubernetes-membership-scheme-1.x.x.jar` is not required from update level **5.10.0.302** onwards (Updates 2.0 model). Additionally the usage of `membershipSchemeClassName` and `KUBERNETES_MASTER_SKIP_SSL_VERIFICATION` parameters are removed from the same update level onwards. See the instructions on [updating WSO2 products](https://updates.docs.wso2.com/en/latest/). + We have updated clustering and adding the `kubernetes-membership-scheme-1.x.x.jar` is not required from update level **5.10.0.302** onwards (Updates 2.0 model). Additionally the usage of `membershipSchemeClassName`, `KUBERNETES_MASTER_SKIP_SSL_VERIFICATION`, and `USE_DNS` parameters are removed from the same update level onwards. See the instructions on [updating WSO2 products](https://updates.docs.wso2.com/en/latest/). - If not already present, download and copy the [kubernetes-membership-scheme-1.x.x.jar](https://github.com/wso2/kubernetes-common/tags) to the `/repository/components/dropins/` directory. @@ -320,8 +320,11 @@ WSO2 supports the following membership schemes for clustering | `membershipScheme` | This is the membership scheme that will be used to manage the membership of nodes in a cluster. | `kubernetes` | | `local_member_host` | This is the member's hostname or IP address. Set it to the pod's local IP address. | `172.17.0.2` | | `local_member_port` | This is the TCP port used by this member and through which other members will contact this member. | `4000` | + | `membershipSchemeClassName` | This is the class name of the membership scheme. Use `org.wso2.carbon.membership.scheme.kubernetes.KubernetesMembershipScheme`. | `org.wso2.carbon.membership.scheme.kubernetes.KubernetesMembershipScheme` | | `KUBERNETES_NAMESPACE` | This is the Kubernetes Namespace in which the pods are deployed. | `wso2-is` | | `KUBERNETES_SERVICES` | These are the Kubernetes Services that belong in the cluster. | `wso2is-service` | + | `KUBERNETES_MASTER_SKIP_SSL_VERIFICATION` | This defines whether the SSL certificate verification of the Kubernetes API should be carried out or not. | `true` | + | `USE_DNS` | This configures the membership scheme to use Kubernetes API for pod IP resolution. Set this to false. | `false` | ```toml [clustering] @@ -330,8 +333,11 @@ WSO2 supports the following membership schemes for clustering local_member_port = "4000" [clustering.properties] + membershipSchemeClassName = "org.wso2.carbon.membership.scheme.kubernetes.KubernetesMembershipScheme" KUBERNETES_NAMESPACE = "wso2-is" KUBERNETES_SERVICES = "wso2is-service" + KUBERNETES_MASTER_SKIP_SSL_VERIFICATION = true + USE_DNS = false ``` - In order to retrieve the pod IP address information from the Kubernetes api server, the Kubernetes