lambroll

lambroll is a deployment tool specifically designed for AWS Lambda functions. It focuses on the lifecycle of the function itself rather than the surrounding infrastructure.

What lambroll can do:

• Create a Lambda function.
• Create Zip archives from local directories.
• Deploy function code, configuration, tags, aliases, and function URLs.
• Rollback functions to previous versions.
• Invoke functions with payloads.
• Manage function versions.
• Show function status and logs.
• Show diffs of function code and configuration.
• Delete functions.

What lambroll does NOT do:

• Manage related AWS resources like IAM Roles, function triggers, or API Gateway (though Function URLs can be managed).
• Build native binaries or extensions for the Linux Lambda runtime environment.

If you need to manage the entire serverless stack (infrastructure + code), tools like AWS SAM or Serverless Framework are recommended.

lambroll uses global flags for all commands. These can be configured via command-line flags, environment variables, or a JSON/Jsonnet option file.

Priority of configuration values:

1. Command-line flags (highest priority)
2. Values defined in the option file
3. Environment variables (lowest priority)

Option File Format: An option file (specified via --option=filename) can contain global flags at the top level and subcommand-specific flags nested under the subcommand name using snake_case keys.

Supported Template Functions in Jsonnet: When parsing an option file, lambroll only evaluates {{env}} and {{must_env}} template functions and the env and must_env native functions.

// option.jsonnet
{
  region: 'ap-northeast-1',  // global flag
  diff: {
    external: 'dyff between',  // --external flag of `lambroll diff`
  },
  deploy: {
    keep_versions: 5,  // --keep-versions flag of `lambroll deploy`
  },
}

The deploy command creates a new Lambda function or updates an existing one. It handles zipping source code, updating configuration, and managing aliases.

Deployment Workflows:

1. Standard Deployment: Creates a zip archive from --src (respecting .lambdaignore), updates/creates the function, and publishes a version/alias.

2. Deploy via S3: If the zip archive is large, set Code.S3Bucket and Code.S3Key in function.json. Use --skip-archive if you upload the zip manually.

{
  "Code": {
    "S3Bucket": "my-bucket",
    "S3Key": "function.zip"
  }
}

To use self-managed code storage, set Code.S3ObjectStorageMode to "REFERENCE".

3. Deploy Container Image: Set PackageType=Image and Code.ImageUri in function.json.

{
  "FunctionName": "container",
  "PackageType": "Image",
  "Code": {
    "ImageUri": "123456789012.dkr.ecr.region.amazonaws.com/repo:tag"
  }
}

Key Flags:

• --src=".": Source directory or zip archive.
• --publish: Publish function (default).
• --alias="current": Alias name for publish.
• --keep-versions=0: Number of latest versions to keep; older versions are deleted.
• --ignore="": Ignore specific fields in function.json using jq queries.
• --skip-configuration: Skip updating function configuration; deploy code and aliases only.

$ lambroll deploy --ignore='.Tags, .Environment'

To start managing an existing Lambda function with lambroll, use the init command with the --download flag. This pulls the current configuration and code into your local directory.

1. Initialize the project:

   mkdir hello
   cd hello
   lambroll init --function-name hello --download

   This creates a function.json (configuration) and downloads the current code (e.g., function.zip).

2. Modify your code or config: Unzip the downloaded code, edit your index.js or function.json, and then remove the temporary zip file.

3. Deploy changes:

   lambroll deploy

   This command creates a new zip archive from your local directory and updates the Lambda function's code and configuration in AWS.

$ mkdir hello
$ cd hello
$ lambroll init --function-name hello --download
# ... edit function.json or index.js ...
$ lambroll deploy