本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
Amazon SAM CLI 的 Terraform 支持入门
本主题介绍如何开始使用 Amazon Serverless Application Model 命令行界面 (Amazon SAMCLI) Terraform。
要提供反馈和提交功能请求,请创建 GitHub 问题
主题
Amazon SAM CLI Terraform 先决条件
完成所有先决条件,即可开始在 Terraform 项目中使用 Amazon SAM CLI。
-
安装或升级 Amazon SAM CLI
要检查是否已 Amazon SAM CLI 安装,请运行以下命令:
$
sam --version
如果已安装 Amazon SAM CLI,则输出将显示一个版本。要升级到最新版本,请参阅 升级 Amazon SAM CLI。
有关安装 Amazon SAM CLI 及其所有先决条件的说明,请参阅 安装 Amazon SAM CLI。
-
安装 Terraform
要检查是否已安装 Terraform,请运行以下命令:
$
terraform -version
要安装 Terraform,请参阅 Terraform 注册表中的安装 Terraform
。 -
安装 Docker 以进行本地测试
Amazon SAM CLI 进行本地测试需要 Docker。要安装 Docker,请参阅 安装 Docker 以与 Amazon SAM CLI 一起使用。
将 Amazon SAM CLI 命令与 Terraform 结合使用
运行支持的 Amazon SAM CLI 命令时,请使用 --hook-name
选项并提供 terraform
值。以下是 示例:
$
sam local invoke --hook-name terraform
您可以按照以下步骤在 Amazon SAM CLI 配置文件中配置此选项:
hook_name = "terraform"
为 Terraform 项目做好准备
完成本主题中的步骤,即可在 Terraform 项目中使用 Amazon SAM CLI。
如果您在Terraform项目之外构建 Amazon Lambda 工件,则无需进行其他设置。使用 Amazon SAM CLI 和 Terraform 进行本地调试和测试要开始使用,请参阅 Amazon SAMCLI。
如果在 Terraform 项目中构建 Lambda 构件,您必须执行以下操作:
-
安装 Python 3.8 或更高版本
-
安装 Make 工具。
-
在 Terraform 项目中定义您的 Lambda 构件构建逻辑。
-
定义
sam metadata
资源以告知 Amazon SAM CLI 您的构建逻辑。 -
使用 Amazon SAMCLI
sam build
命令来构建 Lambda 工件。
安装 Python 3.8 或更高版本
Python必须有 3.8 或更高版本才能与一起使用 Amazon SAMCLI。运行 sam build
时, Amazon SAM CLI 会创建包含用于构建 Lambda 构件 Python 命令的 makefiles
。
有关安装说明,请参阅 Python 的《初学者指南》 中的下载 Python
通过运行以下命令验证 Python 3.8 或更高版本是否已添加到您的计算机路径中:
$
python --version
输出应显示 3.8 或更高版本的 Python 版本。
安装 Make 工具
GNU Make 是一种控制项目可执行文件和其他非源文件生成的工具。 Amazon SAM CLI 创建 makefiles
,其依赖此工具来构建 Lambda 构件。
如果您尚未在本地计算机上安装 Make,请在继续操作之前进行安装。
对于 Windows,您可以使用 Chocolatey
定义 Lambda 构件的构建逻辑
使用 null_resource
Terraform 资源类型来定义您的 Lambda 构建逻辑。以下是使用自定义生成脚本构建 Lambda 函数的示例。
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" } }
定义 sam metadata 资源
sam metadata
资源是一种 null_resource
Terraform 资源类型,它为 Amazon SAM CLI 提供查找您的 Lambda 构件所需的信息。项目中的每个 Lambda 函数或层都需要一个唯一的 sam metadata
资源。要了解有关此资源类型的更多信息,请参阅 Terraform 注册表中的 null_resource
要定义 sam metadata 资源
-
以
sam_metadata_
开头命名您的资源,以将该资源标识为 sam metadata 资源。 -
在资源
triggers
块中定义您的 Lambda 构件属性。 -
使用
depends_on
参数指定包含您的 Lambda 构建逻辑的null_resource
。以下是一个示例模板:
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 ] }以下是
sam metadata
资源示例: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 ] }
您的sam metadata
资源内容将因 Lambda 资源类型(函数或层)和包装类型(ZIP或图像)而异。有关更多信息以及示例,请参阅 sam 元数据资源。
当您配置 sam metadata
资源并使用支持的 Amazon SAM CLI 命令时, Amazon SAM CLI 将在运行该 Amazon SAM CLI 命令之前生成元数据文件。生成此文件后,您可以使用带有未来 Amazon SAM CLI 命令的 --skip-prepare-infra
选项来跳过元数据生成过程并节省时间。只有在您尚未对基础设施进行任何更改(例如创建新的 Lambda 函数或新的API终端节点)时,才应使用此选项。
使用 Amazon SAM CLI 来构建 Lambda 构件
使用 Amazon SAMCLIsam build
命令来构建 Lambda 工件。当您运行 sam build
时, Amazon SAM CLI 会执行以下操作:
-
在您的 Terraform 项目中寻找
sam metadata
资源以了解和查找您的 Lambda 资源。 -
启动您的 Lambda 构建逻辑以构建您的 Lambda 构件。
-
创建用于整理Terraform项目的
.aws-sam
目录,以便与 Amazon SAMCLIsam local
命令一起使用。
要使用 sam build 进行构建
-
在包含 Terraform 根模块的目录中,运行以下命令:
$
sam build --hook-name terraform
-
要构建特定的 Lambda 函数或层,请运行以下命令
$
sam build --hook-name terraform
lambda-resource-id
Lambda 资源 ID 可以是 Lambda 函数名称或完整 Terraform 资源地址,例如
aws_lambda_function.list_books
或module.list_book_function.aws_lambda_function.this[0]
。
如果您的函数源代码或其他 Terraform 配置文件位于 Terraform 根模块所在的目录之外,则需要指定位置。使用 --terraform-project-root-path
选项指定包含这些文件的顶级目录的绝对或相对路径。以下是 示例:
$
sam build --hook-name terraform --terraform-project-root-path
~/projects/terraform/demo
使用容器构建
运行 Amazon SAMCLIsam build
命令时,您可以将配置 Amazon SAMCLI为使用本地Docker容器构建应用程序。
注意
您一定已经安装并配置 Docker。有关说明,请参阅安装 Docker 以与 Amazon SAM CLI 一起使用。
要使用容器构建
-
创建包含 Terraform、Python、和 Make 工具的
Dockerfile
。您还应该纳入 Lambda 函数运行时。以下是
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"]
-
使用 docker build
构建您的 Docker 映像。 以下是 示例:
$
docker build --tag
terraform-build:v1
<path-to-directory-containing-Dockerfile>
-
使用
--use-container
和--build-image
选项运行 Amazon SAMCLIsam build
命令。以下是 示例:
$
sam build --use-container --build-image
terraform-build:v1
后续步骤
要开始在 Terraform 项目中使用 Amazon SAM CLI,请参阅 使用 Amazon SAM CLI 和 Terraform 进行本地调试和测试。
设置 Terraform Cloud
我们建议您使用 Terraform v1.6.0 或更新版本。如果使用较旧版本,您必须在本地生成 Terraform 计划文件。本地计划文件为 Amazon SAM CLI提供了执行本地测试和调试所需的信息。
要生成本地计划文件
注意
Terraform v1.6.0 或更高版本不需要这些步骤。要开始使用 wit Amazon SAM CLI hTerraform Cloud,请参阅结合使用 Amazon SAM CLI 和 Terraform。
-
配置令API牌-令牌的类型将取决于您的访问级别。要了解更多信息,请参阅Terraform Cloud文档中的API代币
。 -
设置您的API令牌环境变量-以下是命令行的示例:
$
export TOKEN="<api-token-value>
" -
获取您的运行 ID — 在Terraform Cloud控制台中,找到您要用于的Terraform运行的运行 ID Amazon SAMCLI。
运行 ID 位于您运行的页面导览痕迹路径中。
-
获取计划文件-使用您的API令牌获取本地计划文件。以下是来自命令行的示例:
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
您现在已准备好将 Amazon SAM CLI 与 Terraform Cloud 一起使用。使用支持的 Amazon SAM CLI 命令时,请使用 --terraform-plan-file
选项指定本地计划文件的名称和路径。以下是 示例:
$
sam local invoke --hook-name terraform --terraform-plan-file custom-plan.json
以下是使用 sam local start-api
命令的示例:
$
sam local start-api --hook-name terraform --terraform-plan-file custom-plan.json
有关可使用这些示例的示例应用程序,请参阅 aws-samples GitHub 存储库中的 api_gateway_v2_tf_cloud
后续步骤
要开始使用 Amazon SAM CLI 和 Terraform Cloud,请参阅 使用 Amazon SAM CLI 和 Terraform 进行本地调试和测试。