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](https://github.com/awslabs/serverless-application-model). 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](DEVELOPMENT_GUIDE.rst) to help you quickly ramp up. Read the [DESIGN.rst](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"
}
2. 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.
yaml
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](https://github.com/awslabs/aws-sam-local/issues/342)
- Globals support [https://github.com/awslabs/aws-sam-local/issues/234](https://github.com/awslabs/aws-sam-local/issues/234) and [https://github.com/awslabs/aws-sam-local/issues/226](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](https://github.com/awslabs/aws-sam-local/issues/244)
- NPM Installation issues [https://github.com/awslabs/aws-sam-local/issues/263](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](https://github.com/awslabs/aws-sam-local/issues/338) and [https://github.com/awslabs/aws-sam-local/issues/340](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](https://github.com/awslabs/aws-sam-local/issues/329) and [https://github.com/awslabs/aws-sam-local/issues/325](https://github.com/awslabs/aws-sam-local/issues/325) and [https://github.com/awslabs/aws-sam-local/issues/361](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](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](https://github.com/awslabs/aws-sam-local/issues/372)
- Better support for ANY method [https://github.com/awslabs/aws-sam-local/issues/289](https://github.com/awslabs/aws-sam-local/issues/289)
- Encode JSON output from `generate-event` [https://github.com/awslabs/aws-sam-local/issues/214](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](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](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/pull/279) [https://github.com/awslabs/aws-sam-local/issues/170](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](https://github.com/awslabs/aws-sam-local/issues/301#issuecomment-385066464)
- Support AWS::Include to inline a Swagger file