Use Serverless to deploy AWS Lambdas (Node/Typescript)

serverless-aws-lambda-instructions.md

Serverless + AWS Lambda + Node/Typescript

Here's the step-by-step guide on how to build & deploy AWS Lambda functions using Serverless library.

This guide was inspired by this tutorial.

I prefer to use Node.js & ideally develop using Typescript. In addition, this has support for running locally, using environment variables through Secrets Manager, etc.

Build Serverless functions

1. Install serverless globally

   npm install -g serverless
   

2. Create a IAM User in your AWS Console.

   • Create a new user w/ programattic access
   • Give the user only the required permissions (Admin by default). More info here
   • Save the Access key ID & Secret access key for that user

3. Enter IAM keys in the Serverless configuration

   serverless config credentials --provider aws --key xxxxxxxxxxxxxx --secret xxxxxxxxxxxxxx
   

4. Initialize Serverless project

   mkdir dear-earth-serverless
   serverless create --template aws-nodejs
   

5. Check serverless.yml file and ensure it has events for httpApi & schedule.

   More info on Node Scheduled Cron here.

   functions:
     hello:
       handler: handler.hello
     events:
       - httpApi:
           path: /hello
           method: get
       - schedule: rate(2 minutes)
     environment:
       variable2: value2
   

6. Commit your code w/ init serverless project

Running Locally

1. Add the Serverless Offline npm package

   npm init
   npm install serverless-offline --save-dev
   

2. Add the Serverless Offline plugin to serverless.yml file

   # emulate AWS λ and API Gateway locally when developing your Serverless project
   plugins:
     - serverless-offline
   

3. Run the serverless functions locally

   serverless offline start
   

4. Commit your code w/ setup serverless-offline

Deploy to AWS

1. Deploy the serverless functions to AWS

   export AWS_ACCESS_KEY_ID=XXXXXXXXX
   export AWS_SECRET_ACCESS_KEY=XXXXXXXXX
   
   # AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are now available for serverless to use
   
   serverless deploy --verbose
   

2. Run the deployed function on AWS with logs

   serverless invoke -f hello --log
   

Adding Typescript

1. Add the Serverless Plugin Typescript npm package

   npm install -D serverless-plugin-typescript typescript
   

2. Add the Serverless Typescript plugin to serverless.yml file and make sure to include it before the offline plugin

   plugins:
   # Add typescript support to local development & deployed files
   - serverless-plugin-typescript
   # emulate AWS λ and API Gateway locally when developing your Serverless project
   - serverless-offline
   

Use dotenv variables

1. Environment variables w/ dotenv are natively supported in Serverless.

   More info on Referencing Environment Variables

   # Serverless will load all env vars in `.env` in 3.0.0+
   # https://www.serverless.com/framework/docs/environment-variables/
   useDotenv: true
   

2. Add a .env file with environment variables. Make sure to add it to .gitignore as well

   NODE_ENV=XXXXXXXX
   

3. Once you update the .env file with real values make sure to mark that file as unchanged so that it doesn't show up in diffs

   git update-index --assume-unchanged .env
   

4. Include the environment variables in the serverless.yml file

   functions:
     hello:
       handler: handler.hello
     environment:
       NODE_ENV: ${env:NODE_ENV}
   

5. Import dotenv config at the root of each serverless function

   import 'dotenv/config';
   

Use Secrets Manager

1. The store sensitive secrets on AWS, you can use the Secrets Manager.

   More info on Tutorial: Create and retrieve a secret

   NODE_ENV=production
   

2. Then update the serverless.yml with a custom handler

   Notice below, the dear-earth-serverless is the name of the secrets folder you create.

   custom:
     secrets: ${ssm:/aws/reference/secretsmanager/dear-earth-serverless}
   

3. Lastly update the environment section in serverless.yml to get the value from the custom handler

   functions:
     hello:
       handler: handler.hello
     environment:
       NODE_ENV: ${self:custom.secrets.NODE_ENV}