Skip to content

Latest commit

 

History

History
216 lines (181 loc) · 7.16 KB

.aws.setup.md

File metadata and controls

216 lines (181 loc) · 7.16 KB
Raw

AWS Lambda & API Gateway setup

Table of Contents

Description

  • This document describes the process to setup your Lambda function and trigger it via an API Gateway

Process

  1. Setup IAM role for Lambda execution
  2. Setup Lambda function with correct execution permissions
  3. Deploy code to new function
  4. Configure Environment variables for your function
  5. Create API Gateway trigger for your Lambda function
  6. Configure API Gateway
  7. Deploy API Gateway
  8. Test API Gateway trigger

IAM Account/Action specific values

 - <region> (eu-west-1, us-east-1, us-west-2....)
 - <account-id> (your amazon account-id)
 - <name-of-function> (target functon name e.g. sendgrid-eventkit)
 - <name-of-role> (name of role you create e.g. travis-lambda)

Steps

1. Setup IAM role for Lambda execution

This policy provides a limited role allowing the function to write to CloudWatch Logs.

Role ARN: arn:aws:iam:::policy/lambda_basic_execution

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:PutLogEvents"
            ],
            "Resource": "arn:aws:logs:*:*:*"
        }
    ]
}

2. Setup Lambda function with correct execution permissions

  • provide desired function name
  • set execution role to lambda_basic_execution

3. Deploy code to new function

Option 1: Travis

  1. Follow the Travis IAM setup here .iam.md: IAM Policy & Setup
  2. Update .travis.yml "deploy" settings as appropriate
deploy:
  provider: lambda
  role: "arn:aws:iam::<account-id>:role/lambda_basic_execution"
  region: "<region>"
  function_name: "<name-of-function>"
  handler_name: "handler"
  runtime: "nodejs8.10"
  1. Link Travis to your repo and the function will auto-deploy after a successful test build (where function exit code = 0)

Option 2: Direct upload (not recommended)

  1. Bundle function into ZIP
mkdir .builds
zip -r .builds/lambda.zip index.js node_modules models/
  1. In Function Code, Select Code entry type -> Upload a .zip file; select lambda.zip

Notes: if using this method, we suggest you add .builds/ to your .gitignore

4. Configure settings your function

  • Configure environment variables
# Mongo Connection URI
DATABASE=mongodb+srv://<mongo_username>:<mongo_password>@<mongo-host>/<mongo-db-name>
# Optional legacy webhook URI for duplicating requests to legacy system
LEGACY_WEBHOOK_URI=https://example.requestcatcher.com/testWebHook

IMPORTANT: Once added, it is recommended that all environment variables are encrypted using AWS KMS

  • Timeout We suggest timeout of 5-10 seconds on Lambda function depending on your expected volume

5. Create API Gateway trigger for your Lambda function

In your function configuration:

  1. Add API Gateway trigger in the Designer section
  2. Select "Create a new API"
  3. Select "Open" security (SendGrid does not allow us to send bespoke Headers)
  4. Click "Add", then Save function
  5. Click on the new API name under "API Gateway" to open API Gateway configuration

6. Configure API Gateway

In your API Gateway Configuration for ANY route:

  1. Click on Integration Request

    • Untick "Use Lambda Proxy integration" & confirm change
    • Expand Mapping Templates, Add Mapping Template
    • Type "application/json" and click green tick, then "Yes, Secure this integration"
    • Click drop-down for Generate Template and select "Method Request passthough" (this will pass all data for API request to the Lambda function)
    • Click Save

  2. Click on Method Response

    • Click "Add Response"
    • Type 500 in HTTP Status and save the row
    • Click "Add Response"
    • Type 408 in HTTP Status and save the row

  3. Click on Integration Response

    • Click "Add Integration Response"
    • Lambda Error Regex: .*"statusCode":500.*
    • Method response status: 500
    • Click Save
    • Click "Add Integration Response"
    • Lambda Error Regex: .*Task timed out.*
    • Method response status: 408
    • Click Save

  4. Click "Test" in Client Box

    • Method: POST
    • Add test Query Strings, e.g. s=test_site_name
    • Enter Test Request Body
    [
    {
        "email": "example@test.com",
        "timestamp": 1513299569,
        "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
        "event": "processed",
        "category": "cat facts",
        "sg_event_id": "sg_event_id_1",
        "sg_message_id": "sg_message_id_1"
    }
]
- Click "Test"
    • Check Status:
      • 200, setup is successful, check Mongo for data
      • 408, timeout occurred check firewall and connection settings for Mongo
      • 500, error occurred, review logs for possible causes

}

7. Deploy API Gateway

In your API Gateway Configuration:

  1. Select "Deploy API" from Actions drop down
  2. Change "Deployment stage" to Deployment stage [New Stage]
  3. Enter new Stage name (e.g. production)
  4. Click Deploy

Back in Lambda configuration:

  1. In Designer section, Click on "API Gateway" box
  2. IN API Gateway section, click Delete, then Save your function
  3. In Designer section, under Add triggers, click API Gateway
  4. In Configure triggers section:
    • API: select your API Gateway here
    • Deployment stage: select the deployment stage you entered above
    • Security: Open
    • Click Add
  5. Save Function

You function is linked to your deployed API Gateway.

8. Test API Gateway trigger

We can now test the API Gateway via Postman or alternative HTTP request application.

  1. In Designer section, Click on "API Gateway" box
  2. Copy the API endpoint URL
  3. Set up a POST request in POSTMAN
  4. URL = API endpoint URL you copied
  5. In Body, switch to Raw and change content type to JSON (application/json)
  6. Drop example Sendgrid data into body, e.g.
[
    {
        "email": "example@test.com",
        "timestamp": 1513299569,
        "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
        "event": "processed",
        "category": "cat facts",
        "sg_event_id": "sg_event_id_1",
        "sg_message_id": "sg_message_id_1"
    }
]
  1. Click to Send the request and review results