|
| 1 | +# Amazon Aurora Serverless V2 Primary to Secondary Global Database |
| 2 | +The pattern creates a serverless global database cluster enabling data replication from the primary to secondary cluster. The regional primary cluster contains a serverless db instance supporting both writes and reads. The regional secondary cluster contains a serverless db instance supporting only reads. In the unlikely event of a regional degradation or outage, the secondary region can be promoted to read and write capabilities in less than 1 minute. Also the pattern adopts the multiple stack capability of CDK to provision the resources across the primary and secondary regions. You can deploy each stack indvidually or deploy all the stacks using --all option. |
| 3 | + |
| 4 | +Learn more about this pattern at Serverless Land Patterns: << Add the live URL here >> |
| 5 | + |
| 6 | +Important: this application uses various AWS services and there are costs associated with these services after the Free Tier usage - please see the [AWS Pricing page](https://aws.amazon.com/pricing/) for details. You are responsible for any AWS costs incurred. No warranty is implied in this example. |
| 7 | + |
| 8 | +## Requirements |
| 9 | + |
| 10 | +* [Create an AWS account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html) if you do not already have one and log in. The IAM user that you use must have sufficient permissions to make necessary AWS service calls and manage AWS resources. |
| 11 | +* [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) installed and configured |
| 12 | +* [Git Installed](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) |
| 13 | +* [Node and NPM](https://nodejs.org/en/download/) installed. |
| 14 | +* [AWS CDK](https://docs.aws.amazon.com/cdk/latest/guide/cli.html) installed and configured |
| 15 | + |
| 16 | +## Deployment Instructions |
| 17 | + |
| 18 | +1. Create a new directory, navigate to that directory in a terminal and clone the GitHub repository: |
| 19 | + ``` |
| 20 | + git clone https://github.com/aws-samples/serverless-patterns |
| 21 | + ``` |
| 22 | +2. Change directory to the pattern directory: |
| 23 | + ``` |
| 24 | + cd aurora-serverless-global-db-cdk |
| 25 | + ``` |
| 26 | +3. Install dependencies: |
| 27 | + ``` |
| 28 | + npm install |
| 29 | + ``` |
| 30 | +4. Configure AWS CDK to bootstrap the AWS account, primary region and secondary region : |
| 31 | + ``` |
| 32 | + cdk bootstrap 111111111111/eu-west-1 |
| 33 | + cdk bootstrap 111111111111/eu-west-2 |
| 34 | + ``` |
| 35 | +5. From the command line, use AWS CDK to deploy the all the stacks synthesized: |
| 36 | + ``` |
| 37 | + cdk deploy --all |
| 38 | + ``` |
| 39 | + Alternatively you can also deploy each stack individually. From the command line, use AWS CDK to deploy each stack: |
| 40 | + ``` |
| 41 | + cdk deploy aurora-global-cluster |
| 42 | + cdk deploy primary-cluster |
| 43 | + cdk deploy secondary-cluster |
| 44 | + cdk deploy primary-test-app |
| 45 | + cdk deploy secondary-test-app |
| 46 | + ``` |
| 47 | +7. Note the outputs from the CDK deployment process. These contain the primary and secondary URLs which are used for testing. |
| 48 | +
|
| 49 | +## How it works |
| 50 | +
|
| 51 | +- The template in this pattern synthesizes five stacks for deployment using the multiple stack approach of CDK. |
| 52 | +- The first stack named aurora-global-cluster creates the Aurora Global Cluster. |
| 53 | +- The second stack named primary-cluster deploys the primary cluster with a serverless v2 instance in the primary region defined. |
| 54 | +- The third stack named secondary-cluster deploys the secondary cluster with a serverless v2 instance in the secondary region defined. |
| 55 | +- The fourth and fifth stack named primary-test-app and secondary-test-app deploys a fargate container with a nodejs app for testing the global database tables. |
| 56 | +- The primary cluster supports both write and read operations. The secondary cluster supports read operation only. |
| 57 | +- Once you deploy all the stacks, you have built a global database that automatically replicates data from the primary to the secondary region. |
| 58 | +
|
| 59 | +## Testing |
| 60 | +
|
| 61 | +Note down the primary-test-app.FargateServiceURL and secondary-test-app.FargateServiceURL values from the CDK output and update them in each of the test commands below. |
| 62 | +
|
| 63 | +1. Initialize the Global Database by creating a table |
| 64 | +
|
| 65 | + ``` |
| 66 | + curl primary-test-app.FargateServiceURL/init |
| 67 | + ``` |
| 68 | +
|
| 69 | + Expected Response : |
| 70 | + "Task table created.." |
| 71 | +
|
| 72 | +2. Write a task into the Primary Cluster |
| 73 | + ``` |
| 74 | + curl -X POST primary-test-app.FargateServiceURL/tasks -H 'Content-Type: application/json' -d '{"name":"Task1","status":"created"}' |
| 75 | + ``` |
| 76 | + Expected Response : Task added with ID: 1 |
| 77 | +3. Read the tasks from the Secondary cluster |
| 78 | + ``` |
| 79 | + curl secondary-test-app.FargateServiceURL/tasks |
| 80 | + ``` |
| 81 | + Expected Response : |
| 82 | + [{"id":1,"name":"Task1","status":"created"}] |
| 83 | +
|
| 84 | +4. Attempt to write a task into the Secondary cluster |
| 85 | + ``` |
| 86 | + curl -X POST secondary-test-app.FargateServiceURL/tasks -H 'Content-Type: application/json' -d '{"name":"Task1","status":"created"}' |
| 87 | + ``` |
| 88 | + Expected Response : error : cannot execute INSERT in a read-only transaction |
| 89 | + |
| 90 | + Note : You can enable Write forwarding feature to continue to use the Secondary cluster endpoint for write transactions as well. |
| 91 | +
|
| 92 | +5. You can also try to update and delete the task on the Primary cluster |
| 93 | + ``` |
| 94 | + curl -X PUT primary-test-app.FargateServiceURL/tasks/1 -H 'Content-Type: application/json' -d '{"name":"Task1","status":"in-progress"}' |
| 95 | +
|
| 96 | + curl -X DELETE primary-test-app.FargateServiceURL/tasks/1 |
| 97 | +
|
| 98 | + ``` |
| 99 | +6. Check if the task is deleted from the Secondary cluster |
| 100 | + ``` |
| 101 | + curl secondary-test-app.FargateServiceURL/tasks |
| 102 | + ``` |
| 103 | + Expected Response : |
| 104 | + [] |
| 105 | +
|
| 106 | +## Cleanup |
| 107 | + |
| 108 | +1. Delete the stack |
| 109 | + ``` |
| 110 | + cdk destroy --all |
| 111 | + ``` |
| 112 | +---- |
| 113 | +Copyright 2023 Amazon.com, Inc. or its affiliates. All Rights Reserved. |
| 114 | +
|
| 115 | +SPDX-License-Identifier: MIT-0 |
0 commit comments