Mini Tutorial: Setup AWS Lambda + ACM + API Gateway with AWS Cloud Development Kit (CDK)

We're going to deploy a functional public API that receives an HTML form (e.g. /contact_us.html) POST request and delivers its data to Pushover notification service.

This tutorial is based on the excellent one that you can find at https://cdkworkshop.com/30-python.html and it resembles it closely.

Here's how it differs:

• bootstrapped from a real live project migration from Terraform to AWS CDK
• shows how to integrate API Gateway and ACM to expose https endpoint under a personal domain (e.g. https://api.yourdomain.com/)
• fully automated with make

Linked blog post: Introducing AWS CDK with a real life Lambda / API gateway example

Original blog post: Setup a custom domain REST API endpoint on AWS Lambda: a step by step tutorial

Architecture

A simple diagram of the deployed AWS resources and 3rd party service:

https://api.yourdomain.com/ <---> API Gateway REST proxy <---> AWS Lambda ---> Pushover (3rd party)
                                          |---> AWS Cert Manager

Requirements

Before reading any further please ensure you've properly installed CDK on your workstation.

Unless you disable ACM integration commenting some code, you need to be able to verify the domain ownership of yourdomain.com via email validation (check docs for details).

Setup

1. create a test AWS environment in your ~/.aws/credentials file with administrator permissions, e.g.

    [testing]
    aws_access_key_id = <your-admin-key>
    aws_secret_access_key = <your-admin-secret>
    region = eu-west-1
   

2. git clone this repository and cd into the base folder

3. add your data to config.mk.example (pay special attention to AWS_PROFILE) and save it to config.mk in the same base folder

4. run make all to bootstrap the CDK project and fully provision the needed infrastructure (WARNING: check emails during deployment and validate domain ownership to speed up the process). You'll be prompted to accept the proposed changes to IAM, type y and enter. You'll also receive some emails asking you to follow a link to validate the ownership of your domain.

At this point you should have a working environment deployed and ready to be tested:

    [...]
    Outputs:
    apitest-l3x-in.apitestl3xingatewayEndpoint70DD9352 = https://utryz8cx6g.execute-api.eu-central-1.amazonaws.com/prod/

    Stack ARN:
    arn:aws:cloudformation:eu-central-1:130728781160:stack/apitest-l3x-in/03fc9db0-4670-11ea-a198-02205d104246
    ###########################################################################
    # remember to add the DNS record to enable owned domain:
    #
    # apitest.l3x.in	CNAME	 d-xnf9352jj8.execute-api.eu-central-1.amazonaws.com
    ###########################################################################

    $ curl -X POST https://utryz8cx6g.execute-api.eu-central-1.amazonaws.com/prod/contact_us
    {"error": "JSON body is malformatted: the JSON object must be str, bytes or bytearray, not NoneType"}

If you see that error message it means that everything should work as expected (we get an HTTP 405 as expected because we're not passing any data in our POST).

You can add now the DNS record and (after propagation) test it with proper URL and data:

    $ curl -X POST https://apitest.l3x.in/contact_us \
        --data '{"name":"Testing the APIs","email":"your@email.com","description":"CDK is powerful"}'
    {"message": "message delivered"}

Playground

You can find the CDK implementation in the src directory, Lambda source code in lambda/contact_us.py.

The setup step will place these source code files in new folders created by CDK: api/ and api/api.

Feel free to add and remove constructs to api/api/api_stack.py and/or edit the Lambda in api/lambda/contact_us.py as you wish, executing make deploy will take care of checking for errors and, if none found, applying your changes (if any).

As an exercise you might think of adding an SQS service in the stack to decouple the Pushover service from the main Lambda and have it in a dedicated Lambda not exposed to the public, etc.

Clean up

Run make destroy to destroy all the resources created by CloudFormation. The only task make will not do for you is to remove a few of the CDK leftovers (CloudFormation CDK meta stack and CloudWatch Logs generated by Lambda)