document CDK deployment

Author: c-wygoda

.github/actions/cdk-deploy/action.yml

@@ -1,15 +1,20 @@
 name: run cdk deploy
 description: deploy example to AWS using CDK
 inputs:
-  AWS_SECRET_ACCESS_KEY:
-    required: true
   AWS_ACCESS_KEY_ID:
+    description: AWS access key id to use
+    required: true
+  AWS_SECRET_ACCESS_KEY:
+    description: AWS secret access key to use
     required: true
   AWS_ECR_REPOSITORY_ARN:
+    description: AWS ECR repository to pull docker image from
     required: true
   IMAGE_TAG_OR_DIGEST:
+    description: docker image tag or digest to pull
     required: true
   BACKEND_NAME:
+    description: STAPI-FastAPI backend implementation to use
     required: true
 
 runs:
@@ -22,7 +27,7 @@ runs:
       shell: bash
     - run: poetry run cdk deploy --require-approval=never
       shell: bash
-      working-directory: deployment
+      working-directory: deploy_cdk
       env:
         AWS_SECRET_ACCESS_KEY: ${{ inputs.AWS_SECRET_ACCESS_KEY }}
         AWS_ACCESS_KEY_ID: ${{ inputs.AWS_ACCESS_KEY_ID }}

.gitignore

@@ -1,12 +1,10 @@
+__pycache__
+.env
+.idea
+.python-version
+.venv
+.vscode
 *.sqlite
 /.coverage
 /.pytest_cache
 /.ruff_cache
-
-# python
-.python-version
-.venv
-__pycache__
-.env
-
-.idea

DEPLOYMENT.md

@@ -0,0 +1,44 @@
+# Deployment
+
+This repository provides a [AWS Cloud Development Kit][cdk] based deployment.
+
+## Architecture
+
+The deployment consists of an AWS Lambda behind an AWS API Gateway. The Lambda is using a Docker image for the service code, which must be pulled from an AWS ECR.
+
+The CDK deployment code is _not_ managing the ECR, please provide it yourself.
+
+```
+API Gateway -> Lambda -> Container Registry
+```
+
+## Prerequisites
+
+- AWS CDK CLI
+- AWS ECR with Docker image
+
+## Deploying
+
+### Configuration
+
+Configuration is managed via environment variables:
+
+- MEMORY: Lambda memory in megabytes, defaults to `1024`
+- TIMEOUT: Lambda timeout in seconds, defaults to `30`
+- AWS_ECR_REPOSITORY_ARN: ARN of the ECR to pull from
+- IMAGE_TAG_OR_DIGEST: Docker tag or digest to pull from ECR, defaults to `latest`
+- BACKEND_NAME: Backend name to use in service, defaults to `landsat`
+
+As well, CDK will need an AWS profile to be configured.
+
+### Execution
+
+Having set up the configuration env vars as required, execute the CDK deployment with
+
+```
+poetry run cdk deploy
+```
+
+This will create a new CloudFormation stack named after the `BACKEND_NAME` configured, i.e. `StapiLandsatBackend`.
+
+[cdk]: https://docs.aws.amazon.com/cdk/

deployment/.gitignore deploy_cdk/.gitignoredeployment/.gitignore renamed to deploy_cdk/.gitignore

@@ -6,7 +6,7 @@
 from aws_cdk.aws_ecr import Repository
 from constructs import Construct
 
-from deployment.profile import DeploymentProfile
+from deploy_cdk.profile import DeploymentProfile
 
 
 class LambdaService(Construct):
@@ -49,7 +49,7 @@ def __init__(self, scope: Construct, id: str, profile: DeploymentProfile) -> Non
         )
 
 
-class STATDeploy(Stack):
+class StapiStack(Stack):
     def __init__(
         self,
         scope: Construct,
@@ -65,7 +65,7 @@ def __init__(
 def main():
     app = App()
     profile = DeploymentProfile()
-    STATDeploy(app, f"Stat{profile.backend_name.capitalize()}Backend", profile)
+    StapiStack(app, f"Stapi{profile.backend_name.capitalize()}Backend", profile)
     app.synth()