GitHub Actions と Terragrunt を使用して API 駆動型リソースオーケストレーションフレームワークを作成する - AWS 規範ガイダンス
概要前提条件と制限アーキテクチャツールベストプラクティスエピック関連リソース追加情報

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

GitHub Actions と Terragrunt を使用して API 駆動型リソースオーケストレーションフレームワークを作成する

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

概要

このパターンでは、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. ユーザーは JSON ペイロードを GitHub Actions に送信し、自動化パイプラインをトリガーします。

  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 のサービス

  • Amazon DynamoDB は、フルマネージド NoSQL データベースサービスです。高速かつ予測可能でスケーラブルなパフォーマンスを提供します。

  • AWS Identity and Access Management (IAM) は、誰を認証し、誰に使用する権限を付与するかを制御することで、 AWS リソースへのアクセスを安全に管理するのに役立ちます。

  • Amazon Simple Storage Service (Amazon S3) は、どのようなデータ量であっても、データを保存、保護、取得することを支援するクラウドベースのオブジェクトストレージサービスです。

  • Amazon Virtual Private Cloud (Amazon VPC) は、定義した仮想ネットワークに AWS リソースを起動するのに役立ちます。この仮想ネットワークは、ユーザー自身のデータセンターで運用されていた従来のネットワークと似ていますが、 AWSのスケーラブルなインフラストラクチャを使用できるという利点があります。

その他のツール

  • GitHub Actions は、GitHub リポジトリと緊密に統合された継続的インテグレーションおよび継続的デリバリー (CI/CD) プラットフォームです。GitHub Actions を使用して、ビルド、テスト、デプロイパイプラインを自動化できます。

  • 「Terraform」は、HashiCorpのinfrastructure as code (IaC) ツールで、クラウドとオンプレミスのリソースの作成と管理を支援します。

  • Terragrunt は、OpenTofu と Terraform の両方の機能を拡張するオーケストレーションツールです。一般的なインフラストラクチャパターンの適用方法を管理し、大規模なインフラストラクチャ資産のスケーリングと維持を容易にします。

コードリポジトリ

このパターンのコードは、GitHub sample-aws-orchestration-pipeline-terraform リポジトリで入手できます。

ベストプラクティス

  • GitHub リポジトリシークレットを使用して AWS 認証情報と機密データを保存し、安全なアクセスを実現します。

  • GitHub Actions の OpenID Connect (OIDC) プロバイダーを設定して IAM ロールを引き受け、静的認証情報を回避します。

  • 最小特権の原則に従い、タスクの実行に必要な最小限のアクセス許可を付与します。詳細については、IAM ドキュメントの「最小特権の付与」と「セキュリティのベストプラクティス」を参照してください。

エピック

タスク説明必要なスキル

GitHub リポジトリを初期化します。

GitHub リポジトリを初期化するには、次の手順を実行します。

  1. パイプラインコードをホストする新しい GitHub リポジトリを作成します。

  2. ソースリポジトリの .github/workflows フォルダにある deployment.ymlおよび workflow-trigger.yml ファイルをインポートします。

DevOps エンジニア

IAM ロールとアクセス許可を設定します。

IAM ロールとアクセス許可を設定するには、次のステップを使用します。

  1. GitHub Actions が OpenID Connect (OIDC) ID プロバイダー (IdP) を使用して のアクションに接続 AWSするために必要な信頼関係を持つ IAM ロールを作成します。 OpenID IdP

  2. 必要なアクセス許可を IAM ロールにアタッチして、バックエンドと必要なリソースを作成します。詳細については、Amazon VPC で VPC を作成するサンプルポリシーと、バックエンドの Amazon S3 バケットと DynamoDB テーブルを参照してください。

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. リポジトリの Actions タブで GitHub Actions ワークフロー実行をモニタリングします。

  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 Actions で削除プロセスをモニタリングします。

  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。パラメータvpc_cidrは Amazon VPC に必須です。