# AWS SAM CLI Terraform support
<a name="terraform-support"></a>

This section covers using the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) with your Terraform projects and Terraform Cloud.

To provide feedback and submit feature requests, create a [GitHub Issue](https://github.com/aws/aws-sam-cli/issues/new?labels=area%2Fterraform).

**Topics**
+ [

# Getting started with Terraform support for AWS SAM CLI
](gs-terraform-support.md)
+ [

# Using the AWS SAM CLI with Terraform for local debugging and testing
](using-samcli-terraform.md)
+ [

# Using the AWS SAM CLI with Serverless.tf for local debugging and testing
](using-samcli-serverlesstf.md)
+ [

# AWS SAM CLI with Terraform reference
](terraform-reference.md)
+ [

## What is AWS SAM CLI support for Terraform?
](#what-is-terraform-support)

# Getting started with Terraform support for AWS SAM CLI
<a name="gs-terraform-support"></a>

This topic covers how to get started with using the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) with Terraform.

To provide feedback and submit feature requests, create a [GitHub Issue](https://github.com/aws/aws-sam-cli/issues/new?labels=area%2Fterraform).

**Topics**
+ [

## AWS SAM CLI Terraform prerequisites
](#gs-terraform-support-prerequisites)
+ [

## Using AWS SAM CLI commands with Terraform
](#gs-terraform-support-using)
+ [

## Set up for Terraform projects
](#gs-terraform-support-projects)
+ [

## Set up for Terraform Cloud
](#gs-terraform-support-cloud)

## AWS SAM CLI Terraform prerequisites
<a name="gs-terraform-support-prerequisites"></a>

Complete all prerequisites to begin using the AWS SAM CLI with your Terraform projects.

1. 

**Install or upgrade the AWS SAM CLI**

   To check if you have the AWS SAM CLI installed, run the following:

   ```
   $ sam --version
   ```

   If the AWS SAM CLI is already installed, the output will display a version. To upgrade to the newest version, see [Upgrading the AWS SAM CLI](manage-sam-cli-versions.md#manage-sam-cli-versions-upgrade).

   For instructions on installing the AWS SAM CLI along with all of its prerequisites, see [Install the AWS SAM CLI](install-sam-cli.md).

1. 

**Install Terraform**

   To check if you have Terraform installed, run the following:

   ```
   $ terraform -version
   ```

   To install Terraform, see [Install Terraform](https://developer.hashicorp.com/terraform/downloads) in the *Terraform registry*.

1. 

**Install Docker for local testing**

   The AWS SAM CLI requires Docker for local testing. To install Docker, see [Installing Docker to use with the AWS SAM CLI](install-docker.md).

## Using AWS SAM CLI commands with Terraform
<a name="gs-terraform-support-using"></a>

When you run a supported AWS SAM CLI command, use the `--hook-name` option and provide the `terraform` value. The following is an example:

```
$ sam local invoke --hook-name terraform
```

You can configure this option in your AWS SAM CLI configuration file with the following:

```
hook_name = "terraform"
```

## Set up for Terraform projects
<a name="gs-terraform-support-projects"></a>

Complete steps in this topic to use the AWS SAM CLI with Terraform projects.

No additional setup is required if you build your AWS Lambda artifacts outside of your Terraform project. See [Using the AWS SAM CLI with Terraform for local debugging and testing](using-samcli-terraform.md) to start using the AWS SAM CLI.

If you build your Lambda artifacts within your Terraform projects, you must do the following:

1. Install Python 3.8 or newer

1. Install the Make tool.

1. Define your Lambda artifacts build logic within your Terraform project.

1. Define a `sam metadata` resource to inform the AWS SAM CLI of your build logic.

1. Use the AWS SAM CLI `sam build` command to build your Lambda artifacts.

### Install Python 3.8 or newer
<a name="gs-terraform-support-projects-python"></a>

Python 3.8 or newer is required for use with the AWS SAM CLI. When you run `sam build`, the AWS SAM CLI creates `makefiles` that contain Python commands to build your Lambda artifacts.

For installation instructions, see [Downloading Python](https://wiki.python.org/moin/BeginnersGuide/Download) in Python's *Beginners Guide*.

Verify that Python 3.8 or newer is added to your machine path by running:

```
$ python --version
```

The output should display a version of Python that is 3.8 or newer.

### Install the Make tool
<a name="gs-terraform-support-projects-make"></a>

GNU [Make](https://www.gnu.org/software/make/) is a tool that controls the generation of executables and other non-source files for your project. The AWS SAM CLI creates `makefiles` which rely on this tool to build your Lambda artifacts.

If you do not have Make installed on your local machine, install it before moving forward.

For Windows, you can install using [Chocolatey](https://chocolatey.org/). For instructions, see [Using Chocolatey](https://www.technewstoday.com/install-and-use-make-in-windows/#using-chocolatey) in *How to Install and Use "Make" in Windows*

### Define the Lambda artifacts build logic
<a name="gs-terraform-support-projects-logic"></a>

Use the `null_resource` Terraform resource type to define your Lambda build logic. The following is an example that uses a custom build script to build a Lambda function.

```
resource "null_resource" "build_lambda_function" {
    triggers = {
        build_number = "${timestamp()}" 
    }

    provisioner "local-exec" {
        command =  substr(pathexpand("~"), 0, 1) == "/"? "./py_build.sh \"${local.lambda_src_path}\" \"${local.building_path}\" \"${local.lambda_code_filename}\" Function" : "powershell.exe -File .\\PyBuild.ps1 ${local.lambda_src_path} ${local.building_path} ${local.lambda_code_filename} Function"
    }
}
```

### Define a sam metadata resource
<a name="gs-terraform-support-projects-metadata"></a>

The `sam metadata` resource is a `null_resource` Terraform resource type that provides the AWS SAM CLI with the information it needs to locate your Lambda artifacts. A unique `sam metadata` resource is required for each Lambda function or layer in your project. To learn more about this resource type, see [null\$1resource](https://registry.terraform.io/providers/hashicorp/null/latest/docs/resources/resource) in the *Terraform registry*.

**To define a sam metadata resource**

1. Name your resource starting with `sam_metadata_` to identify the resource as a sam metadata resource.

1. Define your Lambda artifact properties within the `triggers` block of your resource.

1. Specify your `null_resource` that contains your Lambda build logic with the `depends_on` argument.

   The following is an example template:

   ```
   resource "null_resource" "sam_metadata_..." {
     triggers = {
       resource_name = resource_name
       resource_type = resource_type
       original_source_code = original_source_code
       built_output_path = built_output_path
     }
     depends_on = [
       null_resource.build_lambda_function # ref to your build logic
     ]
   }
   ```

   The following is an example `sam metadata` resource:

   ```
   resource "null_resource" "sam_metadata_aws_lambda_function_publish_book_review" {
       triggers = {
           resource_name = "aws_lambda_function.publish_book_review"
           resource_type = "ZIP_LAMBDA_FUNCTION"
           original_source_code = "${local.lambda_src_path}"
           built_output_path = "${local.building_path}/${local.lambda_code_filename}"
       }
       depends_on = [
           null_resource.build_lambda_function
       ]
   }
   ```

The contents of your `sam metadata` resource will vary based on the Lambda resource type (function or layer), and the packaging type (ZIP or image). For more information, along with examples, see [sam metadata resource](terraform-sam-metadata.md).

When you configure a `sam metadata` resource and use a supported AWS SAM CLI command, the AWS SAM CLI will generate the metadata file before running the AWS SAM CLI command. Once you have generated this file, you can use the `--skip-prepare-infra` option with future AWS SAM CLI commands to skip the metadata generation process and save time. This option should only be used if you haven’t made any infrastructure changes, such as creating new Lambda functions or new API endpoints.

### Use the AWS SAM CLI to build your Lambda artifacts
<a name="gs-terraform-support-projects-build"></a>

Use the AWS SAM CLI `sam build` command to build your Lambda artifacts. When you run `sam build`, the AWS SAM CLI does the following:

1. Looks for `sam metadata` resources in your Terraform project to learn about and locate your Lambda resources.

1. Initiates your Lambda build logic to build your Lambda artifacts.

1. Creates an `.aws-sam` directory that organizes your Terraform project for use with the AWS SAM CLI `sam local` commands.

**To build with sam build**

1. From the directory containing your Terraform root module, run the following:

   ```
   $ sam build --hook-name terraform
   ```

1. To build a specific Lambda function or layer, run the following

   ```
   $ sam build --hook-name terraform lambda-resource-id
   ```

   The Lambda resource ID can be the Lambda function name or full Terraform resource address, such as `aws_lambda_function.list_books` or `module.list_book_function.aws_lambda_function.this[0]`.

If your function source code or other Terraform configuration files are located outside of the directory containing your Terraform root module, you need to specify the location. Use the `--terraform-project-root-path` option to specify the absolute or relative path to the top-level directory containing these files. The following is an example:

```
$ sam build --hook-name terraform --terraform-project-root-path ~/projects/terraform/demo
```

#### Build using a container
<a name="gs-terraform-support-projects-build-container"></a>

When running the AWS SAM CLI `sam build` command, you can configure the AWS SAM CLI to build your application using a local Docker container.

**Note**  
You must have Docker installed and configured. For instructions, see [Installing Docker to use with the AWS SAM CLI](install-docker.md).

**To build using a container**

1. Create a `Dockerfile` that contains the Terraform, Python, and Make tools. You should also include your Lambda function runtime.

   The following is an example `Dockerfile`:

   ```
   FROM public.ecr.aws/amazonlinux/amazonlinux:2
   
   RUN yum -y update \
       && yum install -y unzip tar gzip bzip2-devel ed gcc gcc-c++ gcc-gfortran \
       less libcurl-devel openssl openssl-devel readline-devel xz-devel \
       zlib-devel glibc-static libcxx libcxx-devel llvm-toolset-7 zlib-static \
       && rm -rf /var/cache/yum
   
   RUN yum -y install make \
       && yum -y install zip
   
   RUN yum install -y yum-utils \
       && yum-config-manager --add-repo https://rpm.releases.hashicorp.com/AmazonLinux/hashicorp.repo \
       && yum -y install terraform \
       && terraform --version
   
   # AWS Lambda Builders
   RUN amazon-linux-extras enable python3.8
   RUN yum clean metadata && yum -y install python3.8
   RUN curl -L get-pip.io | python3.8
   RUN pip3 install aws-lambda-builders
   RUN ln -s /usr/bin/python3.8 /usr/bin/python3
   RUN python3 --version
   
   VOLUME /project
   WORKDIR /project
   
   ENTRYPOINT ["sh"]
   ```

1. Use [https://docs.docker.com/engine/reference/commandline/build/](https://docs.docker.com/engine/reference/commandline/build/) to build your Docker image.

   The following is an example:

   ```
   $ docker build --tag terraform-build:v1 <path-to-directory-containing-Dockerfile>
   ```

1. Run the AWS SAM CLI `sam build` command with the `--use-container` and `--build-image` options.

   The following is an example:

   ```
   $ sam build --use-container --build-image terraform-build:v1
   ```

### Next steps
<a name="gs-terraform-support-projects-next"></a>

To start using the AWS SAM CLI with your Terraform projects, see [Using the AWS SAM CLI with Terraform for local debugging and testing](using-samcli-terraform.md).

## Set up for Terraform Cloud
<a name="gs-terraform-support-cloud"></a>

We recommend that you use Terraform v1.6.0 or newer. If you are using an older version, you must generate a Terraform plan file locally. The local plan file provides the AWS SAM CLI with the information it needs to perform local testing and debugging.

**To generate a local plan file**
**Note**  
These steps are not required for Terraform v1.6.0 or newer. To start using the AWS SAM CLI with Terraform Cloud, see [Using AWS SAM CLI with Terraform](using-samcli-terraform.md).

1. **Configure an API token** – The type of token will depend on your access level. To learn more, see [API Tokens](https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/api-tokens) in the *Terraform Cloud documentation*.

1. **Set your API token environment variable** – The following is an example from the command line:

   ```
   $ export TOKEN="<api-token-value>"
   ```

1. **Obtain your run ID** – From the Terraform Cloud console, locate the run ID for the Terraform run that you’d like to use with the AWS SAM CLI.

   The run ID is located in the breadcrumb path of your run.  
![\[Breadcrumb path in Terraform Cloud that displays run ID.\]](http://docs.aws.amazon.com/serverless-application-model/latest/developerguide/images/terraform-01.png)

1. **Fetch the plan file** – Using your API token, obtain your local plan file. The following is an example from the command line:

   ```
   curl \
      --header "Authorization: Bearer $TOKEN" \
      --header "Content-Type: application/vnd.api+json" \
      --location \
      https://app.terraform.io/api/v2/runs/<run ID>/plan/json-output \
      > custom_plan.json
   ```

You are now ready to use the AWS SAM CLI with Terraform Cloud. When using a supported AWS SAM CLI command, use the `--terraform-plan-file` option to specify the name and path of your local plan file. The following is an example:

```
$ sam local invoke --hook-name terraform --terraform-plan-file custom-plan.json
```

The following is an example, using the `sam local start-api` command:

```
$ sam local start-api --hook-name terraform --terraform-plan-file custom-plan.json
```

For a sample application that you can use with these examples, see [api\$1gateway\$1v2\$1tf\$1cloud](https://github.com/aws-samples/aws-sam-terraform-examples/tree/main/ga/api_gateway_v2_tf_cloud) in the *aws-samples GitHub repository*.

### Next steps
<a name="gs-terraform-support-cloud-next"></a>

To start using the AWS SAM CLI with Terraform Cloud, see [Using the AWS SAM CLI with Terraform for local debugging and testing](using-samcli-terraform.md).

# Using the AWS SAM CLI with Terraform for local debugging and testing
<a name="using-samcli-terraform"></a>

This topic covers how to use supported AWS Serverless Application Model Command Line Interface (AWS SAM CLI) commands with your Terraform projects and Terraform Cloud.

To provide feedback and submit feature requests, create a [GitHub Issue](https://github.com/aws/aws-sam-cli/issues/new?labels=area%2Fterraform).

**Topics**
+ [

## Local testing with sam local invoke
](#using-samcli-terraform-local-invoke)
+ [

## Local testing with sam local start-api
](#using-samcli-terraform-local-start-api)
+ [

## Local testing with sam local start-lambda
](#using-samcli-terraform-local-start-lambda)
+ [

## Terraform limitations
](#using-samcli-terraform-unsupported)

## Local testing with sam local invoke
<a name="using-samcli-terraform-local-invoke"></a>

**Note**  
To use the AWS SAM CLI to test locally, you must have Docker installed and configured. For instructions, see [Installing Docker to use with the AWS SAM CLI](install-docker.md).

The following is an example of testing your Lambda function locally by passing in an event:

```
$ sam local invoke --hook-name terraform hello_world_function -e events/event.json -
```

To learn more about using this command, see [Introduction to testing with sam local invoke](using-sam-cli-local-invoke.md).

## Local testing with sam local start-api
<a name="using-samcli-terraform-local-start-api"></a>

To use `sam local start-api` with Terraform, run the following:

```
$ sam local start-api --hook-name terraform
```

The following is an example:

```
$ sam local start-api --hook-name terraform                                                                                                                                                                                                                                                                                           
                                                                                                                                                                                                          
Running Prepare Hook to prepare the current application                                                                                                                                                   
Executing prepare hook of hook "terraform"                                                                                                                                                                
Initializing Terraform application                                                                                                                                                                        
...
Creating terraform plan and getting JSON output                                                                                                                                                           
....
Generating metadata file                                                                                                                                                                                  
                                                                                                                                                                                                          
Unresolvable attributes discovered in project, run terraform apply to resolve them.                                                                                                                       
                                                                                                                                                                                                          
Finished generating metadata file. Storing in...
Prepare hook completed and metadata file generated at: ...    
Mounting HelloWorldFunction at http://127.0.0.1:3000/hello [GET]                                                                                                                                          
Mounting None at http://127.0.0.1:3000/hello [POST]                                                                                                                                                       
You can now browse to the above endpoints to invoke your functions. You do not need to restart/reload SAM CLI while working on your functions, changes will be reflected instantly/automatically. If you  
used sam build before running local commands, you will need to re-run sam build for the changes to be picked up. You only need to restart SAM CLI if you update your AWS SAM template                     
2023-06-26 13:21:20  * Running on http://127.0.0.1:3000/ (Press CTRL+C to quit)
```

To learn more about this command, see [Introduction to testing with sam local start-api](using-sam-cli-local-start-api.md).

### Lambda functions that use Lambda authorizers
<a name="using-sam-cli-terraform-local-start-api-authorizers"></a>

For Lambda functions configured to use Lambda authorizers, the AWS SAM CLI will automatically invoke your Lambda authorizer before invoking your Lambda function endpoint.
+ To learn more about this feature in the AWS SAM CLI, see [Lambda functions that use Lambda authorizers](using-sam-cli-local-start-api.md#using-sam-cli-local-start-api-authorizers).
+ For more information on using Lambda authorizers in Terraform, see [https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_authorizer#example-usage](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_authorizer#example-usage) in the *Terraform registry*.

## Local testing with sam local start-lambda
<a name="using-samcli-terraform-local-start-lambda"></a>

The following is an example of testing your Lambda function locally with the AWS Command Line Interface (AWS CLI):

1. Use the AWS SAM CLI to create a local testing environment:

   ```
   $ sam local start-lambda --hook-name terraform hello_world_function
   ```

1. Use the AWS CLI to invoke your function locally:

   ```
   $ aws lambda invoke --function-name hello_world_function --endpoint-url http://127.0.0.1:3001/ response.json --cli-binary-format raw-in-base64-out --payload file://events/event.json
   ```

To learn more about this command, see [Introduction to testing with sam local start-lambda](using-sam-cli-local-start-lambda.md).

## Terraform limitations
<a name="using-samcli-terraform-unsupported"></a>

The following are limitations when using the AWS SAM CLI with Terraform:
+ Lambda functions linked to multiple layers.
+ Terraform local variables that define links between resources.
+ Referencing a Lambda function that hasn’t been created yet. This includes functions that are defined in the body attribute of the REST API resource.

To avoid these limitations, you can run `terraform apply` when a new resource is added.

# Using the AWS SAM CLI with Serverless.tf for local debugging and testing
<a name="using-samcli-serverlesstf"></a>

The AWS Serverless Application Model Command Line Interface (AWS SAM CLI) can be used with Serverless.tf modules for local debugging and testing of your AWS Lambda functions and layers. The following AWS SAM CLI commands are supported:
+ `sam build`
+ `sam local invoke`
+ `sam local start-api`
+ `sam local start-lambda`

**Note**  
Serverless.tf version 4.6.0 and newer supports AWS SAM CLI integration.

To begin using the AWS SAM CLI with your Serverless.tf modules, update to the latest version of Serverless.tf and the AWS SAM CLI.

Starting from **serverless.tf version 6.0.0**, you must set the `create_sam_metadata` parameter as `true`. This generates the metadata resources that the AWS SAM CLI `sam build` command requires.

To learn more about Serverless.tf, see the [terraform-aws-lambda-module](https://registry.terraform.io/modules/terraform-aws-modules/lambda/aws/latest).

# AWS SAM CLI with Terraform reference
<a name="terraform-reference"></a>

This section is the reference for using the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) with Terraform for local debugging and testing.

To provide feedback and submit feature requests, create a [GitHub Issue](https://github.com/aws/aws-sam-cli/issues/new?labels=area%2Fterraform).

## AWS SAM supported features reference
<a name="terraform-reference-sam"></a>

Reference documentation for AWS SAM CLI features that are supported for use with Terraform can be found here:
+ [sam build](sam-cli-command-reference-sam-build.md)
+ [sam local invoke](sam-cli-command-reference-sam-local-invoke.md)
+ [sam local start-api](sam-cli-command-reference-sam-local-start-api.md)
+ [sam local start-lambda](sam-cli-command-reference-sam-local-start-lambda.md)

## Terraform specific reference
<a name="terraform-reference-specific"></a>

Reference documentation specific to using AWS SAM CLI with Terraform can be found here:
+ [sam metadata resource](terraform-sam-metadata.md)

# sam metadata resource
<a name="terraform-sam-metadata"></a>

This page contains reference information for the **sam metadata resource** resource type used with Terraform projects.
+ For an introduction to using the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) with Terraform, see [What is AWS SAM CLI support for Terraform?](terraform-support.md#what-is-terraform-support).
+ To use the AWS SAM CLI with Terraform, see [Using the AWS SAM CLI with Terraform for local debugging and testing](using-samcli-terraform.md).

**Topics**
+ [

## Arguments
](#terraform-sam-metadata-arguments)
+ [

## Examples
](#terraform-sam-metadata-examples)

## Arguments
<a name="terraform-sam-metadata-arguments"></a>


****  

| Argument | Description | 
| --- | --- | 
| built\$1output\$1path | The path to your AWS Lambda function's built artifacts. | 
| docker\$1build\$1args | Decoded string of the Docker build arguments JSON object. This argument is optional. | 
| docker\$1context | The path to the directory containing the Docker image build context. | 
| docker\$1file |  The path to the Docker file. This path is relative to the `docker_context` path. This argument is optional. Default value is `Dockerfile`.  | 
| docker\$1tag | The value of the created Docker image tag. This value is optional. | 
| depends\$1on | The path to the building resource for your Lambda function or layer. To learn more, see [The **depends\$1on** argument](https://developer.hashicorp.com/terraform/language/meta-arguments/depends_on) in the Terraform registry. | 
| original\$1source\$1code |  The path to where your Lambda function is defined. This value can be a string, array of strings, or a decoded JSON object as a string. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/serverless-application-model/latest/developerguide/terraform-sam-metadata.html)  | 
| resource\$1name | The Lambda function name. | 
| resource\$1type |  The format of your Lambda function package type. Accepted values are: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/serverless-application-model/latest/developerguide/terraform-sam-metadata.html)  | 
| source\$1code\$1property | The path to the Lambda resource code in the JSON object. Define this property when original\$1source\$1code is a JSON object. | 

## Examples
<a name="terraform-sam-metadata-examples"></a>

### sam metadata resource referencing a Lambda function using the ZIP package type
<a name="terraform-sam-metadata-examples-example1"></a>

```
# Lambda function resource
resource "aws_lambda_function" "tf_lambda_func" {
  filename = "${path.module}/python/hello-world.zip"
  handler = "index.lambda_handler"
  runtime = "python3.8"
  function_name = "function_example"
  role = aws_iam_role.iam_for_lambda.arn
  depends_on = [
    null_resource.build_lambda_function # function build logic
  ]
}

# sam metadata resource
resource "null_resource" "sam_metadata_function_example" {
  triggers = {
    resource_name = "aws_lambda_function.function_example"
    resource_type = "ZIP_LAMBDA_FUNCTION"
    original_source_code = "${path.module}/python"
    built_output_path = "${path.module}/building/function_example"
  }
  depends_on = [
    null_resource.build_lambda_function # function build logic
  ]
}
```

### sam metadata resource referencing a Lambda function using the image package type
<a name="terraform-sam-metadata-examples-example2"></a>

```
resource "null_resource" "sam_metadata_function {
  triggers = {
    resource_name = "aws_lambda_function.image_function"
    resource_type = "IMAGE_LAMBDA_FUNCTION"
    docker_context = local.lambda_src_path
    docker_file = "Dockerfile"
    docker_build_args = jsonencode(var.build_args)
    docker_tag = "latest"
  }
}
```

### sam metadata resource referencing a Lambda layer
<a name="terraform-sam-metadata-examples-example3"></a>

```
resource "null_resource" "sam_metadata_layer1" {
  triggers = {
    resource_name = "aws_lambda_layer_version.layer"
    resource_type = "LAMBDA_LAYER"
    original_source_code = local.layer_src
    built_output_path = "${path.module}/${layer_build_path}"
  }
  depends_on = [null_resource.layer_build]
}
```

## What is AWS SAM CLI support for Terraform?
<a name="what-is-terraform-support"></a>

Use the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) with your Terraform projects or Terraform Cloud to perform local debugging and testing of:
+ AWS Lambda functions and layers.
+ Amazon API Gateway APIs.

For an introduction to Terraform, see [What is Terraform?](https://developer.hashicorp.com/terraform/intro) at the *HashiCorp Terraform website*.

To provide feedback and submit feature requests, create a [GitHub Issue](https://github.com/aws/aws-sam-cli/issues/new?labels=area%2Fterraform).

**Note**  
As part of the parsing step of AWS SAM CLI's integration, AWS SAM CLI processes user commands generate project files and data. The command output should remain unchanged, but in certain environments, the environment or runner may inject additional logs or information in the output.

**Topics**
+ [

### What is the AWS SAM CLI?
](#what-is-terraform-support-sam-cli)
+ [

### How do I use the AWS SAM CLI with Terraform?
](#what-is-terraform-support-how)
+ [

### Next steps
](#what-is-terraform-support-next)

### What is the AWS SAM CLI?
<a name="what-is-terraform-support-sam-cli"></a>

The AWS SAM CLI is a command line tool that you can use with AWS SAM templates and supported third-party integrations, such as Terraform, to build and run your serverless applications. For an introduction to the AWS SAM CLI, see [What is the AWS SAM CLI?](what-is-sam-overview.md#what-is-sam-cli).

The AWS SAM CLI supports the following commands for Terraform:
+ `sam local invoke` – Initiate a one-time invocation of an AWS Lambda function resource locally. To learn more about this command, see [Introduction to testing with sam local invoke](using-sam-cli-local-invoke.md).
+ `sam local start-api` – Run your Lambda resources locally and test through a local HTTP server host. This type of testing is helpful for Lambda functions that are invoked by an API Gateway endpoint. To learn more about this command, see [Introduction to testing with sam local start-api](using-sam-cli-local-start-api.md).
+ `sam local start-lambda` – Start a local endpoint for your Lambda function in order to invoke your function locally using AWS Command Line Interface (AWS CLI) or SDKs. To learn more about this command, see [Introduction to testing with sam local start-lambda](using-sam-cli-local-start-lambda.md).

### How do I use the AWS SAM CLI with Terraform?
<a name="what-is-terraform-support-how"></a>

The [core Terraform workflow](https://developer.hashicorp.com/terraform/intro/core-workflow) consists of three stages: **Write**, **Plan**, and **Apply**. With AWS SAM CLI support for Terraform, you can take advantage of the AWS SAM CLI `sam local` set of commands while continuing to use your Terraform workflows to manage your applications on AWS. Generally, this means the following:
+ **Write** – Author your infrastructure as code using Terraform.
+ **Test and debug** – Use the AWS SAM CLI to locally test and debug your applications.
+ **Plan** – Preview changes before applying.
+ **Apply** – Provision your infrastructure.

For an example of using the AWS SAM CLI with Terraform, see [ Better together: AWS SAM CLI and HashiCorp Terraform](https://aws.amazon.com/blogs/compute/better-together-aws-sam-cli-and-hashicorp-terraform/) at the *AWS Compute Blog*.

### Next steps
<a name="what-is-terraform-support-next"></a>

To complete all prerequisites and set up Terraform, see [Getting started with Terraform support for AWS SAM CLI](gs-terraform-support.md).