Skip to content

Commit

Permalink
docs: update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@hpp222
hpp222 committed Oct 17, 2023
1 parent ea9b8df commit 6134911
Show file tree
Hide file tree
Showing 7 changed files with 174 additions and 120 deletions.
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ This is a solution for deploying [Keycloak](https://www.keycloak.org/) to AWS wi

## Quick start

* [Implementatio Guide](https://aws-samples.github.io/keycloak-on-aws/en/implementation-guide/deployment/)
* [Implementation Guide](https://aws-samples.github.io/keycloak-on-aws/en/implementation-guide/deployment/)

## License

Expand Down
77 changes: 45 additions & 32 deletions docs/en/implementation-guide/considerations.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,38 +2,51 @@
## Regional deployments
This solution uses services which may not be currently available in all AWS Regions. Launch this solution in an AWS Region where required services are available. For the most current availability by Region, refer to the [AWS Regional Services List][services].

Because the solution has Amazon Aurora MySQL-Compatible and Amazon Aurora Serverless MySQL-Compatible to choose from, when deploying with CloudFormation, you need to check whether the region supports Amazon Aurora Serverless MySQL-Compatible or Amazon Aurora MySQL-Compatible.

**Supported regions for deployment in AWS Global Regions**

| Region ID | Region Name | Amazon Aurora MySQL-Compatible | Amazon Aurora Serverless MySQL-Compatible |
| -------------- | ------------------------ | :------------: | :----------------------: |
| us-east-1 | US East (N. Virginia) | ✔ | ✔ |
| us-east-2 | US East (Ohio) | ✔ | ✔ |
| us-west-1 | US West (N. California) | ✔ | ✔ |
| us-west-2 | US West (Oregon) | ✔ | ✔ |
| af-south-1 | Asia (Cape Town) | ✔ | - |
| ap-south-1 | Asia Pacific (Mumbai) | ✔ | ✔ |
| ap-northeast-3 | Asia Pacific (Osaka) | ✔ | - |
| ap-northeast-2 | Asia Pacific (Seoul) | ✔ | ✔ |
| ap-southeast-1 | Asia Pacific (Singapore) | ✔ | ✔ |
| ap-southeast-2 | Asia Pacific (Sydney) | ✔ | ✔ |
| ap-northeast-1 | Asia Pacific (Tokyo) | ✔ | ✔ |
| ca-central-1 | Canada (Central) | ✔ | ✔ |
| eu-central-1 | Europe (Frankfurt) | ✔ | ✔ |
| eu-west-1 | Europe (Ireland) | ✔ | ✔ |
| eu-west-2 | Europe (London) | ✔ | ✔ |
| eu-west-3 | Europe (Paris) | ✔ | ✔ |
| eu-north-1 | Europe (Stockholm) | ✔ | - |
| sa-east-1 | South America (Sao Paulo)| ✔ | - |


**Supported regions for deployment in AWS China Regions**

| Region ID | Region Name | Amazon Aurora MySQL-Compatible | Amazon Aurora Serverless MySQL-Compatible |
| -------------- | ----------------------------------------- | :------------: | :----------------------: |
| cn-north-1 | China (Beijing) Region Operated by Sinnet | ✔ | - |
| cn-northwest-1 | China (Ningxia) Region Operated by NWCD | ✔ | ✔ |
Because the solution has Amazon Aurora MySQL-Compatible, Amazon Aurora Serverless v1 MySQL-Compatible and Amazon Aurora Serverless v2 MySQL-Compatible to choose from, when deploying with CloudFormation, you need to check whether the region supports your choice.

For Aurora Serverless deployments, Aurora Serverless v2 MySQL-Compatible is provided by default in the CloudFormation templates. Aurora Serverless v2 scales more quickly and in a more granular way and also has more compatibility with other Aurora features such as reader DB instances. For more information, see [Comparison of Aurora Serverless v2 and Aurora Serverless v1 requirements][comparisons].

**Supported regions for database deployment in AWS Global Regions**

| Region ID | Region Name | Amazon Aurora MySQL-Compatible | Amazon Aurora Serverless v1 MySQL-Compatible |Amazon Aurora Serverless v2 MySQL-Compatible |
| -------------- | ------------------------ | :------------: | :----------------------: | :----------------------: |
| us-east-1 | US East (N. Virginia) | ✔ | ✔ | ✔ |
| us-east-2 | US East (Ohio) | ✔ | ✔ | ✔ |
| us-west-1 | US West (N. California) | ✔ | ✔ | ✔ |
| us-west-2 | US West (Oregon) | ✔ | ✔ | ✔ |
| af-south-1 | Africa (Cape Town) | ✔ | | ✔ |
| ap-east-1 | Asia Pacific (Hongkong) | ✔ | | ✔ |
| ap-south-2 | Asia Pacific (Hyderabad) | ✔ | | ✔ |
| ap-southeast-3 | Asia Pacific (Jakarta) | ✔ | | ✔ |
| ap-southeast-4 | Asia Pacific (Melbourne) | ✔ | | ✔ |
| ap-south-1 | Asia Pacific (Mumbai) | ✔ | ✔ | ✔ |
| ap-northeast-3 | Asia Pacific (Osaka) | ✔ | | ✔ |
| ap-northeast-2 | Asia Pacific (Seoul) | ✔ | ✔ | ✔ |
| ap-southeast-1 | Asia Pacific (Singapore) | ✔ | ✔ | ✔ |
| ap-southeast-2 | Asia Pacific (Sydney) | ✔ | ✔ | ✔ |
| ap-northeast-1 | Asia Pacific (Tokyo) | ✔ | ✔ | ✔ |
| ca-central-1 | Canada (Central) | ✔ | ✔ | ✔ |
| eu-central-1 | Europe (Frankfurt) | ✔ | ✔ | ✔ |
| eu-west-1 | Europe (Ireland) | ✔ | ✔ | ✔ |
| eu-west-2 | Europe (London) | ✔ | ✔ | ✔ |
| eu-south-1 | Europe (Milan) | ✔ | | ✔ |
| eu-west-3 | Europe (Paris) | ✔ | ✔ | ✔ |
| eu-south-2 | Europe (Spain) | ✔ | | ✔ |
| eu-north-1 | Europe (Stockholm) | ✔ | | ✔ |
| eu-central-2 | Europe (Zurich) | ✔ | | ✔ |
| il-central-1 | Israel (Tel Aviv) | ✔ | | ✔ |
| me-south-1 | Middle East (Bahrain) | ✔ | | ✔ |
| me-central-1 | Middle East (UAE) | ✔ | | ✔ |
| sa-east-1 | South America (Sao Paulo)| ✔ | | ✔ |


**Supported regions for database deployment in AWS China Regions**

| Region ID | Region Name | Amazon Aurora MySQL-Compatible | Amazon Aurora Serverless v1 MySQL-Compatible |Amazon Aurora Serverless v2 MySQL-Compatible |
| -------------- | ----------------------------------------- | :------------: | :----------------------: | :----------------------: |
| cn-north-1 | China (Beijing) Region Operated by Sinnet | ✔ | | ✔ |
| cn-northwest-1 | China (Ningxia) Region Operated by NWCD | ✔ | ✔ | ✔ |


[services]: https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/?nc1=h_ls
[comparisons]: https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-serverless-v2.upgrade.html#Serverless.v1-v2-requirements
72 changes: 44 additions & 28 deletions docs/en/implementation-guide/deployment.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Before you launch the solution, review the architecture, supported regions, and

Make sure you have the following in the target region you want to deploy the solution:

- the domain name has been recorded by ICP and used to apply for ACM certificate.
- for deployments in China region, the domain name has been recorded by ICP and used to apply for ACM certificate.
- the certificate of the domain name is created in ACM and verified by the domain name.
- VPC with 4 subnets (including two public subnets and two private subnets) and NAT Gateway.
- all the AWS Services listed in [required AWS Services](./additional-resources.md) are available.
Expand Down Expand Up @@ -82,6 +82,9 @@ Add a CNAME record to Route 53 to authenticate that the domain name is owned and

You have 4 different options to launch the stack.

For Aurora Serverless deployments, Aurora Serverless v2 MySQL-Compatible is provided by default in the CloudFormation templates. For more information, see [Comparison of Aurora Serverless v2 and Aurora Serverless v1 requirements][comparisons].


| Option | VPC | Database | Quick Launch | Template Link |
| :--- | --- | ----- | :--------: | :-----: |
| <a href="#step-3-1-keycloak-aurora-serveless-from-existing-vpc">Option 1: Deploy Keycloak based on Aurora Serverless MySQL-Compatible from an existing VPC</a> | Existing | Aurora Serverless MySQL-Compatible | [Global][Keycloak aurora serveless from existing VPC for Global] </br> [China][Keycloak aurora serveless from existing VPC for China] | [Download][Keycloak aurora serverless from existing VPC template] |
Expand All @@ -107,14 +110,17 @@ You have 4 different options to launch the stack.
6. On the **Step 2 Specify stack details** section, do the following:
1. **Stack name**: A stack name, such as *KeycloakOnAWS*.
2. **CertificateArn**: Enter the **ARN** recorded in [Step 1. Create ACM certificate](#step-1-create-acm-certificate), such as *arn:aws:acm:us-west-2:1436237113227:certificate/571518b3-123b-4502-1ec3-3t2sae704272*.
3. **VpcId**: Select from existing VPCs.
4. **PubSubnets**: Select public subnets for ALB deployment.
5. **PrivSubnets**: Select the private subnet for the ECS Task.
6. **DBSubnets**: Select the private subnet for the database.
7. **MinContainers**: Customize the minimum number of containers for the ECS, with a minimum value of 2.
8. **MaxContainers**: Customize the maximum number of containers for the ECS, with a maximum value of 10.
9. **AutoScalingTargetCpuUtilization**: The percentage of resource utilization that is ensured to be no higher, maximum 100.
10. **JavaOpts**: JAVA_OPTS environment variable.
3. **Hostname**: Enter domain name for your Keycloak server.
4. **VpcId**: Select from existing VPCs.
5. **PubSubnets**: Select public subnets for ALB deployment.
6. **PrivSubnets**: Select the private subnet for the ECS Task.
7. **DBSubnets**: Select the private subnet for the database.
8. **TaskCPU**: Specify the CPU for the Fargate Task running your keycloak application. The default value is 4096 (4 vCPU). See [Task CPU and memory][task cpu and memory] for details.
9. **TaskMemory**: Specify the Memory for the Fargate Task running your keycloak application. The default value is 8192 MiB (8 GB). Please note that this value must be within the range allowed by the TaskCPU you select. See [Task CPU and memory][task cpu and memory] for details.
8. **MinContainers**: Customize the minimum number of containers for the ECS, with a minimum value of 2.
9. **MaxContainers**: Customize the maximum number of containers for the ECS, with a maximum value of 10.
10. **AutoScalingTargetCpuUtilization**: The percentage of resource utilization that is ensured to be no higher, maximum 100.
11. **JavaOpts**: JAVA_OPTS environment variable.

7. Choose **Next**.

Expand Down Expand Up @@ -144,10 +150,13 @@ You have 4 different options to launch the stack.
6. On the **Step 2 Specify stack details** section, do the following:
1. **Stack name**: A stack name, such as *KeycloakOnAWS*.
2. **CertificateArn**: Enter the **ARN** recorded in [Step 1. Create ACM certificate](#step-1-create-acm-certificate), such as *arn:aws:acm:us-west-2:1436237113227:certificate/571518b3-123b-4502-1ec3-3t2sae704272*.
3. **MinContainers**: Customize the minimum number of containers for the ECS, with a minimum value of 2.
4. **MaxContainers**: Customize the maximum number of containers for the ECS, with a maximum value of 10.
5. **AutoScalingTargetCpuUtilization**: The percentage of resource utilization that is ensured to be no higher, maximum 100.
6. **JavaOpts**: JAVA_OPTS environment variable.
3. **Hostname**: Enter domain name for your Keycloak server.
4. **TaskCPU**: Specify the CPU for the Fargate Task running your keycloak application. The default value is 4096 (4 vCPU). See [Task CPU and memory][task cpu and memory] for details.
5. **TaskMemory**: Specify the Memory for the Fargate Task running your keycloak application. The default value is 8192 MiB (8 GB). Please note that this value must be within the range allowed by the TaskCPU you select. See [Task CPU and memory][task cpu and memory] for details.
6. **MinContainers**: Customize the minimum number of containers for the ECS, with a minimum value of 2.
7. **MaxContainers**: Customize the maximum number of containers for the ECS, with a maximum value of 10.
8. **AutoScalingTargetCpuUtilization**: The percentage of resource utilization that is ensured to be no higher, maximum 100.
9. **JavaOpts**: JAVA_OPTS environment variable.

7. Choose **Next**.

Expand Down Expand Up @@ -177,15 +186,18 @@ You have 4 different options to launch the stack.
6. On the **Step 2 Specify stack details** section, do the following:
1. **Stack name**: A stack name, such as *KeycloakOnAWS*.
2. **CertificateArn**: Enter the **ARN** recorded in [Step 1. Create ACM certificate](#step-1-create-acm-certificate), such as *arn:aws:acm:us-west-2:1436237113227:certificate/571518b3-123b-4502-1ec3-3t2sae704272*.
3. **DatabaseInstanceType**: Select the RDS instance type.
4. **VpcId**: Select from existing VPCs.
5. **PubSubnets**: Select public subnets for ALB deployment.
6. **PrivSubnets**: Select the private subnet for the ECS Task.
7. **DBSubnets**: Select the private subnet for the RDS database.
8. **MinContainers**: Customize the minimum number of containers for the ECS, with a minimum value of 2.
9. **MaxContainers**: Customize the maximum number of containers for the ECS, with a maximum value of 10.
10. **AutoScalingTargetCpuUtilization**: The percentage of resource utilization that is ensured to be no higher, maximum 100.
11. **JavaOpts**: JAVA_OPTS environment variable.
3. **Hostname**: Enter domain name for your Keycloak server.
4. **DatabaseInstanceType**: Select the RDS instance type.
5. **VpcId**: Select from existing VPCs.
6. **PubSubnets**: Select public subnets for ALB deployment.
7. **PrivSubnets**: Select the private subnet for the ECS Task.
8. **DBSubnets**: Select the private subnet for the RDS database.
9. **TaskCPU**: Specify the CPU for the Fargate Task running your keycloak application. The default value is 4096 (4 vCPU). See [Task CPU and memory][task cpu and memory] for details.
10. **TaskMemory**: Specify the Memory for the Fargate Task running your keycloak application. The default value is 8192 MiB (8 GB). Please note that this value must be within the range allowed by the TaskCPU you select. See [Task CPU and memory][task cpu and memory] for details.
11. **MinContainers**: Customize the minimum number of containers for the ECS, with a minimum value of 2.
10. **MaxContainers**: Customize the m2ximum number of containers for the ECS, with a maximum value of 10.
13. **AutoScalingTargetCpuUtilization**: The percentage of resource utilization that is ensured to be no higher, maximum 100.
14. **JavaOpts**: JAVA_OPTS environment variable.

7. Choose **Next**.

Expand Down Expand Up @@ -215,11 +227,14 @@ You have 4 different options to launch the stack.
6. On the **Step 2 Specify stack details** section, do the following:
1. **Stack name**: A stack name, such as *KeycloakOnAWS*.
2. **CertificateArn**: Enter the **ARN** recorded in [Step 1. Create ACM certificate](#step-1-create-acm-certificate), such as *arn:aws:acm:us-west-2:1436237113227:certificate/571518b3-123b-4502-1ec3-3t2sae704272`*.
3. **DatabaseInstanceType**: Select the RDS instance type.
4. **MinContainers**: Customize the minimum number of containers for the ECS, with a minimum value of 2.
5. **MaxContainers**: Customize the maximum number of containers for the ECS, with a maximum value of 10.
6. **AutoScalingTargetCpuUtilization**: The percentage of resource utilization that is ensured to be no higher, maximum 100.
7. **JavaOpts**: JAVA_OPTS environment variable.
3. **Hostname**: Enter domain name for your Keycloak server.
4. **DatabaseInstanceType**: Select the RDS instance type.
5. **TaskCPU**: Specify the CPU for the Fargate Task running your keycloak application. The default value is 4096 (4 vCPU). See [Task CPU and memory][task cpu and memory] for details.
6. **TaskMemory**: Specify the Memory for the Fargate Task running your keycloak application. The default value is 8192 MiB (8 GB). Please note that this value must be within the range allowed by the TaskCPU you select. See [Task CPU and memory][task cpu and memory] for details.
7. **MinContainers**: Customize the minimum number of containers for the ECS, with a minimum value of 2.
8. **MaxContainers**: Customize the maximum number of containers for the ECS, with a maximum value of 10.
9. **AutoScalingTargetCpuUtilization**: The percentage of resource utilization that is ensured to be no higher, maximum 100.
10. **JavaOpts**: JAVA_OPTS environment variable.

7. Choose **Next**.

Expand Down Expand Up @@ -305,4 +320,5 @@ You have 4 different options to launch the stack.
[Keycloak aurora serverless from new VPC template]: https://aws-gcr-solutions.s3.cn-north-1.amazonaws.com.cn/keycloakonaws/latest/keycloak-aurora-serverless-from-new-vpc.template
[Keycloak from existing VPC template]: https://aws-gcr-solutions.s3.cn-north-1.amazonaws.com.cn/keycloakonaws/latest/keycloak-from-existing-vpc.template
[Keycloak from new VPC template]: https://aws-gcr-solutions.s3.cn-north-1.amazonaws.com.cn/keycloakonaws/latest/keycloak-from-new-vpc.template

[comparisons]: https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-serverless-v2.upgrade.html#Serverless.v1-v2-requirements
[task cpu and memory]: https://docs.aws.amazon.com/zh_cn/AmazonECS/latest/userguide/fargate-task-defs.html#fargate-tasks-size
2 changes: 1 addition & 1 deletion docs/en/implementation-guide/revisions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,5 @@

| Date | Description |
| ------------ | :------------------------------ |
| July 2022 | Release 2.1.0 <br> 1. Upgrade Keycloak to version 16.1.1 <br> 2. Upgrade aws-cdk to version 1.160.0 <br> 3. Upgrade cdk-keycloak to version 0.2.41 |
| Oct 2023 | Release 2.1.6 <br> 1. Upgrade Keycloak to version 22.0.4 <br> 2. Upgrade aws-cdk to version 2.100.0 <br> 3. Upgrade cdk-keycloak to version 2.9.0 |

Loading

0 comments on commit 6134911

Please sign in to comment.