使用 GitHub Actions 和 Terragrunt 建立 API 驅動的資源協同運作架構 - AWS 方案指引
Summary先決條件和限制架構工具最佳實務史詩相關資源其他資訊

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 GitHub Actions 和 Terragrunt 建立 API 驅動的資源協同運作架構

Tamilselvan P、Abhigyan Dandriyal、Sandeep Gawande 和 Akash Kumar，Amazon Web Services

Summary

此模式利用 GitHub Actions 工作流程，透過標準化 JSON 承載自動化資源佈建，無需手動設定。此自動化管道會管理完整的部署生命週期，並可無縫整合各種前端系統，從自訂 UI 元件到 ServiceNow。解決方案的彈性可讓使用者透過偏好的界面與系統互動，同時維持標準化程序。

可設定的管道架構可以適應不同的組織需求。範例實作著重於 Amazon Virtual Private Cloud (Amazon VPC) 和 Amazon Simple Storage Service (Amazon S3) 佈建。模式透過標準化整個組織的請求並提供一致的整合點，有效地解決常見的雲端資源管理挑戰。這種方法可讓團隊更輕鬆地請求和管理資源，同時確保標準化。

先決條件和限制

先決條件

  • 作用中 AWS 帳戶

  • 可存取已設定儲存庫的作用中 GitHub 帳戶

限制

  • 新資源需要手動將terragrunt.hcl檔案新增至儲存庫組態。

  • 有些 AWS 服務 不適用於所有 AWS 區域。如需區域可用性，請參閱AWS 依區域的服務。如需特定端點，請參閱服務端點和配額，然後選擇服務的連結。

架構

下圖顯示此模式的元件和工作流程。

使用 GitHub Actions 和 Terraform 自動化資源佈建的工作流程。

架構圖顯示下列動作：

  1. 使用者向 GitHub 動作提交 JSON 承載，觸發自動化管道。

  2. GitHub Actions 管道會根據承載規格，從 Terragrunt 和 Terraform 儲存庫擷取所需的資源程式碼。

  3. 管道會使用指定的 AWS 帳戶 ID 擔任適當的 AWS Identity and Access Management (IAM) 角色。然後，管道會將資源部署到目標， AWS 帳戶 並使用帳戶特定的 Amazon S3 儲存貯體和 Amazon DynamoDB 資料表來管理 Terraform 狀態。

每個 都 AWS 帳戶 包含用於安全存取的 IAM 角色、用於 Terraform 狀態儲存的 Amazon S3 儲存貯體，以及用於狀態鎖定的 DynamoDB 資料表。此設計可讓您跨 進行受控的自動化資源部署 AWS 帳戶。部署程序會透過每個帳戶中的專用 Amazon S3 儲存貯體和 IAM 角色，維護適當的狀態管理和存取控制。

工具

AWS 服務

其他工具

  • GitHub Actions 是與 GitHub 儲存庫緊密整合的持續整合和持續交付 (CI/CD) 平台。您可以使用 GitHub 動作來自動化建置、測試和部署管道。

  • Terraform 是 HashiCorp 的基礎設施即程式碼 (IaC) 工具，可協助您建立和管理雲端和內部部署資源。

  • Terragrunt 是一種協同運作工具，可同時延伸 OpenTofu 和 Terraform 功能。它可管理一般基礎設施模式的套用方式，讓您更輕鬆地擴展和維護大型基礎設施資產。

程式碼儲存庫

此模式的程式碼可在 GitHub sample-aws-orchestration-pipeline-terraform 儲存庫中使用。

最佳實務

  • 使用 GitHub 儲存庫秘密存放 AWS 登入資料和敏感資料，以便安全存取。

  • 設定 GitHub 動作的 OpenID Connect (OIDC) 提供者以擔任 IAM 角色，避免靜態登入資料。

  • 遵循最低權限原則，並授予執行任務所需的最低許可。如需詳細資訊，請參閱 IAM 文件中的授予最低權限和安全最佳實務。

史詩

任務描述所需的技能

初始化 GitHub 儲存庫。

若要初始化 GitHub 儲存庫，請使用下列步驟：

  1. 建立新的 GitHub 儲存庫以託管管道程式碼。

  2. 匯入位於來源儲存庫 .github/workflows 資料夾的 deployment.yml和 workflow-trigger.yml 檔案。

DevOps 工程師

設定 IAM 角色和許可。

若要設定 IAM 角色和許可，請使用下列步驟：

  1. 使用 OpenID Connect (OIDC) 身分提供者 (IdP)，建立具有 GitHub 動作在 中連線至動作 AWS所需的信任關係的 IAM 角色。

  2. 將必要的許可連接到 IAM 角色，以建立後端和所需的資源。如需詳細資訊，請參閱使用 Amazon VPC 以及後端 Amazon S3 儲存貯體和 DynamoDB 資料表建立 VPC 的範例政策。

DevOps 工程師

設定 GitHub 秘密和變數。

如需如何在 GitHub 儲存庫中設定儲存庫秘密和變數的指示，請參閱 GitHub 文件中的為儲存庫建立組態變數。設定下列變數：

  • 儲存庫秘密

    • PAT_TOKEN – 具有執行 GitHub 操作許可的個人存取字符

  • 儲存庫變數

DevOps 工程師

建立儲存庫結構。

若要建立儲存庫結構，請使用下列步驟：

  1. 在main分支中建立新的資料夾以存放terragrunt.hcl檔案，以及資源建立後的輸出和變更日誌。

  2. 根據您要透過資料夾佈建的資源類型，使用小寫命名資料夾。資料夾稍後會在承載中依原樣使用。如需詳細資訊，請參閱 儲存庫中 Amazon S3 和 Amazon VPC 的範例結構。

DevOps 工程師
任務描述所需的技能

使用 curl 執行管道。

若要使用 curl 執行管道，請使用下列步驟：

  1. 在本機目錄中建立 payload.json 檔案。遵循承載檔案的定義結構，並在提交請求之前將其字串化。如需詳細資訊，請參閱 儲存庫中的範例承載。

  2. 使用 GitHub API 在終端機上提交請求，如下列範例所示：

    curl -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  -d @payload.json \
  https://api.github.com/repos/OWNER/REPO/actions/workflows/workflow-trigger.yml/dispatches

    在範例中，為下列項目提供您自己的值：

    • YOUR_GITHUB_TOKEN 使用您的 GitHub 個人存取字符

    • OWNER 儲存庫擁有者的名稱

    • REPO 使用儲存庫名稱

如需管道執行程序的詳細資訊，請參閱其他資訊。

DevOps 工程師

驗證管道執行的結果

若要驗證結果，請使用下列步驟：

  1. 在儲存庫的動作索引標籤中監控 GitHub 動作工作流程執行。

  2. 成功執行工作流程後，請使用 驗證資源建立 AWS Management Console ，如下所示：

    1. 對於 Amazon VPC：

      • 導覽至指定 中的 Amazon VPC 服務 AWS 區域。

      • 檢查是否有標籤符合您請求參數的新 VPC。

      • 驗證 CIDR 區塊和其他組態。

    2. 對於 Amazon S3：

      • 導覽至 Amazon S3 儲存貯體。

      • 在一般用途儲存貯體中，檢查符合您請求參數的新儲存貯體。

      • 驗證 S3 儲存貯體名稱和其他組態。

您也可以使用在與 檔案相同資源內的儲存庫中建立output.json的檔案，跨驗證建立的資源terragrunt.hcl。

DevOps 工程師
任務描述所需的技能

提交清除請求。

若要刪除不再需要的資源，請使用下列步驟：

  1. 使用相同的 API 端點提交刪除請求，但修改承載，如下所示：

    • 在 delete中RequestType將 變更為 RequestParameters。

    • 讓所有其他參數保持與create請求相同。

  2. 在 GitHub 動作中監控刪除程序。

  3. 工作流程完成後，確認資源資料夾中changelog.json的檔案顯示 的狀態deleted。

  4. 使用 驗證資源移除 AWS Management Console。

DevOps 工程師

相關資源

AWS 部落格

AWS 服務 文件

GitHub 資源

其他資訊

管道執行程序

以下是管道執行的步驟：

  1. 驗證 JSON 承載格式 - 確保傳入的 JSON 組態結構正確，並包含所有必要的參數

  2. 擔任指定的 IAM 角色 - 驗證並擔任 AWS 操作所需的 IAM 角色

  3. 下載必要的 Terraform 和 Terragrunt 程式碼 - 擷取指定的資源程式碼和相依性版本

  4. 執行資源部署 - 套用組態以在目標環境中部署或更新 AWS 資源

用於建立 VPC 的範例承載

以下是 Terraform 後端狀態儲存貯體建立的範例程式碼：

state_bucket_name = "${local.payload.ApplicationName}-${local.payload.EnvironmentId}-tfstate"
lock_table_name = "${local.payload.ApplicationName}-${local.payload.EnvironmentId}-tfstate-lock"

以下是使用 Amazon VPC 建立 VPC 的範例承載，其中 vpc_cidr 定義 VPC 的 CIDR 區塊規格。Terraform 狀態儲存貯體會映射至terraform檔案中定義的變數。ref 參數包含要執行之程式碼的分支名稱。

{
    "ref": "main",
    "inputs": {
        "RequestParameters": {
            "RequestId": "1111111",
            "RequestType": "create",
            "ResourceType": "vpc",
            "AccountId": "1234567890",
            "AccountAlias": "account-alias",
            "RegionId": "us-west-2",
            "ApplicationName": "myapp",
            "DivisionName": "division-name",
            "EnvironmentId": "dev",
            "Suffix": "poc"
        },
        "ResourceParameters": [
            {
                "VPC": {
                    "vpc_cidr": "10.0.0.0/16"
                }
            }
        ]
    }
}

RequestParameters 用於追蹤管道區段中的請求狀態tfstate，並根據此資訊建立。下列參數包含中繼資料和控制資訊：

  • RequestId – 請求的唯一識別符

  • RequestType – 操作類型 （建立、更新或刪除）

  • ResourceType – 要佈建的資源類型

  • AccountId – 部署 AWS 帳戶 的目標

  • AccountAlias – 的易記名稱 AWS 帳戶

  • RegionId – AWS 區域 用於資源部署

  • ApplicationName – 應用程式的名稱

  • DivisionName – 組織分處

  • EnvironmentId – 環境 （例如，dev 和 prod)

  • Suffix – 資源的其他識別符

ResourceParameters 包含資源特定的組態，對應至 Terraform 檔案中定義的變數。任何需要傳遞至 Terraform 模組的自訂變數都應包含在 中ResourceParameters。Amazon VPC vpc_cidr必須使用 參數。