本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # AWS SAM CLI 的 Terraform 支持入门 本主题介绍如何开始使用 AWS Serverless Application Model 命令行界面 (AWS SAMCLI) Terraform。 要提供反馈和提交功能请求，请创建 [GitHub 问题](https://github.com/aws/aws-sam-cli/issues/new?labels=area%2Fterraform)。 **Topics** + [AWS SAM CLI Terraform 先决条件](#gs-terraform-support-prerequisites) + [将 AWS SAM CLI 命令与 Terraform 结合使用](#gs-terraform-support-using) + [为 Terraform 项目做好准备](#gs-terraform-support-projects) + [设置 Terraform Cloud](#gs-terraform-support-cloud) ## AWS SAM CLI Terraform 先决条件 完成所有先决条件，即可开始在 Terraform 项目中使用 AWS SAM CLI。 1. **安装或升级 AWS SAM CLI** 要检查是否已 AWS SAM CLI 安装，请运行以下命令： ``` $ sam --version ``` 如果已安装 AWS SAM CLI，则输出将显示一个版本。要升级到最新版本，请参阅 [升级 AWS SAM CLI](manage-sam-cli-versions.md#manage-sam-cli-versions-upgrade)。 有关安装 AWS SAM CLI 及其所有先决条件的说明，请参阅 [安装 AWS SAM CLI](install-sam-cli.md)。 1. **安装 Terraform** 要检查是否已安装 Terraform，请运行以下命令： ``` $ terraform -version ``` 要安装 Terraform，请参阅 *Terraform 注册表*中的[安装 Terraform](https://developer.hashicorp.com/terraform/downloads)。 1. **安装 Docker 以进行本地测试** AWS SAM CLI 进行本地测试需要 Docker。要安装 Docker，请参阅 [安装 Docker 以与 AWS SAM CLI 一起使用](install-docker.md)。 ## 将 AWS SAM CLI 命令与 Terraform 结合使用 运行支持的 AWS SAM CLI 命令时，请使用 `--hook-name` 选项并提供 `terraform` 值。以下是示例： ``` $ sam local invoke --hook-name terraform ``` 您可以按照以下步骤在 AWS SAM CLI 配置文件中配置此选项： ``` hook_name = "terraform" ``` ## 为 Terraform 项目做好准备 完成本主题中的步骤，即可在 Terraform 项目中使用 AWS SAM CLI。 如果您在Terraform项目之外构建 AWS Lambda 工件，则无需进行其他设置。[使用 AWS SAM CLI 和 Terraform 进行本地调试和测试](using-samcli-terraform.md)要开始使用，请参阅 AWS SAMCLI。 如果在 Terraform 项目中构建 Lambda 构件，您必须执行以下操作： 1. 安装 Python 3.8 或更高版本 1. 安装 Make 工具。 1. 在 Terraform 项目中定义您的 Lambda 构件构建逻辑。 1. 定义 `sam metadata` 资源以告知 AWS SAM CLI 您的构建逻辑。 1. 使用 AWS SAMCLI`sam build`命令来构建 Lambda 工件。 ### 安装 Python 3.8 或更高版本 Python必须有 3.8 或更高版本才能与一起使用 AWS SAMCLI。运行 `sam build` 时， AWS SAM CLI 会创建包含用于构建 Lambda 构件 Python 命令的 `makefiles`。 有关安装说明，请参阅 Python 的*《初学者指南》* 中的[下载 Python](https://wiki.python.org/moin/BeginnersGuide/Download)。 运行以下命令验证 Python 3.8 或更高版本是否已添加到您的计算机路径中： ``` $ python --version ``` 输出应显示 Python 3.8 或更高版本。 ### 安装 Make 工具 GNU [Make](https://www.gnu.org/software/make/) 是一种控制项目可执行文件和其他非源文件生成的工具。 AWS SAM CLI 创建 `makefiles`，其依赖此工具来构建 Lambda 构件。 如果您尚未在本地计算机上安装 Make，请在继续操作之前进行安装。 对于 Windows，您可以使用 [Chocolatey](https://chocolatey.org/) 进行安装。有关说明，请参阅*如何在 Windows 中安装和使用 “Make”* 中的[使用 Chocolatey](https://www.technewstoday.com/install-and-use-make-in-windows/#using-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 资源类型，它为 AWS SAM CLI 提供查找您的 Lambda 构件所需的信息。项目中的每个 Lambda 函数或层都需要一个唯一的 `sam metadata` 资源。要了解有关此资源类型的更多信息，请参阅 *Terraform 注册表*中的 [null\$1resource](https://registry.terraform.io/providers/hashicorp/null/latest/docs/resources/resource)。 **要定义 sam metadata 资源** 1. 以 `sam_metadata_` 开头命名您的资源，以将该资源标识为 sam metadata 资源。 1. 在资源 `triggers` 块中定义您的 Lambda 构件属性。 1. 使用 `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 元数据资源](terraform-sam-metadata.md)。 当您配置 `sam metadata` 资源并使用支持的 AWS SAM CLI 命令时， AWS SAM CLI 将在运行该 AWS SAM CLI 命令之前生成元数据文件。生成此文件后，您可以使用带有未来 AWS SAM CLI 命令的 `--skip-prepare-infra` 选项来跳过元数据生成过程并节省时间。只有在您尚未对基础设施进行任何更改（例如创建新的 Lambda 函数或新的 API 端点）时，才应使用此选项。 ### 使用 AWS SAM CLI 来构建 Lambda 构件 使用 AWS SAMCLI`sam build`命令来构建 Lambda 工件。当您运行 `sam build` 时， AWS SAM CLI 会执行以下操作： 1. 在您的 Terraform 项目中寻找 `sam metadata` 资源以了解和查找您的 Lambda 资源。 1. 启动您的 Lambda 构建逻辑以构建您的 Lambda 构件。 1. 创建用于整理Terraform项目的`.aws-sam`目录，以便与 AWS SAMCLI`sam local`命令一起使用。 **要使用 sam build 进行构建** 1. 在包含 Terraform 根模块的目录中，运行以下命令： ``` $ sam build --hook-name terraform ``` 1. 要构建特定的 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 ``` #### 使用容器构建 运行 AWS SAMCLI`sam build`命令时，您可以将配置 AWS SAMCLI为使用本地Docker容器构建应用程序。 **注意** 您一定已经安装并配置 Docker。有关说明，请参阅[安装 Docker 以与 AWS SAM CLI 一起使用](install-docker.md)。 **要使用容器构建** 1. 创建包含 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"] ``` 1. 使用 [https://docs.docker.com/engine/reference/commandline/build/](https://docs.docker.com/engine/reference/commandline/build/) 构建您的 Docker 映像。 以下是示例： ``` $ docker build --tag terraform-build:v1 ``` 1. 使用`--use-container`和`--build-image`选项运行 AWS SAMCLI`sam build`命令。 以下是示例： ``` $ sam build --use-container --build-image terraform-build:v1 ``` ### 后续步骤 要开始在 Terraform 项目中使用 AWS SAM CLI，请参阅 [使用 AWS SAM CLI 和 Terraform 进行本地调试和测试](using-samcli-terraform.md)。 ## 设置 Terraform Cloud 我们建议您使用 Terraform v1.6.0 或更新版本。如果使用较旧版本，您必须在本地生成 Terraform 计划文件。本地计划文件为 AWS SAM CLI提供了执行本地测试和调试所需的信息。 **要生成本地计划文件** **注意** Terraform v1.6.0 或更高版本不需要这些步骤。要开始使用 wit AWS SAM CLI hTerraform Cloud，请参阅[结合使用 AWS SAM CLI 和 Terraform](using-samcli-terraform.md)。 1. **配置 API 令牌** – 令牌的类型将取决于您的访问级别。有关更多信息，请参阅 *Terraform Cloud 文档*中的 [API 令牌](https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/api-tokens)。 1. **设置 API 令牌环境变量** – 以下是命令行的示例： ``` $ export TOKEN="" ``` 1. **获取您的运行 ID** — 在Terraform Cloud控制台中，找到您要用于的Terraform运行的运行 ID AWS SAMCLI。 运行 ID 位于您运行的页面导览痕迹路径中。 ![\[显示运行 ID 的 Terraform Cloud 页面导览痕迹路径。\]](http://docs.aws.amazon.com/zh_cn/serverless-application-model/latest/developerguide/images/terraform-01.png) 1. **获取计划文件** – 使用您的 API 令牌获取本地计划文件。以下是来自命令行的示例： ``` curl \ --header "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/vnd.api+json" \ --location \ https://app.terraform.io/api/v2/runs//plan/json-output \ > custom_plan.json ``` 您现在已准备好将 AWS SAM CLI 与 Terraform Cloud 一起使用。使用支持的 AWS 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\$1gateway\$1v2\$1tf\$1cloud](https://github.com/aws-samples/aws-sam-terraform-examples/tree/main/ga/api_gateway_v2_tf_cloud)。 ### 后续步骤 要开始使用 AWS SAM CLI 和 Terraform Cloud，请参阅 [使用 AWS SAM CLI 和 Terraform 进行本地调试和测试](using-samcli-terraform.md)。