aws-sam-cli

What's New

You can now use the sam build command to compile deployment packages for AWS Lambda functions written in Python 2.7 and 3.6. If you write code that uses python packages, such as a graphics library for image processing, you need to create a deployment package that will work on the Amazon Linux AMI. The sam build command allows you to easily create deployment artifacts that target AWS Lambda's execution environment, so the functions you build locally will run in a similar environment in the cloud.

The sam build command iterates through the functions in your application, looks for a manifest file (such as requirements.txt) that contains dependencies, and automatically creates deployment artifacts that you can deploy to Lambda using the sam package and sam deploy commands. If your functions depend on packages that have natively compiled programs, you can also use the sam build command with the --use-container flag. This flag builds your functions in a Lambda-like environment locally so they are in the correct format when you deploy them to the cloud.

As part of this release, we have also updated the sam local invoke and sam package commands to work on built artifacts to streamline the build -> test -> package -> deploy workflow. For example, you can execute sam local invoke right after executing sam build and sam local invoke will use the built artifacts. This makes it easier to operate on the template and source code without dealing with intermediate templates.

Changelog

fix: Attempt to recover/invoke function when docker connectivity is poor (#764) feat: Implementation of "sam build" CLI command (#766) feat: "sam package" defaults to built template (#775) feat: Adding a sam --info command (#776)

Brew for Mac and Linux

You can now install SAM CLI using brew, a popular package manager for installing the packages you need. Installation is as simple as:

brew tap aws/tap
brew install aws-sam-cli

Note: On a Mac you use Homebrew, and on Linux you use Linuxbrew (a fork of the Homebrew package manager).

MSI for Windows

You can now download an MSI to install SAM CLI on Windows. Get the MSI you need here:

• 64-bit
• 32-bit

Changelog:

This release also contains the following bug fixes:

• chore(version_bump): bump to 0.6.2
• Fix: Travis times out when running Integ tests (#739)
• fix: upgrade requests to 2.20.0 (#740)
• Fix typo
• chore: Version bump aws-sam-translator to 1.8.0 (#732)
• Update README.rst
• docs: add instructions for using local version of SAM Transformer (#688)
• docs: Update Docker command to docker (#725)
• fix: Iterate over query param list
• chore: Enable Travis to run integ tests
• fix: Support attaching to host network

Windows 7 and 8 support

SAM CLI now works with Docker Toolbox, so you can now use SAM CLI to test and debug your Lambda functions locally on Windows 7 and 8.

!Ref template parameters locally

We added support for resolving !Ref of template parameters anywhere within a SAM template. You can now provide values for template parameters using the --parameter-overrides CLI option, and reference those within the template. You can also automatically pick up default values of parameters. For example, SAM CLI assigns defaults for CloudFormation pseudo-parameters like AWS::Region.

This release also contains plenty of bug fixes and documentation updates! 🎉

Changelog

add pytest-mock for testing (#703) fix: allow for stdout and stderr streams to be unbufferred directly. (#708) docs: Add installation instructions for linux (Centos) (#670) fix: Updated isBase64Encoded value to bool (#699) fix: correct launch.json for nodejs debugging through VSCode (#704) docs(usage): Update how to debug Python functions using VS Code (#694) docs(Cloud9): Reset bash cache on Cloud9 (#693) docs: Updated virtualenv alias name for 3.7 in guide. (#706) chore: update aws-sam-translator to 1.7.0 (#682) feat: travis CI support for Python 3.7 (#679) docs: Update generate-sample-event-payloads link (#702) Fix: Raise error for invalid environment variables file (#675) fix: remove dependency on pystache (#684) feat(init): .Net Core 2.1 support for init command (#665) feat(generate-event): Add Kinesis Analytics events (#667) feat(intrinsics): Support !Ref of template parameters (#657) fix: conditionally install enum34 based on python version (#671) fix: Update test format for Nodejs8.10 runtime. (#662) fix: Removed dual line in init help text (#664) docs: Update usage.rst to render code inline (#661) fix(path): change windows style path to unix (#633) fix(docs): fixed macOS name (#651) Fix(generate-event): SubCommand help text to be short-text. (#652) feat(generate-event): Support dns_suffix and partition variables (#650) docs: Consistent packaged template naming (#647) docs(installation): Upgrade instructions for AWS Cloud9 (#643) fix(init): Fix camelCase vs snakeCase issue in NodeJS tests (#640) docs(usage): Update generate-event command structure (#638)

This release of SAM CLI makes it even easier to test and debug your serverless applications locally. There are two big features in this release:

1. Go Debugging: You can now use Delve to debug your Go Functions! Get started here: Debugging Go functions. Huge shout out to @austinlparker for this contribution!
2. Sample event generation: Previously, you could generate sample event payloads from S3, Kinesis Streams, DynamoDB, CloudWatch Scheduled Events, API Gateway, and SNS. Now, you can generate and customize sample payloads from 50+ events (including those from CloudFront, CloudFormation, Step Functions, and Alexa). You can also generate different types of events from each service - so, in addition to S3/Put, you can also generate sample payloads for S3/Delete.

BREAKING CHANGE: Because we support multiple event types from each service, the syntax of the generate-command is now different.

For example: sam local generate-event s3

Has become sam local generate-event s3 [put/delete]

Changelog:

feat(debugging): Fixing issues around debugging Golang functions. #565 fix(init): Improve current init samples around docs and fixes #558 refactor(init): renamed handler for camel case, moved callback call up #586 chore: aws-lambda-java-core 1.1.0 -> 1.2.0 for java sam init #578 feat(validate): Add profile and region options #582 fix(start-lambda): Remove Content-Type Header check #594 fix: Fix stringifying λ environment variables when using Python2 #579 feat(generate-event): Added support for 50+ events #612 feat(invoke): Add region parameter to all invoke related commands #608 chore: Update JVM size params to match docker-lambda #615 feat(invoke): Invoke Function Without Parameters through --no-event #604 Many many doc updates!

What is new in 🐿?

This release has two exciting features that make it even easier to programmatically test and troubleshoot your serverless applications. Here is the TL;DR:

1. Run your automated tests in a local, Lambda-like environment using the AWS SDKs
2. Troubleshoot your Lambda functions using the sam logs command to fetch, tail & filter your function logs.

Upgrade now to v0.5.0

pip install --upgrade aws-sam-cli

Run automated tests in a local, lambda-like environment

Previously, you could use the sam local invoke command to run your Lambda functions locally and manually test your code. With this release, SAM CLI makes it easier to author automated integration tests by letting you run tests against local Lambda functions before deploying to the cloud. The new sam local start-lambda command starts a local endpoint that emulates the AWS Lambda service’s invoke endpoint, and you can invoke it from your automated tests. Because this endpoint emulates the Lambda service's invoke endpoint, you can write tests once and run them (without any modifications) against the local Lambda function or against a deployed Lambda function. You can also run the same tests against a deployed SAM stack in your CI/CD pipeline.

Here is how this works:

1. Start the Local Lambda Endpoint Start the local Lambda endpoint by running the following command in the directory that contains your AWS SAM template:

sam local start-lambda

This command starts a local endpoint at http://127.0.0.1:3001 that emulates the AWS Lambda service, and you can run your automated tests against this local Lambda endpoint. When you send an invoke to this endpoint using the AWS CLI or SDK, it will locally execute the Lambda function specified in the request and return a response.

2. Run integration test against local Lambda endpoint In your integration test, you can use AWS SDK to invoke your Lambda function with test data, wait for response, and assert that the response what you expect. To run the integration test locally, you should configure AWS SDK to send Lambda Invoke API call to local Lambda endpoint started in previous step.

Here is an Python example (AWS SDK for other languages have similar configurations):

import boto3

# Set "running_locally" flag if you are running the integration test locally
if running_locally:

    # Create Lambda SDK client to connect to appropriate Lambda endpoint
    lambda_client = boto3.client('lambda',
                                 endpoint_url="http://127.0.0.1:3001",
                                 use_ssl=False,
                                 verify=False,
                                 config=Config(signature_version=UNSIGNED,
                                               read_timeout=0,
                                               retries={'max_attempts': 0}))
else:
    lambda_client = boto3.client('lambda')
                                        

# Invoke your Lambda function as you normally usually do. The function will run 
# locally if it is configured to do so
response = lambda_client.invoke(FunctionName="HelloWorldFunction")

# Verify the response 
assert response == "Hello World"

This code can run without modifications against a Lambda function which is deployed. To do so, set the running_locally flag to False . This will setup AWS SDK to connect to AWS Lambda service on the cloud.

Fetch, tail, and filter your function logs using the new sam logs command

To simplify troubleshooting, we added a new command called sam logs to SAM CLI. sam logs lets you fetch logs generated by your Lambda function from the command line. In addition to printing the logs on the terminal, this command has several nifty features to help you quickly find the bug. Note: This command works for all AWS Lambda functions; not just the ones you deploy using SAM.

Basic Usage: Using CloudFormation Stack When your function is a part of a CloudFormation stack, you can fetch logs using the function's LogicalID:

sam logs -n HelloWorldFunction --stack-name mystack

Basic Usage: Using Lambda Function name Or, you can fetch logs using the function's name

sam logs -n mystack-HelloWorldFunction-1FJ8PD

Tail Logs Add --tail option to wait for new logs and see them as they arrive. This is very handy during deployment or when troubleshooting a production issue.

sam logs -n HelloWorldFunction --stack-name mystack --tail

View logs for specific time range You can view logs for specific time range using the -s and -e options

sam logs -n HelloWorldFunction --stack-name mystack -s '10min ago' -e '2min ago'

Filter Logs Use the --filter option to quickly find logs that match terms, phrases or values in your log events

sam logs -n HelloWorldFunction --stack-name mystack --filter "error"

In the output, SAM CLI will underline all occurrences of the word “error” so you can easily locate the filter keyword within the log output.

Error Highlighting When your Lambda function crashes or times out, SAM CLI will highlight the timeout message in red. This will help you easily locate specific executions that are timing out within a giant stream of log output.

<img width="1278" alt="42301038-3363a366-7fc8-11e8-9d0e-308b209cb92b" src="https://user-images.githubusercontent.com/22755571/42782490-f84cea3c-88fd-11e8-9c4e-5f8aeb730bc0.png">

JSON pretty printing If your log messages print JSON strings, SAM CLI will automatically pretty print the JSON to help you visually parse and understand the JSON.

<img width="801" alt="42301064-50c6cffa-7fc8-11e8-8f31-04ef117a9c5a" src="https://user-images.githubusercontent.com/22755571/42782507-01c4a4f6-88fe-11e8-982a-764e4724a19e.png">

More features & Bug fixes

• Support for running dotnetcore2.1 Lambda functions locally (#545)
• Support for long running Lambda functions & debugging sessions. Previously SAM CLI's socket connection to the Docker container will break when session lasted > 60 seconds (#422)
• Fixing the bug where SAM CLI didn't work when arbitrary proxy path names (#505)

Thanks to the amazing community for contributing features, reporting bugs, and helping out with pull requests. You are awesome 🔥

This release captures another milestone with Python3.6 being fully supported. We have also captured numerous bug/regressions fixes since version 0.3.0. See Changelog below for more details.

CHANGELOG

Tell Flask we are running the service in main (#491) Proper setting of permissions for the tempdir on posix systems. (#485) add version field to schedule event generator (#471) Prevent form data from being consumed by Flask (#419) Preserve file permissions when decompressing a zip file (#464) Python3 support (#446) Options requests not invoking Local Lambda (#468) Update Flask version to 1.0.2 (#459) Value of QueryString in the API Event should be a string (#405) download a swagger file form a given S3 location (#444) Do not add DefinitionUri when Definitionbody Property is given (#447) sam init Dotnet templates to use Cake for builds (#401) Allow for case insensitive header names (#398)

What's new in 🐿?

This release is an important milestone - New command to get started with SAM apps, full fidelity SAM Template validation, tons of bug fixes, and greatly improved stability. Oh did I mention, we rewrote the entire CLI from the ground up?! Yes, in 🐍. With this refresh, SAM CLI uses the recently open sourced transform, enabling you leverage any new SAM functionality immediately after release.

Features

New Command: sam init

sam init is a new command that lets you quickly get started with a SAM app in any runtime of your choice. Just install the CLI and type sam init to create a new "Hello World" SAM app that includes everything (directory structure, tests, SAM template, instructions) you need to get started with serverless and eventually grow into a production scale application.

The cool part is, you can use custom templates to initialize a SAM app. For example, you could create a boilerplate SAM app specific for your organization and publish to a private GitHub repo. Others in your organization can run sam init --location gh:your-org/your-repo to initialize an app. Applications initialized using sam init can be customized to use a different project name, Lambda runtime or even include/exclude various functionalities. Check out the sam init documentation for more information.

Full Fidelity SAM Validation

SAM CLI now provides full-fidelity validation of SAM templates because it uses the recently open-sourced SAM implementation. A template that passes sam validate command locally will pass the validation when deployed through AWS CloudFormation.

SAM Local CLI → SAM CLI

If you didn't already notice, we have started calling this tool "SAM CLI" instead of "SAM Local CLI". This is a non-functional change we are making to better align the tool with its purpose - simplify the process of creating, deploying and maintaining serverless apps using the command line.

Installation Instructions

We now support a PIP-based installation method. To install the new SAM CLI, use the following

# Uninstall the old CLI if you had originally installed
npm uninstall -g aws-sam-local

# Install the new CLI through PIP
pip install --user aws-sam-cli

Go → Python

With this release, we have rewritten SAM CLI in Python to use the open-sourced AWS SAM implementation. As a user, you should notice no difference but as a contributor to the CLI, you would have to adjust your development workflow. We have a detailed DEVELOPMENT_GUIDE.rst to help you quickly ramp up. Read the DESIGN.rst for more details on design rationale and decisions.

Changes to CloudFormation intrinsic functions support

There are two notable changes regarding how intrinsic functions are handled within the CLI:

1. If you use an Inline Swagger definition (in DefinitionBody property) property and use Fn::Join to construct the Lambda Integration ARN in the x-amazon-apigateway-integration section, you would have to convert this to Fn::Sub to work with SAM CLI as of this release. You can easily convert Fn::Join to Fn::Sub without any loss of functionality. For example:

A Fn::Join usage like this:
{
"Fn::Join": ["", ["arn:aws:apigateway:", {"Ref": "AWS::Region"}, ":lambda:path/2015-03-31/functions/", {"Fn::GetAtt": ["MyFunction", "Arn"]}, "/invocations"]]
}

Can be converted to:
{
"Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${MyFunction.Arn}/invocations"
}

1. If you use CloudFormation parameters with default values to reference a Lambda Function's Timeout or Runtime properties, you now need to specify the values of these in the template. If you are using template parameters to standardize the value of Runtime or Timeout across all your functions, you use Globals to specify the value once and have it applied to all your functions.

Parameters:
  NodeRuntime:
    Default: nodejs6.10

Function1:
  Type: AWS::Serverless::Function
  Properties:
    Runtime: !Ref NodeRuntime
    ...
```yaml

You can convert it to:
```yaml
Globals:
  Function:
    # All your functions will get nodejs6.10 runtime
    Runtime: nodejs6.10

Function1:
  Type: AWS::Serverless::Function
  Properties:
    ...

Bug Fixes

• Full fidelity SAM template validation https://github.com/awslabs/aws-sam-local/issues/342
• Globals support https://github.com/awslabs/aws-sam-local/issues/234 and https://github.com/awslabs/aws-sam-local/issues/226
• Value of APIGW Path property on proxy response is now correct https://github.com/awslabs/aws-sam-local/issues/244
• NPM Installation issues https://github.com/awslabs/aws-sam-local/issues/263
• Empty values in Api Event are 'null' instead of empty map/lists https://github.com/awslabs/aws-sam-local/issues/338 and https://github.com/awslabs/aws-sam-local/issues/340
• Content-Type of application/json is always added to headers https://github.com/awslabs/aws-sam-local/issues/329 and https://github.com/awslabs/aws-sam-local/issues/325 and https://github.com/awslabs/aws-sam-local/issues/361
• Full featured YAML support for parsing complex intrinsic functions like !Ref, !GetAtt without failing in template parsing - https://github.com/awslabs/aws-sam-local/issues/342
• Parity with credential resolutions mechanisms supported by AWS CLI since SAM CLI now uses boto3 https://github.com/awslabs/aws-sam-local/issues/372
• Better support for ANY method https://github.com/awslabs/aws-sam-local/issues/289
• Encode JSON output from generate-event https://github.com/awslabs/aws-sam-local/issues/214
• Works with Chalice out-of-box https://github.com/awslabs/aws-sam-local/issues/141#issuecomment-332290858
• Compatibility with API Gateway Binary Media Types implementation https://github.com/awslabs/aws-sam-local/issues/312
• Relative paths in CodeUri get resolved with respect to template path https://github.com/awslabs/aws-sam-local/pull/279 https://github.com/awslabs/aws-sam-local/issues/170
• Make multiple invokes in parallel https://github.com/awslabs/aws-sam-local/issues/301#issuecomment-385066464
• Support AWS::Include to inline a Swagger file