lambda-cfn

 

Quickly create, deploy, and manage AWS Lambda functions via AWS CloudFormation.

Prerequisites

$3

Lambda-cfn (or "Lambda CloudFormation") is a Node.js project that runs on AWS Lambda. Node.js v10.x is the current default, Node.js v8.10 is also available. See AWS Lambda execution environment for more information about the Lambda Node.js runtime environment.

$3

Lambda-cfn uses cfn-config behind the scenes to create and manage CloudFormation stacks. Cfn-config requires two S3 buckets - a config bucket and a template bucket - to work.

Lambda-cfn will look for the following buckets by default if you've set an AWS_ACCOUNT_ID environment variable:

- Config bucket: cfn-configs-$AWS_ACCOUNT_ID-region
- Template bucket: cfn-config-templates-$AWS_ACCOUNT_ID-region

For example, if your AWS account ID is 123456789 and you're using the us-west-1 region then lambda-cfn will look for buckets named cfn-configs-123456789-us-west-1and cfn-config-templates-123456789-us-west-1.

If you don't want to use the default naming convention then you'll need to pass both bucket names as arguments for the create, update, and save commands. You can also set a CFN_CONFIG_BUCKET environment variable if you'd prefer.

Installation

First install lamdba-cfn globally so that you can use lambda-cfn utility commands like lambda-cfn init or lambda-cfn create:

``
npm install -g @mapbox/lambda-cfn
`

Creating new Lambda functions

After installing lambda-cfn, from within your project directory (e.g. myProject) run the following command:

`
lambda-cfn init
`

For example, running lambda-cfn init myFunction will create the following files and directories:

- a package.json file in the currently working directory with lambda-cfn as a dependency
- a myFunction directory, with two files called function.js and function.template.js

This looks like:

`
myProject/
|-- package.json
|-- myFunction/
|-- function.js
|-- function.template.js
`

You can have multiple function directories with the main project directory (myProject).

`
myProject/
|-- package.json
|-- myFunction/
|-- function.js
|-- function.template.js
|-- myOtherFunction/
|-- function.js
|-- function.template.js
`

$3

Add the code for your Lambda function to this file. We have already taken care of setting up the handler function for you. Here's what this file looks like:

`js
var lambdaCfn = require('@mapbox/lambda-cfn');

module.exports.fn = function(event, context, callback) {
// write Lambda function code here

};
`

$3

Configure your Lambda function in this file. Configuration consists of passing in a JavaScript object to the lambdaCfn.build() function. Lambda-cfn will take care of generating the CloudFormation template for you as part of the deployment process.

Here's what the function.template.js file looks like after running lambda-cfn init. The only required property for deployment is the name of the function - all other properties are optional.

`js
const lambdaCfn = require('@mapbox/lambda-cfn');

module.exports = lambdaCfn.build({
name: 'myFunction'
});
`

If you'd like to create a Lambda function that runs on the older Node.js 8.10 runtime with a memory size of 256 MB and a timeout of 120 seconds:

`js
const lambdaCfn = require('@mapbox/lambda-cfn');

module.exports = lambdaCfn.build({
name: 'myFunction',
runtime: 'nodejs8.10',
memorySize: '256',
timeout: '120'
});
`

For a full list of available function properties to configure your Lambda function, see the function specification documentation.

Deploying Lambda functions to AWS

First we'll need to zip up the code for our Lambda function and then upload it to S3 before we can deploy it via CloudFormation. We also need to make sure that our project and its functions are within a git repository. Run git init to set this up.

$3

Lambda-cfn uses cfn-config for creating, retrieving, updating, and deleting CloudFormation stacks. It takes the same parameters and values as cfn-config, see the cfn-config CLI usage documentation.

Lambda-cfn will look for the following environment variables if you'd prefer to not pass in flags for each command:

- CFN_CONFIG_BUCKET for --config-bucket (-c)
- AWS_REGION for --region (-r)

To get a full list of lambda-cfn commands, run lambda-cfn --help.

$3

By default lambda-cfn expects your Lambda code to be in the following location on S3:

s3:////.zip

We created a Bash script called upload.sh within lambda-cfn that will do this for you. The script obtains the current gitsha, zips up the code, copies it to S3, then deletes the zip file.

Run this script from the parent directory (myProject or the one with the package.json file). You'll need to provide the path to your S3 bucket and any prefixes, without the trailing slash:

`sh
sh upload.sh /
`

If I'm using bucket myBucket and the prefix myFunction:

`sh
sh upload.sh myBucket/myFunction
`

This will upload your code to s3://myBucket/myFunction/.zip.

If you'd like to manually upload your code, then zip your entire project directory (myProject or the parent directory containing the package.json file) and copy it to S3 to the location of your choice. You can provide the location of your code during the lambda-cfn create command in the next step.

$3

To create a new CloudFormation stack for your lambda function, run lambda-cfn create . For example, if I want to create to a development environment stack in the default us-east-1 region:

`
lambda-cfn create dev
`

This will use the default config and template S3 buckets mentioned in the prerequisites. If you'd like to override these buckets and deploy to us-west-1:

`
lambda-cfn create dev --region us-west-1 --config-bucket --template-bucket