本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 開始使用 的 Terraform 支援 AWS SAM CLI 本主題說明如何開始使用 AWS Serverless Application Model 命令列界面 (AWS SAM CLI) 搭配 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 先決條件 完成所有先決條件，以開始使用 AWS SAM CLI搭配您的Terraform專案。 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 CLIDocker進行本機測試。若要安裝 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 CLITerraform進行本機偵錯和測試](using-samcli-terraform.md) 以開始使用 AWS SAM CLI。 如果您在Terraform專案中建置 Lambda 成品，您必須執行下列動作： 1. 安裝 Python 3.8 或更新版本 1. 安裝 Make工具。 1. 定義 Lambda 成品在Terraform專案中建置邏輯。 1. 定義 `sam metadata` 資源，以通知 AWS SAM CLI 您的建置邏輯。 1. 使用 AWS SAM CLI`sam build`命令來建置 Lambda 成品。 ### 安裝 Python 3.8 或更新版本 Python 需要 3.8 或更新版本才能與 搭配使用 AWS SAM CLI。當您執行 時`sam build`， AWS SAM CLI會建立 `makefiles`，其中包含建置 Lambda 成品的Python命令。 如需安裝說明，請參閱 [Python 入門指南中的下載](https://wiki.python.org/moin/BeginnersGuide/Download) Python。 ** 執行下列動作，確認 Python 3.8 或更新版本已新增至您的機器路徑： ``` $ python --version ``` 輸出應會顯示 3.8 或更新版本的 Python 版本。 ### 安裝 Make工具 GNU [Make](https://www.gnu.org/software/make/) 是一種工具，可控制專案產生可執行檔和其他非來源檔案。 AWS SAM CLI 會建立`makefiles`依賴此工具來建置 Lambda 成品。 如果您尚未在本機電腦上Make安裝 ，請在繼續之前安裝它。 對於 Windows，您可以使用 [Chocolatey](https://chocolatey.org/) 安裝 。如需說明，請參閱*如何在 Windows 中安裝和使用「製作」中的*[使用 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 函數或 layer 都需要唯一的`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`引數指定`null_resource`包含 Lambda 建置邏輯的 。 以下是範例範本： ``` 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之前產生中繼資料檔案。產生此檔案後，您可以將 `--skip-prepare-infra`選項與未來的 AWS SAM CLI命令搭配使用，以略過中繼資料產生程序並節省時間。只有在您尚未進行任何基礎設施變更，例如建立新的 Lambda 函數或新的 API 端點時，才應使用此選項。 ### 使用 AWS SAM CLI 建置 Lambda 成品 使用 AWS SAM CLI`sam build`命令來建置 Lambda 成品。當您執行 時`sam build`， 會 AWS SAM CLI執行下列動作： 1. 尋找Terraform專案中的`sam metadata`資源，以了解並找到您的 Lambda 資源。 1. 啟動 Lambda 建置邏輯以建置 Lambda 成品。 1. 建立 `.aws-sam`目錄來組織Terraform專案，以便與 AWS SAM CLI`sam local`命令搭配使用。 **使用 sam 建置建置** 1. 從包含Terraform根模組的目錄中，執行下列動作： ``` $ sam build --hook-name terraform ``` 1. 若要建置特定的 Lambda 函數或 layer，請執行下列動作 ``` $ 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 SAM CLI`sam build`命令時，您可以設定 AWS SAM CLI以使用本機Docker容器建置應用程式。 **注意** 您必須Docker已安裝並設定 。如需說明，請參閱[安裝 Docker 以搭配 使用 AWS SAM CLI](install-docker.md)。 **使用容器建置** 1. 建立`Dockerfile`包含 Terraform、 Python和 Make工具的 。您也應該包含 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. 使用 AWS SAM CLI`--use-container`和 `--build-image`選項執行 `sam build`命令。 以下是範例： ``` $ sam build --use-container --build-image terraform-build:v1 ``` ### 後續步驟 若要開始將 AWS SAM CLI與Terraform專案搭配使用，請參閱 [搭配 使用 AWS SAM CLITerraform進行本機偵錯和測試](using-samcli-terraform.md)。 ## 設定 Terraform Cloud 我們建議您使用 Terraform v1.6.0或更新版本。如果您使用的是較舊的版本，則必須在本機產生Terraform計劃檔案。本機計劃檔案會提供 AWS SAM CLI執行本機測試和偵錯所需的資訊。 **產生本機計劃檔案** **注意** Terraform v1.6.0 或更新版本不需要這些步驟。若要開始使用 AWS SAM CLI搭配 Terraform 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 SAM CLI。 執行 ID 位於執行的 breadcrumb 路徑中。 ![\[中顯示執行 ID Terraform Cloud的 Breadcrumb 路徑。\]](http://docs.aws.amazon.com/zh_tw/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 CLITerraform進行本機偵錯和測試](using-samcli-terraform.md)。