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

# 使用 GitHub Actions 和 Terragrunt 建立 API 驅動的資源協同運作架構
<a name="create-an-api-driven-resource-orchestration-framework-using-github-actions-and-terragrunt"></a>

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

## 總結
<a name="create-an-api-driven-resource-orchestration-framework-using-github-actions-and-terragrunt-summary"></a>

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

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

## 先決條件和限制
<a name="create-an-api-driven-resource-orchestration-framework-using-github-actions-and-terragrunt-prereqs"></a>

**先決條件**
+ 作用中 AWS 帳戶
+ 可存取已設定儲存庫的作用中 GitHub 帳戶

**限制**
+ 新資源需要手動將`terragrunt.hcl`檔案新增至儲存庫組態。
+ 有些 AWS 服務 完全無法使用 AWS 區域。如需區域可用性，請參閱[AWS 依區域的服務](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/)。如需特定端點，請參閱[服務端點和配額](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html)，然後選擇服務的連結。

## Architecture
<a name="create-an-api-driven-resource-orchestration-framework-using-github-actions-and-terragrunt-architecture"></a>

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

![使用 GitHub Actions 和 Terraform 自動化資源佈建的工作流程。](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/images/pattern-img/bff5d70e-e8f1-454a-94bc-60e8cc16e69f/images/d4a768c8-4e11-493c-85ed-f4bf7e76ce60.png)


架構圖顯示下列動作：

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

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

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

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

## 工具
<a name="create-an-api-driven-resource-orchestration-framework-using-github-actions-and-terragrunt-tools"></a>

**AWS 服務**
+ [Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Introduction.html) 是一項全受管 NoSQL 資料庫服務，可提供快速、可預期且可擴展的效能。
+ [AWS Identity and Access Management (IAM)](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) 透過控制已驗證並獲授權使用的人員，協助您安全地管理對 AWS 資源的存取。
+ [Amazon Simple Storage Service (Amazon S3)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) 是一種雲端型物件儲存服務，可協助您儲存、保護和擷取任何數量的資料。
+ [Amazon Virtual Private Cloud (Amazon VPC)](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) 可協助您在已定義的虛擬網路中啟動 AWS 資源。此虛擬網路與您在自己的資料中心中操作的傳統網路相似，且具備使用 AWS可擴展基礎設施的優勢。

**其他工具**
+ [GitHub Actions](https://docs.github.com/en/actions) 是與 GitHub 儲存庫緊密整合的持續整合和持續交付 (CI/CD) 平台。您可以使用 GitHub 動作來自動化建置、測試和部署管道。
+ [Terraform](https://www.terraform.io/) 是 HashiCorp 的基礎設施即程式碼 (IaC) 工具，可協助您建立和管理雲端和內部部署資源。
+ [Terragrunt](https://terragrunt.gruntwork.io/docs/getting-started/overview/) 是一種協同運作工具，可同時延伸 OpenTofu 和 Terraform 功能。它可管理一般基礎設施模式的套用方式，讓您更輕鬆地擴展和維護大型基礎設施資產。

**程式碼儲存庫**

此模式的程式碼可在 GitHub [sample-aws-orchestration-pipeline-terraform](https://github.com/aws-samples/sample-aws-orchestration-pipeline-terraform) 儲存庫中使用。

## 最佳實務
<a name="create-an-api-driven-resource-orchestration-framework-using-github-actions-and-terragrunt-best-practices"></a>
+ 使用 GitHub 儲存庫秘密存放 AWS 登入資料和敏感資料，以安全存取。
+ 設定 GitHub 動作的 OpenID Connect (OIDC) 提供者以擔任 IAM 角色，避免靜態登入資料。
+ 遵循最低權限原則，並授予執行任務所需的最低許可。如需詳細資訊，請參閱 IAM 文件中的[授予最低權限](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#grant-least-priv)和[安全最佳實務](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)。

## 史詩
<a name="create-an-api-driven-resource-orchestration-framework-using-github-actions-and-terragrunt-epics"></a>

### 建立和設定儲存庫
<a name="create-and-configure-repository"></a>


| 任務 | Description | 所需的技能 | 
| --- | --- | --- | 
| 初始化 GitHub 儲存庫。 | 若要初始化 GitHub 儲存庫，請使用下列步驟：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/create-an-api-driven-resource-orchestration-framework-using-github-actions-and-terragrunt.html) | DevOps 工程師 | 
| 設定 IAM 角色和許可。 | 若要設定 IAM 角色和許可，請使用下列步驟：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/create-an-api-driven-resource-orchestration-framework-using-github-actions-and-terragrunt.html) | DevOps 工程師 | 
| 設定 GitHub 秘密和變數。 | 如需如何在 GitHub 儲存庫中設定儲存庫秘密和變數的指示，請參閱 GitHub 文件中的[為儲存庫建立組態變數](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables#creating-configuration-variables-for-a-repository)。設定下列變數：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/create-an-api-driven-resource-orchestration-framework-using-github-actions-and-terragrunt.html) | DevOps 工程師 | 
| 建立儲存庫結構。 | 若要建立儲存庫結構，請使用下列步驟：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/create-an-api-driven-resource-orchestration-framework-using-github-actions-and-terragrunt.html) | DevOps 工程師 | 

### 觸發管道並驗證結果
<a name="trigger-the-pipeline-and-validate-results"></a>


| 任務 | Description | 所需的技能 | 
| --- | --- | --- | 
| 使用 curl 執行管道。 | 若要使用 [curl](https://curl.se/) 執行管道，請使用下列步驟：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/create-an-api-driven-resource-orchestration-framework-using-github-actions-and-terragrunt.html)<br />如需管道執行程序的詳細資訊，請參閱[其他資訊](#create-an-api-driven-resource-orchestration-framework-using-github-actions-and-terragrunt-additional)。 | DevOps 工程師 | 
| 驗證管道執行的結果 | 若要驗證結果，請使用下列步驟：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/create-an-api-driven-resource-orchestration-framework-using-github-actions-and-terragrunt.html)<br />您也可以使用在與 檔案相同資源內的儲存庫中建立`output.json`的檔案，跨驗證建立的資源`terragrunt.hcl`。 | DevOps 工程師 | 

### 清除資源
<a name="clean-up-resources"></a>


| 任務 | Description | 所需的技能 | 
| --- | --- | --- | 
| 提交清除請求。 | 若要刪除不再需要的資源，請使用下列步驟：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/create-an-api-driven-resource-orchestration-framework-using-github-actions-and-terragrunt.html) | DevOps 工程師 | 

## 相關資源
<a name="create-an-api-driven-resource-orchestration-framework-using-github-actions-and-terragrunt-resources"></a>

**AWS 部落格**
+ [使用 IAM 角色將 GitHub 動作連線至 中的動作 AWS](https://aws.amazon.com/blogs/security/use-iam-roles-to-connect-github-actions-to-actions-in-aws/)

**AWS 服務 文件**
+ [IAM 角色建立](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html)
+ [使用 Amazon CloudWatch Logs 監控 CloudTrail 日誌檔案](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/monitor-cloudtrail-log-files-with-cloudwatch-logs.html)
+ [Amazon S3 的安全最佳實務](https://docs.aws.amazon.com/AmazonS3/latest/userguide/security-best-practices.html)

**GitHub 資源**
+ [建立儲存庫分派事件](https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#create-a-repository-dispatch-event)
+ [建立 Webhook](https://docs.github.com/en/webhooks/using-webhooks/creating-webhooks#payload)
+ [在 GitHub 儲存庫上實作強大的存取控制](https://docs.github.com/en/get-started/learning-about-github/access-permissions-on-github)
+ [定期稽核儲存庫存取權](https://docs.github.com/en/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization)
+ [CI/CD 管道中的安全檢查](https://github.com/marketplace/actions/checkov-github-action)
+ [對 GitHub 帳戶使用多重驗證](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication)

## 其他資訊
<a name="create-an-api-driven-resource-orchestration-framework-using-github-actions-and-terragrunt-additional"></a>

**管道執行程序**

以下是管道執行的步驟：

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

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

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

1. **執行資源部署** - 套用組態以在目標環境中部署或更新 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 區塊](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-cidr-blocks.html)規格。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`必須使用 參數。