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

Terraform を使用した AWS DevOps エージェントの開始方法

概要

このガイドでは、Terraform を使用して AWS DevOps エージェントリソースを作成およびデプロイする方法を示します。Terraform 設定は、エージェントスペース、IAM ロール、オペレーターアプリ、 AWS アカウントの関連付けの作成を自動化します。

Terraform アプローチは、必要なすべてのリソースをコードとしてのインフラストラクチャとして定義することで、 CLI オンボーディングガイドで説明されている手動ステップを自動化します。

AWS DevOps エージェントは、米国東部 (バージニア北部）、米国西部 (オレゴン）、アジアパシフィック (シドニー）、アジアパシフィック (東京）、欧州 (フランクフルト）、欧州 (アイルランド) の 6 つの AWS リージョンで利用できます。サポートされているリージョンの詳細については、「」を参照してくださいサポートされるリージョン。

前提条件

作業を開始する前に、次の項目があることを確認します。

このガイドの内容

このガイドは 4 つのパートに分かれています。

作成されるリソース

パート 1: アカウントのモニタリング

パート 2: サービスアカウント (オプション)

パート 4: アセットとトリガー (オプション)

この設定では、次のリソースが作成されます。

セットアップ

ステップ 1: サンプルリポジトリのクローンを作成する

git clone https://github.com/aws-samples/sample-aws-devops-agent-terraform.git
cd sample-aws-devops-agent-terraform

ステップ 2: 変数を設定する

サンプル変数ファイルをコピーし、環境に合わせてカスタマイズします。

cp terraform.tfvars.example terraform.tfvars

エージェントスペースの名前と説明terraform.tfvarsを使用して を編集します。

agent_space_name        = "MyCompanyAgentSpace"
agent_space_description = "DevOps Agent Space for monitoring production workloads"

パート 1: エージェントスペースをデプロイする

このセクションでは、エージェントスペース、IAM ロール、オペレーターアプリ、および AWS 関連付けをモニタリングアカウントに作成します。

ステップ 1: オートメーションを使用してデプロイする (推奨)

提供されているデプロイスクリプトを使用して、セットアップを合理化します。

./deploy.sh

このスクリプトは自動的に次のようになります。

または、手動制御が必要な場合は、次の操作を行います。

terraform init
terraform plan
terraform apply

デプロイを確認するプロンプトが表示されyesたら、 と入力します。

ステップ 2: 出力を記録する

デプロイが完了すると、Terraform は出力を出力します。後で使用するために、これらの値を記録します。

Outputs:
agent_space_id              = "abc123"
agent_space_arn             = "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/abc123"
agent_space_name            = "MyCompanyAgentSpace"
devops_agentspace_role_arn  = "arn:aws:iam::<MONITORING_ACCOUNT_ID>:role/DevOpsAgentRole-AgentSpace-a1b2c3d4"
devops_operator_role_arn    = "arn:aws:iam::<MONITORING_ACCOUNT_ID>:role/DevOpsAgentRole-WebappAdmin-a1b2c3d4"
primary_account_id          = "<MONITORING_ACCOUNT_ID>"
primary_account_association_id = "assoc-xyz"

パート 2 を完了する予定がある場合は、agent_space_arn値を保存します。サービスアカウントリソースを設定するには、これが必要です。

ステップ 3: デプロイを検証する

デプロイ後の検証スクリプトを実行します。

./post-deploy.sh

または、 CLI AWS を使用して、エージェントスペースが正常に作成されたことを確認します。

aws devops-agent get-agent-space \
  --agent-space-id <AGENT_SPACE_ID> \
  --region <REGION>

この時点で、エージェントスペースはオペレーターアプリが有効で、モニタリングアカウントが関連付けられている状態でデプロイされます。エージェントはこのアカウントの問題をモニタリングできます。

パート 2 (オプション): クロスアカウントモニタリングを追加する

このセクションでは、エージェントスペースが 2 番目の AWS アカウント (サービスアカウント) のリソースをモニタリングできるようにセットアップを拡張します。これには、次の 2 つのアクションが含まれます。

ステップ 1: サービスアカウント ID を設定する

でterraform.tfvars、サービスアカウント ID を設定します。

service_account_id = "<YOUR_SERVICE_ACCOUNT_ID>"

ステップ 2: エージェントスペース ARN を設定する

パート 1 出力 (ステップ 2) からagent_space_arn値をコピーし、 で設定しますterraform.tfvars。

agent_space_arn = "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/<SPACE_ID>"

サービスアカウントリソースは、この値を使用してセカンダリアカウントロールの信頼ポリシーの範囲を設定します。これらのリソースは、この値が設定されている場合にのみ作成されます。

ステップ 3: 「aws.service」プロバイダーを設定する

でmain.tf、サービスアカウントの認証情報を使用してaws.serviceプロバイダーエイリアスを設定します。名前付きプロファイルまたは継承ロールを使用できます。

プロファイルの使用:

provider "aws" {
  alias   = "service"
  region  = var.aws_region
  profile = "your-service-account-profile"
}

または、継承ロールを使用します。

provider "aws" {
  alias  = "service"
  region = var.aws_region
  assume_role {
    role_arn = "arn:aws:iam::<SERVICE_ACCOUNT_ID>:role/OrganizationAccountAccessRole"
  }
}

ステップ 4: デプロイする

更新された設定を適用します。

terraform apply

これにより、サービスアカウントに次のリソースが作成されます。

また、サービスアカウントをリンクするソース AWS 関連付けをモニタリングアカウントに作成します。

ステップ 5: デプロイを検証する

エコーサービスをテストして、Lambda 関数が正常にデプロイされたことを確認します。

aws lambda invoke \
  --function-name echo-service-tf \
  --payload '{"test": "hello world"}' \
  --profile <your-service-account-profile> \
  --region <REGION> \
  response.json
cat response.json

パート 3 (オプション): サードパーティー統合を登録する

このセクションでは、外部サービス (Dynatrace、ServiceNow、Splunk、New Relic、GitLab、PagerDuty) をエージェントスペースに登録します。これらの統合により、 AWS DevOps Agent は調査中にテレメトリ、インシデントデータ、ソースコントロール情報にアクセスできます。

別の IntegrationsStack フェーズとエージェントスペース ID の手動配線を必要とする AWS CDK サンプルとは異なり、これらのリソースはエージェントスペースを直接参照し、パート 1 terraform applyと同じ にデプロイできます。

サポートされている統合

ステップ 1: 統合認証情報を設定する

integrations ブロックを に追加しterraform.tfvars、必要なサービスのみを入力します。次の例は、Dynatrace 統合を示しています。

integrations = {
  dynatrace = {
    account_urn   = "<DYNATRACE_ACCOUNT_URN>"
    client_id     = "<DYNATRACE_CLIENT_ID>"
    client_name   = "<DYNATRACE_CLIENT_NAME>"
    client_secret = "<DYNATRACE_CLIENT_SECRET>"
    env_id        = "<DYNATRACE_ENVIRONMENT_ID>"
    resources     = ["<DYNATRACE_RESOURCE_1>"]
  }
}

各統合の完全な形状については、サンプルリポジトリterraform.tfvars.exampleの「」を参照してください。

ServiceNow の要件: 常に短いインスタンス名にinstance_id明示的に設定します (例: "ven04972" 完全な ではなく)instance_url。instance_id を省略すると、関連付けは にフォールバックされinstance_url、DevOps エージェント API は で拒否します400 GeneralServiceException: instanceId '<url>' does not match the registered ServiceNow instance。

セキュリティ: integrations変数は とマークされるためsensitive、その値は計画から編集され、出力が適用されます。実際の認証情報を にコミットしないでくださいterraform.tfvars。本番稼働用の場合、プレーンテキストではなく AWS Secrets Manager または AWS Systems Manager パラメータストアからのソースシークレット (dataソースの使用など）。

ステップ 2: デプロイする

以下のとおり設定を適用します。

terraform apply

これにより、有効な統合ごとにサービス登録と関連付けが作成されます。

ステップ 3: 出力を確認する

デプロイが完了すると、統合出力は有効な各サービスをその登録済み IDs。

integration_service_ids = {
  "dynatrace" = "service-abc123"
}
integration_association_ids = {
  "dynatrace" = "assoc-xyz789"
}

各サービスの認証情報の設定の詳細については、以下を参照してください。

パート 4 (オプション): スキル、カスタムエージェント、スケジュールされたトリガーを追加する

このセクションでは、パート 1 で作成したエージェントスペースに 3 つのリソースを追加します。必要に応じてエージェントがロードするスキルと、エージェントを特定のワークフローにスコープするカスタムエージェントを追加します。また、カスタムエージェントを自動的に実行するスケジュールされたトリガーを追加します。これらのリソースは、 awscc_devopsagent_assetおよび awscc_devopsagent_triggerリソースを使用します。

これらのリソースでは、 AWS アカウントに追加料金が発生する場合があります。完了したら、このガイドの最後にある「クリーンアップ」セクションに従ってください。

この例では、 skillおよび custom_agentアセットタイプを使用します。同じawscc_devopsagent_assetリソースは、memory_store、、 などのすべてのアセットタイプを作成しますagents_mdattachment。別のタイプを使用するには、 asset_type引数を変更し、タイプに必要なメタデータを指定します。アセットタイプの詳細なリスト、必要なメタデータ、プロパティリファレンスについては、「」を参照してくださいアセットの管理。

ステップ 1: 設定を追加する

次の内容で、assets.tf という名前のファイルを作成します。時間ベースのトリガーのアクションは、カスタムエージェントをアセット ID で 形式で参照しますcustom:<assetId>。設定では、カスタムエージェントの asset_id 属性から自動的に接続されます。カスタムエージェントskillsのリストは名前ではなくアセット IDs も取得するため、スキルの asset_id 属性を参照します。これにより、Terraform に暗黙的な依存関係が与えられるため、スキルはアタッチするエージェントの前に作成されます。

引数metadataと action引数は文字列として渡される JSON ドキュメントであるため、この例では を使用しますjsonencode。

variable "agent_space_id" {
  type        = string
  description = "The agent space ID from the Part 1 output"
}

# A skill the agent loads when relevant
resource "awscc_devopsagent_asset" "example_skill" {
  agent_space_id = var.agent_space_id
  asset_type     = "skill"

  metadata = jsonencode({
    name        = "rds-performance-investigation"
    description = "Investigation procedures for RDS performance issues."
    agent_types = ["GENERIC"]
  })

  files = [{
    path         = "SKILL.md"
    content_text = <<-EOT
      # RDS Performance Investigation
      Use this skill when investigating database latency, connection
      errors, or query timeouts.
    EOT
  }]
}

# A custom agent with attached skills that a trigger can invoke
resource "awscc_devopsagent_asset" "example_custom_agent" {
  agent_space_id = var.agent_space_id
  asset_type     = "custom_agent"

  metadata = jsonencode({
    name   = "rds-firefighter"
    skills = [awscc_devopsagent_asset.example_skill.asset_id]
  })

  files = [{
    path         = "AGENT.md"
    content_text = <<-EOT
      # RDS Firefighter
      Custom agent for RDS incidents.
    EOT
  }]
}

# A time-based trigger that runs the custom agent on a schedule
resource "awscc_devopsagent_trigger" "daily" {
  agent_space_id = var.agent_space_id
  type           = "TIME_BASED"

  condition = {
    schedule = {
      expression = "rate(1 day)"
    }
  }

  action = jsonencode({
    actionType = "create:task"
    task = {
      agent = "custom:${awscc_devopsagent_asset.example_custom_agent.asset_id}"
    }
  })

  status = "Active"
}

output "skill_asset_id" {
  description = "The skill asset ID"
  value       = awscc_devopsagent_asset.example_skill.asset_id
}

output "custom_agent_asset_id" {
  description = "The custom agent asset ID"
  value       = awscc_devopsagent_asset.example_custom_agent.asset_id
}

output "trigger_id" {
  description = "The trigger ID"
  value       = awscc_devopsagent_trigger.daily.trigger_id
}

これをサンプルリポジトリに追加する場合は、 agent_space_id変数を宣言する代わりに、エージェントスペースリソースを直接参照できます。

ステップ 2: デプロイする

パート 1 出力agent_space_idの値を使用してterraform.tfvars、 でエージェントスペース ID を設定します。

agent_space_id = "<AGENT_SPACE_ID>"

以下のとおり設定を適用します。

terraform apply

アセットの agent_space_idおよび 引asset_type数は、トリガーの agent_space_id、type、condition、 action引数と同様に、作成専用です。いずれかを変更すると、リソースが置き換えられます。トリガーの status (Active または Inactive) を所定の位置に更新できます。 に設定するとInactive、トリガーを削除せずに一時停止できます。

ステップ 3: デプロイを検証する

アセットとトリガーが作成されたことを確認するには、次の AWS CLI コマンドを実行します。

aws devops-agent list-assets \
  --agent-space-id <AGENT_SPACE_ID> \
  --region <REGION>

aws devops-agent list-triggers \
  --agent-space-id <AGENT_SPACE_ID> \
  --region <REGION>

既存の IAM ロールの使用 (オプション)

デフォルトでは、Terraform 設定はエージェントスペースとオペレーターアプリの新しい IAM ロールを作成します。必要なポリシーを持つ IAM ロールがすでにある場合は、ロールの作成をスキップし、代わりに既存のロール ARNs を指定できます。

要件

既存のロールは、次の要件を満たしている必要があります。

エージェントスペースロール

オペレーターアプリロール

設定

でterraform.tfvars、1 つまたは両方のロール ARNs を設定します。

existing_agentspace_role_arn = "arn:aws:iam::ACCOUNT_ID:role/YourAgentSpaceRole"
existing_operator_role_arn   = "arn:aws:iam::ACCOUNT_ID:role/YourOperatorRole"

これらの値を設定すると、 の対応するロールリソースiam.tfはスキップされます。このアプローチは完全に下位互換性があります。空の値 (デフォルト) を持つ既存の設定は、現在のロール作成動作を保持します。

トラブルシューティング

IAM 伝達の遅延

ServiceNow instanceId does not match エラー

Dynatrace の関連付け status: invalid

アクセス許可エラー

クロスアカウントデプロイが失敗する

Terraform リソースタイプが見つかりません

クリーンアップ

パート 4 を完了したら、まずスキル、カスタムエージェント、トリガーを削除します。これらのリソースを別のスタックに配置する AWS CDK ガイドとは異なり、 assets.tfは同じ Terraform 設定の一部であるため、プレーンはエージェントスペースをそれらと一緒にterraform destroy削除します。変更を削除assets.tfして適用し、パート 4 リソースのみを削除します。

rm assets.tf
terraform apply

ファイルを保持するには、代わりに 3 つのリソースをターゲットにします。

terraform destroy \
  -target=awscc_devopsagent_trigger.daily \
  -target=awscc_devopsagent_asset.example_custom_agent \
  -target=awscc_devopsagent_asset.example_skill

これらのリソースのみを削除すると、エージェントスペースはそのまま残ります。他のユーザーと共有しているエージェントスペース、またはパート 1 で作成していないエージェントスペースにパート 4 を適用した場合は、これを行います。

次に、パート 2 をデプロイした場合は、他のすべてを削除するには、逆の順序で破棄します。

./cleanup.sh

または、手動で以下を実行します。

terraform destroy

警告: これにより、エージェントスペースと関連するすべてのデータが完全に削除されます。続行する前に、重要な情報をバックアップしていることを確認してください。

セキュリティに関する考慮事項

次の手順

Terraform を使用して AWS DevOps エージェントをデプロイした後:

その他のリソース