toshke-grunt-aws-lambda
v0.13.3
Published
A grunt plugin to help develop AWS Lambda functions.
Downloads
3
Readme
grunt-aws-lambda
A grunt plugin to assist in developing functions for AWS Lambda.
This plugin provides helpers for:
- Running Lambda functions locally
- Managing npm dependencies which are required by your function
- Packaging required dependencies with your function in a Lambda compatible zip
- Uploading package to Lambda
Getting Started
This plugin requires Grunt ~0.4.5
If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
npm install grunt-aws-lambda --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-aws-lambda');
Gotchas
Add dist to your .npmignore
This will save you from packaging previous packages in future ones.
For example your .npmignore
might look something like this:
event.json
Gruntfile.js
dist
*.iml
Authenticating to AWS
This library supports providing credentials for AWS via an IAM Role, an AWS CLI profile, environment variables, a JSON file on disk, or passed in credentials. To learn more, please see the below section
grunt-aws-lambda tasks
Overview
This plugin contains 3 tasks:
- lambda_invoke - Wrapper to run and test lambda functions locally and view output.
- lambda_package - Packages function along with any npm dependencies in a zip format suitable for lambda.
- lambda_deploy - Uploads the zip package to lambda.
lambda_invoke and lambda_package can be used independently, lambda_deploy will invoke lambda_package before uploading the produced zip file.
lambda_invoke
In your project's Gruntfile, add a section named lambda_invoke
to the data object passed into grunt.initConfig()
.
grunt.initConfig({
lambda_invoke: {
default: {
options: {
// Task-specific options go here.
}
}
},
});
Options
options.handler
Type: String
Default value: handler
Name of the handler function to invoke.
options.file_name
Type: String
Default value: index.js
Name of your script file which contains your handler function.
options.event
Type: String
Default value: event.json
Name of the .json file containing your test event relative to your Gruntfile.
Usage Examples
Default Options
In this example, the default options are used therefore if we have the following in our Gruntfile.js
:
grunt.initConfig({
lambda_invoke: {
default: {
options: {
// Task-specific options go here.
}
}
},
});
And the following in index.js
exports.handler = function (event, context) {
console.log('value1 = ' + event.key1);
console.log('value2 = ' + event.key2);
console.log('value3 = ' + event.key3);
context.done(null, 'Hello World'); // SUCCESS with message
};
And the following in event.json
{
"key1": "value1",
"key2": "value2",
"key3": "value3"
}
Then we run grunt lambda_invoke
, we should get the following output:
Running "lambda_invoke" task
value1 = value1
value2 = value2
value3 = value3
Message
-------
Hello World
Done, without errors.
lambda_package
This task generates a lambda package including npm dependencies using the default npm install functionality.
In your project's Gruntfile, add a section named lambda_package
to the data object passed into grunt.initConfig()
.
grunt.initConfig({
lambda_package: {
default: {
options: {
// Task-specific options go here.
}
}
},
});
Options
options.include_files
Type: Array
Default value: []
List of files to explicitly include in the package, even if they would be ignored by NPM
options.include_time
Type: Boolean
Default value: true
Whether or not to timestamp the packages, if set to true the current date/time will be included in the zip name, if false then the package name will be constant and consist of just the package name and version.
options.include_version
Type: Boolean
Default value: true
Whether or not to include the NPM package version in the artifact package name. Set to false if you'd prefer a static package file name regardless of the version.
options.package_folder
Type: String
Default value: ./
The path to your npm package, must contain the package.json file.
options.dist_folder
Type: String
Default value: dist
The folder where the complete zip files should be saved relative to the Gruntfile.
Usage Examples
Default Options
In this example, the default options are used therefore if we have the following in our Gruntfile.js
:
grunt.initConfig({
lambda_package: {
default: {
options: {
// Task-specific options go here.
}
}
},
});
And the following in package.json
{
"name": "my-lambda-function",
"description": "An Example Lamda Function",
"version": "0.0.1",
"private": "true",
"dependencies": {
"jquery": "2.1.1"
},
"devDependencies": {
"grunt": "0.4.*",
"grunt-pack": "0.1.*",
"grunt-aws-lambda": "0.1.*"
}
}
Then we run grunt lambda_package
, we should see a new zip file in a new folder called dist
called something like:
my-lambda-function_0-0-1_2014-10-30-18-29-4.zip
If you unzip that and look inside you should see something like:
index.js
package.json
node_modules/
node_modules/jquery
node_modules/jquery/... etc
Given that by default the dist folder is inside your function folder you can easily end up bundling previous packages inside subsequent packages therefore it is strongly advised that you add dist to your .npmignore.
For example your .npmignore
might look something like this:
event.json
Gruntfile.js
dist
*.iml
lambda_deploy
In your project's Gruntfile, add a section named lambda_deploy
to the data object passed into grunt.initConfig()
.
grunt.initConfig({
lambda_deploy: {
default: {
arn: 'arn:aws:lambda:us-east-1:123456781234:function:my-function',
options: {
// Task-specific options go here.
}
}
},
});
Options
arn
Type: String
Default value: None - Required
The ARN of your target Lambda function.
function
Type: String
Default value: None - Required (if you havn't specified an ARN)
This option is deprecated, use arn instead. The name of your target Lambda function, ie. the name of the function in the AWS console.
Proxy
On Linux based hosts you can set proxy server for deploy task by specifying standard environment variable - https_proxy. E.g: env https_proxy=http://localhost:8080 grunt deploy
package
Type: String
Default value: Package name set by package task of same target - see below.
The name of the package to be uploaded.
When the lambda_package task runs it sets the package value for the lambda_deploy target with the same name.
Therefore if lambda_package and lambda_deploy have a target (eg. default) with the same name you will not need to provide this value - it will be passed automatically.
For example, your Gruntfile.js might contain the following:
grunt.initConfig({
lambda_deploy: {
default: {
arn: 'arn:aws:lambda:us-east-1:123456781234:function:my-function'
}
},
lambda_package: {
default: {
}
}
});
You could then run grunt lambda_package lambda_deploy
and it'll automatically create the package and deploy it without
having to specify a package name.
options.deploy_mode
Type: String
Default value: zip
Can be zip
or s3
. Determines how the code will be uploaded to lambda - via direct upload or via S3. For larger archives,
S3 may be more suitable.
options.S3bucketName
Type: String
Default value: null
Mandatory if options.deploy_mode='s3'
. S3 bucket to upload code archive to.
options.S3Prefix
Type: String
Default value: ``
Used only for options.deploy_mode='s3'
. S3 bucket prefix to be used when uploading code archive.
options.S3MultiUploadPartSize
Type: String
Default value 5mb
For larger archives, determines chunk size for s3 multi-upload. Minimum value is '5mb'.
options.profile
Type: String
Default value: null
If you wish to use a specific AWS credentials profile you can specify it here, otherwise it will use the environment default.
You can also specify it with the environment variable AWS_PROFILE
options.RoleArn
Type: String
Default value: null
If you wish to assume a specific role from an EC2 instance you can specify it here, otherwise it will use the environment default.
options.accessKeyId
Type: String
Default value: null
If you wish to use hardcoded AWS credentials you should specify the Access Key ID here
options.secretAccessKey
Type: String
Default value: null
If you wish to use hardcoded AWS credentials you should specify the Secret Access Key here
options.credentialsJSON
Type: String
Default value: null
If you wish to use hardcoded AWS credentials saved in a JSON file, put the path to the JSON here. The JSON must conform to the AWS format.
options.region
Type: String
Default value: us-east-1
Specify the AWS region your functions will be uploaded to. Note that if an ARN is supplied this option is not required.
options.timeout
Type: Integer
Default value: null
Depending on your Lambda function, you might need to increase the timeout value. The default timeout assigned by AWS is currently 3 seconds.
If you wish to increase this timeout set the value here.
options.memory
Type: Integer
Default value: null
Sets the memory assigned to the function. If null then the current setting for the function will be used. Value is in MB and must be a multiple of 64.
options.handler
Type: String
Default value: null
Sets the handler for your lambda function. If left null, the current setting will remain unchanged.
options.enableVersioning
Type: boolean
Default value: false
When enabled each deployment creates a new version.
options.aliases
Type: String
or Array
Default value: null
If a string or an array of strings then creates these aliases. If versioning enabled then points to the created version,
otherwise points to $LATEST
.
It is recommended that enableVersioning
is also enabled when using this feature.
Examples:
Creates one beta
alias:
aliases: 'beta'
Creates two aliases, alias1
and alias2
:
aliases: [
'alias1',
'alias2'
]
options.enablePackageVersionAlias
Type: boolean
Default value: false
When enabled creates a second alias using the NPM package version. When the NPM package version is bumped a new alias will be created, allowing you to keep the old alias available for backward compatibility.
It is recommended that enableVersioning
is also enabled when using this feature.
options.subnetIds
Type: Array
Default value: null
A list of one or more subnet IDs in your VPC.
options.securityGroupIds
Type: Array
Default value: null
A list of one or more security groups IDs in your VPC.
If your Lambda function accesses resources in a VPC you must provide at least one security group and one subnet ID. These must belong to the same VPC
Usage Examples
Default Options
In this example, the default options are used therefore if we have the following in our Gruntfile.js
:
grunt.initConfig({
lambda_deploy: {
default: {
arn: 'arn:aws:lambda:us-east-1:123456781234:function:my-function'
}
}
});
And now if you run grunt lambda_deploy
your package should be created and uploaded to the specified function.
Increasing the Timeout Options to 10 seconds
In this example, the timeout value is increased to 10 seconds and set memory to 256mb.
grunt.initConfig({
lambda_deploy: {
default: {
arn: 'arn:aws:lambda:us-east-1:123456781234:function:my-function',
options: {
timeout : 10,
memory: 256
}
}
}
});
Example with a beta and prod deployment configuration
Deploy to beta with deploy
and to prod with deploy_prod
:
grunt.initConfig({
lambda_invoke: {
default: {
}
},
lambda_deploy: {
default: {
options: {
aliases: 'beta',
enableVersioning: true
},
arn: 'arn:aws:lambda:us-east-1:123456789123:function:myfunction'
},
prod: {
options: {
aliases: 'prod',
enableVersioning: true
},
arn: 'arn:aws:lambda:us-east-1:123456789123:function:myfunction'
}
},
lambda_package: {
default: {
},
prod: {
}
}
});
grunt.registerTask('deploy', ['lambda_package', 'lambda_deploy:default']);
grunt.registerTask('deploy_prod', ['lambda_package', 'lambda_deploy:prod']);
Misc info
Streamlining deploy
You can combine the lambda_package and lambda_deploy into a single deploy task by adding the following to your Gruntfile.js:
grunt.registerTask('deploy', ['lambda_package', 'lambda_deploy']);
You can then run grunt deploy
to perform both these functions in one step.
AWS credentials
The AWS SDK is configured to look for credentials in the following order:
- an IAM Role (if running on EC2)
- an AWS CLI profile (from
~/.aws/credentials
) - environment variables (
AWS_ACCESS_KEY_ID
,AWS_SECRET_ACCESS_KEY
,AWS_SESSION_TOKEN
) - a JSON file on disk
- Hardcoded credentials passed into grunt-aws
The preferred method of authenticating during local development is by providing credentials in ~/.aws/credentials
,
it should look something like this:
[default]
aws_access_key_id = <YOUR_ACCESS_KEY_ID>
aws_secret_access_key = <YOUR_SECRET_ACCESS_KEY>
For more information read this documentation.
AWS permissions
To run the deploy command the AWS credentials require permissions to access lambda including lambda:GetFunction
,
lambda:UploadFunction
, lambda:UpdateFunctionCode
, lambda:UpdateFunctionConfiguration
and
iam:PassRole
for the role which is assigned to the function.
It is recommended that the following policy be applied to the user:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Stmt1442787227063",
"Action": [
"lambda:GetFunction",
"lambda:UploadFunction",
"lambda:UpdateFunctionCode",
"lambda:UpdateFunctionConfiguration",
"lambda:GetAlias",
"lambda:UpdateAlias",
"lambda:CreateAlias",
"lambda:PublishVersion"
],
"Effect": "Allow",
"Resource": "arn:aws:lambda:*"
},
{
"Sid": "Stmt1442787265773",
"Action": [
"iam:PassRole"
],
"Effect": "Allow",
"Resource": "arn:aws:iam::<my_account_id>:role/<my_role_name>"
}
]
}
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.
Release History
0.1.0
Initial release
0.2.0
Adding some unit tests, refactoring deploy task into single task and converting tasks to multitasks
0.3.0
Adding more warnings for various failure cases
0.4.0
- Added support for succeed and fail functions - pull request by jonyo
- Added NPM to package.json - pull request by jonyo, should address issue 2
- Added timeout and memory options - timeout pull request by aidancasey
- Bumped aws-sdk version
- Bumped adm-zip version, will hopefully address issue 4
0.5.0
- Fixed issue where dotfiles weren't packaged - see issue 17
- Fixed issue where task could be done before zip writing is finished - pull request by qen
- Monkey patched node-archiver to force permissions to be 777 for all files in package - see issue 6
0.6.0
- Fixing a minor issue caused by some code that shouldn't have been commented out.
0.7.0
- Removing some unneeded files from the NPM package.
0.8.0
- Adding
include_files
option to package - pull request by dhleong
0.9.0
- Parsing region automatically from ARN - pull request by jvwing
0.10.0
- Making NPM a regular dependency to resolve #20 - pull request by timdp
0.11.0
- Including AWS API error message in deployment failure - pull request by CaseyBurns
- Providing a method to pass AWS credentials in either the Gruntfile or credentials file - pull request by robbiet480
- Adding support for AWS temporary credentials - pull request by olih
0.12.0
- Added package_folder option to lambda_invoke task - pull request by dcaravana
- Adding optional files to contain JSON objects for clientContext and identity to be passed into the lambda_invoke command - pull request by Skorch
- Add handler option to lambda_deploy task - pull request by Rawbz
- Fix lambda_deploy config example - pull request by pracucci
- Context object methods cleanup - pull request by ubergoob, also fixes issue 54
- When deploy_arn is not defined in the Gruntfile the value is undefined - pull request by varunvairavan
- Extensive refactoring to improve testability and a new unit test suite
- Bumped AWS SDK version to 2.2.32
- Added support for versioning and aliases
- Added support for excluding the package version from the package artifact name - based on pull request by leecrossley
0.13.0
- Added support for Node 4.3 runtime callback function - pull request by bobhigs
- Added VPC support - pull request by beeva-arturomartinez
- Added local proxy support - pull request by alekstr