feat: Add AWS CDK deployment (#44)

This adds an AWS CDK (Python) application that can be used to deploy a
stac-fastapi-geoparquet
application to a Lambda function with an HTTP API.

Remaining tasks:
- [x] Pick an AWS account to deploy this in
- [x] Set up OIDC role for Github Actions (if not already done)
- [x] Set the role arn in ci.yml

Stretch goals
- [ ] See if there is a better way to do IP-based throttling

@alukach @zacdezgeo is there a particular AWS account you suggest using?
Maybe `Development Seed - Main`?

Resolves #9

---------

Co-authored-by: Pete Gadomski <[email protected]>

Author: hrodmn

.github/workflows/ci.yml

@@ -5,6 +5,9 @@ on:
     branches:
       - main
   pull_request:
+  workflow_dispatch:
+  release:
+    types: [published]
 
 jobs:
   lint-and-test:
@@ -23,3 +26,58 @@ jobs:
         run: scripts/test
       - name: Validate
         run: scripts/validate
+
+  deploy:
+    name: Deploy
+    needs: [lint-and-test]
+    permissions:
+      id-token: write
+      contents: read
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
+    env:
+      STACK_NAME: stac-fastapi-geoparquet-labs-375
+      STACK_STAGE: dev
+      STACK_OWNER: labs-375
+      STACK_RELEASE: ${{ github.event.release.tag_name }}
+      STACK_BUCKET_NAME: stac-fastapi-geoparquet-devseed
+      STACK_GEOPARQUET_KEY: naip.parquet
+      STACK_RATE_LIMIT: 10
+  
+    defaults:
+      run:
+        working-directory: infrastructure/aws
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v2
+        with:
+          role-to-assume: arn:aws:iam::390960605471:role/labs-375-stac-fastapi-geoparquet-github-actions 
+          role-session-name: stac-fastapi-geoparquet-deploy
+          aws-region: us-east-1
+
+      - name: Set up node
+        uses: actions/setup-node@v2
+        with:
+          node-version: 22
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: |
+          uv sync --only-group deploy
+          uv run --only-group deploy npm install
+
+      - name: CDK Synth
+        run: uv run --only-group deploy npm run cdk -- synth
+      
+      - name: CDK Deploy
+        run: |
+          uv run --only-group deploy npm run cdk -- deploy --require-approval never
+          aws s3 cp ../../data/naip.parquet s3://${STACK_BUCKET_NAME}/${STACK_GEOPARQUET_KEY}
+          
+          API_URL=$(aws cloudformation describe-stacks --stack-name ${STACK_NAME}-${STACK_STAGE} --query 'Stacks[0].Outputs[?OutputKey==`ApiURL`].OutputValue' --output text)
+          echo "::notice title=API URL::${API_URL}"

.gitignore

@@ -172,3 +172,10 @@ cython_debug/
 # PyPI configuration file
 .pypirc
 .vscode/
+
+# AWS deployment
+infrastructure/aws/node_modules/
+infrastructure/aws/cdk.out/
+infrastructure/aws/.env
+infrastructure/aws/cdk-outputs.json
+

infrastructure/aws/.env.local

@@ -0,0 +1,7 @@
+STACK_NAME=stac-fastapi-geoparquet-test
+STACK_STAGE=test
+STACK_OWNER=hrodmn
+STACK_RELEASE=dev
+STACK_BUCKET_NAME=stac-fastapi-geoparquet-test
+STACK_GEOPARQUET_KEY=naip.parquet
+STACK_RATE_LIMIT=50

infrastructure/aws/__init__.py

@@ -0,0 +1,161 @@
+"""AWS CDK application for the stac-fastapi-geoparquet Stack
+
+Generates a Lambda function with an API Gateway trigger and an S3 bucket.
+
+After deploying the stack you will need to make sure the geoparquet file
+specified in the config gets uploaded to the bucket associated with this stack!
+"""
+
+import os
+from typing import Any
+
+from aws_cdk import (
+    App,
+    CfnOutput,
+    Duration,
+    RemovalPolicy,
+    Stack,
+    Tags,
+)
+from aws_cdk.aws_apigatewayv2 import HttpApi, HttpStage, ThrottleSettings
+from aws_cdk.aws_apigatewayv2_integrations import HttpLambdaIntegration
+from aws_cdk.aws_iam import AnyPrincipal, Effect, PolicyStatement
+from aws_cdk.aws_lambda import Code, Function, Runtime
+from aws_cdk.aws_logs import RetentionDays
+from aws_cdk.aws_s3 import BlockPublicAccess, Bucket
+from aws_cdk.custom_resources import (
+    AwsCustomResource,
+    AwsCustomResourcePolicy,
+    AwsSdkCall,
+    PhysicalResourceId,
+)
+from config import Config
+from constructs import Construct
+
+
+class StacFastApiGeoparquetStack(Stack):
+    def __init__(
+        self,
+        scope: Construct,
+        construct_id: str,
+        config: Config,
+        runtime: Runtime = Runtime.PYTHON_3_12,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(scope, construct_id, **kwargs)
+
+        for key, value in config.tags.items():
+            Tags.of(self).add(key, value)
+
+        bucket = Bucket(
+            scope=self,
+            id="bucket",
+            bucket_name=config.bucket_name,
+            versioned=True,
+            removal_policy=RemovalPolicy.RETAIN
+            if config.stage != "test"
+            else RemovalPolicy.DESTROY,
+            public_read_access=True,
+            block_public_access=BlockPublicAccess(
+                block_public_acls=False,
+                block_public_policy=False,
+                ignore_public_acls=False,
+                restrict_public_buckets=False,
+            ),
+        )
+
+        # make the bucket public, requester-pays
+        bucket.add_to_resource_policy(
+            PolicyStatement(
+                actions=["s3:GetObject"],
+                resources=[bucket.arn_for_objects("*")],
+                principals=[AnyPrincipal()],
+                effect=Effect.ALLOW,
+            )
+        )
+
+        add_request_pay = AwsSdkCall(
+            action="putBucketRequestPayment",
+            service="S3",
+            region=self.region,
+            parameters={
+                "Bucket": bucket.bucket_name,
+                "RequestPaymentConfiguration": {"Payer": "Requester"},
+            },
+            physical_resource_id=PhysicalResourceId.of(bucket.bucket_name),
+        )
+
+        aws_custom_resource = AwsCustomResource(
+            self,
+            "RequesterPaysCustomResource",
+            policy=AwsCustomResourcePolicy.from_sdk_calls(
+                resources=[bucket.bucket_arn]
+            ),
+            on_create=add_request_pay,
+            on_update=add_request_pay,
+        )
+
+        aws_custom_resource.node.add_dependency(bucket)
+
+        CfnOutput(self, "BucketName", value=bucket.bucket_name)
+
+        api_lambda = Function(
+            scope=self,
+            id="lambda",
+            runtime=runtime,
+            handler="handler.handler",
+            memory_size=config.memory,
+            log_retention=RetentionDays.ONE_WEEK,
+            timeout=Duration.seconds(config.timeout),
+            code=Code.from_docker_build(
+                path=os.path.abspath("../.."),
+                file="infrastructure/aws/lambda/Dockerfile",
+                build_args={
+                    "PYTHON_VERSION": runtime.to_string().replace("python", ""),
+                },
+            ),
+            environment={
+                "STAC_FASTAPI_GEOPARQUET_HREF": f"s3://{bucket.bucket_name}/{config.geoparquet_key}",
+                "HOME": "/tmp",  # for duckdb's home_directory
+            },
+        )
+
+        bucket.grant_read(api_lambda)
+
+        api = HttpApi(
+            scope=self,
+            id="api",
+            default_integration=HttpLambdaIntegration(
+                "api-integration",
+                handler=api_lambda,
+            ),
+            default_domain_mapping=None,  # TODO: enable custom domain name
+            create_default_stage=False,  # Important: disable default stage creation
+        )
+
+        stage = HttpStage(
+            self,
+            "api-stage",
+            http_api=api,
+            auto_deploy=True,
+            stage_name="$default",
+            throttle=ThrottleSettings(
+                rate_limit=config.rate_limit,
+                burst_limit=config.rate_limit * 2,
+            )
+            if config.rate_limit
+            else None,
+        )
+
+        assert stage.url
+        CfnOutput(self, "ApiURL", value=stage.url)
+
+
+app = App()
+config = Config()
+StacFastApiGeoparquetStack(
+    app,
+    config.stack_name,
+    config=config,
+)
+app.synth()

infrastructure/aws/app.py

@@ -0,0 +1,3 @@
+{
+  "app": "python3 app.py"
+}

infrastructure/aws/cdk.json

@@ -0,0 +1,62 @@
+"""STACK Configs."""
+
+from typing import Annotated, Optional
+
+from pydantic import field_validator
+from pydantic_settings import BaseSettings
+
+
+class Config(BaseSettings):
+    """Application settings"""
+
+    name: str = "stac-fastapi-geoparquet"
+    stage: str = "dev"
+    owner: str = "labs-375"  # Add owner field for tracking
+    project: str = "stac-fastapi-geoparquet"  # Add project field for tracking
+    release: str = "dev"
+
+    bucket_name: str = "stac-fastapi-geoparquet"
+    geoparquet_key: Annotated[
+        Optional[str], "storage key for the geoparquet file within the S3 bucket"
+    ] = None
+
+    timeout: int = 30
+    memory: int = 3009
+
+    # The maximum of concurrent executions you want to reserve for the function.
+    # Default: - No specific limit - account limit.
+    max_concurrent: Optional[int] = None
+
+    # rate limiting settings
+    rate_limit: Annotated[
+        Optional[int],
+        "maximum average requests per second over an extended period of time",
+    ] = 10
+
+    @field_validator("geoparquet_key")
+    def validate_geoparquet_key(cls, v: str | None) -> str:
+        if v is None:
+            raise ValueError("geoparquet_key must be provided")
+        return v
+
+    @property
+    def stack_name(self) -> str:
+        """Generate consistent resource prefix."""
+        return f"{self.name}-{self.stage}"
+
+    @property
+    def tags(self) -> dict[str, str]:
+        """Generate consistent tags for resources."""
+        return {
+            "Project": self.project,
+            "Owner": self.owner,
+            "Stage": self.stage,
+            "Name": self.name,
+            "Release": self.release,
+        }
+
+    class Config:
+        """model config"""
+
+        env_file = ".env"
+        env_prefix = "STACK_"

infrastructure/aws/config.py

@@ -0,0 +1,28 @@
+ARG PYTHON_VERSION=3.12
+
+FROM public.ecr.aws/lambda/python:${PYTHON_VERSION}
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+# Install required utilities
+RUN dnf install -y findutils binutils && \
+  dnf clean all && \
+  rm -rf /var/cache/dnf
+
+WORKDIR /tmp
+COPY pyproject.toml pyproject.toml
+COPY README.md README.md
+COPY src/stac_fastapi/ src/stac_fastapi/
+
+RUN uv pip install --compile-bytecode .[lambda] --target /asset 
+
+# Reduce package size and remove useless files
+WORKDIR /asset
+RUN find . -type f -name '*.pyc' | while read f; do n=$(echo $f | sed 's/__pycache__\///' | sed 's/.cpython-[0-9]*//'); cp $f $n; done;
+RUN find . -type d -a -name '__pycache__' -print0 | xargs -0 rm -rf
+RUN find . -type f -a -name '*.py' -print0 | xargs -0 rm -f
+RUN find . -type d -a -name 'tests' -print0 | xargs -0 rm -rf
+
+# Strip debug symbols from compiled C/C++ code
+RUN find . -type f -name '*.so*' -exec strip --strip-unneeded {} \;
+
+COPY infrastructure/aws/lambda/handler.py /asset/handler.py

infrastructure/aws/lambda/Dockerfile

@@ -0,0 +1,12 @@
+"""AWS Lambda handler."""
+
+import logging
+
+from mangum import Mangum
+
+from stac_fastapi.geoparquet.main import app
+
+logging.getLogger("mangum.lifespan").setLevel(logging.ERROR)
+logging.getLogger("mangum.http").setLevel(logging.ERROR)
+
+handler = Mangum(app, lifespan="on")