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

# 使用 GitHub Actions 建立 Terraform 受管 AWS 基礎設施的自動提取請求
<a name="create-automated-pull-requests-for-terraform-managed-aws-infrastructure"></a>

*Matt Padgett、Ashish Bhatt、Ashwin Divakaran、Sandip Gangapadhyay 和 Prafful Gupta，Amazon Web Services*

## 總結
<a name="create-automated-pull-requests-for-terraform-managed-aws-infrastructure-summary"></a>

此模式提供自動化公用程式，旨在消除在多個 Terraform 儲存庫中管理變更時涉及的手動重複工作。許多組織使用 Terraform 儲存庫以程式碼 (IaC) 的形式管理其基礎設施，通常具有數百個代表不同環境、服務或團隊的個別儲存庫。大規模管理這些儲存庫會帶來重大的操作挑戰。更新參數、升級模組版本或套用組態變更等例行任務，通常需要每天多次跨許多儲存庫建立和管理提取請求 (PRs)。

即使是簡單的變更，這個重複的手動程序也非常耗時且容易出錯。工程師必須一致地在所有目標儲存庫中套用相同的變更，並製作有意義的 PR 標題和描述。此外，他們通常必須與 Jira 等外部工具互動，以擷取或包含問題追蹤參考。這些任務雖然必要，但是無差別的繁重工作，會耗用寶貴的工程時間並降低整體效率。此工作流程中缺乏自動化會造成摩擦、減慢交付速度，並增加負責維護大規模 Terraform 基礎設施之團隊的認知負擔。

**解決方案概觀**

為了解決此挑戰，此模式提供完全以組態為導向的公用程式，可讓使用者在結構化組態檔案中定義所需的變更。此檔案會使用明確定義的結構描述來指定目標儲存庫、模組、參數和值。

設定完成後，公用程式會執行下列自動化步驟：

1. **讀取使用者定義的組態**，以判斷變更的範圍和性質

1. 在每個目標儲存庫中**建立新的分支**，並套用必要的更新

1. 為每個變更**產生 PR**，確保所有儲存庫的一致性

1. **傳送 Slack 通知** （選用），以使用建立PRs 的直接連結來提醒利益相關者

透過自動化這些重複性任務，公用程式可大幅減少與管理大規模基礎設施更新相關的時間、精力和風險。它可讓團隊專注於更高價值的工程工作，同時協助確保一致地套用變更，並可追蹤所有儲存庫。

## 先決條件和限制
<a name="create-automated-pull-requests-for-terraform-managed-aws-infrastructure-prereqs"></a>

**先決條件**
+ 作用中 AWS 帳戶。
+ Python 3.8 版或更新版本。
+ GitHub 個人存取字符 (PAT)。如需詳細資訊，請參閱 GitHub 文件中的[建立個人存取字符 （傳統）](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)。
+ GitHub PAT 可以存取您的目標儲存庫，讓公用程式可以執行建立分支和提取請求等操作。如需詳細資訊，請參閱此模式的 GitHub [程式碼儲存庫](https://github.com/aws-samples/sample-terraform-pr-automation-utility?tab=readme-ov-file#repository-access-verification)。

**限制**
+ **組態複雜性**代表主要挑戰。自動化的有效性受到其組態檔案的功能限制。雖然系統有效率地處理標準變更，但複雜的基礎設施修改可能需要手動介入，而且某些邊緣案例仍超出自動處理的範圍。
+ **安全性和存取**提供重要的考量，特別是在管理 GitHub 存取權杖和 API 速率限制時。組織必須仔細平衡自動化與安全登入資料儲存和管理的需求，確保適當的存取控制，同時維持營運效率。
+ **驗證限制**構成另一個值得注意的限制，因為自動化系統驗證業務邏輯和環境特定需求的能力有限。複雜的相依性和跨服務互動通常需要人工監督，因為自動化驗證無法完全擷取所有情境細節和業務規則。
+ 處理大規模基礎設施變更時，會出現規模**和效能**問題。系統必須在 GitHub API 限制內操作，同時同時管理多個儲存庫。跨廣泛基礎設施的資源密集型操作可能會產生需要謹慎管理的效能瓶頸。
+ **整合界限**會限制系統的靈活性，因為它主要設計用於 GitHub 和 Slack 等特定工具。使用不同工具的組織可能需要自訂解決方案，且此模式的工作流程自訂選項僅限於支援的整合點。

## Architecture
<a name="create-automated-pull-requests-for-terraform-managed-aws-infrastructure-architecture"></a>

下圖顯示此解決方案的工作流程和元件。

![\[使用 GitHub 動作建立自動提取請求的工作流程。\]](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/images/pattern-img/e211359a-03b1-4e69-b152-eb7c09bdb01a/images/6cee0660-5b44-4abe-970c-c0a3c830a9aa.png)


工作流程由以下步驟組成：

1. 開發人員透過指定 Terraform 儲存庫來觸發 GitHub 動作。

1. 自動化公用程式會讀取定義的組態。

1. 自動化公用程式也會提取提供的 Terraform 儲存庫。

1. 自動化公用程式會建立新的分支，並在本機更新 Terraform 範本。

1. 自動化公用程式會將新的分支推送至儲存庫，並建立新的 PR。

1. 自動化公用程式使用包含 PR 連結的 Slack 通知來通知開發人員，並啟用 Terraform 範本以進行 AWS 雲端 部署。

## 工具
<a name="create-automated-pull-requests-for-terraform-managed-aws-infrastructure-tools"></a>
+ [GitHub](https://docs.github.com/) 是一種開發人員平台，開發人員可用來建立、存放、管理和共用其程式碼。
+ [GitHub Actions](https://docs.github.com/en/actions) 是與 GitHub 儲存庫緊密整合的持續整合和持續交付 (CI/CD) 平台。您可以使用 GitHub 動作來自動化建置、測試和部署管道。
+ [HashiCorp Terraform](https://www.terraform.io/) 是一種基礎設施即程式碼 (IaC) 工具，可協助您建立和管理雲端和內部部署資源。
+ [Slack](https://slack.com/help/articles/115004071768-What-is-Slack-) 是 Salesforce 產品，是一種採用 AI 技術的對話平台，可提供聊天和視訊協作、自動化沒有程式碼的程序，並支援資訊共用。

**程式碼儲存庫**

此模式的程式碼可在使用 GitHub [動作儲存庫的 GitHub 自動化 Terraform 基礎設施更新工作流程](https://github.com/aws-samples/sample-terraform-pr-automation-utility?tab=readme-ov-file)中取得。

## 最佳實務
<a name="create-automated-pull-requests-for-terraform-managed-aws-infrastructure-best-practices"></a>
+ 有效的**變更管理**對於成功實作至關重要。組織應針對大規模變更採用逐步推展策略。維持一致的分支命名慣例和 PR 描述，並確保所有變更的完整文件。
+ 必須嚴格實作**安全控制**，專注於最低權限的存取原則和安全登入資料管理。啟用分支保護規則以防止未經授權的變更。定期執行安全稽核以維護系統完整性。
+ 強大的**測試通訊協定**應包括在持續整合和持續部署 (CI/CD) 管道中自動`terraform plan`執行。通訊協定也應該包含遞交前驗證檢查，以及針對重大變更的專用審核環境。這種多層測試方法有助於及早發現問題，並確保基礎設施的穩定性。
+ **監控策略**需要包含全面的提醒機制、詳細的成功/失敗指標追蹤，以及失敗操作的自動重試機制。此策略有助於確保營運可見性，並能夠快速回應任何出現的問題。
+ **組態標準**應強調所有組態的版本控制，維護模組化以實現可重複使用性和可擴展性。清楚的結構描述和範例文件，可協助團隊有效地了解和使用自動化系統。

## 史詩
<a name="create-automated-pull-requests-for-terraform-managed-aws-infrastructure-epics"></a>

### 設定和安裝
<a name="installation-and-setup"></a>


| 任務 | Description | 所需的技能 | 
| --- | --- | --- | 
| 設定儲存庫。 | 若要設定儲存庫，請執行下列命令：<pre># Clone the automation tool repository<br />git clone https://github.com/aws-samples/sample-terraform-pr-automation-utility<br />cd sample-terraform-pr-automation-utility<br /><br /># Copy example configuration<br />cp config.example.yaml config.yaml<br /></pre> | AWS DevOps | 
| 安裝依存項目。 | 若要安裝和驗證 Python 相依性，請執行下列命令：<pre># Install Python dependencies<br />pip3 install -r requirements.txt<br /><br /># Verify installation<br />python3 -c "import github; import hcl2; import yaml; import requests; print('All packages installed successfully')"<br /></pre> | AWS DevOps | 
| 設定 GitHub 字符。 | 若要設定 GitHub 字符，然後驗證其是否正常運作，請執行下列命令：<pre># Set GitHub token environment variable<br />export GITHUB_TOKEN="your_github_token_here"<br /><br /># Verify token works<br />curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user<br /></pre> | AWS DevOps | 

### 設定 Terraform 變更的組態檔案
<a name="set-up-configuration-file-for-terraform-changes"></a>


| 任務 | Description | 所需的技能 | 
| --- | --- | --- | 
| 設定 `config.yaml` 檔案。 | 若要定義您的目標儲存庫和所需的變更，請編輯 `config.yam`l 檔案，如下所示：<pre>repositories:<br />  - owner: "your-org"<br />    repo: "your-terraform-repo"<br />    files:<br />      - path: "variables.tf"<br />        changes:<br />          variables:<br />            - app_version:<br />                default:<br />                  update:<br />                    - from: ["1.0.0"]<br />                      to: "1.1.0"<br /><br />settings:<br />  pr_title_template: "Infrastructure Update - {{timestamp}}"<br />  slack:<br />    username: "Terraform Bot"<br />    icon_emoji: ":terraform:"<br />    notify_on_success: true<br />    notify_on_error: true<br />    notify_batch_summary: true<br /></pre> | AWS DevOps | 

### 測試和驗證
<a name="test-and-validate"></a>


| 任務 | Description | 所需的技能 | 
| --- | --- | --- | 
| 執行飛行前測試。 | 在生產儲存庫上執行組態之前，請務必先測試組態。使用下列命令：<pre># 1. Test configuration syntax<br />python3 -c "from main import get_config_content; get_config_content()"<br /><br /># 2. Run in dry-run mode first<br />DRY_RUN=true python3 main.py<br /><br /># 3. Test with minimal configuration<br /># Use a simple config.yaml with just one repository and one change</pre> | AWS DevOps | 
| 驗證儲存庫存取。 | 若要驗證 GitHub 字符是否可以存取儲存庫，請執行下列命令：<pre># Test GitHub token access<br />curl -H "Authorization: token $GITHUB_TOKEN" \<br />  https://api.github.com/repos/owner/repo-name<br /><br /># Should return repository information, not 404</pre> | AWS DevOps | 

### 執行自動化公用程式
<a name="run-the-automation-utility"></a>


| 任務 | Description | 所需的技能 | 
| --- | --- | --- | 
| 使用 GitHub Actions UI 執行自動化公用程式。 | 若要使用 GitHub Actions UI 執行自動化公用程式，請執行下列動作：[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/create-automated-pull-requests-for-terraform-managed-aws-infrastructure.html) | AWS DevOps | 
| （替代） 從命令列執行自動化公用程式。 | 如果您願意，您可以從命令列執行自動化公用程式，而不是使用 GitHub Actions UI。使用下列命令：<pre># Run actual automation<br />python3 main.py</pre> | AWS DevOps | 

### 驗證 PRs和變更
<a name="validate-prs-and-changes"></a>


| 任務 | Description | 所需的技能 | 
| --- | --- | --- | 
| 檢閱建立的 PRs和變更。 | 若要監控 GitHub 工作流程執行的結果，請執行下列動作：[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/create-automated-pull-requests-for-terraform-managed-aws-infrastructure.html) | AWS DevOps | 

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


| 任務 | Description | 所需的技能 | 
| --- | --- | --- | 
| （選用） 清除 PRs。 | 關閉已捨棄或不必要的 PRs。 | AWS DevOps | 

## 相關資源
<a name="create-automated-pull-requests-for-terraform-managed-aws-infrastructure-resources"></a>

**AWS 方案指引**
+ [使用 Terraform 做為 的 IaC 工具 AWS 雲端](https://docs.aws.amazon.com/prescriptive-guidance/latest/choose-iac-tool/terraform.html)

**GitHub 文件**
+ [關於提取請求](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)
+ [管理您的個人存取字符](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
+ [了解 GitHub 動作](https://docs.github.com/en/actions/get-started/understand-github-actions)
+ [GitHub 動作的快速入門](https://docs.github.com/en/actions/get-started/quickstart)