kanata2/lambroll

lambroll is a minimal deployment tool for AWS Lambda.

lambroll

lambroll is a minimal deployment tool for AWS Lambda.

lambroll does,

• Create a function.
• Create a Zip archive from local directory.
• Update function code / configuration / tags / aliases.

That's all.

lambroll does not,

• Manage resources related to the Lambda function.
  • e.g. IAM Role, function triggers, API Gateway, etc.
• Build native binaries or extensions for Linux (AWS Lambda running environment).

When you hope to manage these resources, we recommend other deployment tools (AWS SAM, Serverless Framework, etc.).

Install

Homebrew (macOS only)

$ brew install fujiwara/tap/lambroll

Binary packages

Releases

Quick start

Try migrate your existing Lambda function hello.

$ mkdir hello
$ cd hello
$ lambroll init --function-name hello --download
2019/10/26 01:19:23 [info] function hello found
2019/10/26 01:19:23 [info] downloading function.zip
2019/10/26 01:19:23 [info] creating function.json
2019/10/26 01:19:23 [info] completed

$ unzip -l function.zip
Archive:  function.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
      408  10-26-2019 00:30   index.js
---------                     -------
      408                     1 file

$ unzip function.zip
Archive:  function.zip
 extracting: index.js

$ rm function.zip

See or edit function.json or index.js.

Now you can deploy hello fuction using lambroll deploy.

$ lambroll deploy
2019/10/26 01:24:52 [info] starting deploy function hello
2019/10/26 01:24:53 [info] creating zip archive from .
2019/10/26 01:24:53 [info] zip archive wrote 1042 bytes
2019/10/26 01:24:53 [info] updating function configuration
2019/10/26 01:24:53 [info] updating function code hello
2019/10/26 01:24:53 [info] completed

Usage

usage: lambroll [<flags>] <command> [<args> ...]

Flags:
  --help                      Show context-sensitive help (also try --help-long and --help-man).
  --region="ap-northeast-1"   AWS region
  --log-level=info            log level (trace, debug, info, warn, error)
  --function="function.json"  Function file path

Commands:
  help [<command>...]
    Show help.

  version
    show version

  init --function-name=FUNCTION-NAME [<flags>]
    init function.json

  list
    list functions

  deploy [<flags>]
    deploy or create function

  rollback [<flags>]
    rollback function

  delete [<flags>]
    delete function

  invoke [<flags>]
    invoke function

  archive [<flags>]
    archive zip

Init

lambroll init initialize function.json by existing function.

usage: lambroll init --function-name=FUNCTION-NAME [<flags>]

init function.json

Flags:
  --function-name=FUNCTION-NAME  Function name for initialize
  --download                     Download function.zip

init creates function.json as a configuration file of the function.

Deploy

usage: lambroll deploy [<flags>]

deploy or create function

Flags:
  --help                      Show context-sensitive help (also try --help-long
                              and --help-man).
  --region="ap-northeast-1"   AWS region
  --log-level=info            log level (trace, debug, info, warn, error)
  --function="function.json"  Function file path
  --src="."                   function zip archive src dir
  --exclude-file=".lambdaignore"  
                              exclude file
  --dry-run                   dry run
  --publish                   publish function
  --alias="current"           alias name for publish

deplpoy works as below.

• Create a zip archive from --src directory.
  • Excludes files matched (wildcard pattern) in --exclude-file.
• Create / Update Lambda function
• Create an alias to the published version when --publish (default).

Rollback

usage: lambroll rollback [<flags>]

rollback function

Flags:
  --help                      Show context-sensitive help (also try --help-long and --help-man).
  --region="ap-northeast-1"   AWS region
  --log-level=info            log level (trace, debug, info, warn, error)
  --function="function.json"  Function file path
  --delete-version            Delete rolled back version
  --dry-run                   dry run

lambroll deploy create/update alias current to the published function version on deploy.

lambroll rollback works as below.

1. Find previous one version of function.
2. Update alias current to the previous version.
3. When --delete-version specified, delete old version of function.

Invoke

usage: lambroll invoke [<flags>]

invoke function

Flags:
  --help                      Show context-sensitive help (also try --help-long and --help-man).
  --region="ap-northeast-1"   AWS region
  --log-level=info            log level (trace, debug, info, warn, error)
  --function="function.json"  Function file path
  --async                     invocation type async
  --log-tail                  output tail of log to STDERR

lambroll invoke accepts multiple JSON payloads for invocations from STDIN.

Outputs from function are printed in STDOUT.

$ echo '{"foo":1}{"foo":2}' | lambroll invoke --log-tail
{"success": true, payload{"foo:1}}
2019/10/28 23:16:43 [info] StatusCode:200 ExecutionVersion:$LATEST
START RequestId: 60140e16-018e-41b1-bb46-3f021d4960c0 Version: $LATEST
END RequestId: 60140e16-018e-41b1-bb46-3f021d4960c0
REPORT RequestId: 60140e16-018e-41b1-bb46-3f021d4960c0	Duration: 561.77 ms	Billed Duration: 600 ms	Memory Size: 128 MB	Max Memory Used: 50 MB
{"success": true, payload:{"foo":2}}
2019/10/28 23:16:43 [info] StatusCode:200 ExecutionVersion:$LATEST
START RequestId: dcc584f5-ceaf-4109-b405-8e59ca7ae92f Version: $LATEST
END RequestId: dcc584f5-ceaf-4109-b405-8e59ca7ae92f
REPORT RequestId: dcc584f5-ceaf-4109-b405-8e59ca7ae92f	Duration: 597.87 ms	Billed Duration: 600 ms	Memory Size: 128 MB	Max Memory Used: 50 MB
2019/10/28 23:16:43 [info] completed

function.json

function.json is a definition for Lambda function. JSON structure is based from CreateFunction for Lambda API.

{
  "Description": "hello function for {{ must_env `ENV` }}",
  "Environment": {
    "Variables": {
      "BAR": "baz",
      "FOO": "{{ env `FOO` `default for FOO` }}"
    }
  },
  "FunctionName": "{{ must_env `ENV` }}-hello",
  "Handler": "index.js",
  "MemorySize": 128,
  "Role": "arn:aws:iam::123456789012:role/hello_lambda_function",
  "Runtime": "nodejs10.x",
  "Tags": {
    "Env": "dev"
  },
  "Timeout": 5,
  "TracingConfig": {
    "Mode": "PassThrough"
  }
}

Tags

When "Tags" key exists in function.json, lambroll set / remove tags to the lambda function at deploy.

{
  // ...
  "Tags": {
    "Env": "dev",
    "Foo": "Bar"
  }
}

When "Tags" key does not exist, lambroll doesn't manage tags. If you hope to remove all tags, set "Tags": {} expressly.

Expand enviroment variables

At reading the file, lambrol evaluates {{ env }} and {{ must_env }} syntax in JSON.

For example,

{{ env `FOO` `default for FOO` }}

Environment variable FOO is expanded here. When FOO is not defined, use default value.

{{ must_env `FOO` }}

Environment variable FOO is expanded. When FOO is not defined, lambroll will panic and abort.

.lambdaignore

lambroll will ignore files defined in .lambdaignore file at creating a zip archive.

For example,

# comment

*.zip
*~

For each line in .lambdaignore are evaluated as Go's path/filepath#Match.

LICENSE

MIT License

Copyright (c) 2019 FUJIWARA Shunichiro