Optimizing serverless development with samconfig

The AWS Serverless Application Model (AWS SAM) is an open-source framework for building serverless applications using infrastructure as code (IaC). Using shorthand syntax, developers declare AWS CloudFormation resources or specialized serverless resources that are transformed to infrastructure during deployment.

AWS SAM commands list

AWS SAM’s companion, the AWS SAM Command Line Interface (CLI), provides a set of commands to help developers create, develop, and deploy serverless applications. Each of these commands is configurable with optional flags based on the preferences of the application and developer. This post shows how you can optimize development time by customizing the default settings for a serverless application by using the samconfig.

Creating the samconfig file

The samconfig.toml is a text file that uses the Tom’s Obvious Minimal Language (TOML) structure. AWS SAM creates the file the first time you run the sam deploy –guided command to deploy an application. For example, I run the deploy command and enter the appropriate information:

Guided SAM deployment

The AWS SAM CLI stores this information in the samconfig file:

Initial samconfig file after deployment

After the deployment is complete, if you used the default values, the samconfig file contains a profile named default. When I rerun the deploy command, AWS SAM applies the stored configuration settings from this profile.

The benefit of the samconfig file is that AWS SAM stores configuration settings for any other commands available in addition to the deploy command. Beyond these values created at a new deploy, there are a number of attributes that you can set in the samconfig. These can simplify other aspects of the developer workflow with AWS SAM CLI.

AWS SAM build

The AWS SAM build command has many options available when used to build serverless applications. For example, set the AWS user profile with the --profile flag or change the build directory to store the built artifacts with the --build-directory flag.

There are two commonly used configuration flags. The --cached flag configures AWS SAM to save each built AWS Lambda function or AWS Lambda layer as an artifact in a cache directory. The next time I build, AWS SAM checks for differences in the Lambda function or layer. If there is no difference, AWS SAM uses the cached version if available.

During the build process, AWS SAM builds each Lambda function and layer separately, one after the other. The --parallel flag configures AWS SAM to build each resource at the same time. This flag is optional as it requires more resources on your development machine. I connect remotely to a large Amazon EC2 instance via AWS Cloud9 so I choose to build resources with the parallel option.

To enable by default, add these options to the samconfig file. First, create the default.build section of the TOML file and add the default.build.parameters section. Then add the required settings to the parameters group.

Another important parameter is the --use-container flag. This option configures AWS SAM to use an AWS managed container to build the application. This change ensures that any compiled artifacts are compatible with the Lambda service’s architecture.

This option is also helpful if your local development environment is not configured for a particular runtime. For example, if the local environment is configured for Python 3.7 and the application runtime is set to Python 3.8, use this option to avoid changing the local environment. Note that this option is not currently available for all runtimes.

The final samconfig setting for AWS SAM build is:

Final SAM Build configuration example

These settings reduce:

sam build --cached --parallel --use-containers

To the shorter version:

sam build

When you run the build command, AWS SAM uses the cached and parallel options and does the build work in a container. You can also add other, less common flags as needed. For example, to specify a particular build directory:

sam build --build-directory /my/build/directory

AWS SAM local

The AWS SAM local command allows developers to emulate the Lambda service locally by using the local invoke and local start-lambda commands. It also emulates calling a Lambda function via an Amazon API Gateway REST API or HTTP API using the local start-api command. Like the build command, each of these commands for AWS SAM local has many different options.

For the local invoke command, the --env-vars parameter passes the path to a local environment variables file. The file maps resources in the cloud to variables for the local development environment. This mapping allows a local version of a Lambda function to access these live resources. An example of an environment file is:

Example environment variables file

For example, I always name the environment file locals.json to make it easier to remember and consistent for local testing. To set this default, add the entry in the samconfig file for the AWS SAM local invoke command.

Default environment file setting

To do this, add another command to the default group called default.local_invoke and add a parameters group as you did for the build command. Note that the underline represents a space in the command. This syntax is part of the samconfig convention found in the samconfig documentation.

The last set of parameters is for the sam local start-api command:

sam local start-api --env-vars locals.json --warm-containers EAGER

This command starts a local API Gateway emulator for REST APIs or HTTP APIs with an endpoint for local client testing. Use the locals.json file for environment variables and a new option called warm-containers.

The warm-containers option tells AWS SAM to run each endpoint in a container and keep it active until you stop the service. The warm-containers parameter takes one of two values EAGER or LAZY. EAGER instructs AWS SAM to load all the containers at launch time and have them ready to invoke on request. LAZY instructs AWS SAM to load the endpoint into a container only on the first invocation. The container is then kept warm for followup calls. Finally, if you change the code for that endpoint, AWS SAM reloads the container on the next invocation as well.

To add these setting to the samconfig file, enter:

Warm container settings

With all of the common settings I use in place, the complete samconfig file looks like this:

version = 0.1
[default]
[default.build]
[default.build.parameters]
cached=true
parallel=true
use_container=true

[default.local_invoke]
[default.local_invoke.parameters]
env_vars="locals.json"

[default.local_start_api]
[default.local_start_api.parameters]
env_vars="locals.json"
warm_containers="EAGER"

Adding samconfig to a project

AWS SAM creates the samconfig file when you deploy an application for the first time and choose to save the settings. However, you may need a samconfig file for local development before deployment. To do this, use the sam init command. Note that this overwrites any existing samconfig.toml file. To add this starter template to a current project, use the following command:

sam init

For the template source, choose 2 – Custom Template Location, and for the location, enter https://github.com/aws-samples/samconfig-starter. For the project name, keep the default of samconfig.

SAM config starter example

Once complete, AWS SAM copies the samconfig file from the repository to your project. After this change, running AWS SAM commands for the build, local invoke, and local start-api run with these default settings applied.

As a result, the following optimization occurs:

The first time you run sam deploy --guided, AWS SAM saves the deploy settings to this file.

Conclusion

AWS SAM helps developers take serverless applications from new idea to production in a reduced amount of time. One of the benefits of AWS SAM is to optimize a developer’s time by removing repetitive actions. AWS SAM CLI uses the samconfig file for this purpose.

In this post, I cover some examples that you can use in your own samconfig files. Each of these can help accelerate serverless development and reduce human error from typing command parameters. You can use these in both new and existing projects to see the same benefits.

I hope this post helps to add efficiency to your development cycle with AWS SAM. For more tips, visit https://serverlessland.com/video?tag=AWS%20SAM.

#ServerlessForEveryone