There are two high level tasks.
- µApp : create your app using your favourite dev stack and toolchain. This should typically be in
./lib/workload/stateless/
- CDK : write up the deployment CDK Stack of your app
NOTE:
- We only have one CDK project at outer level of the Git repository root; i.e. a CDK project in TypeScript.
Either tasks (developing an app and/or cdk deployment constructs); we promote code reuse for some boilerplate and common best practise patterns. Please give time to read articles/concepts in the Reading
section below for developer background technical alignment. We also share knowledge-based (KB) discussion, revise and harmonise these high level technical concepts through our routine OrcaBus catchup meetings.
µApp = microservice app
Mac user: Option + M for the µ symbol
When integrating the microservice with a client, you might create a new Cognito app client ID. If this is the case, you
will need to add the new client ID to the AWS API Gateway setup to ensure the token generated by that Cognito app is
valid for use with the microservice API Gateway. Store this Cognito app ID in an SSM Parameter and pass the SSM
Parameter name in the cognitoApiGatewayConfig
constant file (./config/constants.ts
). Additionally, you may need to set
the appropriate CORS origin in the corsAllowOrigins
constant file to prevent any CORS errors in your client.
Reference on creating new Cognito App: https://github.com/umccr/infrastructure/tree/master/terraform/stacks/cognito_aai
You may also just simply use "native toolchain bootstrap" method. This could be the typical "getting started" of respective tool or framework. Some examples as follows.
cargo init
npx tsc --init
django-admin startproject
...
...
<etc>
The "skel" profile are one abstraction up; from the native toolchain application bootstrapping method; such that you help your peer developer to fast track with some boilerplate code and common setup; up to speed.
Think of; it is "the origin" of where your now very complex application to date in near future. Doing this way is optional. We may revise whether this skel approach is useful in the future iterations.
Q. My microservice app is an "AWS native app" with StepFunction and/or DynamoDB, then what?
A. That would mean it is just a CDK TypeScript construct code arrange under
./lib/workload/stateless/<your AWS native app>
directory as an infrastructure stateless component. In this case, you may leverage Localstack compose stack and/or chosen AWS SDK (e.g. Boto3/Python orawslocal
CLI in bash script) for local dev, mocking and unit testing purpose.
Since it is the single CDK Project, all CDK dependencies are managed centrally at package.json
at the Git repo project root and, the CDK CLI version is harmonised with localised Node.js execution through Yarn. With this way, every developer's local dev environment and, automation CodePipeline environment will have the same CDK version, enforced.
For example, to use https://docs.aws.amazon.com/solutions/latest/constructs/aws-cognito-apigateway-lambda.html
At project root, execute as follows:
yarn add @aws-solutions-constructs/aws-cognito-apigateway-lambda
Or, to remove:
yarn remove @aws-solutions-constructs/aws-cognito-apigateway-lambda
You are encouraged to use CDK with TypeScript.
In general the microservice application should be deployed as an independent stack. Having your CDK as a stack allow to deploy your microservice app without touching other microservices app.
Most probably you microservice stack should only create new stateless resources as most of the stateful part may already be provisioned from the shared stateful stack. For example, your application may need an RDS cluster for its database, but the shared stack has an existing RDS cluster that is intended to be used across microservices.
See README.md in the stateful shared stack for more detail.
Useful resources:
- https://docs.aws.amazon.com/solutions/latest/constructs/welcome.html
- https://serverlessland.com
- https://constructs.dev
- https://trello.com/c/KDVIxQfm/1407-orcabus-v1-capture-high-level-orcabus-design-tech-choices
- https://microservices.io/patterns/microservice-chassis.html
- https://docs.aws.amazon.com/whitepapers/latest/microservices-on-aws/microservices-on-aws.html
- https://www.google.com/search?q=mono+repo
- https://docs.aws.amazon.com/cdk/v2/guide/core_concepts.html
- https://www.google.com/search?q=cdk+stateful+stateless
- https://www.google.com/search?q=cdk+app+vs+stack+vs+construct