翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# GitHub Actions を使用して Terraform マネージド AWS インフラストラクチャの自動プルリクエストを作成する
<a name="create-automated-pull-requests-for-terraform-managed-aws-infrastructure"></a>

*Amazon Web Services、Matt Padgett、Ashish Bhatt、Ashwin Divakaran、Sandip Gangapadhyay、および Prafful Gupta*

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

このパターンでは、複数の Terraform リポジトリ間での変更管理に伴う手動の繰り返し作業を排除するように設計された自動化ユーティリティについて説明します。多くの組織は、Terraform リポジトリを使用して Infrastructure as Code (IaC) を管理しています。多くの場合、数百の個別のリポジトリがさまざまな環境、サービス、チームを表しています。これらのリポジトリを大規模に管理することは、運用上の重要な課題となります。パラメータの更新、モジュールバージョンのアップグレード、設定変更の適用などの日常的なタスクでは、多くの場合、多くのリポジトリに 1 日に何度もプルリクエスト (PR) を作成および管理する必要があります。

単純な変更であっても、この繰り返しで手動のプロセスには時間がかかり、エラーが発生しやすくなります。エンジニアは、すべてのターゲットリポジトリに同じ変更を一貫して適用し、意味のある PR タイトルと説明を作成する必要があります。さらに、問題追跡リファレンスを取得または含めるために、Jira などの外部ツールとやり取りする必要がたびたび生じます。これらのタスクは、必要ではあるものの、貴重なエンジニアリング時間を消費し、全体的な効率を低下させるような、差別化にならない重労働です。このワークフローを自動化しないと、衝突が発生し、引き渡しが遅くなり、大規模な Terraform インフラストラクチャの維持を担当するチームの認知負担が増大します。

**ソリューションの概要**

この課題に対処するために、このパターンでは完全に設定駆動型のユーティリティを提供します。これにより、ユーザーは構造化された設定ファイルで必要な変更を定義できます。このファイルでは、明確に定義されたスキーマを使用して、ターゲットリポジトリ、モジュール、パラメータ、および値を指定できます。

設定が済むと、ユーティリティは次の自動ステップを実行します。

1. **ユーザー定義の設定を読み取り**、変更の範囲と性質を決定する

1. 各ターゲットリポジトリに、必要な更新が適用された**新しいブランチを作成**する

1. 変更ごとに **PR を生成**し、すべてのリポジトリ間で整合性を確保する

1. **Slack 通知を送信**して (オプション)、作成された PR へのリンクと共に関係者に警告する

これらの繰り返しのタスクを自動化することにより、このユーティリティは大規模なインフラストラクチャ更新の管理に伴う時間、労力、リスクを大幅に削減します。その結果、チームは、変更が一貫して適用されて、すべてのリポジトリで追跡できることを容易に確認できると同時に、より価値の高いエンジニアリング作業に集中できます。

## 前提条件と制限
<a name="create-automated-pull-requests-for-terraform-managed-aws-infrastructure-prereqs"></a>

**前提条件**
+ アクティブ AWS アカウント。
+ Python バージョン 3.8 以降。
+ GitHub の個人用アクセストークン (PAT)。詳細は、GitHub ドキュメントの「[Creating a personal access token (classic)](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 などの特定のツールで動作するように設計されているため、システムの柔軟性を制限します。さまざまなツールを使用する組織にはカスタムソリューションが必要になる場合があり、このパターンのワークフローカスタマイズオプションはサポート対象の統合ポイントに制限されます。

## アーキテクチャ
<a name="create-automated-pull-requests-for-terraform-managed-aws-infrastructure-architecture"></a>

次の図は、このソルーションのワークフローとコンポーネントを示しています。

![\[GitHub Actions を使用して自動プルリクエストを作成するワークフロー。\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/images/pattern-img/e211359a-03b1-4e69-b152-eb7c09bdb01a/images/6cee0660-5b44-4abe-970c-c0a3c830a9aa.png)


ワークフローの主なステップは、以下のとおりです。

1. デベロッパーは Terraform リポジトリを指定して GitHub Actions の実行を開始します。

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 Actions を使用して、生成、テスト、デプロイのパイプラインを自動化できます。
+ [HashiCorp Terraform](https://www.terraform.io/) は、Infrastructure as Code (IaC) ツールで、クラウドとオンプレミスのリソースの作成と管理を支援します。
+ Salesforce の製品である [Slack](https://slack.com/help/articles/115004071768-What-is-Slack-) は、チャットとビデオでの共同作業、ノーコードでのプロセスの自動化、情報共有が可能な、AI を活用した対話型プラットフォームです。

**コードリポジトリ**

このパターンのコードは、GitHub の [Automated Terraform Infrastructure Update Workflow using GitHub Actions](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>


| タスク | 説明 | 必要なスキル | 
| --- | --- | --- | 
| リポジトリを設定します。 | リポジトリのクローンを作成するには、次のコマンドを実行します。<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>


| タスク | 説明 | 必要なスキル | 
| --- | --- | --- | 
| `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>


| タスク | 説明 | 必要なスキル | 
| --- | --- | --- | 
| 事前テストを実行します。 | 本番用リポジトリで実行する前に、必ず設定をテストしてください。次のコマンドを使用します。<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>


| タスク | 説明 | 必要なスキル | 
| --- | --- | --- | 
| GitHub Actions UI を使用して自動化ユーティリティを実行します。 | GitHub Actions UI を使用して自動化ユーティリティを実行するには、次の手順を実行します。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/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 | 

### PR と変更を検証する
<a name="validate-prs-and-changes"></a>


| タスク | 説明 | 必要なスキル | 
| --- | --- | --- | 
| 作成された PR と変更を確認します。 | GitHub ワークフロー実行の結果をモニタリングするには、次を実行します。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/patterns/create-automated-pull-requests-for-terraform-managed-aws-infrastructure.html) | AWS DevOps | 

### クリーンアップ
<a name="clean-up"></a>


| タスク | 説明 | 必要なスキル | 
| --- | --- | --- | 
| (オプション) PR をクリーンアップします。 | 中止された、もしくは不要な PR を閉じます。 | AWS DevOps  | 

## 関連リソース
<a name="create-automated-pull-requests-for-terraform-managed-aws-infrastructure-resources"></a>

**AWS 規範ガイダンス**
+ [の IaC ツールとしての Terraform の使用 AWS クラウド](https://docs.aws.amazon.com/prescriptive-guidance/latest/choose-iac-tool/terraform.html)

**GitHub ドキュメント**
+ [pull requests について](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 Actions を理解する](https://docs.github.com/en/actions/get-started/understand-github-actions)
+ [GitHub Actions のクイックスタート](https://docs.github.com/en/actions/get-started/quickstart)