# Develop your serverless application with AWS SAM
This section contains topics about validating your AWS SAM template and building your application with dependencies. It also contains topics about using AWS SAM for certain use cases such as working with Lambda layers, using nested applications, controlling access to API Gateway APIs, orchestrating AWS resources with Step Functions, and code signing your applications. The three major milestones you need to complete to develop your application are listed below.
**Topics**
+ [
# Create your application in AWS SAM
](using-sam-cli-init.md)
+ [
# Define your infrastructure with AWS SAM
](serverless-authoring.md)
+ [
# Build your application with AWS SAM
](serverless-building.md)
# Create your application in AWS SAM
After completing [Getting started](serverless-getting-started.md) and reading [How to use AWS Serverless Application Model (AWS SAM)](chapter-using-sam.md), you will be ready to create an AWS SAM project in your developer environment. Your AWS SAM project will serve as the starting point for writing your serverless application. For a list of AWS SAM CLI `sam init` command options, see [sam init](sam-cli-command-reference-sam-init.md).
The AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam init` command provides options to initialize a new serverless application that consists of:
+ An AWS SAM template to define your infrastructure code.
+ A folder structure that organizes your application.
+ Configuration for your AWS Lambda functions.
To create an AWS SAM project, refer to the topics in this sections.
**Note**
`sam init` includes project templates for durable functions in supported runtimes (TypeScript, Python, Java). These templates provide starter code and configuration for building stateful serverless applications.
**Topics**
+ [
## Initialize a new serverless application
](#using-sam-cli-init-new)
+ [
## Options for sam init
](#using-sam-cli-init-options)
+ [
## Troubleshooting
](#using-sam-cli-init-troubleshooting)
+ [
## Examples
](#using-sam-cli-init-examples)
+ [
## Learn more
](#using-sam-cli-init-learn)
+ [
## Next steps
](#w2aac18c11c39)
## Initialize a new serverless application
**To initialize a new serverless application using the AWS SAM CLI**
1. `cd` to a starting directory.
1. Run the following at the command line:
```
$ sam init
```
1. The AWS SAM CLI will guide you through an interactive flow to create a new serverless application.
**Note**
As detailed in [Tutorial: Deploy a Hello World application with AWS SAM](serverless-getting-started-hello-world.md), this command initializes your serverless application, creating your project directory. This directory will contain several files and folders. The most important file is `template.yaml`. This is your AWS SAM template. Your version of python must match the version of python listed in the `template.yaml` file that the **sam init** command created.
### Choose a starting template
A *template* consists of the following:
1. An AWS SAM template for your infrastructure code.
1. A starting project directory that organizes your project files. For example, this may include:
1. A structure for your Lambda function code and their dependencies.
1. An `events` folder that contains test events for local testing.
1. A `tests` folder to support unit testing.
1. A `samconfig.toml` file to configure project settings.
1. A `ReadMe` file and other basic starting project files.
The following is an example of a starting project directory:
```
sam-app
├── README.md
├── __init__.py
├── events
│ └── event.json
├── hello_world
│ ├── __init__.py
│ ├── app.py
│ └── requirements.txt
├── samconfig.toml
├── template.yaml
└── tests
├── __init__.py
├── integration
│ ├── __init__.py
│ └── test_api_gateway.py
├── requirements.txt
└── unit
├── __init__.py
└── test_handler.py
```
You can select from a list of available *AWS Quick Start Templates* or provide your own *Custom Template Location*.
**To choose an AWS Quick Start Template**
1. When prompted, select **AWS Quick Start Templates**.
1. Select an AWS Quick Start template to begin with. The following is an example:
```
Which template source would you like to use?
1 - AWS Quick Start Templates
2 - Custom Template Location
Choice: 1
Choose an AWS Quick Start application template
1 - Hello World Example
2 - Multi-step workflow
3 - Serverless API
4 - Scheduled task
5 - Standalone function
6 - Data processing
7 - Hello World Example With Powertools
8 - Infrastructure event management
9 - Serverless Connector Hello World Example
10 - Multi-step workflow with Connectors
11 - Lambda EFS example
12 - DynamoDB Example
13 - Machine Learning
Template: 4
```
**To choose your own custom template location**
1. When prompted, select the **Custom Template Location**.
```
Which template source would you like to use?
1 - AWS Quick Start Templates
2 - Custom Template Location
Choice: 2
```
1. The AWS SAM CLI will prompt you to provide a template location.
```
Template location (git, mercurial, http(s), zip, path):
```
Provide any of the following locations to your template .zip file archive:
+ **GitHub repository** – The path to the .zip file in your GitHub repository. The file must be in the root of your repository.
+ **Mercurial repository** – The path to the .zip file in your Mercurial repository. The file must be in the root of your repository.
+ **.zip path** – An HTTPS or local path to your .zip file.
1. The AWS SAM CLI will initialize your serverless application using your custom template.
### Choose a runtime
When you choose an *AWS Quick Start Template*, the AWS SAM CLI prompts you to select a runtime for your Lambda functions. The list of options displayed by the AWS SAM CLI are the runtimes supported natively by Lambda.
+ The [runtime](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-concepts.html#gettingstarted-concepts-runtime) provides a language-specific environment that runs in an execution environment.
+ When deployed to the AWS Cloud, the Lambda service invokes your function in an [execution environment](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtime-environment.html).
You can use any other programming language with a custom runtime. To do this, you need to manually create your starting application structure. You can then use `sam init` to quickly initialize your application by configuring a custom template location.
From your selection, the AWS SAM CLI creates the starting directory for your Lambda function code and dependencies.
If Lambda supports multiple dependency managers for your runtime, you will be prompted to choose your preferred dependency manager.
### Choose a package type
When you choose an *AWS Quick Start Template* and a *runtime*, the AWS SAM CLI prompts you to select a *package type*. The package type determines how your Lambda functions are deployed to use with the Lambda service. The two supported package types are:
1. **Container image** – Contains the base operating system, the runtime, Lambda extensions, your application code, and its dependencies.
1. **.zip file archive** – Contains your application code and its dependencies.
To learn more about deployment package types, see [Lambda deployment packages](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-package.html) in the *AWS Lambda Developer Guide*.
The following is an example directory structure of an application with a Lambda function packaged as a container image. The AWS SAM CLI downloads the image and creates a `Dockerfile` in the function's directory to specify the image.
```
sam-app
├── README.md
├── __init__.py
├── events
│ └── event.json
├── hello_world
│ ├── Dockerfile
│ ├── __init__.py
│ ├── app.py
│ └── requirements.txt
├── samconfig.toml
├── template.yaml
└── tests
├── __init__.py
└── unit
├── __init__.py
└── test_handler.py
```
The following is an example directory structure of an application with a function packaged as a .zip file archive.
```
sam-app
├── README.md
├── __init__.py
├── events
│ └── event.json
├── hello_world
│ ├── __init__.py
│ ├── app.py
│ └── requirements.txt
├── samconfig.toml
├── template.yaml
└── tests
├── __init__.py
├── integration
│ ├── __init__.py
│ └── test_api_gateway.py
├── requirements.txt
└── unit
├── __init__.py
└── test_handler.py
```
### Configure AWS X-Ray tracing
You can choose to activate AWS X-Ray tracing. To learn more, see [What is AWS X-Ray?](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html) in the *AWS X-Ray Developer Guide*.
If you activate, the AWS SAM CLI configures your AWS SAM template. The following is an example:
```
Globals:
Function:
...
Tracing: Active
Api:
TracingEnabled: True
```
### Configure monitoring with Amazon CloudWatch Application Insights
You can choose to activate monitoring using Amazon CloudWatch Application Insights. To learn more, see [Amazon CloudWatch Application Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-application-insights.html) in the *Amazon CloudWatch User Guide*.
If you activate, the AWS SAM CLI configures your AWS SAM template. The following is an example:
```
Resources:
ApplicationResourceGroup:
Type: AWS::ResourceGroups::Group
Properties:
Name:
Fn::Join:
- ''
- - ApplicationInsights-SAM-
- Ref: AWS::StackName
ResourceQuery:
Type: CLOUDFORMATION_STACK_1_0
ApplicationInsightsMonitoring:
Type: AWS::ApplicationInsights::Application
Properties:
ResourceGroupName:
Fn::Join:
- ''
- - ApplicationInsights-SAM-
- Ref: AWS::StackName
AutoConfigurationEnabled: 'true'
DependsOn: ApplicationResourceGroup
```
### Name your application
Provide a name for your application. The AWS SAM CLI creates a top-level folder for your application using this name.
## Options for sam init
The following are some of the main options you can use with the `sam init` command. For a list of all options, see [sam init](sam-cli-command-reference-sam-init.md).
### Initialize an application using a custom template location
Use the `--location` option and provide a supported custom template location. The following is an example:
```
$ sam init --location https://github.com/aws-samples/sessions-with-aws-sam/raw/master/starter-templates/web-app.zip
```
### Initialize an application without the interactive flow
Use the `--no-interactive` option and provide your configuration choices at the command line to skip the interactive flow. The following is an example:
```
$ sam init --no-interactive --runtime go1.x --name go-demo --dependency-manager mod --app-template hello-world
```
## Troubleshooting
To troubleshoot the AWS SAM CLI, see [AWS SAM CLI troubleshooting](sam-cli-troubleshooting.md).
## Examples
### Initialize a new serverless application using the Hello World AWS Starter Template
For this example, see [Step 1: Initialize the sample Hello World application](serverless-getting-started-hello-world.md#serverless-getting-started-hello-world-init) in *Tutorial: Deploying a Hello World application*.
### Initialize a new serverless application with a custom template location
The following are examples of providing a GitHub location to your custom template:
```
$ sam init --location gh:aws-samples/cookiecutter-aws-sam-python
$ sam init --location git+sh://git@github.com/aws-samples/cookiecutter-aws-sam-python.git
$ sam init --location hg+ssh://hg@bitbucket.org/repo/template-name
```
The following is an example of a local file path:
```
$ sam init --location /path/to/template.zip
```
The following is an example of a path reachable by HTTPS:
```
$ sam init --location https://github.com/aws-samples/sessions-with-aws-sam/raw/master/starter-templates/web-app.zip
```
## Learn more
To learn more about using the `sam init` command, see the following:
+ **[Learning AWS SAM: sam init](https://www.youtube.com/watch?v=9m3R-leD5Xo) ** – Serverless Land "Learning AWS SAM" series on YouTube.
+ **[Structuring serverless applications for use with the AWS SAM CLI (Sessions with SAM S2E7)](https://www.youtube.com/watch?v=k9IRdgze9fQ)** – Sessions with AWS SAM series on YouTube.
## Next steps
Now that you have created your AWS SAM project, you are ready to start authoring your application. See [Define your infrastructure with AWS SAM](serverless-authoring.md) for detailed instructions on the tasks you need to complete to do this.
# Define your infrastructure with AWS SAM
Now that you have created your project, you are ready to define your application infrastructure with AWS SAM. Do this by configuring your AWS SAM template to define your application's resources and properties, which is the `template.yaml` file in your AWS SAM project.
The topics in this section provide content on defining your infrastructure in your AWS SAM template (your `template.yaml` file). It also contains topics on defining resources for specific use cases, such as working with Lambda layers, using nested applications, controlling access to API Gateway APIs, orchestrating AWS resources with Step Functions, code signing your applications, and validating your AWS SAM template.
**Topics**
+ [
# Define application resources in your AWS SAM template
](authoring-define-resources.md)
+ [
# Set up and manage resource access in your AWS SAM template
](sam-permissions.md)
+ [
# Control API access with your AWS SAM template
](serverless-controlling-access-to-apis.md)
+ [
# Increase efficiency using Lambda layers with AWS SAM
](serverless-sam-cli-layers.md)
+ [
# Reuse code and resources using nested applications in AWS SAM
](serverless-sam-template-nested-applications.md)
+ [
# Manage time-based events with EventBridge Scheduler in AWS SAM
](using-eventbridge-scheduler.md)
+ [
# Orchestrating AWS SAM resources with AWS Step Functions
](serverless-step-functions-in-sam.md)
+ [
# Set up code signing for your AWS SAM application
](authoring-codesigning.md)
+ [
# Validate AWS SAM template files
](serverless-sam-cli-using-validate.md)
# Define application resources in your AWS SAM template
You define the AWS resources your serverless application uses in the `Resources` section of your AWS SAM template. When you define a resource, you identify what the resource is, how it interacts with other resources, and how it can be accessed (that is, the permissions of the resource).
The `Resources` section of your AWS SAM template can contain a combination of CloudFormation resources and AWS SAM resources. Additionally, you can use AWS SAM's short-hand syntax for the following resources:
| AWS SAM short-hand syntax | What it does with a related AWS resource |
| --- | --- |
| [AWS::Serverless::Api](sam-resource-api.md) | Creates a collection of API Gateway resources and methods that can be invoked through HTTPS endpoints. |
| [AWS::Serverless::Application](sam-resource-application.md) | Embeds a serverless application from the [AWS Serverless Application Repository](https://serverlessrepo.aws.amazon.com/applications) or from an Amazon S3 bucket as a nested application. |
| [AWS::Serverless::Connector](sam-resource-connector.md) | Configures permissions between two resources. For an introduction to connectors, see [Managing resource permissions with AWS SAM connectors](managing-permissions-connectors.md). |
| [AWS::Serverless::Function](sam-resource-function.md) | Creates an AWS Lambda function, an AWS Identity and Access Management (IAM) execution role, and event source mappings that trigger the function. |
| [AWS::Serverless::GraphQLApi](sam-resource-graphqlapi.md) | creates and configures an AWS AppSync GraphQL API for your serverless application. |
| [AWS::Serverless::HttpApi](sam-resource-httpapi.md) | Creates an Amazon API Gateway HTTP API, which enables you to create RESTful APIs with lower latency and lower costs than REST APIs. |
| [AWS::Serverless::LayerVersion](sam-resource-layerversion.md) | Creates a Lambda LayerVersion that contains library or runtime code needed by a Lambda Function. |
| [AWS::Serverless::SimpleTable](sam-resource-simpletable.md) | Creates a DynamoDB table with a single attribute primary key. |
| [AWS::Serverless::StateMachine](sam-resource-statemachine.md) | Creates an AWS Step Functions state machine, which you can use to orchestrate AWS Lambda functions and other AWS resources to form complex and robust workflows. |
The above resources are also listed in [AWS SAM resources and properties](sam-specification-resources-and-properties.md).
For reference information for all the AWS resource and property types CloudFormation and AWS SAM support, see [AWS resource and property types reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html) in the *AWS CloudFormation User Guide*.
# Set up and manage resource access in your AWS SAM template
For your AWS resources to interact with one another, the proper access and permissions must be configured between your resources. Doing this requires the configuration of AWS Identity and Access Management (IAM) users, roles, and policies to accomplish your interaction in a secure manner.
The topics in this section are all related to setting up access to the resources defined in your template. This section starts with general best practices. The next two topics review two options you have for setting up access and permissions between the resources referenced in your serverless application: AWS SAM connectors and AWS SAM policy templates. The last topic provides details for managing user access using the same mechanics CloudFormation uses for managing users.
To learn more, see [Controlling access with AWS Identity and Access Management](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-template.html) in the *AWS CloudFormation User Guide*.
The AWS Serverless Application Model (AWS SAM) provides two options that simplify management of access and permissions for your serverless applcations.
1. AWS SAM connectors
1. AWS SAM policy templates
## AWS SAM connectors
Connectors are a way of provisioning permissions between two resources. You do this by describing how they should interact with each other in your AWS SAM template. They can be defined using either the `Connectors` resource attribute or `AWS::Serverless::Connector` resource type. Connectors support the provisioning of `Read` and `Write` access of data and events between a combination of AWS resources. To learn more about AWS SAM connectors, see [Managing resource permissions with AWS SAM connectors](managing-permissions-connectors.md).
## AWS SAM policy templates
AWS SAM policy templates are pre-defined sets of permissions that you can add to your AWS SAM templates to manage access and permissions between your AWS Lambda functions, AWS Step Functions state machines and the resources they interact with. To learn more about AWS SAM policy templates, see [AWS SAM policy templates](serverless-policy-templates.md).
## AWS CloudFormation mechanisms
CloudFormation mechanisms include the configuring of IAM users, roles, and policies to manage permissions between your AWS resources. To learn more, see [Managing AWS SAM permissions with CloudFormation mechanisms](sam-permissions-cloudformation.md).
## Best practices
Throughout your serverless applications, you can use multiple methods to configure permissions between your resources. Therefore, you can select the best option for each scenario and use multiple options together throughout your applications. Here are a few things to consider when choosing the best option for you:
+ AWS SAM connectors and policy templates both reduce the IAM expertise required to facilitate secure interactions between your AWS resources. Use connectors and policy templates when supported.
+ AWS SAM connectors provide a simple and intuitive short-hand syntax to define permissions in your AWS SAM templates and require the least amount of IAM expertise. When both AWS SAM connectors and policy templates are supported, use AWS SAM connectors.
+ AWS SAM connectors can provision `Read` and `Write` access of data and events between supported AWS SAM source and destination resources. For a list of supported resources, see [AWS SAM connector reference](reference-sam-connector.md). When supported, use AWS SAM connectors.
+ While AWS SAM policy templates are limited to permissions between your Lambda functions, Step Functions state machines and the AWS resources they interact with, policy templates do support all CRUD operations. When supported, and when an AWS SAM policy template for your scenario is available, use AWS SAM policy templates. For a list of available policy templates, see [AWS SAM policy templates](serverless-policy-templates.md).
+ For all other scenarios, or when granularity is required, use CloudFormation mechanisms.
# Managing resource permissions with AWS SAM connectors
Connectors are an AWS Serverless Application Model (AWS SAM) abstract resource type, identified as `AWS::Serverless::Connector`, that provides simple and well-scoped permissions between your serverless application resources.
## Benefits of AWS SAM connectors
By automatically composing the appropriate access policies between resources, connectors give you the ability to author your serverless applications and focus on your application architecture without needing expertise in AWS authorization capabilities, policy language, and service-specific security settings. Therefore, connectors are a great benefit to developers who may be new to serverless development, or seasoned developers looking to increase their development velocity.
## Using AWS SAM connectors
Use the `Connectors` resource attribute by embedding it within a **source** resource. Then, define your **destination** resource and describe how data or events should flow between those resources. AWS SAM then composes the access policies necessary to facilitate the required interactions.
The following outlines how this resource attribute is written:
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
:
Type:
...
Connectors:
:
Properties:
Destination:
Permissions:
...
```
## How connectors work
**Note**
This section explains how connectors provision the necessary resources behind the scenes. This happens for you automatically when using connectors.
First, the embedded `Connectors` resource attribute is transformed into an `AWS::Serverless::Connector` resource type. Its logical ID is automatically created as **.
For example, here is an embedded connector:
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
MyFunction:
Type: AWS::Lambda::Function
Connectors:
MyConn:
Properties:
Destination:
Id: MyTable
Permissions:
- Read
- Write
MyTable:
Type: AWS::DynamoDB::Table
```
This will generate the following `AWS::Serverless::Connector` resource:
```
Transform: AWS::Serverless-2016-10-31
Resources:
...
MyFunctionMyConn:
Type: AWS::Serverless::Connector
Properties:
Source:
Id: MyFunction
Destination:
Id: MyTable
Permissions:
- Read
- Write
```
**Note**
You can also define connectors in your AWS SAM template by using this syntax. This is recommended when your source resource is defined on a separate template from your connector.
Next, the necessary access policies for this connection are automatically composed. For more information about the resources generated by connectors, see [CloudFormation resources generated when you specify AWS::Serverless::Connector](sam-specification-generated-resources-connector.md).
## Example of connectors
The following example shows how you can use connectors to write data from an AWS Lambda function to an Amazon DynamoDB table.
![\[A Lambda function writing data to a DynamoDB table using AWS SAM connectors.\]](http://docs.aws.amazon.com/serverless-application-model/latest/developerguide/images/managing-connectors-example.png)
```
Transform: AWS::Serverless-2016-10-31
Resources:
MyTable:
Type: AWS::Serverless::SimpleTable
MyFunction:
Type: AWS::Serverless::Function
Connectors:
MyConn:
Properties:
Destination:
Id: MyTable
Permissions:
- Write
Properties:
Runtime: nodejs16.x
Handler: index.handler
InlineCode: |
const AWS = require("aws-sdk");
const docClient = new AWS.DynamoDB.DocumentClient();
exports.handler = async (event, context) => {
await docClient.put({
TableName: process.env.TABLE_NAME,
Item: {
id: context.awsRequestId,
event: JSON.stringify(event)
}
}).promise();
}
Environment:
Variables:
TABLE_NAME: !Ref MyTable
```
The `Connectors` resource attribute is embedded within the Lambda function source resource. The DynamoDB table is defined as the destination resource using the `Id` property. Connectors will provision `Write` permissions between these two resources.
When you deploy your AWS SAM template to CloudFormation, AWS SAM will automatically compose the necessary access policies required for this connection to work.
## Supported connections between source and destination resources
Connectors support `Read` and `Write` data and event permission types between a select combination of source and destination resource connections. For example, connectors support a `Write` connection between an `AWS::ApiGateway::RestApi` source resource and an `AWS::Lambda::Function` destination resource.
Source and destination resources can be defined by using a combination of supported properties. Property requirements will depend on the connection you are making and where the resources are defined.
**Note**
Connectors can provision permissions between supported serverless and non-serverless resource types.
For a list of supported resource connections and their property requirements, see [Supported source and destination resource types for connectors](reference-sam-connector.md#supported-connector-resource-types).
# Define Read and Write permissions in AWS SAM
In AWS SAM, `Read` and `Write` permissions can be provisioned within a single connector:
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
MyFunction:
Type: AWS::Lambda::Function
Connectors:
MyTableConn:
Properties:
Destination:
Id: MyTable
Permissions:
- Read
- Write
MyTable:
Type: AWS::DynamoDB::Table
```
For more information on using connectors, refer to [AWS SAM connector reference](reference-sam-connector.md).
# Define resources by using other supported properties in AWS SAM
For both source and destination resources, when defined within the same template, use the `Id` property. Optionally, a `Qualifier` can be added to narrow the scope of your defined resource. When the resource is not within the same template, use a combination of supported properties.
+ For a list of supported property combinations for source and destination resources, see [Supported source and destination resource types for connectors](reference-sam-connector.md#supported-connector-resource-types).
+ For a description of properties that you can use with connectors, see [AWS::Serverless::Connector](sam-resource-connector.md).
When you define a source resource with a property other than `Id`, use the `SourceReference` property.
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
:
Type:
...
Connectors:
:
Properties:
SourceReference:
Qualifier:
Destination:
Permissions:
```
Here's an example, using a `Qualifier` to narrow the scope of an Amazon API Gateway resource:
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
MyApi:
Type: AWS::Serverless::Api
Connectors:
ApiToLambdaConn:
Properties:
SourceReference:
Qualifier: Prod/GET/foobar
Destination:
Id: MyFunction
Permissions:
- Write
...
```
Here's an example, using a supported combination of `Arn` and `Type` to define a destination resource from another template:
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
MyFunction:
Type: AWS::Serverless::Function
Connectors:
TableConn:
Properties:
Destination:
Type: AWS::DynamoDB::Table
Arn: !GetAtt MyTable.Arn
...
```
For more information on using connectors, refer to [AWS SAM connector reference](reference-sam-connector.md).
# Create multiple connectors from a single source in AWS SAM
Within a source resource, you can define multiple connectors, each with a different destination resource.
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
MyFunction:
Type: AWS::Serverless::Function
Connectors:
BucketConn:
Properties:
Destination:
Id: amzn-s3-demo-bucket
Permissions:
- Read
- Write
SQSConn:
Properties:
Destination:
Id: MyQueue
Permissions:
- Read
- Write
TableConn:
Properties:
Destination:
Id: MyTable
Permissions:
- Read
- Write
TableConnWithTableArn:
Properties:
Destination:
Type: AWS::DynamoDB::Table
Arn: !GetAtt MyTable.Arn
Permissions:
- Read
- Write
...
```
For more information on using connectors, refer to [AWS SAM connector reference](reference-sam-connector.md).
# Create multi-destination connectors in AWS SAM
Within a source resource, you can define a single connector with multiple destination resources. Here's an example of a Lambda function source resource connecting to an Amazon Simple Storage Service (Amazon S3) bucket and DynamoDB table:
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
MyFunction:
Type: AWS::Serverless::Function
Connectors:
WriteAccessConn:
Properties:
Destination:
- Id: OutputBucket
- Id: CredentialTable
Permissions:
- Write
...
OutputBucket:
Type: AWS::S3::Bucket
CredentialTable:
Type: AWS::DynamoDB::Table
```
For more information on using connectors, refer to [AWS SAM connector reference](reference-sam-connector.md).
# Define resource attributes with connectors in AWS SAM
Resource attributes can be defined for resources to specify additional behaviors and relationships. To learn more about resource attributes, see [Resource attribute reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-product-attribute-reference.html) in the *AWS CloudFormation User Guide*.
You can add resource attributes to your embedded connector by defining them on the same level as your connector properties. When your AWS SAM template is transformed at deployment, attributes will pass through to the generated resources.
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
MyFunction:
Type: AWS::Serverless::Function
Connectors:
MyConn:
DeletionPolicy: Retain
DependsOn: AnotherFunction
Properties:
...
```
For more information on using connectors, refer to [AWS SAM connector reference](reference-sam-connector.md).
## Learn more
For more information about using AWS SAM connectors, see the following topics:
+ [AWS::Serverless::Connector](sam-resource-connector.md)
+ [Define Read and Write permissions in AWS SAM](connector-usage-define.md)
+ [Define resources by using other supported properties in AWS SAM](connector-usage-other-properties.md)
+ [Create multiple connectors from a single source in AWS SAM](connector-usage-single-source.md)
+ [Create multi-destination connectors in AWS SAM](connector-usage-multi-destination.md)
+ [Define Read and Write permissions in AWS SAM](connector-usage-define.md)
+ [Define resource attributes with connectors in AWS SAM](connector-usage-resource-attributes.md)
## Provide feedback
To provide feedback on connectors, [submit a new issue](https://github.com/aws/serverless-application-model/issues/new?assignees=&labels=area%2Fconnectors,stage%2Fneeds-triage&template=other.md&title=%28Feature%20Request%29) at the *serverless-application-model AWS GitHub repository*.
# AWS SAM policy templates
The AWS Serverless Application Model (AWS SAM) allows you to choose from a list of policy templates to scope the permissions of your Lambda functions and AWS Step Functions state machines to the resources that are used by your application.
AWS SAM applications in the AWS Serverless Application Repository that use policy templates don't require any special customer acknowledgments to deploy the application from the AWS Serverless Application Repository.
If you want to request a new policy template to be added, do the following:
1. Submit a pull request against the policy\$1templates.json source file in the `develop` branch of the AWS SAM GitHub project. You can find the source file in [policy\$1templates.json](https://github.com/aws/serverless-application-model/blob/develop/samtranslator/policy_templates_data/policy_templates.json) on the GitHub website.
1. Submit an issue in the AWS SAM GitHub project that includes the reasons for your pull request and a link to the request. Use this link to submit a new issue: [AWS Serverless Application Model: Issues](https://github.com/aws/serverless-application-model/issues/new).
## Syntax
For every policy template you specify in your AWS SAM template file, you must always specify an object containing the policy template's placeholder values. If a policy template does not require any placeholder values, you must specify an empty object.
### YAML
```
MyFunction:
Type: AWS::Serverless::Function
Properties:
Policies:
- PolicyTemplateName1: # Policy template with placeholder value
Key1: Value1
- PolicyTemplateName2: {} # Policy template with no placeholder value
```
**Note**
If you have set up a regular IAM policy or have managed policies through Lambda, the policy template could be set without using an empty object.
## Examples
### Example 1: Policy template with placeholder values
The following example shows that the [SQSPollerPolicy](serverless-policy-template-list.md#sqs-poller-policy) policy template expects a `QueueName` as a resource. The AWS SAM template retrieves the name of the "`MyQueue`" Amazon SQS queue, which you can create in the same application or requested as a parameter to the application.
```
1. MyFunction:
2. Type: 'AWS::Serverless::Function'
3. Properties:
4. CodeUri: ${codeuri}
5. Handler: hello.handler
6. Runtime: python2.7
7. Policies:
8. - SQSPollerPolicy:
9. QueueName:
10. !GetAtt MyQueue.QueueName
```
### Example 2: Policy template with no placeholder values
The following example contains the [CloudWatchPutMetricPolicy](serverless-policy-template-list.md#cloudwatch-put-metric-policy) policy template, which has no placeholder values.
**Note**
Even though there are no placeholder values, you must specify an empty object, otherwise an error will result.
```
1. MyFunction:
2. Type: 'AWS::Serverless::Function'
3. Properties:
4. CodeUri: ${codeuri}
5. Handler: hello.handler
6. Runtime: python2.7
7. Policies:
8. - CloudWatchPutMetricPolicy: {}
```
### Example 3: Policy template with placeholder values and a regular IAM policy
The following example contains the AmazonSQSFullAcess policy and [DynamoDBCrudPolicy](serverless-policy-template-list.md#dynamo-db-crud-policy) policy template. The AmazonSQSFullAccess policy is an IAM policy and not a AWS SAM policy, so you don't have to specify an empty object as the policy would be directly passed to the CloudFormation.
```
1. MyFunction:
2. Type: 'AWS::Serverless::Function'
3. Properties:
4. CodeUri: ${codeuri}
5. Handler: hello.handler
6. Runtime: python2.7
7. Policies:
8. - AmazonSQSFullAccess // IAM policy could be set without passing an empty object
9. - DynamoDBCrudPolicy: // SAM specific policy, has a defined structure
10. TableName:
11. !Ref SampleTable
```
## Policy template table
The following is a table of the available policy templates.
****
| Policy Template | Description |
| --- | --- |
| [AcmGetCertificatePolicy](serverless-policy-template-list.md#acm-get-certificate-policy) | Gives a permission to read a certificate from AWS Certificate Manager. |
| [AMIDescribePolicy](serverless-policy-template-list.md#ami-describe-policy) | Gives permission to describe Amazon Machine Images (AMIs). |
| [AthenaQueryPolicy](serverless-policy-template-list.md#athena-query-policy) | Gives permissions to execute Athena queries. |
| [AWSSecretsManagerGetSecretValuePolicy](serverless-policy-template-list.md#secrets-manager-get-secret-value-policy) | Gives permission to get the secret value for the specified AWS Secrets Manager secret. |
| [AWSSecretsManagerRotationPolicy](serverless-policy-template-list.md#secrets-manager-rotation-policy) | Gives permission to rotate a secret in AWS Secrets Manager. |
| [CloudFormationDescribeStacksPolicy](serverless-policy-template-list.md#cloud-formation-describe-stacks-policy) | Gives permission to describe CloudFormation stacks. |
| [CloudWatchDashboardPolicy](serverless-policy-template-list.md#cloudwatch-dashboard-policy) | Gives permissions to put metrics to operate on CloudWatch dashboards. |
| [CloudWatchDescribeAlarmHistoryPolicy](serverless-policy-template-list.md#cloudwatch-describe-alarm-history-policy) | Gives permission to describe CloudWatch alarm history. |
| [CloudWatchPutMetricPolicy](serverless-policy-template-list.md#cloudwatch-put-metric-policy) | Gives permission to send metrics to CloudWatch. |
| [CodeCommitCrudPolicy](serverless-policy-template-list.md#codecommit-crud-policy) | Gives permissions to create/read/update/delete objects within a specific CodeCommit repository. |
| [CodeCommitReadPolicy](serverless-policy-template-list.md#codecommit-read-policy) | Gives permissions to read objects within a specific CodeCommit repository. |
| [CodePipelineLambdaExecutionPolicy](serverless-policy-template-list.md#code-pipeline-lambda-execution-policy) | Gives permission for a Lambda function invoked by CodePipeline to report the status of the job. |
| [CodePipelineReadOnlyPolicy](serverless-policy-template-list.md#code-pipeline-readonly-policy) | Gives read permission to get details about a CodePipeline pipeline. |
| [ComprehendBasicAccessPolicy](serverless-policy-template-list.md#comprehend-basic-access-policy) | Gives permission for detecting entities, key phrases, languages, and sentiments. |
| [CostExplorerReadOnlyPolicy](serverless-policy-template-list.md#cost-explorer-readonly-policy) | Gives read-only permission to the read-only Cost Explorer APIs for billing history. |
| [DynamoDBBackupFullAccessPolicy](serverless-policy-template-list.md#ddb-back-full-policy) | Gives read and write permission to DynamoDB on-demand backups for a table. |
| [DynamoDBCrudPolicy](serverless-policy-template-list.md#dynamo-db-crud-policy) | Gives create, read, update, and delete permissions to an Amazon DynamoDB table. |
| [DynamoDBReadPolicy](serverless-policy-template-list.md#dynamo-db-read-policy) | Gives read-only permission to a DynamoDB table. |
| [DynamoDBReconfigurePolicy](serverless-policy-template-list.md#dynamo-db-reconfigure-policy) | Gives permission to reconfigure a DynamoDB table. |
| [DynamoDBRestoreFromBackupPolicy](serverless-policy-template-list.md#ddb-restore-from-backup-policy) | Gives permission to restore a DynamoDB table from backup. |
| [DynamoDBStreamReadPolicy](serverless-policy-template-list.md#dynamo-db-stream-read-policy) | Gives permission to describe and read DynamoDB streams and records. |
| [DynamoDBWritePolicy](serverless-policy-template-list.md#dynamo-db-write-policy) | Gives write-only permission to a DynamoDB table. |
| [EC2CopyImagePolicy](serverless-policy-template-list.md#ec2-copy-image-policy) | Gives permission to copy Amazon EC2 images. |
| [EC2DescribePolicy](serverless-policy-template-list.md#ec2-describe-policy) | Gives permission to describe Amazon Elastic Compute Cloud (Amazon EC2) instances. |
| [EcsRunTaskPolicy](serverless-policy-template-list.md#ecs-run-task-policy) | Gives permission to start a new task for a task definition. |
| [EFSWriteAccessPolicy](serverless-policy-template-list.md#efs-write-access-policy) | Gives permission to mount an Amazon EFS file system with write access. |
| [EKSDescribePolicy](serverless-policy-template-list.md#eks-describe-policy) | Gives permission to describe or list Amazon EKS clusters. |
| [ElasticMapReduceAddJobFlowStepsPolicy](serverless-policy-template-list.md#elastic-map-reduce-add-job-flows-policy) | Gives permission to add new steps to a running cluster. |
| [ElasticMapReduceCancelStepsPolicy](serverless-policy-template-list.md#elastic-map-reduce-cancel-steps-policy) | Gives permission to cancel a pending step or steps in a running cluster. |
| [ElasticMapReduceModifyInstanceFleetPolicy](serverless-policy-template-list.md#elastic-map-reduce-modify-instance-fleet-policy) | Gives permission to list details and modify capacities for instance fleets within a cluster. |
| [ElasticMapReduceModifyInstanceGroupsPolicy](serverless-policy-template-list.md#elastic-map-reduce-modify-instance-groups-policy) | Gives permission to list details and modify settings for instance groups within a cluster. |
| [ElasticMapReduceSetTerminationProtectionPolicy](serverless-policy-template-list.md#elastic-map-reduce-set-termination-protection-policy) | Gives permission to set termination protection for a cluster. |
| [ElasticMapReduceTerminateJobFlowsPolicy](serverless-policy-template-list.md#elastic-map-reduce-terminate-job-flows-policy) | Gives permission to shut down a cluster. |
| [ElasticsearchHttpPostPolicy](serverless-policy-template-list.md#elastic-search-http-post-policy) | Gives POST permission to Amazon OpenSearch Service. |
| [EventBridgePutEventsPolicy](serverless-policy-template-list.md#eventbridge-put-events-policy) | Gives permissions to send events to EventBridge. |
| [FilterLogEventsPolicy](serverless-policy-template-list.md#filter-log-events-policy) | Gives permission to filter CloudWatch Logs events from a specified log group. |
| [FirehoseCrudPolicy](serverless-policy-template-list.md#firehose-crud-policy) | Gives permission to create, write, update, and delete a Firehose delivery stream. |
| [FirehoseWritePolicy](serverless-policy-template-list.md#firehose-write-policy) | Gives permission to write to a Firehose delivery stream. |
| [KinesisCrudPolicy](serverless-policy-template-list.md#kinesis-crud-policy) | Gives permission to create, publish, and delete an Amazon Kinesis stream. |
| [KinesisStreamReadPolicy](serverless-policy-template-list.md#kinesis-stream-read-policy) | Gives permission to list and read an Amazon Kinesis stream. |
| [KMSDecryptPolicy](serverless-policy-template-list.md#kms-decrypt-policy) | Gives permission to decrypt with an AWS Key Management Service (AWS KMS) key. |
| [KMSEncryptPolicy](serverless-policy-template-list.md#kms-encrypt-policy) | Gives permission to encrypt with an AWS Key Management Service (AWS KMS) key. |
| [LambdaInvokePolicy](serverless-policy-template-list.md#lambda-invoke-policy) | Gives permission to invoke an AWS Lambda function, alias, or version. |
| [MobileAnalyticsWriteOnlyAccessPolicy](serverless-policy-template-list.md#mobile-analytics-write-only-access-policy) | Gives write-only permission to put event data for all application resources. |
| [OrganizationsListAccountsPolicy](serverless-policy-template-list.md#organizations-list-accounts-policy) | Gives read-only permission to list child account names and IDs. |
| [PinpointEndpointAccessPolicy](serverless-policy-template-list.md#pinpoint-endpoint-access-policy) | Gives permission to get and update endpoints for an Amazon Pinpoint application. |
| [PollyFullAccessPolicy](serverless-policy-template-list.md#polly-full-access-policy) | Gives full access permission to Amazon Polly lexicon resources. |
| [RekognitionDetectOnlyPolicy](serverless-policy-template-list.md#rekognition-detect-only-policy) | Gives permission to detect faces, labels, and text. |
| [RekognitionFacesManagementPolicy](serverless-policy-template-list.md#rekognition-face-management-policy) | Gives permission to add, delete, and search faces in an Amazon Rekognition collection. |
| [RekognitionFacesPolicy](serverless-policy-template-list.md#rekognition-faces-policy) | Gives permission to compare and detect faces and labels. |
| [RekognitionLabelsPolicy](serverless-policy-template-list.md#rekognition-labels-policy) | Gives permission to detect object and moderation labels. |
| [RekognitionNoDataAccessPolicy](serverless-policy-template-list.md#rekognition-no-data-access-policy) | Gives permission to compare and detect faces and labels. |
| [RekognitionReadPolicy](serverless-policy-template-list.md#rekognition-read-policy) | Gives permission to list and search faces. |
| [RekognitionWriteOnlyAccessPolicy](serverless-policy-template-list.md#rekognition-write-only-access-policy) | Gives permission to create collection and index faces. |
| [Route53ChangeResourceRecordSetsPolicy](serverless-policy-template-list.md#route53-change-resource-record-sets-policy) | Gives permission to change resource record sets in Route 53. |
| [S3CrudPolicy](serverless-policy-template-list.md#s3-crud-policy) | Gives create, read, update, and delete permission to act on the objects in an Amazon S3 bucket. |
| [S3FullAccessPolicy](serverless-policy-template-list.md#s3-full-access-policy) | Gives full access permission to act on the objects in an Amazon S3 bucket. |
| [S3ReadPolicy](serverless-policy-template-list.md#s3-read-policy) | Gives read-only permission to read objects in an Amazon Simple Storage Service (Amazon S3) bucket. |
| [S3WritePolicy](serverless-policy-template-list.md#s3-write-policy) | Gives write permission to write objects into an Amazon S3 bucket. |
| [SageMakerCreateEndpointConfigPolicy](serverless-policy-template-list.md#sagemaker-create-endpoint-config-policy) | Gives permission to create an endpoint configuration in SageMaker AI. |
| [SageMakerCreateEndpointPolicy](serverless-policy-template-list.md#sagemaker-create-endpoint-policy) | Gives permission to create an endpoint in SageMaker AI. |
| [ServerlessRepoReadWriteAccessPolicy](serverless-policy-template-list.md#serverlessrepo-read-write-access-policy) | Gives permission to create and list applications in the AWS Serverless Application Repository service. |
| [SESBulkTemplatedCrudPolicy](serverless-policy-template-list.md#ses-bulk-templated-crud-policy) | Gives permission to send email, templated email, templated bulk emails and verify identity. |
| [SESBulkTemplatedCrudPolicy\$1v2](serverless-policy-template-list.md#ses-bulk-templated-crud-policy-v2) | Gives permission to send Amazon SES email, templated email, and templated bulk emails and to verify identity. |
| [SESCrudPolicy](serverless-policy-template-list.md#ses-crud-policy) | Gives permission to send email and verify identity. |
| [SESEmailTemplateCrudPolicy](serverless-policy-template-list.md#ses-email-template-crud-policy) | Gives permission to create, get, list, update and delete Amazon SES email templates. |
| [SESSendBouncePolicy](serverless-policy-template-list.md#ses-send-bounce-policy) | Gives SendBounce permission to an Amazon Simple Email Service (Amazon SES) identity. |
| [SNSCrudPolicy](serverless-policy-template-list.md#sns-crud-policy) | Gives permission to create, publish, and subscribe to Amazon SNS topics. |
| [SNSPublishMessagePolicy](serverless-policy-template-list.md#sqs-publish-message-policy) | Gives permission to publish a message to an Amazon Simple Notification Service (Amazon SNS) topic. |
| [SQSPollerPolicy](serverless-policy-template-list.md#sqs-poller-policy) | Gives permission to poll an Amazon Simple Queue Service (Amazon SQS) queue. |
| [SQSSendMessagePolicy](serverless-policy-template-list.md#sqs-send-message-policy) | Gives permission to send message to an Amazon SQS queue. |
| [SSMParameterReadPolicy](serverless-policy-template-list.md#ssm-parameter-read-policy) | Gives permission to access a parameter from an Amazon EC2 Systems Manager (SSM) parameter store to load secrets in this account. Use when parameter name doesn't have slash prefix. |
| [SSMParameterWithSlashPrefixReadPolicy](serverless-policy-template-list.md#ssm-parameter-slash-read-policy) | Gives permission to access a parameter from an Amazon EC2 Systems Manager (SSM) parameter store to load secrets in this account. Use when parameter name has slash prefix. |
| [StepFunctionsExecutionPolicy](serverless-policy-template-list.md#stepfunctions-execution-policy) | Gives permission to start a Step Functions state machine execution. |
| [TextractDetectAnalyzePolicy](serverless-policy-template-list.md#textract-detect-analyze-policy) | Gives access to detect and analyze documents with Amazon Textract. |
| [TextractGetResultPolicy](serverless-policy-template-list.md#textract-get-result-policy) | Gives access to get detected and analyzed documents from Amazon Textract. |
| [TextractPolicy](serverless-policy-template-list.md#textract-policy) | Gives full access to Amazon Textract. |
| [VPCAccessPolicy](serverless-policy-template-list.md#vpc-access-policy) | Gives access to create, delete, describe, and detach elastic network interfaces. |
## Troubleshooting
### SAM CLI error: "Must specify valid parameter values for policy template ''"
When executing `sam build`, you see the following error:
```
"Must specify valid parameter values for policy template ''"
```
This means that you did not pass an empty object when declaring a policy template that does not have any placeholder values.
To fix this, declare the policy like the following example for [CloudWatchPutMetricPolicy](serverless-policy-template-list.md#cloudwatch-put-metric-policy).
```
1. MyFunction:
2. Policies:
3. - CloudWatchPutMetricPolicy: {}
```
# AWS SAM policy template list
The following are the available policy templates, along with the permissions that are applied to each one. AWS Serverless Application Model (AWS SAM) automatically populates the placeholder items (such as AWS Region and account ID) with the appropriate information.
**Topics**
+ [
## AcmGetCertificatePolicy
](#acm-get-certificate-policy)
+ [
## AMIDescribePolicy
](#ami-describe-policy)
+ [
## AthenaQueryPolicy
](#athena-query-policy)
+ [
## AWSSecretsManagerGetSecretValuePolicy
](#secrets-manager-get-secret-value-policy)
+ [
## AWSSecretsManagerRotationPolicy
](#secrets-manager-rotation-policy)
+ [
## CloudFormationDescribeStacksPolicy
](#cloud-formation-describe-stacks-policy)
+ [
## CloudWatchDashboardPolicy
](#cloudwatch-dashboard-policy)
+ [
## CloudWatchDescribeAlarmHistoryPolicy
](#cloudwatch-describe-alarm-history-policy)
+ [
## CloudWatchPutMetricPolicy
](#cloudwatch-put-metric-policy)
+ [
## CodePipelineLambdaExecutionPolicy
](#code-pipeline-lambda-execution-policy)
+ [
## CodePipelineReadOnlyPolicy
](#code-pipeline-readonly-policy)
+ [
## CodeCommitCrudPolicy
](#codecommit-crud-policy)
+ [
## CodeCommitReadPolicy
](#codecommit-read-policy)
+ [
## ComprehendBasicAccessPolicy
](#comprehend-basic-access-policy)
+ [
## CostExplorerReadOnlyPolicy
](#cost-explorer-readonly-policy)
+ [
## DynamoDBBackupFullAccessPolicy
](#ddb-back-full-policy)
+ [
## DynamoDBCrudPolicy
](#dynamo-db-crud-policy)
+ [
## DynamoDBReadPolicy
](#dynamo-db-read-policy)
+ [
## DynamoDBReconfigurePolicy
](#dynamo-db-reconfigure-policy)
+ [
## DynamoDBRestoreFromBackupPolicy
](#ddb-restore-from-backup-policy)
+ [
## DynamoDBStreamReadPolicy
](#dynamo-db-stream-read-policy)
+ [
## DynamoDBWritePolicy
](#dynamo-db-write-policy)
+ [
## EC2CopyImagePolicy
](#ec2-copy-image-policy)
+ [
## EC2DescribePolicy
](#ec2-describe-policy)
+ [
## EcsRunTaskPolicy
](#ecs-run-task-policy)
+ [
## EFSWriteAccessPolicy
](#efs-write-access-policy)
+ [
## EKSDescribePolicy
](#eks-describe-policy)
+ [
## ElasticMapReduceAddJobFlowStepsPolicy
](#elastic-map-reduce-add-job-flows-policy)
+ [
## ElasticMapReduceCancelStepsPolicy
](#elastic-map-reduce-cancel-steps-policy)
+ [
## ElasticMapReduceModifyInstanceFleetPolicy
](#elastic-map-reduce-modify-instance-fleet-policy)
+ [
## ElasticMapReduceModifyInstanceGroupsPolicy
](#elastic-map-reduce-modify-instance-groups-policy)
+ [
## ElasticMapReduceSetTerminationProtectionPolicy
](#elastic-map-reduce-set-termination-protection-policy)
+ [
## ElasticMapReduceTerminateJobFlowsPolicy
](#elastic-map-reduce-terminate-job-flows-policy)
+ [
## ElasticsearchHttpPostPolicy
](#elastic-search-http-post-policy)
+ [
## EventBridgePutEventsPolicy
](#eventbridge-put-events-policy)
+ [
## FilterLogEventsPolicy
](#filter-log-events-policy)
+ [
## FirehoseCrudPolicy
](#firehose-crud-policy)
+ [
## FirehoseWritePolicy
](#firehose-write-policy)
+ [
## KinesisCrudPolicy
](#kinesis-crud-policy)
+ [
## KinesisStreamReadPolicy
](#kinesis-stream-read-policy)
+ [
## KMSDecryptPolicy
](#kms-decrypt-policy)
+ [
## KMSEncryptPolicy
](#kms-encrypt-policy)
+ [
## LambdaInvokePolicy
](#lambda-invoke-policy)
+ [
## MobileAnalyticsWriteOnlyAccessPolicy
](#mobile-analytics-write-only-access-policy)
+ [
## OrganizationsListAccountsPolicy
](#organizations-list-accounts-policy)
+ [
## PinpointEndpointAccessPolicy
](#pinpoint-endpoint-access-policy)
+ [
## PollyFullAccessPolicy
](#polly-full-access-policy)
+ [
## RekognitionDetectOnlyPolicy
](#rekognition-detect-only-policy)
+ [
## RekognitionFacesManagementPolicy
](#rekognition-face-management-policy)
+ [
## RekognitionFacesPolicy
](#rekognition-faces-policy)
+ [
## RekognitionLabelsPolicy
](#rekognition-labels-policy)
+ [
## RekognitionNoDataAccessPolicy
](#rekognition-no-data-access-policy)
+ [
## RekognitionReadPolicy
](#rekognition-read-policy)
+ [
## RekognitionWriteOnlyAccessPolicy
](#rekognition-write-only-access-policy)
+ [
## Route53ChangeResourceRecordSetsPolicy
](#route53-change-resource-record-sets-policy)
+ [
## S3CrudPolicy
](#s3-crud-policy)
+ [
## S3FullAccessPolicy
](#s3-full-access-policy)
+ [
## S3ReadPolicy
](#s3-read-policy)
+ [
## S3WritePolicy
](#s3-write-policy)
+ [
## SageMakerCreateEndpointConfigPolicy
](#sagemaker-create-endpoint-config-policy)
+ [
## SageMakerCreateEndpointPolicy
](#sagemaker-create-endpoint-policy)
+ [
## ServerlessRepoReadWriteAccessPolicy
](#serverlessrepo-read-write-access-policy)
+ [
## SESBulkTemplatedCrudPolicy
](#ses-bulk-templated-crud-policy)
+ [
## SESBulkTemplatedCrudPolicy\$1v2
](#ses-bulk-templated-crud-policy-v2)
+ [
## SESCrudPolicy
](#ses-crud-policy)
+ [
## SESEmailTemplateCrudPolicy
](#ses-email-template-crud-policy)
+ [
## SESSendBouncePolicy
](#ses-send-bounce-policy)
+ [
## SNSCrudPolicy
](#sns-crud-policy)
+ [
## SNSPublishMessagePolicy
](#sqs-publish-message-policy)
+ [
## SQSPollerPolicy
](#sqs-poller-policy)
+ [
## SQSSendMessagePolicy
](#sqs-send-message-policy)
+ [
## SSMParameterReadPolicy
](#ssm-parameter-read-policy)
+ [
## SSMParameterWithSlashPrefixReadPolicy
](#ssm-parameter-slash-read-policy)
+ [
## StepFunctionsExecutionPolicy
](#stepfunctions-execution-policy)
+ [
## TextractDetectAnalyzePolicy
](#textract-detect-analyze-policy)
+ [
## TextractGetResultPolicy
](#textract-get-result-policy)
+ [
## TextractPolicy
](#textract-policy)
+ [
## VPCAccessPolicy
](#vpc-access-policy)
## AcmGetCertificatePolicy
Gives a permission to read a certificate from AWS Certificate Manager.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"acm:GetCertificate"
],
"Resource": {
"Fn::Sub": [
"${certificateArn}",
{
"certificateArn": {
"Ref": "CertificateArn"
}
}
]
}
}
]
```
## AMIDescribePolicy
Gives permission to describe Amazon Machine Images (AMIs).
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:DescribeImages"
],
"Resource": "*"
}
]
```
## AthenaQueryPolicy
Gives permissions to execute Athena queries.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"athena:ListWorkGroups",
"athena:GetExecutionEngine",
"athena:GetExecutionEngines",
"athena:GetNamespace",
"athena:GetCatalogs",
"athena:GetNamespaces",
"athena:GetTables",
"athena:GetTable"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"athena:StartQueryExecution",
"athena:GetQueryResults",
"athena:DeleteNamedQuery",
"athena:GetNamedQuery",
"athena:ListQueryExecutions",
"athena:StopQueryExecution",
"athena:GetQueryResultsStream",
"athena:ListNamedQueries",
"athena:CreateNamedQuery",
"athena:GetQueryExecution",
"athena:BatchGetNamedQuery",
"athena:BatchGetQueryExecution",
"athena:GetWorkGroup"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:athena:${AWS::Region}:${AWS::AccountId}:workgroup/${workgroupName}",
{
"workgroupName": {
"Ref": "WorkGroupName"
}
}
]
}
}
]
```
## AWSSecretsManagerGetSecretValuePolicy
Gives permission to get the secret value for the specified AWS Secrets Manager secret.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": {
"Fn::Sub": [
"${secretArn}",
{
"secretArn": {
"Ref": "SecretArn"
}
}
]
}
}
]
```
## AWSSecretsManagerRotationPolicy
Gives permission to rotate a secret in AWS Secrets Manager.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:DescribeSecret",
"secretsmanager:GetSecretValue",
"secretsmanager:PutSecretValue",
"secretsmanager:UpdateSecretVersionStage"
],
"Resource": {
"Fn::Sub": "arn:${AWS::Partition}:secretsmanager:${AWS::Region}:${AWS::AccountId}:secret:*"
},
"Condition": {
"StringEquals": {
"secretsmanager:resource/AllowRotationLambdaArn": {
"Fn::Sub": [
"arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:${functionName}",
{
"functionName": {
"Ref": "FunctionName"
}
}
]
}
}
}
},
{
"Effect": "Allow",
"Action": [
"secretsmanager:GetRandomPassword"
],
"Resource": "*"
}
]
```
## CloudFormationDescribeStacksPolicy
Gives permission to describe CloudFormation stacks.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"cloudformation:DescribeStacks"
],
"Resource": {
"Fn::Sub": "arn:${AWS::Partition}:cloudformation:${AWS::Region}:${AWS::AccountId}:stack/*"
}
}
]
```
## CloudWatchDashboardPolicy
Gives permissions to put metrics to operate on CloudWatch dashboards.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"cloudwatch:GetDashboard",
"cloudwatch:ListDashboards",
"cloudwatch:PutDashboard",
"cloudwatch:ListMetrics"
],
"Resource": "*"
}
]
```
## CloudWatchDescribeAlarmHistoryPolicy
Gives permission to describe Amazon CloudWatch alarm history.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"cloudwatch:DescribeAlarmHistory"
],
"Resource": "*"
}
]
```
## CloudWatchPutMetricPolicy
Gives permission to send metrics to CloudWatch.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"cloudwatch:PutMetricData"
],
"Resource": "*"
}
]
```
## CodePipelineLambdaExecutionPolicy
Gives permission for a Lambda function invoked by AWS CodePipeline to report the status of the job.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"codepipeline:PutJobSuccessResult",
"codepipeline:PutJobFailureResult"
],
"Resource": "*"
}
]
```
## CodePipelineReadOnlyPolicy
Gives read permission to get details about a CodePipeline pipeline.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"codepipeline:ListPipelineExecutions"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:codepipeline:${AWS::Region}:${AWS::AccountId}:${pipelinename}",
{
"pipelinename": {
"Ref": "PipelineName"
}
}
]
}
}
]
```
## CodeCommitCrudPolicy
Gives permissions to create, read, update, and delete objects within a specific CodeCommit repository.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"codecommit:GitPull",
"codecommit:GitPush",
"codecommit:CreateBranch",
"codecommit:DeleteBranch",
"codecommit:GetBranch",
"codecommit:ListBranches",
"codecommit:MergeBranchesByFastForward",
"codecommit:MergeBranchesBySquash",
"codecommit:MergeBranchesByThreeWay",
"codecommit:UpdateDefaultBranch",
"codecommit:BatchDescribeMergeConflicts",
"codecommit:CreateUnreferencedMergeCommit",
"codecommit:DescribeMergeConflicts",
"codecommit:GetMergeCommit",
"codecommit:GetMergeOptions",
"codecommit:BatchGetPullRequests",
"codecommit:CreatePullRequest",
"codecommit:DescribePullRequestEvents",
"codecommit:GetCommentsForPullRequest",
"codecommit:GetCommitsFromMergeBase",
"codecommit:GetMergeConflicts",
"codecommit:GetPullRequest",
"codecommit:ListPullRequests",
"codecommit:MergePullRequestByFastForward",
"codecommit:MergePullRequestBySquash",
"codecommit:MergePullRequestByThreeWay",
"codecommit:PostCommentForPullRequest",
"codecommit:UpdatePullRequestDescription",
"codecommit:UpdatePullRequestStatus",
"codecommit:UpdatePullRequestTitle",
"codecommit:DeleteFile",
"codecommit:GetBlob",
"codecommit:GetFile",
"codecommit:GetFolder",
"codecommit:PutFile",
"codecommit:DeleteCommentContent",
"codecommit:GetComment",
"codecommit:GetCommentsForComparedCommit",
"codecommit:PostCommentForComparedCommit",
"codecommit:PostCommentReply",
"codecommit:UpdateComment",
"codecommit:BatchGetCommits",
"codecommit:CreateCommit",
"codecommit:GetCommit",
"codecommit:GetCommitHistory",
"codecommit:GetDifferences",
"codecommit:GetObjectIdentifier",
"codecommit:GetReferences",
"codecommit:GetTree",
"codecommit:GetRepository",
"codecommit:UpdateRepositoryDescription",
"codecommit:ListTagsForResource",
"codecommit:TagResource",
"codecommit:UntagResource",
"codecommit:GetRepositoryTriggers",
"codecommit:PutRepositoryTriggers",
"codecommit:TestRepositoryTriggers",
"codecommit:GetBranch",
"codecommit:GetCommit",
"codecommit:UploadArchive",
"codecommit:GetUploadArchiveStatus",
"codecommit:CancelUploadArchive"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:codecommit:${AWS::Region}:${AWS::AccountId}:${repositoryName}",
{
"repositoryName": {
"Ref": "RepositoryName"
}
}
]
}
}
]
```
## CodeCommitReadPolicy
Gives permissions to read objects within a specific CodeCommit repository.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"codecommit:GitPull",
"codecommit:GetBranch",
"codecommit:ListBranches",
"codecommit:BatchDescribeMergeConflicts",
"codecommit:DescribeMergeConflicts",
"codecommit:GetMergeCommit",
"codecommit:GetMergeOptions",
"codecommit:BatchGetPullRequests",
"codecommit:DescribePullRequestEvents",
"codecommit:GetCommentsForPullRequest",
"codecommit:GetCommitsFromMergeBase",
"codecommit:GetMergeConflicts",
"codecommit:GetPullRequest",
"codecommit:ListPullRequests",
"codecommit:GetBlob",
"codecommit:GetFile",
"codecommit:GetFolder",
"codecommit:GetComment",
"codecommit:GetCommentsForComparedCommit",
"codecommit:BatchGetCommits",
"codecommit:GetCommit",
"codecommit:GetCommitHistory",
"codecommit:GetDifferences",
"codecommit:GetObjectIdentifier",
"codecommit:GetReferences",
"codecommit:GetTree",
"codecommit:GetRepository",
"codecommit:ListTagsForResource",
"codecommit:GetRepositoryTriggers",
"codecommit:TestRepositoryTriggers",
"codecommit:GetBranch",
"codecommit:GetCommit",
"codecommit:GetUploadArchiveStatus"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:codecommit:${AWS::Region}:${AWS::AccountId}:${repositoryName}",
{
"repositoryName": {
"Ref": "RepositoryName"
}
}
]
}
}
]
```
## ComprehendBasicAccessPolicy
Gives permission for detecting entities, key phrases, languages, and sentiments.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"comprehend:BatchDetectKeyPhrases",
"comprehend:DetectDominantLanguage",
"comprehend:DetectEntities",
"comprehend:BatchDetectEntities",
"comprehend:DetectKeyPhrases",
"comprehend:DetectSentiment",
"comprehend:BatchDetectDominantLanguage",
"comprehend:BatchDetectSentiment"
],
"Resource": "*"
}
]
```
## CostExplorerReadOnlyPolicy
Gives read-only permission to the read-only AWS Cost Explorer (Cost Explorer) APIs for billing history.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"ce:GetCostAndUsage",
"ce:GetDimensionValues",
"ce:GetReservationCoverage",
"ce:GetReservationPurchaseRecommendation",
"ce:GetReservationUtilization",
"ce:GetTags"
],
"Resource": "*"
}
]
```
## DynamoDBBackupFullAccessPolicy
Gives read and write permission to DynamoDB on-demand backups for a table.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:CreateBackup",
"dynamodb:DescribeContinuousBackups"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${tableName}",
{
"tableName": {
"Ref": "TableName"
}
}
]
}
},
{
"Effect": "Allow",
"Action": [
"dynamodb:DeleteBackup",
"dynamodb:DescribeBackup",
"dynamodb:ListBackups"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${tableName}/backup/*",
{
"tableName": {
"Ref": "TableName"
}
}
]
}
}
]
```
## DynamoDBCrudPolicy
Gives create, read, update, and delete permissions to an Amazon DynamoDB table.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:GetItem",
"dynamodb:DeleteItem",
"dynamodb:PutItem",
"dynamodb:Scan",
"dynamodb:Query",
"dynamodb:UpdateItem",
"dynamodb:BatchWriteItem",
"dynamodb:BatchGetItem",
"dynamodb:DescribeTable",
"dynamodb:ConditionCheckItem"
],
"Resource": [
{
"Fn::Sub": [
"arn:${AWS::Partition}:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${tableName}",
{
"tableName": {
"Ref": "TableName"
}
}
]
},
{
"Fn::Sub": [
"arn:${AWS::Partition}:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${tableName}/index/*",
{
"tableName": {
"Ref": "TableName"
}
}
]
}
]
}
]
```
## DynamoDBReadPolicy
Gives read-only permission to a DynamoDB table.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:GetItem",
"dynamodb:Scan",
"dynamodb:Query",
"dynamodb:BatchGetItem",
"dynamodb:DescribeTable"
],
"Resource": [
{
"Fn::Sub": [
"arn:${AWS::Partition}:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${tableName}",
{
"tableName": {
"Ref": "TableName"
}
}
]
},
{
"Fn::Sub": [
"arn:${AWS::Partition}:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${tableName}/index/*",
{
"tableName": {
"Ref": "TableName"
}
}
]
}
]
}
]
```
## DynamoDBReconfigurePolicy
Gives permission to reconfigure a DynamoDB table.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:UpdateTable"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${tableName}",
{
"tableName": {
"Ref": "TableName"
}
}
]
}
}
]
```
## DynamoDBRestoreFromBackupPolicy
Gives permission to restore a DynamoDB table from backup.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:RestoreTableFromBackup"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${tableName}/backup/*",
{
"tableName": {
"Ref": "TableName"
}
}
]
}
},
{
"Effect": "Allow",
"Action": [
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem",
"dynamodb:Query",
"dynamodb:Scan",
"dynamodb:BatchWriteItem"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${tableName}",
{
"tableName": {
"Ref": "TableName"
}
}
]
}
}
]
```
## DynamoDBStreamReadPolicy
Gives permission to describe and read DynamoDB streams and records.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:DescribeStream",
"dynamodb:GetRecords",
"dynamodb:GetShardIterator"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${tableName}/stream/${streamName}",
{
"tableName": {
"Ref": "TableName"
},
"streamName": {
"Ref": "StreamName"
}
}
]
}
},
{
"Effect": "Allow",
"Action": [
"dynamodb:ListStreams"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${tableName}/stream/*",
{
"tableName": {
"Ref": "TableName"
}
}
]
}
}
]
```
## DynamoDBWritePolicy
Gives write-only permission to a DynamoDB table.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:BatchWriteItem"
],
"Resource": [
{
"Fn::Sub": [
"arn:${AWS::Partition}:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${tableName}",
{
"tableName": {
"Ref": "TableName"
}
}
]
},
{
"Fn::Sub": [
"arn:${AWS::Partition}:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${tableName}/index/*",
{
"tableName": {
"Ref": "TableName"
}
}
]
}
]
}
]
```
## EC2CopyImagePolicy
Gives permission to copy Amazon EC2 images.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CopyImage"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:ec2:${AWS::Region}:${AWS::AccountId}:image/${imageId}",
{
"imageId": {
"Ref": "ImageId"
}
}
]
}
}
]
```
## EC2DescribePolicy
Gives permission to describe Amazon Elastic Compute Cloud (Amazon EC2) instances.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:DescribeRegions",
"ec2:DescribeInstances"
],
"Resource": "*"
}
]
```
## EcsRunTaskPolicy
Gives permission to start a new task for a task definition.
```
"Statement": [
{
"Action": [
"ecs:RunTask"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:ecs:${AWS::Region}:${AWS::AccountId}:task-definition/${taskDefinition}",
{
"taskDefinition": {
"Ref": "TaskDefinition"
}
}
]
},
"Effect": "Allow"
}
]
```
## EFSWriteAccessPolicy
Gives permission to mount an Amazon EFS file system with write access.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"elasticfilesystem:ClientMount",
"elasticfilesystem:ClientWrite"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:elasticfilesystem:${AWS::Region}:${AWS::AccountId}:file-system/${FileSystem}",
{
"FileSystem": {
"Ref": "FileSystem"
}
}
]
},
"Condition": {
"StringEquals": {
"elasticfilesystem:AccessPointArn": {
"Fn::Sub": [
"arn:${AWS::Partition}:elasticfilesystem:${AWS::Region}:${AWS::AccountId}:access-point/${AccessPoint}",
{
"AccessPoint": {
"Ref": "AccessPoint"
}
}
]
}
}
}
}
]
```
## EKSDescribePolicy
Gives permission to describe or list Amazon Elastic Kubernetes Service (Amazon EKS) clusters.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"eks:DescribeCluster",
"eks:ListClusters"
],
"Resource": "*"
}
]
```
## ElasticMapReduceAddJobFlowStepsPolicy
Gives permission to add new steps to a running cluster.
```
"Statement": [
{
"Action": "elasticmapreduce:AddJobFlowSteps",
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:elasticmapreduce:${AWS::Region}:${AWS::AccountId}:cluster/${clusterId}",
{
"clusterId": {
"Ref": "ClusterId"
}
}
]
},
"Effect": "Allow"
}
]
```
## ElasticMapReduceCancelStepsPolicy
Gives permission to cancel a pending step or steps in a running cluster.
```
"Statement": [
{
"Action": "elasticmapreduce:CancelSteps",
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:elasticmapreduce:${AWS::Region}:${AWS::AccountId}:cluster/${clusterId}",
{
"clusterId": {
"Ref": "ClusterId"
}
}
]
},
"Effect": "Allow"
}
]
```
## ElasticMapReduceModifyInstanceFleetPolicy
Gives permission to list details and modify capacities for instance fleets within a cluster.
```
"Statement": [
{
"Action": [
"elasticmapreduce:ModifyInstanceFleet",
"elasticmapreduce:ListInstanceFleets"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:elasticmapreduce:${AWS::Region}:${AWS::AccountId}:cluster/${clusterId}",
{
"clusterId": {
"Ref": "ClusterId"
}
}
]
},
"Effect": "Allow"
}
]
```
## ElasticMapReduceModifyInstanceGroupsPolicy
Gives permission to list details and modify settings for instance groups within a cluster.
```
"Statement": [
{
"Action": [
"elasticmapreduce:ModifyInstanceGroups",
"elasticmapreduce:ListInstanceGroups"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:elasticmapreduce:${AWS::Region}:${AWS::AccountId}:cluster/${clusterId}",
{
"clusterId": {
"Ref": "ClusterId"
}
}
]
},
"Effect": "Allow"
}
]
```
## ElasticMapReduceSetTerminationProtectionPolicy
Gives permission to set termination protection for a cluster.
```
"Statement": [
{
"Action": "elasticmapreduce:SetTerminationProtection",
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:elasticmapreduce:${AWS::Region}:${AWS::AccountId}:cluster/${clusterId}",
{
"clusterId": {
"Ref": "ClusterId"
}
}
]
},
"Effect": "Allow"
}
]
```
## ElasticMapReduceTerminateJobFlowsPolicy
Gives permission to shut down a cluster.
```
"Statement": [
{
"Action": "elasticmapreduce:TerminateJobFlows",
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:elasticmapreduce:${AWS::Region}:${AWS::AccountId}:cluster/${clusterId}",
{
"clusterId": {
"Ref": "ClusterId"
}
}
]
},
"Effect": "Allow"
}
]
```
## ElasticsearchHttpPostPolicy
Gives POST and PUT permission to Amazon OpenSearch Service.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"es:ESHttpPost",
"es:ESHttpPut"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:es:${AWS::Region}:${AWS::AccountId}:domain/${domainName}/*",
{
"domainName": {
"Ref": "DomainName"
}
}
]
}
}
]
```
## EventBridgePutEventsPolicy
Gives permissions to send events to Amazon EventBridge.
```
"Statement": [
{
"Effect": "Allow",
"Action": "events:PutEvents",
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:events:${AWS::Region}:${AWS::AccountId}:event-bus/${eventBusName}",
{
"eventBusName": {
"Ref": "EventBusName"
}
}
]
}
}
]
```
## FilterLogEventsPolicy
Gives permission to filter CloudWatch Logs events from a specified log group.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:FilterLogEvents"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:logs:${AWS::Region}:${AWS::AccountId}:log-group:${logGroupName}:log-stream:*",
{
"logGroupName": {
"Ref": "LogGroupName"
}
}
]
}
}
]
```
## FirehoseCrudPolicy
Gives permission to create, write, update, and delete a Firehose delivery stream.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"firehose:CreateDeliveryStream",
"firehose:DeleteDeliveryStream",
"firehose:DescribeDeliveryStream",
"firehose:PutRecord",
"firehose:PutRecordBatch",
"firehose:UpdateDestination"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:firehose:${AWS::Region}:${AWS::AccountId}:deliverystream/${deliveryStreamName}",
{
"deliveryStreamName": {
"Ref": "DeliveryStreamName"
}
}
]
}
}
]
```
## FirehoseWritePolicy
Gives permission to write to a Firehose delivery stream.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"firehose:PutRecord",
"firehose:PutRecordBatch"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:firehose:${AWS::Region}:${AWS::AccountId}:deliverystream/${deliveryStreamName}",
{
"deliveryStreamName": {
"Ref": "DeliveryStreamName"
}
}
]
}
}
]
```
## KinesisCrudPolicy
Gives permission to create, publish, and delete an Amazon Kinesis stream.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"kinesis:AddTagsToStream",
"kinesis:CreateStream",
"kinesis:DecreaseStreamRetentionPeriod",
"kinesis:DeleteStream",
"kinesis:DescribeStream",
"kinesis:DescribeStreamSummary",
"kinesis:GetShardIterator",
"kinesis:IncreaseStreamRetentionPeriod",
"kinesis:ListTagsForStream",
"kinesis:MergeShards",
"kinesis:PutRecord",
"kinesis:PutRecords",
"kinesis:SplitShard",
"kinesis:RemoveTagsFromStream"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:kinesis:${AWS::Region}:${AWS::AccountId}:stream/${streamName}",
{
"streamName": {
"Ref": "StreamName"
}
}
]
}
}
]
```
## KinesisStreamReadPolicy
Gives permission to list and read an Amazon Kinesis stream.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"kinesis:ListStreams",
"kinesis:DescribeLimits"
],
"Resource": {
"Fn::Sub": "arn:${AWS::Partition}:kinesis:${AWS::Region}:${AWS::AccountId}:stream/*"
}
},
{
"Effect": "Allow",
"Action": [
"kinesis:DescribeStream",
"kinesis:DescribeStreamSummary",
"kinesis:GetRecords",
"kinesis:GetShardIterator"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:kinesis:${AWS::Region}:${AWS::AccountId}:stream/${streamName}",
{
"streamName": {
"Ref": "StreamName"
}
}
]
}
}
]
```
## KMSDecryptPolicy
Gives permission to decrypt with an AWS Key Management Service (AWS KMS) key. Note that `keyId` must be an AWS KMS key ID, and not a key alias.
```
"Statement": [
{
"Action": "kms:Decrypt",
"Effect": "Allow",
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:kms:${AWS::Region}:${AWS::AccountId}:key/${keyId}",
{
"keyId": {
"Ref": "KeyId"
}
}
]
}
}
]
```
## KMSEncryptPolicy
Gives permission to encrypt with an AWS KMS key. Note that keyId must be an AWS KMS key ID, and not a key alias.
```
"Statement": [
{
"Action": "kms:Encrypt",
"Effect": "Allow",
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:kms:${AWS::Region}:${AWS::AccountId}:key/${keyId}",
{
"keyId": {
"Ref": "KeyId"
}
}
]
}
}
]
```
## LambdaInvokePolicy
Gives permission to invoke an AWS Lambda function, alias, or version.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"lambda:InvokeFunction"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:${functionName}*",
{
"functionName": {
"Ref": "FunctionName"
}
}
]
}
}
]
```
## MobileAnalyticsWriteOnlyAccessPolicy
Gives write-only permission to put event data for all application resources.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"mobileanalytics:PutEvents"
],
"Resource": "*"
}
]
```
## OrganizationsListAccountsPolicy
Gives read-only permission to list child account names and IDs.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"organizations:ListAccounts"
],
"Resource": "*"
}
]
```
## PinpointEndpointAccessPolicy
Gives permission to get and update endpoints for an Amazon Pinpoint application.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"mobiletargeting:GetEndpoint",
"mobiletargeting:UpdateEndpoint",
"mobiletargeting:UpdateEndpointsBatch"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:mobiletargeting:${AWS::Region}:${AWS::AccountId}:apps/${pinpointApplicationId}/endpoints/*",
{
"pinpointApplicationId": {
"Ref": "PinpointApplicationId"
}
}
]
}
}
]
```
## PollyFullAccessPolicy
Gives full access permission to Amazon Polly lexicon resources.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"polly:GetLexicon",
"polly:DeleteLexicon"
],
"Resource": [
{
"Fn::Sub": [
"arn:${AWS::Partition}:polly:${AWS::Region}:${AWS::AccountId}:lexicon/${lexiconName}",
{
"lexiconName": {
"Ref": "LexiconName"
}
}
]
}
]
},
{
"Effect": "Allow",
"Action": [
"polly:DescribeVoices",
"polly:ListLexicons",
"polly:PutLexicon",
"polly:SynthesizeSpeech"
],
"Resource": [
{
"Fn::Sub": "arn:${AWS::Partition}:polly:${AWS::Region}:${AWS::AccountId}:lexicon/*"
}
]
}
]
```
## RekognitionDetectOnlyPolicy
Gives permission to detect faces, labels, and text.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"rekognition:DetectFaces",
"rekognition:DetectLabels",
"rekognition:DetectModerationLabels",
"rekognition:DetectText"
],
"Resource": "*"
}
]
```
## RekognitionFacesManagementPolicy
Gives permission to add, delete, and search faces in an Amazon Rekognition collection.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"rekognition:IndexFaces",
"rekognition:DeleteFaces",
"rekognition:SearchFaces",
"rekognition:SearchFacesByImage",
"rekognition:ListFaces"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:rekognition:${AWS::Region}:${AWS::AccountId}:collection/${collectionId}",
{
"collectionId": {
"Ref": "CollectionId"
}
}
]
}
}
]
```
## RekognitionFacesPolicy
Gives permission to compare and detect faces and labels.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"rekognition:CompareFaces",
"rekognition:DetectFaces"
],
"Resource": "*"
}
]
```
## RekognitionLabelsPolicy
Gives permission to detect object and moderation labels.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"rekognition:DetectLabels",
"rekognition:DetectModerationLabels"
],
"Resource": "*"
}
]
```
## RekognitionNoDataAccessPolicy
Gives permission to compare and detect faces and labels.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"rekognition:CompareFaces",
"rekognition:DetectFaces",
"rekognition:DetectLabels",
"rekognition:DetectModerationLabels"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:rekognition:${AWS::Region}:${AWS::AccountId}:collection/${collectionId}",
{
"collectionId": {
"Ref": "CollectionId"
}
}
]
}
}
]
```
## RekognitionReadPolicy
Gives permission to list and search faces.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"rekognition:ListCollections",
"rekognition:ListFaces",
"rekognition:SearchFaces",
"rekognition:SearchFacesByImage"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:rekognition:${AWS::Region}:${AWS::AccountId}:collection/${collectionId}",
{
"collectionId": {
"Ref": "CollectionId"
}
}
]
}
}
]
```
## RekognitionWriteOnlyAccessPolicy
Gives permission to create collection and index faces.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"rekognition:CreateCollection",
"rekognition:IndexFaces"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:rekognition:${AWS::Region}:${AWS::AccountId}:collection/${collectionId}",
{
"collectionId": {
"Ref": "CollectionId"
}
}
]
}
}
]
```
## Route53ChangeResourceRecordSetsPolicy
Gives permission to change resource record sets in Route 53.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"route53:ChangeResourceRecordSets"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:route53:::hostedzone/${HostedZoneId}",
{
"HostedZoneId": {
"Ref": "HostedZoneId"
}
}
]
}
}
]
```
## S3CrudPolicy
Gives create, read, update, and delete permission to act on the objects in an Amazon S3 bucket.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:ListBucket",
"s3:GetBucketLocation",
"s3:GetObjectVersion",
"s3:PutObject",
"s3:PutObjectAcl",
"s3:GetLifecycleConfiguration",
"s3:PutLifecycleConfiguration",
"s3:DeleteObject"
],
"Resource": [
{
"Fn::Sub": [
"arn:${AWS::Partition}:s3:::${bucketName}",
{
"bucketName": {
"Ref": "BucketName"
}
}
]
},
{
"Fn::Sub": [
"arn:${AWS::Partition}:s3:::${bucketName}/*",
{
"bucketName": {
"Ref": "BucketName"
}
}
]
}
]
}
]
```
## S3FullAccessPolicy
Gives full access permission to act on the objects in an Amazon S3 bucket.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:GetObjectAcl",
"s3:GetObjectVersion",
"s3:PutObject",
"s3:PutObjectAcl",
"s3:DeleteObject",
"s3:DeleteObjectTagging",
"s3:DeleteObjectVersionTagging",
"s3:GetObjectTagging",
"s3:GetObjectVersionTagging",
"s3:PutObjectTagging",
"s3:PutObjectVersionTagging"
],
"Resource": [
{
"Fn::Sub": [
"arn:${AWS::Partition}:s3:::${bucketName}/*",
{
"bucketName": {
"Ref": "BucketName"
}
}
]
}
]
},
{
"Effect": "Allow",
"Action": [
"s3:ListBucket",
"s3:GetBucketLocation",
"s3:GetLifecycleConfiguration",
"s3:PutLifecycleConfiguration"
],
"Resource": [
{
"Fn::Sub": [
"arn:${AWS::Partition}:s3:::${bucketName}",
{
"bucketName": {
"Ref": "BucketName"
}
}
]
}
]
}
]
```
## S3ReadPolicy
Gives read-only permission to read objects in an Amazon Simple Storage Service (Amazon S3) bucket.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:ListBucket",
"s3:GetBucketLocation",
"s3:GetObjectVersion",
"s3:GetLifecycleConfiguration"
],
"Resource": [
{
"Fn::Sub": [
"arn:${AWS::Partition}:s3:::${bucketName}",
{
"bucketName": {
"Ref": "BucketName"
}
}
]
},
{
"Fn::Sub": [
"arn:${AWS::Partition}:s3:::${bucketName}/*",
{
"bucketName": {
"Ref": "BucketName"
}
}
]
}
]
}
]
```
## S3WritePolicy
Gives write permission to write objects into an Amazon S3 bucket.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:PutObjectAcl",
"s3:PutLifecycleConfiguration"
],
"Resource": [
{
"Fn::Sub": [
"arn:${AWS::Partition}:s3:::${bucketName}",
{
"bucketName": {
"Ref": "BucketName"
}
}
]
},
{
"Fn::Sub": [
"arn:${AWS::Partition}:s3:::${bucketName}/*",
{
"bucketName": {
"Ref": "BucketName"
}
}
]
}
]
}
]
```
## SageMakerCreateEndpointConfigPolicy
Gives permission to create an endpoint configuration in SageMaker AI.
```
"Statement": [
{
"Action": [
"sagemaker:CreateEndpointConfig"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:sagemaker:${AWS::Region}:${AWS::AccountId}:endpoint-config/${endpointConfigName}",
{
"endpointConfigName": {
"Ref": "EndpointConfigName"
}
}
]
},
"Effect": "Allow"
}
]
```
## SageMakerCreateEndpointPolicy
Gives permission to create an endpoint in SageMaker AI.
```
"Statement": [
{
"Action": [
"sagemaker:CreateEndpoint"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:sagemaker:${AWS::Region}:${AWS::AccountId}:endpoint/${endpointName}",
{
"endpointName": {
"Ref": "EndpointName"
}
}
]
},
"Effect": "Allow"
}
]
```
## ServerlessRepoReadWriteAccessPolicy
Gives permission to create and list applications in the AWS Serverless Application Repository (AWS SAM) service.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"serverlessrepo:CreateApplication",
"serverlessrepo:CreateApplicationVersion",
"serverlessrepo:GetApplication",
"serverlessrepo:ListApplications",
"serverlessrepo:ListApplicationVersions"
],
"Resource": [
{
"Fn::Sub": "arn:${AWS::Partition}:serverlessrepo:${AWS::Region}:${AWS::AccountId}:applications/*"
}
]
}
]
```
## SESBulkTemplatedCrudPolicy
Gives permission to send Amazon SES email, templated email, and templated bulk emails and to verify identity.
**Note**
The `ses:SendTemplatedEmail` action requires a template ARN. Use `SESBulkTemplatedCrudPolicy_v2` instead.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"ses:GetIdentityVerificationAttributes",
"ses:SendEmail",
"ses:SendRawEmail",
"ses:SendTemplatedEmail",
"ses:SendBulkTemplatedEmail",
"ses:VerifyEmailIdentity"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:ses:${AWS::Region}:${AWS::AccountId}:identity/${identityName}",
{
"identityName": {
"Ref": "IdentityName"
}
}
]
}
}
]
```
## SESBulkTemplatedCrudPolicy\$1v2
Gives permission to send Amazon SES email, templated email, and templated bulk emails and to verify identity.
```
"Statement": [
{
"Action": [
"ses:SendEmail",
"ses:SendRawEmail",
"ses:SendTemplatedEmail",
"ses:SendBulkTemplatedEmail"
],
"Effect": "Allow",
"Resource": [
{
"Fn::Sub": [
"arn:${AWS::Partition}:ses:${AWS::Region}:${AWS::AccountId}:identity/${identityName}",
{
"identityName": {
"Ref": "IdentityName"
}
}
]
},
{
"Fn::Sub": [
"arn:${AWS::Partition}:ses:${AWS::Region}:${AWS::AccountId}:template/${templateName}",
{
"templateName": {
"Ref": "TemplateName"
}
}
]
}
]
},
{
"Action": [
"ses:GetIdentityVerificationAttributes",
"ses:VerifyEmailIdentity"
],
"Effect": "Allow",
"Resource": "*"
}
]
```
## SESCrudPolicy
Gives permission to send email and verify identity.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"ses:GetIdentityVerificationAttributes",
"ses:SendEmail",
"ses:SendRawEmail",
"ses:VerifyEmailIdentity"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:ses:${AWS::Region}:${AWS::AccountId}:identity/${identityName}",
{
"identityName": {
"Ref": "IdentityName"
}
}
]
}
}
]
```
## SESEmailTemplateCrudPolicy
Gives permission to create, get, list, update, and delete Amazon SES email templates.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"ses:CreateTemplate",
"ses:GetTemplate",
"ses:ListTemplates",
"ses:UpdateTemplate",
"ses:DeleteTemplate",
"ses:TestRenderTemplate"
],
"Resource": "*"
}
]
```
## SESSendBouncePolicy
Gives SendBounce permission to an Amazon Simple Email Service (Amazon SES) identity.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"ses:SendBounce"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:ses:${AWS::Region}:${AWS::AccountId}:identity/${identityName}",
{
"identityName": {
"Ref": "IdentityName"
}
}
]
}
}
]
```
## SNSCrudPolicy
Gives permission to create, publish, and subscribe to Amazon SNS topics.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"sns:ListSubscriptionsByTopic",
"sns:CreateTopic",
"sns:SetTopicAttributes",
"sns:Subscribe",
"sns:Publish"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:sns:${AWS::Region}:${AWS::AccountId}:${topicName}*",
{
"topicName": {
"Ref": "TopicName"
}
}
]
}
}
]
```
## SNSPublishMessagePolicy
Gives permission to publish a message to an Amazon Simple Notification Service (Amazon SNS) topic.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"sns:Publish"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:sns:${AWS::Region}:${AWS::AccountId}:${topicName}",
{
"topicName": {
"Ref": "TopicName"
}
}
]
}
}
]
```
## SQSPollerPolicy
Gives permission to poll an Amazon Simple Queue Service (Amazon SQS) queue.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"sqs:ChangeMessageVisibility",
"sqs:ChangeMessageVisibilityBatch",
"sqs:DeleteMessage",
"sqs:DeleteMessageBatch",
"sqs:GetQueueAttributes",
"sqs:ReceiveMessage"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:sqs:${AWS::Region}:${AWS::AccountId}:${queueName}",
{
"queueName": {
"Ref": "QueueName"
}
}
]
}
}
]
```
## SQSSendMessagePolicy
Gives permission to send message to an Amazon SQS queue.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"sqs:SendMessage*"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:sqs:${AWS::Region}:${AWS::AccountId}:${queueName}",
{
"queueName": {
"Ref": "QueueName"
}
}
]
}
}
]
```
## SSMParameterReadPolicy
Gives permission to access a parameter from an Amazon EC2 Systems Manager (SSM) parameter store to load secrets in this account. Use when parameter name doesn't have slash prefix.
**Note**
If you are not using default key, you will also need the `KMSDecryptPolicy` policy.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:DescribeParameters"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ssm:GetParameters",
"ssm:GetParameter",
"ssm:GetParametersByPath"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:ssm:${AWS::Region}:${AWS::AccountId}:parameter/${parameterName}",
{
"parameterName": {
"Ref": "ParameterName"
}
}
]
}
}
]
```
## SSMParameterWithSlashPrefixReadPolicy
Gives permission to access a parameter from an Amazon EC2 Systems Manager (SSM) parameter store to load secrets in this account. Use when parameter name has slash prefix.
**Note**
If you are not using default key, you will also need the `KMSDecryptPolicy` policy.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:DescribeParameters"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ssm:GetParameters",
"ssm:GetParameter",
"ssm:GetParametersByPath"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:ssm:${AWS::Region}:${AWS::AccountId}:parameter${parameterName}",
{
"parameterName": {
"Ref": "ParameterName"
}
}
]
}
}
]
```
## StepFunctionsExecutionPolicy
Gives permission to start a Step Functions state machine execution.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"states:StartExecution"
],
"Resource": {
"Fn::Sub": [
"arn:${AWS::Partition}:states:${AWS::Region}:${AWS::AccountId}:stateMachine:${stateMachineName}",
{
"stateMachineName": {
"Ref": "StateMachineName"
}
}
]
}
}
]
```
## TextractDetectAnalyzePolicy
Gives access to detect and analyze documents with Amazon Textract.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"textract:DetectDocumentText",
"textract:StartDocumentTextDetection",
"textract:StartDocumentAnalysis",
"textract:AnalyzeDocument"
],
"Resource": "*"
}
]
```
## TextractGetResultPolicy
Gives access to get detected and analyzed documents from Amazon Textract.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"textract:GetDocumentTextDetection",
"textract:GetDocumentAnalysis"
],
"Resource": "*"
}
]
```
## TextractPolicy
Gives full access to Amazon Textract.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"textract:*"
],
"Resource": "*"
}
]
```
## VPCAccessPolicy
Gives access to create, delete, describe, and detach elastic network interfaces.
```
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DetachNetworkInterface"
],
"Resource": "*"
}
]
```
# Managing AWS SAM permissions with CloudFormation mechanisms
To control access to AWS resources, the AWS Serverless Application Model (AWS SAM) can use the same mechanisms as CloudFormation. For more information, see [Controlling access with AWS Identity and Access Management](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-template.html) in the *AWS CloudFormation User Guide*.
There are three main options for granting a user permission to manage serverless applications. Each option provides users with different levels of access control.
+ Grant administrator permissions.
+ Attach necessary AWS managed policies.
+ Grant specific AWS Identity and Access Management (IAM) permissions.
Depending on which option you choose, users can manage only serverless applications containing AWS resources that they have permission to access.
The following sections describe each option in more detail.
## Grant administrator permissions
If you grant administrator permissions to a user, they can manage serverless applications that contain any combination of AWS resources. This is the simplest option, but it also grants users the broadest set of permissions, which therefore enables them to perform actions with the highest impact.
For more information about granting administrator permissions to a user, see [Creating your first IAM admin user and group](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-admin-group.html) in the *IAM User Guide*.
## Attach necessary AWS managed policies
You can grant users a subset of permissions using [AWS managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies), rather than granting full administrator permissions. If you use this option, make sure that the set of AWS managed policies covers all of the actions and resources required for the serverless applications that the users manage.
For example, the following AWS managed policies are sufficient to [deploy the sample Hello World application](serverless-getting-started-hello-world.md):
+ AWSCloudFormationFullAccess
+ IAMFullAccess
+ AWSLambda\$1FullAccess
+ AmazonAPIGatewayAdministrator
+ AmazonS3FullAccess
+ AmazonEC2ContainerRegistryFullAccess
For information about attaching policies to an IAM user, see [Changing permissions for an IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html) in the *IAM User Guide*.
## Grant specific IAM permissions
For the most granular level of access control, you can grant specific IAM permissions to users using [policy statements](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_statement.html). If you use this option, make sure that the policy statement includes all of the actions and resources required for the serverless applications that the users manage.
The best practice with this option is to deny users the permission to create roles, including Lambda execution roles, so they can't grant themselves escalated permissions. So, you as the administrator must first create a [Lambda execution role](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html) that will be specified in the serverless applications that users will manage. For information about creating Lambda execution roles, see [Creating an execution role in the IAM console](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html#permissions-executionrole-console).
For the [sample Hello World application](serverless-getting-started-hello-world.md) the **AWSLambdaBasicExecutionRole** is sufficient to run the application. After you've created a Lambda execution role, modify the AWS SAM template file of the sample Hello World application to add the following property to the `AWS::Serverless::Function` resource:
```
Role: lambda-execution-role-arn
```
With the modified Hello World application in place, the following policy statement grants sufficient permissions for users to deploy, update, and delete the application:
**Note**
The example policy statement in this section grants sufficient permission for you to deploy, update, and delete the the [sample Hello World application](serverless-getting-started-hello-world.md). If you add additional resource types to your application, you need to update the policy statement to include the following:
Permission for your application to call the service's actions.
The service principal, if needed for the service's actions.
For example, if you add a Step Functions workflow, you may need to add permissions for actions listed [here](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsstepfunctions.html#awsstepfunctions-actions-as-permissions), and the `states.amazonaws.com` service principal.
For more information about IAM policies, see [Managing IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage.html) in the *IAM User Guide*.
# Control API access with your AWS SAM template
Controlling access to your API Gateway APIs helps ensure your serverless application is secure and can only be accessed through the authorization you enable. You can enable authorization in your AWS SAM template to control who can access your API Gateway APIs.
AWS SAM supports several mechanisms for controlling access to your API Gateway APIs. The set of supported mechanisms differs between `AWS::Serverless::HttpApi` and `AWS::Serverless::Api` resource types.
The following table summarizes the mechanisms that each resource type supports.
| Mechanisms for controlling access | AWS::Serverless::HttpApi | AWS::Serverless::Api |
| --- | --- | --- |
| Lambda authorizers | ✓ | ✓ |
| IAM permissions | | ✓ |
| Amazon Cognito user pools | ✓ \$1 | ✓ |
| API keys | | ✓ |
| Resource policies | | ✓ |
| OAuth 2.0/JWT authorizers | ✓ | |
\$1 You can use Amazon Cognito as a JSON Web Token (JWT) issuer with the `AWS::Serverless::HttpApi` resource type.
+ **Lambda authorizers** – A Lambda authorizer (formerly known as a *custom authorizer*) is a Lambda function that you provide to control access to your API. When your API is called, this Lambda function is invoked with a request context or an authorization token that the client application provides. The Lambda function responds whether the caller is authorized to perform the requested operation.
Both the `AWS::Serverless::HttpApi` and `AWS::Serverless::Api` resource types support Lambda authorizers.
For more information about Lambda authorizers with `AWS::Serverless::HttpApi`, see [Working with AWS Lambda authorizers for HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-lambda-authorizer.html) in the *API Gateway Developer Guide*. For more information about Lambda authorizers with `AWS::Serverless::Api`, see [Use API Gateway Lambda authorizers](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html) in the *API Gateway Developer Guide*.
For examples of Lambda authorizers for either resource type, see [Lambda authorizer examples for AWS SAM](serverless-controlling-access-to-apis-lambda-authorizer.md).
+ **IAM permissions** – You can control who can invoke your API using [AWS Identity and Access Management (IAM) permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html). Users calling your API must be authenticated with IAM credentials. Calls to your API succeed only if there is an IAM policy attached to the IAM user that represents the API caller, an IAM group that contains the user, or an IAM role that the user assumes.
Only the `AWS::Serverless::Api` resource type supports IAM permissions.
For more information, see [Control access to an API with IAM permissions](https://docs.aws.amazon.com/apigateway/latest/developerguide/permissions.html) in the *API Gateway Developer Guide*. For an example, see [IAM permission example for AWS SAM](serverless-controlling-access-to-apis-permissions.md).
+ **Amazon Cognito user pools** – Amazon Cognito user pools are user directories in Amazon Cognito. A client of your API must first sign in a user to the user pool and obtain an identity or access token for the user. Then the client calls your API with one of the returned tokens. The API call succeeds only if the required token is valid.
The `AWS::Serverless::Api` resource type supports Amazon Cognito user pools. The `AWS::Serverless::HttpApi` resource type supports the use of Amazon Cognito as a JWT issuer.
For more information, see [Control access to a REST API using Amazon Cognito user pools as authorizer](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-integrate-with-cognito.html) in the *API Gateway Developer Guide*. For an example, see [Amazon Cognito user pool example for AWS SAM](serverless-controlling-access-to-apis-cognito-user-pool.md).
+ **API keys** – API keys are alphanumeric string values that you distribute to application developer customers to grant access to your API.
Only the `AWS::Serverless::Api` resource type supports API keys.
For more information about API keys, see [Creating and using usage plans with API keys](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html) in the *API Gateway Developer Guide*. For an example of API keys, see [API key example for AWS SAM](serverless-controlling-access-to-apis-keys.md).
+ **Resource policies** – Resource policies are JSON policy documents that you can attach to an API Gateway API. Use resource policies to control whether a specified principal (typically an IAM user or role) can invoke the API.
Only the `AWS::Serverless::Api` resource type supports resource policies as a mechanism for controlling access to API Gateway APIs.
For more information about resource policies, see [Controlling access to an API with API Gateway resource policies](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-resource-policies.html) in the *API Gateway Developer Guide*. For an example of resource policies, see [Resource policy example for AWS SAM](serverless-controlling-access-to-apis-resource-policies.md).
+ **OAuth 2.0/JWT authorizers** – You can use JWTs as a part of [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html) and [OAuth 2.0](https://oauth.net/2/) frameworks to control access to your APIs. API Gateway validates the JWTs that clients submit with API requests, and allows or denies requests based on token validation and, optionally, scopes in the token.
Only the `AWS::Serverless::HttpApi` resource type supports OAuth 2.0/JWT authorizers.
For more information, see [Controlling access to HTTP APIs with JWT authorizers](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-jwt-authorizer.html) in the *API Gateway Developer Guide*. For an example, see [OAuth 2.0/JWT authorizer example for AWS SAM](serverless-controlling-access-to-apis-oauth2-authorizer.md).
## Choosing a mechanism to control access
The mechanism that you choose to use for controlling access to your API Gateway APIs depends on a few factors. For example, if you have a greenfield project without either authorization or access control set up, then Amazon Cognito user pools might be your best option. This is because when you set up user pools, you also automatically set up both authentication and access control.
However, if your application already has authentication set up, then using Lambda authorizers might be your best option. This is because you can call your existing authentication service and return a policy document based on the response. Also, if your application requires custom authentication or access control logic that user pools don't support, then Lambda authorizers might be your best option.
When you've chosen which mechanism to use, see the corresponding section in [Examples](#serverless-controlling-access-to-apis-examples) for how to use AWS SAM to configure your application to use that mechanism.
## Customizing error responses
You can use AWS SAM to customize the content of some API Gateway error responses. Only the `AWS::Serverless::Api` resource type supports customized API Gateway responses.
For more information about API Gateway responses, see [Gateway responses in API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-gatewayResponse-definition.html) in the *API Gateway Developer Guide*. For an example of customized responses, see [Customized response example for AWS SAM](serverless-controlling-access-to-apis-customize-response.md).
## Examples
+ [Lambda authorizer examples for AWS SAM](serverless-controlling-access-to-apis-lambda-authorizer.md)
+ [IAM permission example for AWS SAM](serverless-controlling-access-to-apis-permissions.md)
+ [Amazon Cognito user pool example for AWS SAM](serverless-controlling-access-to-apis-cognito-user-pool.md)
+ [API key example for AWS SAM](serverless-controlling-access-to-apis-keys.md)
+ [Resource policy example for AWS SAM](serverless-controlling-access-to-apis-resource-policies.md)
+ [OAuth 2.0/JWT authorizer example for AWS SAM](serverless-controlling-access-to-apis-oauth2-authorizer.md)
+ [Customized response example for AWS SAM](serverless-controlling-access-to-apis-customize-response.md)
# Lambda authorizer examples for AWS SAM
The `AWS::Serverless::Api` resource type supports two types of Lambda authorizers: `TOKEN` authorizers and `REQUEST` authorizers. The `AWS::Serverless::HttpApi` resource type supports only `REQUEST` authorizers. The following are examples of each type.
## Lambda `TOKEN` authorizer example (AWS::Serverless::Api)
You can control access to your APIs by defining a Lambda `TOKEN` authorizer within your AWS SAM template. To do this, you use the [ApiAuth](sam-property-api-apiauth.md) data type.
The following is an example AWS SAM template section for a Lambda `TOKEN` authorizer:
**Note**
In the following example, the SAM `FunctionRole` is implicitly generated.
```
Resources:
MyApi:
Type: AWS::Serverless::Api
Properties:
StageName: Prod
Auth:
DefaultAuthorizer: MyLambdaTokenAuthorizer
Authorizers:
MyLambdaTokenAuthorizer:
FunctionArn: !GetAtt MyAuthFunction.Arn
MyFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: ./src
Handler: index.handler
Runtime: nodejs12.x
Events:
GetRoot:
Type: Api
Properties:
RestApiId: !Ref MyApi
Path: /
Method: get
MyAuthFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: ./src
Handler: authorizer.handler
Runtime: nodejs12.x
```
For more information about Lambda authorizers, see [Use API Gateway Lambda authorizers](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html) in the *API Gateway Developer Guide*.
## Lambda `REQUEST` authorizer example (AWS::Serverless::Api)
You can control access to your APIs by defining a Lambda `REQUEST` authorizer within your AWS SAM template. To do this, you use the [ApiAuth](sam-property-api-apiauth.md) data type.
The following is an example AWS SAM template section for a Lambda `REQUEST` authorizer:
```
Resources:
MyApi:
Type: AWS::Serverless::Api
Properties:
StageName: Prod
Auth:
DefaultAuthorizer: MyLambdaRequestAuthorizer
Authorizers:
MyLambdaRequestAuthorizer:
FunctionPayloadType: REQUEST
FunctionArn: !GetAtt MyAuthFunction.Arn
Identity:
QueryStrings:
- auth
MyFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: ./src
Handler: index.handler
Runtime: nodejs12.x
Events:
GetRoot:
Type: Api
Properties:
RestApiId: !Ref MyApi
Path: /
Method: get
MyAuthFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: ./src
Handler: authorizer.handler
Runtime: nodejs12.x
```
For more information about Lambda authorizers, see [Use API Gateway Lambda authorizers](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html) in the *API Gateway Developer Guide*.
## Lambda authorizer example (AWS::Serverless::HttpApi)
You can control access to your HTTP APIs by defining a Lambda authorizer within your AWS SAM template. To do this, you use the [HttpApiAuth](sam-property-httpapi-httpapiauth.md) data type.
The following is an example AWS SAM template section for a Lambda authorizer:
```
Resources:
MyApi:
Type: AWS::Serverless::HttpApi
Properties:
StageName: Prod
Auth:
DefaultAuthorizer: MyLambdaRequestAuthorizer
Authorizers:
MyLambdaRequestAuthorizer:
FunctionArn: !GetAtt MyAuthFunction.Arn
FunctionInvokeRole: !GetAtt MyAuthFunctionRole.Arn
Identity:
Headers:
- Authorization
AuthorizerPayloadFormatVersion: 2.0
EnableSimpleResponses: true
MyFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: ./src
Handler: index.handler
Runtime: nodejs12.x
Events:
GetRoot:
Type: HttpApi
Properties:
ApiId: !Ref MyApi
Path: /
Method: get
PayloadFormatVersion: "2.0"
MyAuthFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: ./src
Handler: authorizer.handler
Runtime: nodejs12.x
```
# IAM permission example for AWS SAM
You can control access to your APIs by defining IAM permissions within your AWS SAM template. To do this, you use the [ApiAuth](sam-property-api-apiauth.md) data type.
The following is an example AWS SAM template that uses for IAM permissions:
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Resources:
MyApi:
Type: AWS::Serverless::Api
Properties:
StageName: Prod
Description: 'API with IAM authorization'
Auth:
DefaultAuthorizer: AWS_IAM #sets AWS_IAM auth for all methods in this API
MyFunction:
Type: AWS::Serverless::Function
Properties:
Handler: index.handler
Runtime: python3.10
Events:
GetRoot:
Type: Api
Properties:
RestApiId: !Ref MyApi
Path: /
Method: get
InlineCode: |
def handler(event, context):
return {'body': 'Hello World!', 'statusCode': 200}
```
For more information about IAM permissions, see [Control access for invoking an API](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-control-access-using-iam-policies-to-invoke-api.html) in the *API Gateway Developer Guide*.
# Amazon Cognito user pool example for AWS SAM
You can control access to your APIs by defining Amazon Cognito user pools within your AWS SAM template. To do this, you use the [ApiAuth](sam-property-api-apiauth.md) data type.
The following is an example AWS SAM template section for a user pool:
```
Resources:
MyApi:
Type: AWS::Serverless::Api
Properties:
StageName: Prod
Cors: "'*'"
Auth:
DefaultAuthorizer: MyCognitoAuthorizer
Authorizers:
MyCognitoAuthorizer:
UserPoolArn: !GetAtt MyCognitoUserPool.Arn
MyFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: ./src
Handler: lambda.handler
Runtime: nodejs12.x
Events:
Root:
Type: Api
Properties:
RestApiId: !Ref MyApi
Path: /
Method: GET
MyCognitoUserPool:
Type: AWS::Cognito::UserPool
Properties:
UserPoolName: !Ref CognitoUserPoolName
Policies:
PasswordPolicy:
MinimumLength: 8
UsernameAttributes:
- email
Schema:
- AttributeDataType: String
Name: email
Required: false
MyCognitoUserPoolClient:
Type: AWS::Cognito::UserPoolClient
Properties:
UserPoolId: !Ref MyCognitoUserPool
ClientName: !Ref CognitoUserPoolClientName
GenerateSecret: false
```
For more information about Amazon Cognito user pools, see [Control access to a REST API using Amazon Cognito user pools as authorizer](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-integrate-with-cognito.html) in the *API Gateway Developer Guide*.
# API key example for AWS SAM
You can control access to your APIs by requiring API keys within your AWS SAM template. To do this, you use the [ApiAuth](sam-property-api-apiauth.md) data type.
The following is an example AWS SAM template section for API keys:
```
Resources:
MyApi:
Type: AWS::Serverless::Api
Properties:
StageName: Prod
Auth:
ApiKeyRequired: true # sets for all methods
MyFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: .
Handler: index.handler
Runtime: nodejs12.x
Events:
ApiKey:
Type: Api
Properties:
RestApiId: !Ref MyApi
Path: /
Method: get
Auth:
ApiKeyRequired: true
```
For more information about API keys, see [Creating and using usage plans with API keys](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html) in the *API Gateway Developer Guide*.
# Resource policy example for AWS SAM
You can control access to your APIs by attaching a resource policy within your AWS SAM template. To do this, you use the [ApiAuth](sam-property-api-apiauth.md) data type.
The following is an example AWS SAM template for a private API. A private API must have a resource policy to deploy.
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Resources:
MyPrivateApi:
Type: AWS::Serverless::Api
Properties:
StageName: Prod
EndpointConfiguration: PRIVATE # Creates a private API. Resource policies are required for all private APIs.
Auth:
ResourcePolicy:
CustomStatements:
- Effect: 'Allow'
Action: 'execute-api:Invoke'
Resource: ['execute-api:/*/*/*']
Principal: '*'
- Effect: 'Deny'
Action: 'execute-api:Invoke'
Resource: ['execute-api:/*/*/*']
Principal: '*'
MyFunction:
Type: 'AWS::Serverless::Function'
Properties:
InlineCode: |
def handler(event, context):
return {'body': 'Hello World!', 'statusCode': 200}
Handler: index.handler
Runtime: python3.10
Events:
AddItem:
Type: Api
Properties:
RestApiId:
Ref: MyPrivateApi
Path: /
Method: get
```
For more information about resource policies, see [Controlling access to an API with API Gateway resource policies](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-resource-policies.html) in the *API Gateway Developer Guide*. For more information about private APIs, see [Creating a private API in Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-apis.html) in the *API Gateway Developer Guide*.
# OAuth 2.0/JWT authorizer example for AWS SAM
You can control access to your APIs using JWTs as part of [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html) and [OAuth 2.0](https://oauth.net/2/) frameworks. To do this, you use the [HttpApiAuth](sam-property-httpapi-httpapiauth.md) data type.
The following is an example AWS SAM template section for an OAuth 2.0/JWT authorizer:
```
Resources:
MyApi:
Type: AWS::Serverless::HttpApi
Properties:
Auth:
Authorizers:
MyOauth2Authorizer:
AuthorizationScopes:
- scope
IdentitySource: $request.header.Authorization
JwtConfiguration:
audience:
- audience1
- audience2
issuer: "https://www.example.com/v1/connect/oidc"
DefaultAuthorizer: MyOauth2Authorizer
StageName: Prod
MyFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: ./src
Events:
GetRoot:
Properties:
ApiId: MyApi
Method: get
Path: /
PayloadFormatVersion: "2.0"
Type: HttpApi
Handler: index.handler
Runtime: nodejs12.x
```
For more information about OAuth 2.0/JWT authorizers, see [Controlling access to HTTP APIs with JWT authorizers](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-jwt-authorizer.html) in the *API Gateway Developer Guide*.
# Customized response example for AWS SAM
You can customize some API Gateway error responses by defining response headers within your AWS SAM template. To do this, you use the [Gateway Response Object](https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#gateway-response-object) data type.
The following is an example AWS SAM template that creates a customized response for the `DEFAULT_5XX` error.
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Resources:
MyApi:
Type: AWS::Serverless::Api
Properties:
StageName: Prod
GatewayResponses:
DEFAULT_5XX:
ResponseParameters:
Headers:
Access-Control-Expose-Headers: "'WWW-Authenticate'"
Access-Control-Allow-Origin: "'*'"
ErrorHeader: "'MyCustomErrorHeader'"
ResponseTemplates:
application/json: "{\"message\": \"Error on the $context.resourcePath resource\" }"
GetFunction:
Type: AWS::Serverless::Function
Properties:
Runtime: python3.10
Handler: index.handler
InlineCode: |
def handler(event, context):
raise Exception('Check out the new response!')
Events:
GetResource:
Type: Api
Properties:
Path: /error
Method: get
RestApiId: !Ref MyApi
```
For more information about API Gateway responses, see [Gateway responses in API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-gatewayResponse-definition.html) in the *API Gateway Developer Guide*.
# Increase efficiency using Lambda layers with AWS SAM
Using AWS SAM, you can include layers in your serverless applications. AWS Lambda layers allow you to extract code from a Lambda function into a Lambda layer which can then be used across several Lambda functions. Doing this allows you to reduce the size of your deployment packages, separate core function logic from dependencies, and share dependencies across multiple functions. For more information about layers, see [Lambda layers](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html) in the *AWS Lambda Developer Guide*.
This topic provides information about the following:
+ Including layers in your application
+ How layers are cached locally
For information about building custom layers, see [Building Lambda layers in AWS SAM](building-layers.md).
## Including layers in your application
To include layers in your application, use the `Layers` property of the [AWS::Serverless::Function](sam-resource-function.md) resource type.
Following is an example AWS SAM template with a Lambda function that includes a layer:
```
ServerlessFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: .
Handler: my_handler
Runtime: Python3.7
Layers:
-
```
## How layers are cached locally
When you invoke your function using one of the `sam local` commands, the layers package of your function is downloaded and cached on your local host.
The following table shows the default cache directory locations for different operating systems.
****
| OS | Location |
| --- | --- |
| Windows 7 | C:\$1Users\$1\$1AppData\$1Roaming\$1AWS SAM |
| Windows 8 | C:\$1Users\$1\$1AppData\$1Roaming\$1AWS SAM |
| Windows 10 | C:\$1Users\$1\$1AppData\$1Roaming\$1AWS SAM |
| macOS | \$1/.aws-sam/layers-pkg |
| Unix | \$1/.aws-sam/layers-pkg |
After the package is cached, the AWS SAM CLI overlays the layers onto a Docker image that's used to invoke your function. The AWS SAM CLI generates the names of the images it builds, as well as the LayerVersions that are held in the cache. You can find more details about the schema in the following sections.
To inspect the overlaid layers, execute the following command to start a bash session in the image that you want to inspect:
```
docker run -it --entrypoint=/bin/bash samcli/lambda: -i
```
**Layer Caching Directory name schema**
Given a LayerVersionArn that's defined in your template, the AWS SAM CLI extracts the LayerName and Version from the ARN. It creates a directory to place the layer contents in named `LayerName-Version-`.
Example:
```
ARN = arn:aws:lambda:us-west-2:111111111111:layer:myLayer:1
Directory name = myLayer-1-926eeb5ff1
```
**Docker Images tag schema**
To compute the unique layers hash, combine all unique layer names with a delimiter of '-', take the SHA256 hash, and then take the first 10 characters.
Example:
```
ServerlessFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: .
Handler: my_handler
Runtime: Python3.7
Layers:
- arn:aws:lambda:us-west-2:111111111111:layer:myLayer:1
- arn:aws:lambda:us-west-2:111111111111:layer:mySecondLayer:1
```
Unique names are computed the same as the Layer Caching Directory name schema:
```
arn:aws:lambda:us-west-2:111111111111:layer:myLayer:1 = myLayer-1-926eeb5ff1
arn:aws:lambda:us-west-2:111111111111:layer:mySecondLayer:1 = mySecondLayer-1-6bc1022bdf
```
To compute the unique layers hash, combine all unique layer names with a delimiter of '-', take the sha256 hash, and then take the first 25 characters:
```
myLayer-1-926eeb5ff1-mySecondLayer-1-6bc1022bdf = 2dd7ac5ffb30d515926aef
```
Then combine this value with the function's runtime and architecture, with a delimiter of '-':
```
python3.7-x86_64-2dd7ac5ffb30d515926aefffd
```
# Reuse code and resources using nested applications in AWS SAM
A serverless application can include one or more **nested applications**. A nested application is a part of a larger application and can be packaged and deployed either as a stand-alone artifact or as a component of the larger application. Nested applications allow you to turn frequently used code and into its own application that can then be reused across a larger serverless application or multiple serverless applications.
As your serverless architectures grows, common patterns typically emerge in which the same components are defined in multiple application templates. Nested applications allow you to reuse common code, functionality, resources, and configurations in separate AWS SAM templates, allowing you to only maintain code from a single source. This reduces duplicated code and configurations. Additionally, this modular approach streamlines development, enhances code organization, and facilitates consistency across serverless applications. With nested applications, you can stay more focused on the business logic that's unique to your application.
To define a nested application in your serverless application, use the [AWS::Serverless::Application](sam-resource-application.md) resource type.
You can define nested applications from the following two sources:
+ An **AWS Serverless Application Repository application** – You can define nested applications by using applications that are available to your account in the AWS Serverless Application Repository. These can be *private* applications in your account, applications that are *privately shared* with your account, or applications that are *publicly shared* in the AWS Serverless Application Repository. For more information about the different deployment permissions levels, see [Application Deployment Permissions](https://docs.aws.amazon.com/serverlessrepo/latest/devguide/serverless-app-consuming-applications.html#application-deployment-permissions) and [Publishing Applications](https://docs.aws.amazon.com/serverlessrepo/latest/devguide/serverless-app-publishing-applications.html) in the *AWS Serverless Application Repository Developer Guide*.
+ A **local application** – You can define nested applications by using applications that are stored on your local file system.
See the following sections for details on how to use AWS SAM to define both of these types of nested applications in your serverless application.
**Note**
The maximum number of applications that can be nested in a serverless application is 200.
The maximum number of parameters a nested application can have is 60.
## Defining a nested application from the AWS Serverless Application Repository
You can define nested applications by using applications that are available in the AWS Serverless Application Repository. You can also store and distribute applications that contain nested applications using the AWS Serverless Application Repository. To review details of a nested application in the AWS Serverless Application Repository, you can use the AWS SDK, the AWS CLI, or the Lambda console.
To define an application that's hosted in the AWS Serverless Application Repository in your serverless application's AWS SAM template, use the **Copy as SAM Resource** button on the detail page of every AWS Serverless Application Repository application. To do this, follow these steps:
1. Make sure that you're signed in to the AWS Management Console.
1. Find the application that you want to nest in the AWS Serverless Application Repository by using the steps in the [Browsing, Searching, and Deploying Applications](https://docs.aws.amazon.com/serverlessrepo/latest/devguide/serverless-app-consuming-applications.html#browse-and-search-applications ) section of the *AWS Serverless Application Repository Developer Guide*.
1. Choose the **Copy as SAM Resource** button. The SAM template section for the application that you're viewing is now in your clipboard.
1. Paste the SAM template section into the `Resources:` section of the SAM template file for the application that you want to nest in this application.
The following is an example SAM template section for a nested application that's hosted in the AWS Serverless Application Repository:
```
Transform: AWS::Serverless-2016-10-31
Resources:
applicationaliasname:
Type: AWS::Serverless::Application
Properties:
Location:
ApplicationId: arn:aws:serverlessrepo:us-east-1:123456789012:applications/application-alias-name
SemanticVersion: 1.0.0
Parameters:
# Optional parameter that can have default value overridden
# ParameterName1: 15 # Uncomment to override default value
# Required parameter that needs value to be provided
ParameterName2: YOUR_VALUE
```
If there are no required parameter settings, you can omit the `Parameters:` section of the template.
**Important**
Applications that contain nested applications hosted in the AWS Serverless Application Repository inherit the nested applications' sharing restrictions.
For example, suppose an application is publicly shared, but it contains a nested application that's only privately shared with the AWS account that created the parent application. In this case, if your AWS account doesn't have permission to deploy the nested application, you aren't able to deploy the parent application. For more information about permissions to deploy applications, see [Application Deployment Permissions](https://docs.aws.amazon.com/serverlessrepo/latest/devguide/serverless-app-consuming-applications.html#application-deployment-permissions) and [Publishing Applications](https://docs.aws.amazon.com/serverlessrepo/latest/devguide/serverless-app-publishing-applications.html) in the *AWS Serverless Application Repository Developer Guide*.
## Defining a nested application from the local file system
You can define nested applications by using applications that are stored on your local file system. You do this by specifying the path to the AWS SAM template file that's stored on your local file system.
The following is an example SAM template section for a nested local application:
```
Transform: AWS::Serverless-2016-10-31
Resources:
applicationaliasname:
Type: AWS::Serverless::Application
Properties:
Location: ../my-other-app/template.yaml
Parameters:
# Optional parameter that can have default value overridden
# ParameterName1: 15 # Uncomment to override default value
# Required parameter that needs value to be provided
ParameterName2: YOUR_VALUE
```
If there are no parameter settings, you can omit the `Parameters:` section of the template.
## Deploying nested applications
You can deploy your nested application by using the AWS SAM CLI command `sam deploy`. For more details, see [Deploy your application and resources with AWS SAM](serverless-deploying.md).
**Note**
When you deploy an application that contains nested applications, you must acknowledge it contains nested applications. You do this by passing `CAPABILITY_AUTO_EXPAND` to the [CreateCloudFormationChangeSet API](https://docs.aws.amazon.com/goto/WebAPI/serverlessrepo-2017-09-08/CreateCloudFormationChangeSet),or using the [https://docs.aws.amazon.com/cli/latest/reference/serverlessrepo/create-cloud-formation-change-set.html](https://docs.aws.amazon.com/cli/latest/reference/serverlessrepo/create-cloud-formation-change-set.html) AWS CLI command.
For more information about acknowledging nested applications, see [Acknowledging IAM Roles, Resource Policies, and Nested Applications when Deploying Applications](https://docs.aws.amazon.com/serverlessrepo/latest/devguide/acknowledging-application-capabilities.html) in the *AWS Serverless Application Repository Developer Guide*.
# Manage time-based events with EventBridge Scheduler in AWS SAM
The content in this topic provides details on what Amazon EventBridge Scheduler is, what support AWS SAM offers, how you can create Scheduler events, and examples you can reference when creating Scheduler events.
## What is Amazon EventBridge Scheduler?
Use EventBridge Scheduler to schedule events in your AWS SAM templates. Amazon EventBridge Scheduler is a scheduling service that lets you create, initiate, and manage tens of millions of events and tasks across all AWS services. This service is particularly useful for time-related events. You can use it to schedule events and recurring time-based invocations. It also supports one-time events as well as rate and chron expressions with a start and end time.
To learn more about Amazon EventBridge Scheduler, see [What is Amazon EventBridge Scheduler?](https://docs.aws.amazon.com/scheduler/latest/UserGuide/what-is-scheduler.html) in the *EventBridge Scheduler User Guide*.
**Topics**
+ [
## What is Amazon EventBridge Scheduler?
](#using-eventbridge-scheduler-intro)
+ [
## EventBridge Scheduler support in AWS SAM
](#using-eventbridge-scheduler-sam-support)
+ [
## Creating EventBridge Scheduler events in AWS SAM
](#using-eventbridge-scheduler-sam-create)
+ [
## Examples
](#using-eventbridge-scheduler-examples)
+ [
## Learn more
](#using-eventbridge-scheduler-learn)
## EventBridge Scheduler support in AWS SAM
The AWS Serverless Application Model (AWS SAM) template specification provides a simple, short-hand syntax that you can use to schedule events with EventBridge Scheduler for AWS Lambda and AWS Step Functions.
## Creating EventBridge Scheduler events in AWS SAM
Set the `ScheduleV2` property as the event type in your AWS SAM template to define your EventBridge Scheduler event. This property supports the `AWS::Serverless::Function` and `AWS::Serverless::StateMachine` resource types.
```
MyFunction:
Type: AWS::Serverless::Function
Properties:
Events:
CWSchedule:
Type: ScheduleV2
Properties:
ScheduleExpression: 'rate(1 minute)'
Name: TestScheduleV2Function
Description: Test schedule event
MyStateMachine:
Type: AWS::Serverless::StateMachine
Properties:
Events:
CWSchedule:
Type: ScheduleV2
Properties:
ScheduleExpression: 'rate(1 minute)'
Name: TestScheduleV2StateMachine
Description: Test schedule event
```
EventBridge Scheduler event scheduling also supports *dead-letter queues (DLQ)* for unprocessed events. For more information on dead-letter queues, see [Configuring a dead-letter queue for EventBridge Scheduler](https://docs.aws.amazon.com/scheduler/latest/UserGuide/configuring-schedule-dlq.html) in the *EventBridge Scheduler User Guide*.
When a DLQ ARN is specified, AWS SAM configures permissions for the Scheduler schedule to send messages to the DLQ. When a DLQ ARN is not specified, AWS SAM will create the DLQ resource.
## Examples
### Basic example of defining an EventBridge Scheduler event with AWS SAM
```
Transform: AWS::Serverless-2016-10-31
Resources:
MyLambdaFunction:
Type: AWS::Serverless::Function
Properties:
Handler: index.handler
Runtime: python3.8
InlineCode: |
def handler(event, context):
print(event)
return {'body': 'Hello World!', 'statusCode': 200}
MemorySize: 128
Events:
Schedule:
Type: ScheduleV2
Properties:
ScheduleExpression: rate(1 minute)
Input: '{"hello": "simple"}'
MySFNFunction:
Type: AWS::Serverless::Function
Properties:
Handler: index.handler
Runtime: python3.8
InlineCode: |
def handler(event, context):
print(event)
return {'body': 'Hello World!', 'statusCode': 200}
MemorySize: 128
StateMachine:
Type: AWS::Serverless::StateMachine
Properties:
Type: STANDARD
Definition:
StartAt: MyLambdaState
States:
MyLambdaState:
Type: Task
Resource: !GetAtt MySFNFunction.Arn
End: true
Policies:
- LambdaInvokePolicy:
FunctionName: !Ref MySFNFunction
Events:
Schedule:
Type: ScheduleV2
Properties:
ScheduleExpression: rate(1 minute)
Input: '{"hello": "simple"}'
```
## Learn more
To learn more about defining the `ScheduleV2` EventBridge Scheduler property, see:
+ [ScheduleV2](sam-property-function-schedulev2.md) for `AWS::Serverless::Function`.
+ [ScheduleV2](sam-property-statemachine-statemachineschedulev2.md) for `AWS::Serverless::StateMachine`.
# Orchestrating AWS SAM resources with AWS Step Functions
You can use [AWS Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/) to orchestrate AWS Lambda functions and other AWS resources to form complex and robust workflows. Step Functions to tell your application when and under what conditions your AWS resources, like AWS Lambda functions, are used. This simplifies the process of forming complex and robust workflows. Using [AWS::Serverless::StateMachine](sam-resource-statemachine.md), you define the individual steps in your workflow, associate resources in each step, and then sequence these steps together. You also add transitions and conditions where they are needed. This simplifies the process of making a complex and robust workflow.
**Note**
To manage AWS SAM templates that contain Step Functions state machines, you must use version 0.52.0 or later of the AWS SAM CLI. To check which version you have, execute the command `sam --version`.
Step Functions is based on the concepts of [tasks](https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-task-state.html) and [state machines](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-states.html). You define state machines using the JSON-based [Amazon States Language](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-amazon-states-language.html). The [Step Functions console](https://console.aws.amazon.com/states/home?region=us-east-1#/) displays a graphical view of your state machine's structure so you can visually check your state machine's logic and monitor executions.
With Step Functions support in AWS Serverless Application Model (AWS SAM), you can do the following:
+ Define state machines, either directly within an AWS SAM template or in a separate file
+ Create state machine execution roles through AWS SAM policy templates, inline policies, or managed policies
+ Trigger state machine executions with API Gateway or Amazon EventBridge events, on a schedule within an AWS SAM template, or by calling APIs directly
+ Use available [AWS SAM Policy Templates](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-policy-templates.html) for common Step Functions development patterns.
## Example
The following example snippet from a AWS SAM template file defines a Step Functions state machine in a definition file. Note that the `my_state_machine.asl.json` file must be written in [Amazon States Language](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-amazon-states-language.html).
```
AWSTemplateFormatVersion: "2010-09-09"
Transform: AWS::Serverless-2016-10-31
Description: Sample SAM template with Step Functions State Machine
Resources:
MyStateMachine:
Type: AWS::Serverless::StateMachine
Properties:
DefinitionUri: statemachine/my_state_machine.asl.json
...
```
To download a sample AWS SAM application that includes a Step Functions state machine, see [Create a Step Functions State Machine Using AWS SAM](https://docs.aws.amazon.com/step-functions/latest/dg/tutorial-state-machine-using-sam.html) in the *AWS Step Functions Developer Guide*.
## More information
To learn more about Step Functions and using it with AWS SAM, see the following:
+ [How AWS Step Functions works](https://docs.aws.amazon.com/step-functions/latest/dg/how-step-functions-works.html)
+ [AWS Step Functions and AWS Serverless Application Model](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-sam-sfn.html)
+ [Tutorial: Create a Step Functions State Machine Using AWS SAM](https://docs.aws.amazon.com/step-functions/latest/dg/tutorial-state-machine-using-sam.html)
+ [AWS SAM Specification: AWS::Serverless::StateMachine](sam-resource-statemachine.md)
# Set up code signing for your AWS SAM application
To ensure that only trusted code is deployed, you can use AWS SAM to enable code signing with your serverless applications. Signing your code helps ensure that code has not been altered since signing and that only signed code packages from trusted publishers run in your Lambda functions. This helps free up organizations from the burden of building gatekeeper components in their deployment pipelines.
For more information about code signing, see [Configuring code signing for Lambda functions](https://docs.aws.amazon.com/lambda/latest/dg/configuration-codesigning.html) in the *AWS Lambda Developer Guide*.
Before you can configure code signing for your serverless application, you must create a signing profile using AWS Signer. You use this signing profile for the following tasks:
1. **Creating a code signing configuration** – Declare an [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-codesigningconfig.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-codesigningconfig.html) resource to specify the signing profiles of trusted publishers and to set the policy action for validation checks. You can declare this object in the same AWS SAM template as your serverless function, in a different AWS SAM template, or in an CloudFormation template. You then enable code signing for a serverless function by specify the [https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html#sam-function-codesigningconfigarn](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html#sam-function-codesigningconfigarn) property the function with the Amazon Resource Name (ARN) of an [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-codesigningconfig.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-codesigningconfig.html) resource.
1. **Signing your code** – Use the [https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-package.html](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-package.html) or [https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-deploy.html](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-deploy.html) command with the `--signing-profiles` option.
**Note**
In order to successfully sign your code with the `sam package` or `sam deploy` commands, versioning must be enabled for the Amazon S3 bucket you use with these commands. If you are using the Amazon S3 Bucket that AWS SAM creates for you, versioning is enabled automatically. For more information about Amazon S3 bucket versioning and instructions for enabling versioning on an Amazon S3 bucket that you provide, see [Using versioning in Amazon S3 buckets](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html) in the *Amazon Simple Storage Service User Guide*.
When you deploy a serverless application, Lambda performs validation checks on all functions that you've enabled code signing for. Lambda also performs validation checks on any layers that those functions depend on. For more information about Lambda's validation checks, see [Signature validation](https://docs.aws.amazon.com/lambda/latest/dg/configuration-codesigning.html#config-codesigning-valid) in the *AWS Lambda Developer Guide*.
## Example
### Creating a signing profile
To create a signing profile, run the following command:
```
aws signer put-signing-profile --platform-id "AWSLambda-SHA384-ECDSA" --profile-name MySigningProfile
```
If the previous command is successful, you see the signing profile's ARN returned. For example:
```
{
"arn": "arn:aws:signer:us-east-1:111122223333:/signing-profiles/MySigningProfile",
"profileVersion": "SAMPLEverx",
"profileVersionArn": "arn:aws:signer:us-east-1:111122223333:/signing-profiles/MySigningProfile/SAMPLEverx"
}
```
The `profileVersionArn` field contains the ARN to use when you create the code signing configuration.
### Creating a code signing configuration and enabling code signing for a function
The following example AWS SAM template declares an [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-codesigningconfig.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-codesigningconfig.html) resource and enables code signing for a Lambda function. In this example, there is one trusted profile, and deployments are rejected if the signature checks fail.
```
Resources:
HelloWorld:
Type: AWS::Serverless::Function
Properties:
CodeUri: hello_world/
Handler: app.lambda_handler
Runtime: python3.7
CodeSigningConfigArn: !Ref MySignedFunctionCodeSigningConfig
MySignedFunctionCodeSigningConfig:
Type: AWS::Lambda::CodeSigningConfig
Properties:
Description: "Code Signing for MySignedLambdaFunction"
AllowedPublishers:
SigningProfileVersionArns:
- MySigningProfile-profileVersionArn
CodeSigningPolicies:
UntrustedArtifactOnDeployment: "Enforce"
```
### Signing your code
You can sign your code when packaging or deploying your application. Specify the `--signing-profiles` option with either the `sam package` or `sam deploy` command, as shown in the following example commands.
Signing your function code when packaging your application:
```
sam package --signing-profiles HelloWorld=MySigningProfile --s3-bucket amzn-s3-demo-bucket --output-template-file packaged.yaml
```
Signing both your function code and a layer that your function depends on, when packaging your application:
```
sam package --signing-profiles HelloWorld=MySigningProfile MyLayer=MySigningProfile --s3-bucket amzn-s3-demo-bucket --output-template-file packaged.yaml
```
Signing your function code and a layer, then performing a deployment:
```
sam deploy --signing-profiles HelloWorld=MySigningProfile MyLayer=MySigningProfile --s3-bucket amzn-s3-demo-bucket --template-file packaged.yaml --stack-name --region us-east-1 --capabilities CAPABILITY_IAM
```
**Note**
In order to successfully sign your code with the `sam package` or `sam deploy` commands, versioning must be enabled for the Amazon S3 bucket you use with these commands. If you are using the Amazon S3 Bucket that AWS SAM creates for you, versioning is enabled automatically. For more information about Amazon S3 bucket versioning and instructions for enabling versioning on an Amazon S3 bucket that you provide, see [Using versioning in Amazon S3 buckets](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html) in the *Amazon Simple Storage Service User Guide*.
## Providing signing profiles with `sam deploy --guided`
When you run the `sam deploy --guided` command with a serverless application that's configured with code signing, AWS SAM prompts you to provide the signing profile to use for code signing. For more information about `sam deploy --guided` prompts, see [sam deploy](sam-cli-command-reference-sam-deploy.md) in the AWS SAM CLI command reference.
# Validate AWS SAM template files
Validate your templates with `sam validate`. Currently, this command validates that the template provided is valid JSON / YAML. As with most AWS SAM CLI commands, it looks for a `template.[yaml|yml]` file in your current working directory by default. You can specify a different template file/location with the `-t` or `--template` option.
Example:
```
$ sam validate
/template.yaml is a valid SAM Template
```
**Note**
The `sam validate` command requires AWS credentials to be configured. For more information, see [Configuring the AWS SAM CLI](using-sam-cli-configure.md).
# Build your application with AWS SAM
After you have added your infrastructure as code (IaC) to your AWS SAM template, you’ll be ready to start building your application using the **sam build** command. This command creates build artifacts from the files in your application project directory (that is, your AWS SAM template file, application code, and any applicable language-specific files and dependencies). These build artifacts prepare your serverless application for later steps of your application's development, such as local testing and deploying to the AWS Cloud. Both testing and deploying use build artifacts as inputs.
You can use **sam build** to build your entire serverless application. Additionally, you can create customized builds, like one's with specific functions, layers, or custom runtimes. To read more on how and why you use **sam build**, see the topics in this section. For an introduction to using the `sam build` command, see [Introduction to building with AWS SAM](using-sam-cli-build.md).
**Topics**
+ [
# Introduction to building with AWS SAM
](using-sam-cli-build.md)
+ [
# Default build with AWS SAM
](serverless-sam-cli-using-build.md)
+ [
# Customize builds with AWS SAM
](building-lambda-functions.md)
# Introduction to building with AWS SAM
Use the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) `sam build` command to prepare your serverless application for subsequent steps in your development workflow, such as local testing or deploying to the AWS Cloud. This command creates a `.aws-sam` directory that structures your application in a format and location that `sam local` and `sam deploy` require.
+ For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli).
+ For a list of `sam build` command options, see [sam build](sam-cli-command-reference-sam-build.md).
+ For an example of using `sam build` during a typical development workflow, see [Step 2: Build your application](serverless-getting-started-hello-world.md#serverless-getting-started-hello-world-build).
**Note**
Using `sam build` requires that you start with the basic components of a serverless application on your development machine. This includes an AWS SAM template, AWS Lambda function code, and any language-specific files and dependencies. To learn more, see [Create your application in AWS SAM](using-sam-cli-init.md).
**Topics**
+ [
## Building applications with sam build
](#using-sam-cli-build-apps)
+ [
## Local testing and deployment
](#using-sam-cli-build-test-deploy)
+ [
## Best practices
](#using-sam-cli-build-best)
+ [
## Options for sam build
](#using-sam-cli-build-options)
+ [
## Troubleshooting
](#using-sam-cli-build-troubleshooting)
+ [
## Examples
](#using-sam-cli-build-examples)
+ [
## Learn more
](#using-sam-cli-build-learn)
## Building applications with sam build
Before using `sam build`, consider configuring the following:
1. **Lambda functions and layers** – The `sam build` command can build Lambda functions and layers. To learn more about Lambda layers, see [Building Lambda layers in AWS SAM](building-layers.md).
1. **Lambda runtime** – The *runtime* provides a language-specific environment that runs your function in an execution environment when invoked. You can configure native and custom runtimes.
1. **Native runtime** – Author your Lambda functions in a supported Lambda runtime and build you functions to use a native Lambda runtime in the AWS Cloud.
1. **Custom runtime** – Author your Lambda functions using any programming language and build your runtime using a custom process defined in a makefile or third-party builder such as esbuild. To learn more, see [Building Lambda functions with custom runtimes in AWS SAM](building-custom-runtimes.md).
1. **Lambda package type** – Lambda functions can be packaged in the following Lambda deployment package types:
1. **.zip file archive** – Contains your application code and its dependencies.
1. **Container image** – Contains the base operating system, the runtime, Lambda extensions, your application code and its dependencies.
These application settings can be configured when initializing an application using `sam init`.
+ To learn more about using `sam init`, see [Create your application in AWS SAM](using-sam-cli-init.md).
+ To learn more about configuring these settings in your application, see [Default build with AWS SAM](serverless-sam-cli-using-build.md).
**To build an application**
1. `cd` to the root of your project. This is the same location as your AWS SAM template.
```
$ cd sam-app
```
1. Run the following:
```
sam-app $ sam build
```
**Note**
A commonly used option is `--use-container`. To learn more, see [Building a Lambda function inside of a provided container](#using-sam-cli-build-options-container).
The following is an example of the AWS SAM CLI output:
```
sam-app $ sam build
Starting Build use cache
Manifest file is changed (new hash: 3298f1304...d4d421) or dependency folder (.aws-sam/deps/4d3dfad6-a267-47a6-a6cd-e07d6fae318c) is missing for (HelloWorldFunction), downloading dependencies and copying/building source
Building codeuri: /Users/.../sam-app/hello_world runtime: python3.12 metadata: {} architecture: x86_64 functions: HelloWorldFunction
Running PythonPipBuilder:CleanUp
Running PythonPipBuilder:ResolveDependencies
Running PythonPipBuilder:CopySource
Running PythonPipBuilder:CopySource
Build Succeeded
Built Artifacts : .aws-sam/build
Built Template : .aws-sam/build/template.yaml
Commands you can use next
=========================
[*] Validate SAM template: sam validate
[*] Invoke Function: sam local invoke
[*] Test Function in the Cloud: sam sync --stack-name {{stack-name}} --watch
[*] Deploy: sam deploy --guided
```
1. The AWS SAM CLI creates a `.aws-sam` build directory. The following is an example:
```
.aws-sam
├── build
│ ├── HelloWorldFunction
│ │ ├── __init__.py
│ │ ├── app.py
│ │ └── requirements.txt
│ └── template.yaml
└── build.toml
```
Depending on how your application is configured, the AWS SAM CLI does the following:
1. Downloads, installs, and organizes dependencies in the `.aws-sam/build` directory.
1. Prepares your Lambda code. This can include compiling your code, creating executable binaries, and building container images.
1. Copies build artifacts to the `.aws-sam` directory. The format will vary based on your application package type.
1. For .zip package types, the artifacts are not zipped yet so that they can be used for local testing. The AWS SAM CLI zips your application when using `sam deploy`.
1. For container image package types, a container image is created locally and referenced in the `.aws-sam/build.toml` file.
1. Copies the AWS SAM template over to the `.aws-sam` directory and modifies it with new file paths when necessary.
The following are the major components that make up your build artifacts in the `.aws-sam` directory:
+ **The build directory** – Contains your Lambda functions and layers structured independently of each other. This results in a unique structure for each function or layer in the `.aws-sam/build` directory.
+ **The AWS SAM template** – Modified with updated values based on changes during the build process.
+ **The build.toml file** – A configuration file that contains build settings used by the AWS SAM CLI.
## Local testing and deployment
When performing local testing with `sam local` or deployment with `sam deploy`, the AWS SAM CLI does the following:
1. It first checks to see if an `.aws-sam` directory exists and if an AWS SAM template is located within that directory. If these conditions are met, the AWS SAM CLI considers this as the root directory of your application.
1. If these conditions are not met, the AWS SAM CLI considers the original location of your AWS SAM template as the root directory of your application.
When developing, if changes are made to your original application files, run `sam build` to update the `.aws-sam` directory before testing locally.
## Best practices
+ Don’t edit any code under the `.aws-sam/build` directory. Instead, update your original source code in your project folder and run `sam build` to update the `.aws-sam/build` directory.
+ When you modify your original files, run `sam build` to update the `.aws-sam/build` directory.
+ You may want the AWS SAM CLI to reference your project’s original root directory instead of the `.aws-sam` directory, such as when developing and testing with `sam local`. Delete the `.aws-sam` directory or the AWS SAM template in the `.aws-sam` directory to have the AWS SAM CLI recognize your original project directory as the root project directory. When ready, run `sam build` again to create the `.aws-sam` directory.
+ When you run `sam build`, the `.aws-sam/build` directory gets overwritten each time. The `.aws-sam` directory does not. If you want to store files, such as logs, store them in `.aws-sam` to prevent them from being overwritten.
## Options for sam build
### Building a single resource
Provide the resource’s logical ID to build only that resource. The following is an example:
```
$ sam build HelloWorldFunction
```
To build a resource of a nested application or stack, provide the application or stack logical ID along with the resource logical ID using the format `/` :
```
$ sam build MyNestedStack/MyFunction
```
### Building a Lambda function inside of a provided container
The `--use-container` option downloads a container image and uses it to build your Lambda functions. The local container is then referenced in your `.aws-sam/build.toml` file.
This option requires Docker to be installed. For instructions, see [Installing Docker](install-docker.md).
The following is an example of this command:
```
$ sam build --use-container
```
You can specify the container image to use with the `--build-image` option. The following is an example:
```
$ sam build --use-container --build-image amazon/aws-sam-cli-build-image-nodejs20.x
```
To specify the container image to use for a single function, provide the function logical ID. The following is an example:
```
$ sam build --use-container --build-image Function1=amazon/aws-sam-cli-build-image-python3.12
```
### Pass environment variables to the build container
Use the `--container-env-var` to pass environment variables to the build container. The following is an example:
```
$ sam build --use-container --container-env-var Function1.GITHUB_TOKEN= --container-env-var GLOBAL_ENV_VAR=
```
To pass environment variables from a file, use the `--container-env-var-file` option. The following is an example:
```
$ sam build --use-container --container-env-var-file
```
Example of the `env.json` file:
```
{
"MyFunction1": {
"GITHUB_TOKEN": "TOKEN1"
},
"MyFunction2": {
"GITHUB_TOKEN": "TOKEN2"
}
}
```
### Speed up the building of applications that contain multiple functions
When you run `sam build` on an application with multiple functions, the AWS SAM CLI builds each function one at a time. To speed up the build process, use the `--parallel` option. This builds all of your functions and layers at the same time.
The following is an example of this command:
```
$ sam build —-parallel
```
### Speed up build times by building your project in the source folder
For supported runtimes and build methods, you can use the `--build-in-source` option to build your project directly in the source folder. By default, the AWS SAM CLI builds in a temporary directory, which involves copying over source code and project files. With `--build-in-source`, the AWS SAM CLI builds directly in your source folder, which speeds up the build process by removing the need to copy files to a temporary directory.
For a list of supported runtimes and build methods, see `--build-in-source`.
## Troubleshooting
To troubleshoot the AWS SAM CLI, see [AWS SAM CLI troubleshooting](sam-cli-troubleshooting.md).
## Examples
### Building an application that uses a native runtime and .zip package type
For this example, see [Tutorial: Deploy a Hello World application with AWS SAM](serverless-getting-started-hello-world.md).
### Building an application that uses a native runtime and image package type
First, we run `sam init` to initialize a new application. During the interactive flow, we select the `Image` package type. The following is an example:
```
$ sam init
...
Which template source would you like to use?
1 - AWS Quick Start Templates
2 - Custom Template Location
Choice: 1
Choose an AWS Quick Start application template
1 - Hello World Example
2 - Multi-step workflow
3 - Serverless API
4 - Scheduled task
5 - Standalone function
6 - Data processing
7 - Hello World Example With Powertools
8 - Infrastructure event management
9 - Serverless Connector Hello World Example
10 - Multi-step workflow with Connectors
11 - Lambda EFS example
12 - DynamoDB Example
13 - Machine Learning
Template: 1
Use the most popular runtime and package type? (Python and zip) [y/N]: ENTER
Which runtime would you like to use?
...
10 - java8
11 - nodejs20.x
12 - nodejs18.x
13 - nodejs16.x
...
Runtime: 12
What package type would you like to use?
1 - Zip
2 - Image
Package type: 2
Based on your selections, the only dependency manager available is npm.
We will proceed copying the template using npm.
Would you like to enable X-Ray tracing on the function(s) in your application? [y/N]: ENTER
Would you like to enable monitoring using CloudWatch Application Insights?
For more info, please view https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-application-insights.html [y/N]: ENTER
Project name [sam-app]: ENTER
Cloning from https://github.com/aws/aws-sam-cli-app-templates (process may take a moment)
-----------------------
Generating application:
-----------------------
Name: sam-app
Base Image: amazon/nodejs18.x-base
Architectures: x86_64
Dependency Manager: npm
Output Directory: .
Configuration file: sam-app/samconfig.toml
Next steps can be found in the README file at sam-app/README.md
...
```
The AWS SAM CLI initializes an application and creates the following project directory:
```
sam-app
├── README.md
├── events
│ └── event.json
├── hello-world
│ ├── Dockerfile
│ ├── app.mjs
│ ├── package.json
│ └── tests
│ └── unit
│ └── test-handler.mjs
├── samconfig.toml
└── template.yaml
```
Next, we run `sam build` to build our application:
```
sam-app $ sam build
Building codeuri: /Users/.../build-demo/sam-app runtime: None metadata: {'DockerTag': 'nodejs18.x-v1', 'DockerContext': '/Users/.../build-demo/sam-app/hello-world', 'Dockerfile': 'Dockerfile'} architecture: arm64 functions: HelloWorldFunction
Building image for HelloWorldFunction function
Setting DockerBuildArgs: {} for HelloWorldFunction function
Step 1/4 : FROM public.ecr.aws/lambda/nodejs:18
---> f5b68038c080
Step 2/4 : COPY app.mjs package*.json ./
---> Using cache
---> 834e565aae80
Step 3/4 : RUN npm install
---> Using cache
---> 31c2209dd7b5
Step 4/4 : CMD ["app.lambdaHandler"]
---> Using cache
---> 2ce2a438e89d
Successfully built 2ce2a438e89d
Successfully tagged helloworldfunction:nodejs18.x-v1
Build Succeeded
Built Artifacts : .aws-sam/build
Built Template : .aws-sam/build/template.yaml
Commands you can use next
=========================
[*] Validate SAM template: sam validate
[*] Invoke Function: sam local invoke
[*] Test Function in the Cloud: sam sync --stack-name {{stack-name}} --watch
[*] Deploy: sam deploy --guided
```
### Building an application that includes a compiled programming language
In this example, we build an application that contains a Lambda function using the Go runtime.
First, we initialize a new application using `sam init` and configure our application to use Go:
```
$ sam init
...
Which template source would you like to use?
1 - AWS Quick Start Templates
2 - Custom Template Location
Choice: 1
Choose an AWS Quick Start application template
1 - Hello World Example
2 - Multi-step workflow
3 - Serverless API
...
Template: 1
Use the most popular runtime and package type? (Python and zip) [y/N]: ENTER
Which runtime would you like to use?
...
4 - dotnetcore3.1
5 - go1.x
6 - go (provided.al2)
...
Runtime: 5
What package type would you like to use?
1 - Zip
2 - Image
Package type: 1
Based on your selections, the only dependency manager available is mod.
We will proceed copying the template using mod.
Would you like to enable X-Ray tracing on the function(s) in your application? [y/N]: ENTER
Would you like to enable monitoring using CloudWatch Application Insights?
For more info, please view https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-application-insights.html [y/N]: ENTER
Project name [sam-app]: ENTER
Cloning from https://github.com/aws/aws-sam-cli-app-templates (process may take a moment)
-----------------------
Generating application:
-----------------------
Name: sam-app
Runtime: go1.x
Architectures: x86_64
Dependency Manager: mod
Application Template: hello-world
Output Directory: .
Configuration file: sam-app/samconfig.toml
Next steps can be found in the README file at sam-app-go/README.md
...
```
The AWS SAM CLI initializes the application. The following is an example of the application directory structure:
```
sam-app
├── Makefile
├── README.md
├── events
│ └── event.json
├── hello-world
│ ├── go.mod
│ ├── go.sum
│ ├── main.go
│ └── main_test.go
├── samconfig.toml
└── template.yaml
```
We reference the `README.md` file for this application’s requirements.
```
...
## Requirements
* AWS CLI already configured with Administrator permission
* [Docker installed](https://www.docker.com/community-edition)
* [Golang](https://golang.org)
* SAM CLI - [Install the SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)
...
```
Next, we run `sam local invoke` to test our function. This command errors since Go is not installed on our local machine:
```
sam-app $ sam local invoke
Invoking hello-world (go1.x)
Local image was not found.
Removing rapid images for repo public.ecr.aws/sam/emulation-go1.x
Building image.................................................................................................................................................................................................................................................
Using local image: public.ecr.aws/lambda/go:1-rapid-x86_64.
Mounting /Users/.../Playground/build/sam-app/hello-world as /var/task:ro,delegated inside runtime container
START RequestId: c6c5eddf-042b-4e1e-ba66-745f7c86dd31 Version: $LATEST
fork/exec /var/task/hello-world: no such file or directory: PathError
null
END RequestId: c6c5eddf-042b-4e1e-ba66-745f7c86dd31
REPORT RequestId: c6c5eddf-042b-4e1e-ba66-745f7c86dd31 Init Duration: 0.88 ms Duration: 175.75 ms Billed Duration: 176 ms Memory Size: 128 MB Max Memory Used: 128 MB
{"errorMessage":"fork/exec /var/task/hello-world: no such file or directory","errorType":"PathError"}%
```
Next, we run `sam build` to build our application. We encounter an error since Go is not installed on our local machine:
```
sam-app $ sam build
Starting Build use cache
Cache is invalid, running build and copying resources for following functions (HelloWorldFunction)
Building codeuri: /Users/.../Playground/build/sam-app/hello-world runtime: go1.x metadata: {} architecture: x86_64 functions: HelloWorldFunction
Build Failed
Error: GoModulesBuilder:Resolver - Path resolution for runtime: go1.x of binary: go was not successful
```
While we could configure our local machine to properly build our function, we instead use the `--use-container` option with `sam build`. The AWS SAM CLI downloads a container image, builds our function using the native GoModulesBuilder, and copies the resulting binary to our `.aws-sam/build/HelloWorldFunction` directory.
```
sam-app $ sam build --use-container
Starting Build use cache
Starting Build inside a container
Cache is invalid, running build and copying resources for following functions (HelloWorldFunction)
Building codeuri: /Users/.../build/sam-app/hello-world runtime: go1.x metadata: {} architecture: x86_64 functions: HelloWorldFunction
Fetching public.ecr.aws/sam/build-go1.x:latest-x86_64 Docker container image.....................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
Mounting /Users/.../build/sam-app/hello-world as /tmp/samcli/source:ro,delegated inside runtime container
Running GoModulesBuilder:Build
Build Succeeded
Built Artifacts : .aws-sam/build
Built Template : .aws-sam/build/template.yaml
Commands you can use next
=========================
[*] Validate SAM template: sam validate
[*] Invoke Function: sam local invoke
[*] Test Function in the Cloud: sam sync --stack-name {{stack-name}} --watch
[*] Deploy: sam deploy --guided
```
The following is an example of the `.aws-sam` directory:
```
.aws-sam
├── build
│ ├── HelloWorldFunction
│ │ └── hello-world
│ └── template.yaml
├── build.toml
├── cache
│ └── c860d011-4147-4010-addb-2eaa289f4d95
│ └── hello-world
└── deps
```
Next, we run `sam local invoke`. Our function is successfully invoked:
```
sam-app $ sam local invoke
Invoking hello-world (go1.x)
Local image is up-to-date
Using local image: public.ecr.aws/lambda/go:1-rapid-x86_64.
Mounting /Users/.../Playground/build/sam-app/.aws-sam/build/HelloWorldFunction as /var/task:ro,delegated inside runtime container
START RequestId: cfc8ffa8-29f2-49d4-b461-45e8c7c80479 Version: $LATEST
END RequestId: cfc8ffa8-29f2-49d4-b461-45e8c7c80479
REPORT RequestId: cfc8ffa8-29f2-49d4-b461-45e8c7c80479 Init Duration: 1.20 ms Duration: 1782.46 ms Billed Duration: 1783 ms Memory Size: 128 MB Max Memory Used: 128 MB
{"statusCode":200,"headers":null,"multiValueHeaders":null,"body":"Hello, 72.21.198.67\n"}%
```
## Learn more
To learn more about using the `sam build` command, see the following:
+ **[Learning AWS SAM: sam build](https://www.youtube.com/watch?v=fDhYKp4op_g)** – Serverless Land "Learning AWS SAM" series on YouTube.
+ **[Learning AWS SAM \$1 sam build \$1 E3 ](https://www.youtube.com/watch?v=vsAvRyLnB7Y)** – Serverless Land "Learning AWS SAM" series on YouTube.
+ **[AWS SAM build: how it provides artifacts for deployment (Sessions With SAM S2E8)](https://www.youtube.com/watch?v=bNbBd6XoDHg)** – Sessions with AWS SAM series on YouTube.
+ **[AWS SAM custom builds: How to use Makefiles to customize builds in SAM (S2E9)](https://www.youtube.com/watch?v=wpccutnSbAk)** – Sessions with AWS SAM series on YouTube.
# Default build with AWS SAM
To build your serverless application, use the `sam build` command. This command also gathers the build artifacts of your application's dependencies and places them in the proper format and location for next steps, such as locally testing, packaging, and deploying.
You specify your application's dependencies in a manifest file, such as `requirements.txt` (Python) or `package.json` (Node.js), or by using the `Layers` property of a function resource. The `Layers` property contains a list of [AWS Lambda layer](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html) resources that the Lambda function depends on.
The format of your application's build artifacts depends on each function's `PackageType` property. The options for this property are:
+ **`Zip`** – A .zip file archive, which contains your application code and its dependencies. If you package your code as a .zip file archive, you must specify a Lambda runtime for your function.
+ **`Image`** – A container image, which includes the base operating system, runtime, and extensions, in addition to your application code and its dependencies.
For more information about Lambda package types, see [Lambda deployment packages](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-package.html) in the *AWS Lambda Developer Guide*.
**Topics**
+ [
## Building a .zip file archive
](#build-zip-archive)
+ [
## Building a container image
](#build-container-image)
+ [
## Container environment variable file
](#serverless-sam-cli-using-container-environment-file)
+ [
## Speed up build times by building your project in the source folder
](#serverless-sam-cli-using-build-in-source)
+ [
## Examples
](#building-applications-examples)
+ [
## Building functions outside of AWS SAM
](#building-applications-skip)
## Building a .zip file archive
To build your serverless application as a .zip file archive, declare `PackageType: Zip` for your serverless function.
AWS SAM builds your application for the [architecture](sam-resource-function.md#sam-function-architectures) that you specify. If you don't specify an architecture, AWS SAM uses `x86_64` by default.
If your Lambda function depends on packages that have natively compiled programs, use the `--use-container` flag. This flag locally compiles your functions in a container that behaves like a Lambda environment, so they're in the right format when you deploy them to the AWS Cloud.
When you use the `--use-container` option, by default AWS SAM pulls the container image from [Amazon ECR Public](https://docs.aws.amazon.com/AmazonECR/latest/public/what-is-ecr.html). If you would like to pull a container image from another repository or for a specific version of AWS SAM CLI, you can use the `--build-image` option and provide the URI of an alternate container image. Following are two example commands for building applications using container images from a specific version of AWS SAM CLI:
```
# Build a Node.js 20 application using a container image for a specific version of AWS SAM CLI (1.136.0)
sam build --use-container --build-image public.ecr.aws/sam/build-nodejs22.x:1.136.0
# Build a function resource using the Python 3.13 container image from a specific version of AWS SAM CLI (1.136.0)(
sam build --use-container --build-image Function1=public.ecr.aws/sam/build-python3.13:1.136.0
```
For additional examples of building a .zip file archive application, see the Examples section later in this topic.
## Building a container image
To build your serverless application as a container image, declare `PackageType: Image` for your serverless function. You must also declare the `Metadata` resource attribute with the following entries:
`Dockerfile`
The name of the Dockerfile associated with the Lambda function.
`DockerContext`
The location of the Dockerfile.
`DockerTag`
(Optional) A tag to apply to the built image.
`DockerBuildArgs`
Build arguments for the build.
The AWS SAM CLI doesn't redact or obfuscate any information you include in `DockerBuildArgs` arguments. We strongly recommend you don't use this section to store sensitive information, such as passwords or secrets.
The following is an example `Metadata` resource attribute section:
```
Metadata:
Dockerfile: Dockerfile
DockerContext: ./hello_world
DockerTag: v1
```
To download a sample application that's configured with the `Image` package type, see [Tutorial: Deploy a Hello World application with AWS SAM](serverless-getting-started-hello-world.md). At the prompt asking which package type you want to install, choose `Image`.
**Note**
If you specify a multi-architecture base image in your Dockerfile, AWS SAM builds your container image for your host machine's architecture. To build for a different architecture, specify a base image that uses the specific target architecture.
## Container environment variable file
To provide a JSON file that contains environment variables for the build container, use the `--container-env-var-file` argument with the `sam build` command. You can provide a single environment variable that applies to all serverless resources, or different environment variables for each resource.
### Format
The format for passing environment variables to a build container depends on how many environment variables you provide for your resources.
To provide a single environment variable for all resources, specify a `Parameters` object like the following:
```
{
"Parameters": {
"GITHUB_TOKEN": "TOKEN_GLOBAL"
}
}
```
To provide different environment variables for each resource, specify objects for each resource like the following:
```
{
"MyFunction1": {
"GITHUB_TOKEN": "TOKEN1"
},
"MyFunction2": {
"GITHUB_TOKEN": "TOKEN2"
}
}
```
Save your environment variables as a file, for example, named `env.json`. The following command uses this file to pass your environment variables to the build container:
```
sam build --use-container --container-env-var-file env.json
```
### Precedence
+ The environment variables that you provide for specific resources take precedence over the single environment variable for all resources.
+ Environment variables that you provide on the command line take precedence over environment variables in a file.
## Speed up build times by building your project in the source folder
For supported runtimes and build methods, you can use the `--build-in-source` option to build your project directly in the source folder. By default, the AWS SAM CLI builds in a temporary directory, which involves copying over source code and project files. With `--build-in-source`, the AWS SAM CLI builds directly in your source folder, which speeds up the build process by removing the need to copy files to a temporary directory.
For a list of supported runtimes and build methods, see `--build-in-source`.
## Examples
### Example 1: .zip file archive
The following `sam build` commands build a .zip file archive:
```
# Build all functions and layers, and their dependencies
sam build
# Run the build process inside a Docker container that functions like a Lambda environment
sam build --use-container
# Build a Node.js 20 application using a container image for a specific version of AWS SAM CLI (1.136.0)
sam build --use-container --build-image public.ecr.aws/sam/build-nodejs22.x:1.136.0
# Build a function resource using the Python 3.13 container image from a specific version of AWS SAM CLI (1.136.0)(
sam build --use-container --build-image Function1=public.ecr.aws/sam/build-python3.13:1.136.0
# Build and run your functions locally
sam build && sam local invoke
# For more options
sam build --help
```
### Example 2: Container image
The following AWS SAM template builds as a container image:
```
Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function
Properties:
PackageType: Image
ImageConfig:
Command: ["app.lambda_handler"]
Metadata:
Dockerfile: Dockerfile
DockerContext: ./hello_world
DockerTag: v1
```
The following is an example Dockerfile:
```
FROM public.ecr.aws/lambda/python:3.12
COPY app.py requirements.txt ./
RUN python3.12 -m pip install -r requirements.txt
# Overwrite the command by providing a different command directly in the template.
CMD ["app.lambda_handler"]
```
### Example 3: npm ci
For Node.js applications, you can use `npm ci` instead of `npm install` to install dependencies. To use `npm ci`, specify `UseNpmCi: True` under `BuildProperties` in your Lambda function's `Metadata` resource attribute. To use `npm ci`, your application must have a `package-lock.json` or `npm-shrinkwrap.json` file present in the `CodeUri` for your Lambda function.
The following example uses `npm ci` to install dependencies when you run `sam build`:
```
Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: hello-world/
Handler: app.handler
Runtime: nodejs20.x
Architectures:
- x86_64
Events:
HelloWorld:
Type: Api
Properties:
Path: /hello
Method: get
Metadata:
BuildProperties:
UseNpmCi: True
```
### Python parent packages
For Python applications, you can preserve your package structure during the build process to enable absolute imports. To preserve package structure, specify `ParentPackageMode` under `BuildProperties` in your Lambda function's `Metadata` resource attribute.
The following example preserves the `app` package structure when you run `sam build`:
```
Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: hello-world/
Handler: app.main.handler
Runtime: python3.12
Architectures:
- x86_64
Metadata:
BuildProperties:
ParentPackageMode: explicit
ParentPackages: app
```
With this configuration, your code can use absolute imports like `from app.utils import logger` instead of relative imports like `from .utils import logger`.
## Building functions outside of AWS SAM
By default, when you run **sam build**, AWS SAM builds all of your function resources. Other options include:
+ **Build all function resources outside of AWS SAM** – If you build all of your function resources manually or through another tool, **sam build** is not required. You can skip **sam build** and move on to the next step in your process, such as performing local testing or deploying your application.
+ **Build some function resources outside of AWS SAM** – If you want AWS SAM to build some of your function resources while having other function resources built outside of AWS SAM, you can specify this in your AWS SAM template.
### Build some function resources outside of AWS SAM
To have AWS SAM skip a function when using **sam build**, configure the following in your AWS SAM template:
1. Add the `SkipBuild: True` metadata property to your function.
1. Specify the path to your built function resources.
Here is an example, with `TestFunction` configured to be skipped. Its built resources are located at `built-resources/TestFunction.zip`.
```
TestFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: built-resources/TestFunction.zip
Handler: TimeHandler::handleRequest
Runtime: java11
Metadata:
SkipBuild: True
```
Now, when you run **sam build**, AWS SAM will do the following:
1. AWS SAM will skip functions configured with `SkipBuild: True`.
1. AWS SAM will build all other function resources and cache them in the `.aws-sam` build directory.
1. For skipped functions, their template in the `.aws-sam` build directory will automatically be updated to reference the specified path to your built function resources.
Here is an example of the cached template for `TestFunction` in the `.aws-sam` build directory:
```
TestFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: ../../built-resources/TestFunction.zip
Handler: TimeHandler::handleRequest
Runtime: java11
Metadata:
SkipBuild: True
```
# Customize builds with AWS SAM
You can customize your build to include specific Lambda functions or Lambda layers. A function is a resource that you can invoke to run your code in Lambda. A Lambda layer allows you to extract code from a Lambda function that can then be re-used across several Lambda functions. You may choose to customize your build with specific Lambda functions when you want to focus on developing and deploying individual serverless functions without the complexity of managing shared dependencies or resources. Additionally, you may choose to build a Lambda layer to help you reduce the size of your deployment packages, separate core function logic from dependencies, and allow you to share dependencies across multiple functions.
The topics in this section explore some of the different ways you can build Lambda functions with AWS SAM. This includes building Lambda functions with customer runtimes and building Lambda layers. Custom runtimes let you install and use a language not listed in Lambda runtimes in the AWS Lambda Developer Guide. This allows you to create a specialized execution environment for running serverless functions and applications. Building only Lambda layers (instead of building your entire application) can benefit you in a few ways. It can help you reduce the size of your deployment packages, separate core function logic from dependencies, and allow you to share dependencies across multiple functions.
For more information on functions, see [Lambda concepts](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-concepts.html) in the *AWS Lambda Developer Guide*.
**Topics**
+ [
# Building Node.js Lambda functions with esbuild in AWS SAM
](serverless-sam-cli-using-build-typescript.md)
+ [
# Building .NET Lambda functions with Native AOT compilation in AWS SAM
](build-dotnet7.md)
+ [
# Building Rust Lambda functions with Cargo Lambda in AWS SAM
](building-rust.md)
+ [
# Building Python Lambda functions with uv in AWS SAM
](building-python-uv.md)
+ [
# Building Lambda functions with custom runtimes in AWS SAM
](building-custom-runtimes.md)
+ [
# Building Lambda layers in AWS SAM
](building-layers.md)
# Building Node.js Lambda functions with esbuild in AWS SAM
To build and package Node.js AWS Lambda functions, you can use the AWS SAM CLI with the esbuild JavaScript bundler. The esbuild bundler supports Lambda functions that you write in TypeScript.
To build a Node.js Lambda function with esbuild, add a `Metadata` object to your `AWS:Serverless::Function` resource and specify `esbuild` for the `BuildMethod`. When you run the **sam build** command, AWS SAM uses esbuild to bundle your Lambda function code.
## Metadata properties
The `Metadata` object supports the following properties for esbuild.
### BuildMethod
Specifies the bundler for your application. The only supported value is `esbuild`.
### BuildProperties
Specifies the build properties for your Lambda function code.
The `BuildProperties` object supports the following properties for esbuild. All of the properties are optional. By default, AWS SAM uses your Lambda function handler for the entry point.
**EntryPoints**
Specifies entry points for your application.
**External**
Specifies the list of packages to omit from the build. For more information, see [External](https://esbuild.github.io/api/#external) in the *esbuild website*.
**Format**
Specifies the output format of the generated JavaScript files in your application. For more information, see [Format](https://esbuild.github.io/api/#format) in the *esbuild website*.
**Loader**
Specifies the list of configurations for loading data for a given file type.
**MainFields**
Specifies which `package.json` fields to try to import when resolving a package. The default value is `main,module`.
**Minify**
Specifies whether to minify the bundled output code. The default value is `true`.
**OutExtension**
Customize the file extension of the files that esbuild generates. For more information, see [Out extension](https://esbuild.github.io/api/#out-extension) in the *esbuild website*.
**Sourcemap**
Specifies whether the bundler produces a source map file. The default value is `false`.
When set to `true`, `NODE_OPTIONS: --enable-source-maps` is appended to the Lambda function's environment variables, and a source map is generated and included in the function.
Alternatively, when `NODE_OPTIONS: --enable-source-maps` is included in the function's environment variables, `Sourcemap` is automatically set to `true`.
When conflicting, `Sourcemap: false` takes precedence over `NODE_OPTIONS: --enable-source-maps`.
By default, Lambda encrypts all environment variables at rest with AWS Key Management Service (AWS KMS). When using source maps, for the deployment to succeed, your function's execution role must have permission to perform the `kms:Encrypt` action.
**SourcesContent**
Specifies whether to include your source code in your source map file. Configure this property when `Sourcemap` is set to `'true'`.
+ Specify `SourcesContent: 'true'` to include all source code.
+ Specify `SourcesContent: 'false'` to exclude all source code. This results in smaller source maps file sizes, which is useful in production by reducing start-up times. However, source code won't be available in the debugger.
The default value is `SourcesContent: true`.
For more information, see [Sources content](https://esbuild.github.io/api/#sources-content) in the *esbuild website*.
**Target**
Specifies the target ECMAScript version. The default value is `es2020`.
## TypeScript Lambda function example
The following example AWS SAM template snippet uses esbuild to create a Node.js Lambda function from TypeScript code in `hello-world/app.ts`.
```
Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: hello-world/
Handler: app.handler
Runtime: nodejs20.x
Architectures:
- x86_64
Events:
HelloWorld:
Type: Api
Properties:
Path: /hello
Method: get
Environment:
Variables:
NODE_OPTIONS: --enable-source-maps
Metadata:
BuildMethod: esbuild
BuildProperties:
Format: esm
Minify: false
OutExtension:
- .js=.mjs
Target: "es2020"
Sourcemap: true
EntryPoints:
- app.ts
External:
- ""
```
# Building .NET Lambda functions with Native AOT compilation in AWS SAM
Build and package your .NET 8 AWS Lambda functions with the AWS Serverless Application Model (AWS SAM), utilizing Native Ahead-of-Time (AOT) compilation to improve AWS Lambda cold-start times.
**Topics**
+ [
## .NET 8 Native AOT overview
](#build-dotnet7-overview)
+ [
## Using AWS SAM with your .NET 8 Lambda functions
](#build-dotnet7-sam)
+ [
## Install prerequisites
](#build-dotnet7-prerequisites)
+ [
## Define .NET 8 Lambda functions in your AWS SAM template
](#build-dotnet7-sam-define)
+ [
## Build your application with the AWS SAM CLI
](#build-dotnet7-sam-build)
+ [
## Learn more
](#build-dotnet7-learn-more)
## .NET 8 Native AOT overview
Historically, .NET Lambda functions have cold-start times which impact user experience, system latency, and usage costs of your serverless applications. With .NET Native AOT compilation, you can improve cold-start times of your Lambda functions. To learn more about Native AOT for .NET 8, see [Using Native AOT](https://github.com/dotnet/runtime/tree/main/src/coreclr/nativeaot#readme) in the *Dotnet GitHub repository*.
## Using AWS SAM with your .NET 8 Lambda functions
Do the following to configure your .NET 8 Lambda functions with the AWS Serverless Application Model (AWS SAM):
+ Install prerequisites on your development machine.
+ Define .NET 8 Lambda functions in your AWS SAM template.
+ Build your application with the AWS SAM CLI.
## Install prerequisites
The following are required prerequisites:
+ The AWS SAM CLI
+ The .NET Core CLI
+ The Amazon.Lambda.Tools .NET Core Global Tool
+ Docker
**Install the AWS SAM CLI**
1. To check if you already have the AWS SAM CLI installed, run the following:
```
sam --version
```
1. To install the AWS SAM CLI, see [Install the AWS SAM CLI](install-sam-cli.md).
1. To upgrade an installed version of the AWS SAM CLI, see [Upgrading the AWS SAM CLI](manage-sam-cli-versions.md#manage-sam-cli-versions-upgrade).
**Install the .NET Core CLI**
1. To download and install the .NET Core CLI, see [Download .NET](https://dotnet.microsoft.com/download) from Microsoft's website.
1. For more information on the .NET Core CLI, see [.NET Core CLI](https://docs.aws.amazon.com/lambda/latest/dg/csharp-package-cli.html) in the *AWS Lambda Developer Guide*.
**Install the Amazon.Lambda.Tools .NET Core Global Tool**
1. Run the following command:
```
dotnet tool install -g Amazon.Lambda.Tools
```
1. If you already have the tool installed, you can make sure that it is the latest version using the following command:
```
dotnet tool update -g Amazon.Lambda.Tools
```
1. For more information about the Amazon.Lambda.Tools .NET Core Global Tool, see the [AWS Extensions for .NET CLI](https://github.com/aws/aws-extensions-for-dotnet-cli) repository on GitHub.
**Install Docker**
+ Building with Native AOT, requires Docker to be installed. For installation instructions, see [Installing Docker to use with the AWS SAM CLI](install-docker.md).
## Define .NET 8 Lambda functions in your AWS SAM template
To define a .NET8 Lambda function in your AWS SAM template, do the following:
1. Run the following command from a starting directory of your choice::
```
sam init
```
1. Select `AWS Quick Start Templates` to choose a starting template.
1. Choose the `Hello World Example` template.
1. Choose to not use the most popular runtime and package type by entering `n`.
1. For runtime, choose `dotnet8`.
1. For package type, choose `Zip`.
1. For your starter template, choose `Hello World Example using native AOT`.
**Install Docker**
+ Building with Native AOT, requires Docker to be installed. For installation instructions, see [Installing Docker to use with the AWS SAM CLI](install-docker.md).
```
Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: ./src/HelloWorldAot/
Handler: bootstrap
Runtime: dotnet8
Architectures:
- x86_64
Events:
HelloWorldAot:
Type: Api
Properties:
Path: /hello
Method: get
```
**Note**
When the `Event` property of an `AWS::Serverless::Function` is set to `Api`, but the `RestApiId` property is not specified, AWS SAM generates the `AWS::ApiGateway::RestApi` CloudFormation resource.
## Build your application with the AWS SAM CLI
From your project's root directory, run the `sam build` command to begin building your application. If the `PublishAot` property has been defined in your .NET 8 project file, the AWS SAM CLI will build with Native AOT compilation. To learn more about the `PublishAot` property, see [Native AOT Deployment](https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot/) in Microsoft's *.NET documentation*.
To build your function, the AWS SAM CLI invokes the .NET Core CLI which uses the Amazon.Lambda.Tools .NET Core Global Tool.
**Note**
When building, if a `.sln` file exists in the same or parent directory of your project, the directory containing the `.sln` file will be mounted to the container. If a `.sln` file is not found, only the project folder is mounted. Therefore, if you are building a multi-project application, ensure the `.sln` file is property located.
## Learn more
For more information on building .NET 8 Lambda functions, see [Introducing the .NET 8 runtime for AWS Lambda](https://aws.amazon.com/blogs/compute/introducing-the-net-8-runtime-for-aws-lambda/).
For a reference of the **sam build** command, see [sam build](sam-cli-command-reference-sam-build.md).
# Building Rust Lambda functions with Cargo Lambda in AWS SAM
| |
| --- |
| This feature is in preview release for AWS SAM and is subject to change. |
Use the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) with your Rust AWS Lambda functions.
**Topics**
+ [
## Prerequisites
](#building-rust-prerequisites)
+ [
## Configuring AWS SAM to use with Rust Lambda functions
](#building-rust-configure)
+ [
## Examples
](#building-rust-examples)
## Prerequisites
**Rust language**
To install Rust, see [Install Rust](https://www.rust-lang.org/tools/install) in the *Rust language website*.
**Cargo Lambda**
The AWS SAM CLI requires installation of [https://www.cargo-lambda.info/guide/what-is-cargo-lambda.html](https://www.cargo-lambda.info/guide/what-is-cargo-lambda.html), a subcommand for Cargo. For installation instructions, see [Installation](https://www.cargo-lambda.info/guide/installation.html) in the *Cargo Lambda documentation*.
**Docker**
Building and testing Rust Lambda functions requires Docker. For installation instructions, see [Installing Docker](install-docker.md).
**Opt in to AWS SAM CLI beta feature**
Since this feature is in preview, you must opt in using one of the following methods:
1. Use the environment variable: `SAM_CLI_BETA_RUST_CARGO_LAMBDA=1`.
1. Add the following to your `samconfig.toml` file:
```
[default.build.parameters]
beta_features = true
[default.sync.parameters]
beta_features = true
```
1. Use the `--beta-features` option when using a supported AWS SAM CLI command. For example:
```
$ sam build --beta-features
```
1. Choose option `y` when the AWS SAM CLI prompts you to opt in. The following is an example:
```
$ sam build
Starting Build use cache
Build method "rust-cargolambda" is a beta feature.
Please confirm if you would like to proceed
You can also enable this beta feature with "sam build --beta-features". [y/N]: y
```
## Configuring AWS SAM to use with Rust Lambda functions
### Step 1: Configure your AWS SAM template
Configure your AWS SAM template with the following:
+ **Binary** – Optional. Specify when your template contains multiple Rust Lambda functions.
+ **BuildMethod** – `rust-cargolambda`.
+ **CodeUri** – path to your `Cargo.toml` file.
+ **Handler** – `bootstrap`.
+ **Runtime** – `provided.al2`.
To learn more about custom runtimes, see [Custom AWS Lambda runtimes](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-custom.html) in the *AWS Lambda Developer Guide*.
Here is an example of a configured AWS SAM template:
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
MyFunction:
Type: AWS::Serverless::Function
Metadata:
BuildMethod: rust-cargolambda
BuildProperties: function_a
Properties:
CodeUri: ./rust_app
Handler: bootstrap
Runtime: provided.al2
...
```
### Step 2: Use the AWS SAM CLI with your Rust Lambda function
Use any AWS SAM CLI command with your AWS SAM template. For more information, see [AWS SAM CLI](using-sam-cli.md).
## Examples
### Hello World example
**In this example, we build the sample Hello World application using Rust as our runtime.**
First, we initialize a new serverless application using `sam init`. During the interactive flow, we select the **Hello World application** and choose the **Rust** runtime.
```
$ sam init
...
Which template source would you like to use?
1 - AWS Quick Start Templates
2 - Custom Template Location
Choice: 1
Choose an AWS Quick Start application template
1 - Hello World Example
2 - Multi-step workflow
3 - Serverless API
...
Template: 1
Use the most popular runtime and package type? (Python and zip) [y/N]: ENTER
Which runtime would you like to use?
1 - dotnet8
2 - dotnet6
3 - go (provided.al2)
...
18 - python3.11
19 - python3.10
20 - ruby3.3
21 - ruby3.2
22 - rust (provided.al2)
23 - rust (provided.al2023)
Runtime: 22
Based on your selections, the only Package type available is Zip.
We will proceed to selecting the Package type as Zip.
Based on your selections, the only dependency manager available is cargo.
We will proceed copying the template using cargo.
Would you like to enable X-Ray tracing on the function(s) in your application? [y/N]: ENTER
Would you like to enable monitoring using CloudWatch Application Insights?
For more info, please view https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-application-insights.html [y/N]: ENTER
Project name [sam-app]: hello-rust
-----------------------
Generating application:
-----------------------
Name: hello-rust
Runtime: rust (provided.al2)
Architectures: x86_64
Dependency Manager: cargo
Application Template: hello-world
Output Directory: .
Configuration file: hello-rust/samconfig.toml
Next steps can be found in the README file at hello-rust/README.md
Commands you can use next
=========================
[*] Create pipeline: cd hello-rust && sam pipeline init --bootstrap
[*] Validate SAM template: cd hello-rust && sam validate
[*] Test Function in the Cloud: cd hello-rust && sam sync --stack-name {stack-name} --watch
```
The following is the structure of our Hello World application:
```
hello-rust
├── README.md
├── events
│ └── event.json
├── rust_app
│ ├── Cargo.toml
│ └── src
│ └── main.rs
├── samconfig.toml
└── template.yaml
```
In our AWS SAM template, our Rust function is defined as the following:
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function
Metadata:
BuildMethod: rust-cargolambda
Properties:
CodeUri: ./rust_app
Handler: bootstrap
Runtime: provided.al2
Architectures:
- x86_64
Events:
HelloWorld:
Type: Api
Path: /hello
Method: get
```
Next, we run `sam build` to build our application and prepare for deployment. The AWS SAM CLI creates a `.aws-sam` directory and organizes our build artifacts there. Our function is built using Cargo Lambda and stored as an executable binary at `.aws-sam/build/HelloWorldFunction/bootstrap`.
**Note**
If you plan on running the **sam local invoke** command in MacOS, you need to build functions different before invoking. To do this, use the following command:
**SAM\$1BUILD\$1MODE=debug sam build**
This command is only needed if local testing will be done. This is not recommended when building for deployment.
```
hello-rust$ sam build
Starting Build use cache
Build method "rust-cargolambda" is a beta feature.
Please confirm if you would like to proceed
You can also enable this beta feature with "sam build --beta-features". [y/N]: y
Experimental features are enabled for this session.
Visit the docs page to learn more about the AWS Beta terms https://aws.amazon.com/service-terms/.
Cache is invalid, running build and copying resources for following functions (HelloWorldFunction)
Building codeuri: /Users/.../hello-rust/rust_app runtime: provided.al2 metadata: {'BuildMethod': 'rust-cargolambda'} architecture: x86_64 functions: HelloWorldFunction
Running RustCargoLambdaBuilder:CargoLambdaBuild
Running RustCargoLambdaBuilder:RustCopyAndRename
Build Succeeded
Built Artifacts : .aws-sam/build
Built Template : .aws-sam/build/template.yaml
Commands you can use next
=========================
[*] Validate SAM template: sam validate
[*] Invoke Function: sam local invoke
[*] Test Function in the Cloud: sam sync --stack-name {{stack-name}} --watch
[*] Deploy: sam deploy --guided
```
Next, we deploy our application using `sam deploy --guided`.
```
hello-rust$ sam deploy --guided
Configuring SAM deploy
======================
Looking for config file [samconfig.toml] : Found
Reading default arguments : Success
Setting default arguments for 'sam deploy'
=========================================
Stack Name [hello-rust]: ENTER
AWS Region [us-west-2]: ENTER
#Shows you resources changes to be deployed and require a 'Y' to initiate deploy
Confirm changes before deploy [Y/n]: ENTER
#SAM needs permission to be able to create roles to connect to the resources in your template
Allow SAM CLI IAM role creation [Y/n]: ENTER
#Preserves the state of previously provisioned resources when an operation fails
Disable rollback [y/N]: ENTER
HelloWorldFunction may not have authorization defined, Is this okay? [y/N]: y
Save arguments to configuration file [Y/n]: ENTER
SAM configuration file [samconfig.toml]: ENTER
SAM configuration environment [default]: ENTER
Looking for resources needed for deployment:
...
Uploading to hello-rust/56ba6585d80577dd82a7eaaee5945c0b 817973 / 817973 (100.00%)
Deploying with following values
===============================
Stack name : hello-rust
Region : us-west-2
Confirm changeset : True
Disable rollback : False
Deployment s3 bucket : aws-sam-cli-managed-default-samclisam-s3-demo-bucket-1a4x26zbcdkqr
Capabilities : ["CAPABILITY_IAM"]
Parameter overrides : {}
Signing Profiles : {}
Initiating deployment
=====================
Uploading to hello-rust/a4fc54cb6ab75dd0129e4cdb564b5e89.template 1239 / 1239 (100.00%)
Waiting for changeset to be created..
CloudFormation stack changeset
---------------------------------------------------------------------------------------------------------
Operation LogicalResourceId ResourceType Replacement
---------------------------------------------------------------------------------------------------------
+ Add HelloWorldFunctionHelloW AWS::Lambda::Permission N/A
orldPermissionProd
...
---------------------------------------------------------------------------------------------------------
Changeset created successfully. arn:aws:cloudformation:us-west-2:012345678910:changeSet/samcli-deploy1681427201/f0ef1563-5ab6-4b07-9361-864ca3de6ad6
Previewing CloudFormation changeset before deployment
======================================================
Deploy this changeset? [y/N]: y
2023-04-13 13:07:17 - Waiting for stack create/update to complete
CloudFormation events from stack operations (refresh every 5.0 seconds)
---------------------------------------------------------------------------------------------------------
ResourceStatus ResourceType LogicalResourceId ResourceStatusReason
---------------------------------------------------------------------------------------------------------
CREATE_IN_PROGRESS AWS::IAM::Role HelloWorldFunctionRole -
CREATE_IN_PROGRESS AWS::IAM::Role HelloWorldFunctionRole Resource creation
...
---------------------------------------------------------------------------------------------------------
CloudFormation outputs from deployed stack
---------------------------------------------------------------------------------------------------------
Outputs
---------------------------------------------------------------------------------------------------------
Key HelloWorldFunctionIamRole
Description Implicit IAM Role created for Hello World function
Value arn:aws:iam::012345678910:role/hello-rust-HelloWorldFunctionRole-10II2P13AUDUY
Key HelloWorldApi
Description API Gateway endpoint URL for Prod stage for Hello World function
Value https://ggdxec9le9.execute-api.us-west-2.amazonaws.com/Prod/hello/
Key HelloWorldFunction
Description Hello World Lambda Function ARN
Value arn:aws:lambda:us-west-2:012345678910:function:hello-rust-HelloWorldFunction-
yk4HzGzYeZBj
---------------------------------------------------------------------------------------------------------
Successfully created/updated stack - hello-rust in us-west-2
```
To test, we can invoke our Lambda function using the API endpoint.
```
$ curl https://ggdxec9le9.execute-api.us-west-2.amazonaws.com/Prod/hello/
Hello World!%
```
To test our function locally, first we ensure our function’s `Architectures` property matches our local machine.
```
...
Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function # More info about Function Resource: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#awsserverlessfunction
Metadata:
BuildMethod: rust-cargolambda # More info about Cargo Lambda: https://github.com/cargo-lambda/cargo-lambda
Properties:
CodeUri: ./rust_app # Points to dir of Cargo.toml
Handler: bootstrap # Do not change, as this is the default executable name produced by Cargo Lambda
Runtime: provided.al2
Architectures:
- arm64
...
```
Since we modified our architecture from `x86_64` to `arm64` in this example, we run `sam build` to update our build artifacts. We then run `sam local invoke` to locally invoke our function.
```
hello-rust$ sam local invoke
Invoking bootstrap (provided.al2)
Local image was not found.
Removing rapid images for repo public.ecr.aws/sam/emulation-provided.al2
Building image.....................................................................................................................................
Using local image: public.ecr.aws/lambda/provided:al2-rapid-arm64.
Mounting /Users/.../hello-rust/.aws-sam/build/HelloWorldFunction as /var/task:ro,delegated, inside runtime container
START RequestId: fbc55e6e-0068-45f9-9f01-8e2276597fc6 Version: $LATEST
{"statusCode":200,"body":"Hello World!"}END RequestId: fbc55e6e-0068-45f9-9f01-8e2276597fc6
REPORT RequestId: fbc55e6e-0068-45f9-9f01-8e2276597fc6 Init Duration: 0.68 ms Duration: 130.63 ms Billed Duration: 131 ms Memory Size: 128 MB Max Memory Used: 128 MB
```
### Single Lambda function project
**Here is an example of a serverless application containing one Rust Lambda function. **
Project directory structure:
```
.
├── Cargo.lock
├── Cargo.toml
├── src
│ └── main.rs
└── template.yaml
```
AWS SAM template:
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
MyFunction:
Type: AWS::Serverless::Function
Metadata:
BuildMethod: rust-cargolambda
Properties:
CodeUri: ./
Handler: bootstrap
Runtime: provided.al2
...
```
### Multiple Lambda function project
**Here is an example of a serverless application containing multiple Rust Lambda functions.**
Project directory structure:
```
.
├── Cargo.lock
├── Cargo.toml
├── src
│ ├── function_a.rs
│ └── function_b.rs
└── template.yaml
```
AWS SAM template:
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
FunctionA:
Type: AWS::Serverless::Function
Metadata:
BuildMethod: rust-cargolambda
BuildProperties:
Binary: function_a
Properties:
CodeUri: ./
Handler: bootstrap
Runtime: provided.al2
FunctionB:
Type: AWS::Serverless::Function
Metadata:
BuildMethod: rust-cargolambda
BuildProperties:
Binary: function_b
Properties:
CodeUri: ./
Handler: bootstrap
Runtime: provided.al2
```
`Cargo.toml` file:
```
[package]
name = "test-handler"
version = "0.1.0"
edition = "2021"
[dependencies]
lambda_runtime = "0.6.0"
serde = "1.0.136"
tokio = { version = "1", features = ["macros"] }
tracing = { version = "0.1", features = ["log"] }
tracing-subscriber = { version = "0.3", default-features = false, features = ["fmt"] }
[[bin]]
name = "function_a"
path = "src/function_a.rs"
[[bin]]
name = "function_b"
path = "src/function_b.rs"
```
# Building Python Lambda functions with uv in AWS SAM
| |
| --- |
| This feature is in preview release for AWS SAM and is subject to change. |
Use the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) with uv, a fast Python package installer and resolver, to build your Python AWS Lambda functions.
**Topics**
+ [
## Prerequisites
](#building-python-uv-prerequisites)
+ [
## Configuring AWS SAM to use with Python Lambda functions and uv
](#building-python-uv-configure)
+ [
## Examples
](#building-python-uv-examples)
## Prerequisites
**Python**
To install Python, see [Download Python](https://www.python.org/downloads/) in the *Python website*.
**uv**
The AWS SAM CLI requires installation of [https://docs.astral.sh/uv/](https://docs.astral.sh/uv/), an extremely fast Python package installer and resolver. For installation instructions, see [Installation](https://docs.astral.sh/uv/getting-started/installation/) in the *uv documentation*.
**Opt in to AWS SAM CLI beta feature**
Since this feature is in preview, you must opt in using one of the following methods:
1. Use the environment variable: `SAM_CLI_BETA_PYTHON_UV=1`.
1. Add the following to your `samconfig.toml` file:
```
[default.build.parameters]
beta_features = true
[default.sync.parameters]
beta_features = true
```
1. Use the `--beta-features` option when using a supported AWS SAM CLI command. For example:
```
$ sam build --beta-features
```
1. Choose option `y` when the AWS SAM CLI prompts you to opt in. The following is an example:
```
$ sam build
Starting Build use cache
Build method "python-uv" is a beta feature.
Please confirm if you would like to proceed
You can also enable this beta feature with "sam build --beta-features". [y/N]: y
```
## Configuring AWS SAM to use with Python Lambda functions and uv
### Step 1: Configure your AWS SAM template
Configure your AWS SAM template with the following:
+ **BuildMethod** – `python-uv`.
+ **CodeUri** – path to your function code directory containing `pyproject.toml` or `requirements.txt`.
+ **Handler** – your function handler (e.g., `app.lambda_handler`).
+ **Runtime** – Python runtime version (e.g., `python3.12`).
Here is an example of a configured AWS SAM template:
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
MyFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: ./my_function
Handler: app.lambda_handler
Runtime: python3.12
Metadata:
BuildMethod: python-uv
...
```
## Examples
### Hello World example
**In this example, we build a sample Hello World application using Python with uv as the package manager.**
uv can use either `pyproject.toml` or `requirements.txt` to read dependencies. If both are given, `sam build` will read from `requirements.txt` for dependencies.
The following is the structure of our Hello World application:
```
hello-python-uv
├── README.md
├── events
│ └── event.json
├── hello_world
│ ├── __init__.py
│ ├── app.py
│ └── pyproject.toml
├── samconfig.toml
└── template.yaml
```
`pyproject.toml` file:
```
[project]
name = "my-function"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
"requests>=2.31.0",
"boto3>=1.28.0",
]
```
In our AWS SAM template, our Python function is defined as the following:
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: hello_world/
Handler: app.lambda_handler
Runtime: python3.12
Architectures:
- x86_64
Metadata:
BuildMethod: python-uv
```
Next, we run `sam build` to build our application and prepare for deployment. The AWS SAM CLI creates a `.aws-sam` directory and organizes our build artifacts there. Our function dependencies are installed using uv and stored at `.aws-sam/build/HelloWorldFunction/`.
```
hello-python-uv$ sam build
Starting Build use cache
Build method "python-uv" is a beta feature.
Please confirm if you would like to proceed
You can also enable this beta feature with "sam build --beta-features". [y/N]: y
Experimental features are enabled for this session.
Visit the docs page to learn more about the AWS Beta terms https://aws.amazon.com/service-terms/.
Cache is invalid, running build and copying resources for following functions (HelloWorldFunction)
Building codeuri: /Users/.../hello-python-uv/hello_world runtime: python3.12 metadata: {'BuildMethod': 'python-uv'} architecture: x86_64 functions: HelloWorldFunction
Running PythonUvBuilder:UvBuild
Running PythonUvBuilder:CopySource
Build Succeeded
Built Artifacts : .aws-sam/build
Built Template : .aws-sam/build/template.yaml
Commands you can use next
=========================
[*] Validate SAM template: sam validate
[*] Invoke Function: sam local invoke
[*] Test Function in the Cloud: sam sync --stack-name {{stack-name}} --watch
[*] Deploy: sam deploy --guided
```
**Note**
The `python-uv` build method is configured per function in the `Metadata` section. Each function in your template can use a different build method, allowing you to mix uv-based functions with `pip`-based functions in the same AWS SAM template. If no build method is specified, `pip` is used by default.
# Building Lambda functions with custom runtimes in AWS SAM
You can use the `sam build` command to build custom runtimes required for your Lambda function. You declare your Lambda function to use a custom runtime by specifying `Runtime: provided` for the function.
To build a custom runtime, declare the `Metadata` resource attribute with a `BuildMethod: makefile` entry. You provide a custom makefile, where you declare a build target of the form `build-function-logical-id` that contains the build commands for your runtime. Your makefile is responsible for compiling the custom runtime if necessary, and copying the build artifacts into the proper location required for subsequent steps in your workflow. The location of the makefile is specified by the `CodeUri` property of the function resource, and must be named `Makefile`.
## Examples
### Example 1: Custom runtime for a function written in Rust
**Note**
We recommend building Lambda functions with Cargo Lambda. To learn more, see [Building Rust Lambda functions with Cargo Lambda in AWS SAM](building-rust.md).
The following AWS SAM template declares a function that uses a custom runtime for a Lambda function written in Rust, and instructs `sam build` to execute the commands for the `build-HelloRustFunction` build target.
```
Resources:
HelloRustFunction:
Type: AWS::Serverless::Function
Properties:
FunctionName: HelloRust
Handler: bootstrap.is.real.handler
Runtime: provided
MemorySize: 512
CodeUri: .
Metadata:
BuildMethod: makefile
```
The following makefile contains the build target and commands that will be executed. Note that the `CodeUri` property is set to `.`, so the makefile must be located in the project root directory (that is, the same directory as the application's AWS SAM template file). The filename must be `Makefile`.
```
build-HelloRustFunction:
cargo build --release --target x86_64-unknown-linux-musl
cp ./target/x86_64-unknown-linux-musl/release/bootstrap $(ARTIFACTS_DIR)
```
For more information about setting up your development environment in order to execute the `cargo build` command in the previous `makefile`, see the [Rust Runtime for AWS Lambda](https://aws.amazon.com/blogs/opensource/rust-runtime-for-aws-lambda/) blog post.
### Example 2: Makefile builder for Python3.12 (alternative to using the bundled builder)
You might want to use a library or module that is not included in a bundled builder. This example shows a AWS SAM template for a Python3.12 runtime with a makefile builder.
```
Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: hello_world/
Handler: app.lambda_handler
Runtime: python3.12
Metadata:
BuildMethod: makefile
```
The following makefile contains the build target and commands that will be executed. Note that the `CodeUri` property is set to `hello_world`, so the makefile must be located in the root of the `hello_world` subdirectory, and the filename must be `Makefile`.
```
build-HelloWorldFunction:
cp *.py $(ARTIFACTS_DIR)
cp requirements.txt $(ARTIFACTS_DIR)
python -m pip install -r requirements.txt -t $(ARTIFACTS_DIR)
rm -rf $(ARTIFACTS_DIR)/bin
```
# Building Lambda layers in AWS SAM
You can use AWS SAM to build custom Lambda layers. Lambda layers allow you to extract code from a Lambda function that can then be re-used across several Lambda functions. Building only Lambda layers (instead of building your entire application) can benefit you in a few ways. It can help you reduce the size of your deployment packages, separate core function logic from dependencies, and allow you to share dependencies across multiple functions. For information about layers, see [AWS Lambda layers](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html) in the *AWS Lambda Developer Guide*.
## How to build a Lambda layer in AWS SAM
**Note**
Before you can build a Lambda layer, you must first write a Lambda layer in your AWS SAM template. For information and examples on doing this, see [Increase efficiency using Lambda layers with AWS SAM](serverless-sam-cli-layers.md).
To build a custom layer, declare it in your AWS Serverless Application Model (AWS SAM) template file and include a `Metadata` resource attribute section with a `BuildMethod` entry. Valid values for `BuildMethod` are identifiers for an [AWS Lambda runtime](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html), or `makefile`. Include a `BuildArchitecture` entry to specify the instruction set architectures that your layer supports. Valid values for `BuildArchitecture` are [Lambda instruction set architectures](https://docs.aws.amazon.com/lambda/latest/dg/foundation-arch.html).
If you specify `makefile`, provide the custom makefile, where you declare a build target of the form `build-layer-logical-id` that contains the build commands for your layer. Your makefile is responsible for compiling the layer if necessary, and copying the build artifacts into the proper location required for subsequent steps in your workflow. The location of the makefile is specified by the `ContentUri` property of the layer resource, and must be named `Makefile`.
**Note**
When you create a custom layer, AWS Lambda depends on environment variables to find your layer code. Lambda runtimes include paths in the `/opt` directory where your layer code is copied into. Your project's build artifact folder structure must match the runtime's expected folder structure so your custom layer code can be found.
For example, for Python you can place your code in the `python/` subdirectory. For NodeJS, you can place your code in the `nodejs/node_modules/` subdirectory.
For more information, see [Including library dependencies in a layer](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html#configuration-layers-path) in the *AWS Lambda Developer Guide*.
The following is an example `Metadata` resource attribute section.
```
Metadata:
BuildMethod: python3.12
BuildArchitecture: arm64
```
**Note**
If you don't include the `Metadata` resource attribute section, AWS SAM doesn't build the layer. Instead, it copies the build artifacts from the location specified in the `CodeUri` property of the layer resource. For more information, see the [ContentUri](sam-resource-layerversion.md#sam-layerversion-contenturi) property of the `AWS::Serverless::LayerVersion` resource type.
When you include the `Metadata` resource attribute section, you can use the `sam build` command to build the layer, both as an independent object, or as a dependency of an AWS Lambda function.
+ ****As an independent object.**** You might want to build just the layer object, for example when you're locally testing a code change to the layer and don't need to build your entire application. To build the layer independently, specify the layer resource with the `sam build layer-logical-id` command.
+ **As a dependency of a Lambda function.** When you include a layer's logical ID in the `Layers` property of a Lambda function in the same AWS SAM template file, the layer is a dependency of that Lambda function. When that layer also includes a `Metadata` resource attribute section with a `BuildMethod` entry, you build the layer either by building the entire application with the `sam build` command or by specifying the function resource with the `sam build function-logical-id` command.
## Examples
### Template example 1: Build a layer against the Python 3.12 runtime environment
The following example AWS SAM template builds a layer against the Python 3.12 runtime environment.
```
Resources:
MyLayer:
Type: AWS::Serverless::LayerVersion
Properties:
ContentUri: my_layer
CompatibleRuntimes:
- python3.12
Metadata:
BuildMethod: python3.12 # Required to have AWS SAM build this layer
```
### Template example 2: Build a layer using a custom makefile
The following example AWS SAM template uses a custom `makefile` to build the layer.
```
Resources:
MyLayer:
Type: AWS::Serverless::LayerVersion
Properties:
ContentUri: my_layer
CompatibleRuntimes:
- python3.12
Metadata:
BuildMethod: makefile
```
The following `makefile` contains the build target and commands that will be executed. Note that the `ContentUri` property is set to `my_layer`, so the makefile must be located in the root of the `my_layer` subdirectory, and the filename must be `Makefile`. Note also that the build artifacts are copied into the `python/` subdirectory so that AWS Lambda will be able to find the layer code.
```
build-MyLayer:
mkdir -p "$(ARTIFACTS_DIR)/python"
cp *.py "$(ARTIFACTS_DIR)/python"
python -m pip install -r requirements.txt -t "$(ARTIFACTS_DIR)/python"
```
**Note**
When the `makefile` is called, the appropriate target is triggered and artifacts should be copied to the exposed environmental variable `$ARTIFACTS_DIR`. For more information, refer to [aws-lambda-builders in GitHub](https://github.com/aws/aws-lambda-builders/blob/develop/aws_lambda_builders/workflows/custom_make/DESIGN.md).
### Example sam build commands
The following `sam build` commands build layers that include the `Metadata` resource attribute sections.
```
# Build the 'layer-logical-id' resource independently
$ sam build layer-logical-id
# Build the 'function-logical-id' resource and layers that this function depends on
$ sam build function-logical-id
# Build the entire application, including the layers that any function depends on
$ sam build
```