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

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

概要

このガイドでは、 AWS クラウド開発キット (AWS CDK) を使用して AWS DevOps エージェントリソースを作成およびデプロイする方法を示します。 AWS CDK アプリケーションは、 AWS CloudFormation を通じてエージェントスペース、 AWS Identity and Access Management (IAM) ロール、オペレーターアプリ、および AWS アカウントの関連付けの作成を自動化します。

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

AWS DevOps エージェントは複数の AWS リージョンで使用できます。利用できるタイムゾーンの一覧については、「サポートされるリージョン」を参照してください。

前提条件

作業を開始する前に、以下の準備が整っていることを確認します。

npm install -g aws-cdk

このガイドの内容

このガイドは、以下のパートに分かれています。

作成されるリソース

パート 1: DevOpsAgentStack (モニタリングアカウント)

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

パート 3: アセットとトリガー (モニタリングアカウント、オプション)

このスタックは、次のリソースを作成します。

セットアップ

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

次のコマンドを実行してリポジトリのクローンを作成し、プロジェクトディレクトリに変更します。

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

ステップ 2: 依存関係をインストールする

次のコマンドを実行して、プロジェクトの依存関係をインストールします。

npm install

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

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

ステップ 1: モニタリングアカウント ID を設定する

を開きlib/constants.ts、モニタリングアカウント ID を設定します。

次の例は、更新する定数を示しています。

export const MONITORING_ACCOUNT_ID = "<YOUR_MONITORING_ACCOUNT_ID>";

ステップ 2: AWS CDK 環境をブートストラップする

モニタリングアカウントで AWS CDK をブートストラップしていない場合は、次のコマンドを実行します。

cdk bootstrap aws://<MONITORING_ACCOUNT_ID>/<REGION> --profile monitoring

ステップ 3: ビルドとデプロイ

次のコマンドを実行して TypeScript コードを構築し、スタックをデプロイします。

npm run build
cdk deploy DevOpsAgentStack --profile monitoring

ステップ 4: スタック出力を記録する

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

次の例は、予想される出力を示しています。

Outputs:
DevOpsAgentStack.AgentSpaceArn = arn:aws:aidevops:<REGION>:123456789012:agentspace/abc123
DevOpsAgentStack.AgentSpaceRoleArn = arn:aws:iam::123456789012:role/DevOpsAgentRole-AgentSpace
DevOpsAgentStack.OperatorRoleArn = arn:aws:iam::123456789012:role/DevOpsAgentRole-WebappAdmin
DevOpsAgentStack.AssociationId = assoc-xyz

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

スタックは、エージェントスペース ID ではなく、エージェントスペース ARN を出力します。後のステップでは、ARN の の後のセグメントである ID agentspace/を要求します。前の例では、ARN は で終わるためagentspace/abc123、エージェントスペース ID は ですabc123。その値も記録します。

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

エージェントスペースが正常に作成されたことを確認するには、次の AWS CLI コマンドを実行します。

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

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

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

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

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

を開きlib/constants.ts、サービスアカウント ID を設定します。

次の例は、更新する定数を示しています。

export const SERVICE_ACCOUNT_ID = "<YOUR_SERVICE_ACCOUNT_ID>";

DevOpsAgentStack は、このアカウント ID を使用してソース AWS の関連付けを作成します。この値を設定する前に DevOpsAgentStack をデプロイした場合は、再デプロイして関連付けを作成します。

次のコマンドを実行して再デプロイします。

npm run build
cdk deploy DevOpsAgentStack --profile monitoring

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

DevOpsAgentStack 出力 (パート 1、ステップ 4) からAgentSpaceArn値をコピーし、 で設定しますlib/constants.ts。

次の例は、更新する定数を示しています。

export const AGENT_SPACE_ARN = "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/<SPACE_ID>";

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

ステップ 3: サービスアカウントをブートストラップする

サービスアカウントで AWS CDK をブートストラップしていない場合は、次のコマンドを実行します。

cdk bootstrap aws://<SERVICE_ACCOUNT_ID>/<REGION> --profile service

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

次のコマンドを実行して、サービスアカウントの認証情報を使用して ServiceStack を構築およびデプロイします。

npm run build
cdk deploy ServiceStack --profile service

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

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

Lambda 関数が正常にデプロイされたことを確認するには、次のコマンドを実行してエコーサービスをテストします。

aws lambda invoke \
  --function-name echo-service \
  --payload '{"test": "hello world"}' \
  --profile service \
  response.json
cat response.json

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

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

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

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

ステップ 1: コンテンツスタックを作成する

次の内容で、lib/content-stack.ts という名前のファイルを作成します。時間ベースのトリガーのアクションは、カスタムエージェントをアセット ID で 形式で参照しますcustom:<assetId>。スタックは、カスタムエージェントの attrAssetId 属性の値を使用して、このリファレンスを自動的にワイヤリングします。カスタムエージェントskillsのリストは名前ではなくアセット IDs も取得するため、スキルの を使用しますattrAssetId。これにより、スタックに暗黙的な依存関係が与えられるため、スキルはアタッチするエージェントの前に作成されます。

import * as cdk from 'aws-cdk-lib';
import { CfnAsset, CfnTrigger } from 'aws-cdk-lib/aws-devopsagent';
import { Construct } from 'constructs';

export interface ContentStackProps extends cdk.StackProps {
  readonly agentSpaceId: string;
}

export class ContentStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props: ContentStackProps) {
    super(scope, id, props);

    // A skill the agent loads when relevant
    const skill = new CfnAsset(this, 'ExampleSkill', {
      agentSpaceId: props.agentSpaceId,
      assetType: 'skill',
      metadata: {
        name: 'rds-performance-investigation',
        description: 'Investigation procedures for RDS performance issues.',
        agent_types: ['GENERIC'],
      },
      files: [
        {
          path: 'SKILL.md',
          contentText: [
            '# RDS Performance Investigation',
            'Use this skill when investigating database latency, connection',
            'errors, or query timeouts.',
          ].join('\n'),
        },
      ],
    });

    // A custom agent with attached skills that a trigger can invoke
    const customAgent = new CfnAsset(this, 'ExampleCustomAgent', {
      agentSpaceId: props.agentSpaceId,
      assetType: 'custom_agent',
      metadata: {
        name: 'rds-firefighter',
        skills: [skill.attrAssetId],
      },
      files: [
        {
          path: 'AGENT.md',
          contentText: ['# RDS Firefighter', 'Custom agent for RDS incidents.'].join('\n'),
        },
      ],
    });

    // A time-based trigger that runs the custom agent on a schedule
    const dailyTrigger = new CfnTrigger(this, 'DailyTrigger', {
      agentSpaceId: props.agentSpaceId,
      type: 'TIME_BASED',
      condition: {
        schedule: {
          expression: 'rate(1 day)',
        },
      },
      action: {
        actionType: 'create:task',
        task: {
          agent: `custom:${customAgent.attrAssetId}`,
        },
      },
      status: 'Active',
    });

    new cdk.CfnOutput(this, 'SkillAssetId', {
      description: 'The skill asset ID',
      value: skill.attrAssetId,
    });
    new cdk.CfnOutput(this, 'CustomAgentAssetId', {
      description: 'The custom agent asset ID',
      value: customAgent.attrAssetId,
    });
    new cdk.CfnOutput(this, 'TriggerId', {
      description: 'The trigger ID',
      value: dailyTrigger.attrTriggerId,
    });
  }
}

ステップ 2: AWS CDK アプリにスタックを追加する

アプリのエントリポイント ( などbin/app.ts) で、スタックをインスタンス化し、パート 1、ステップ 4 で記録したエージェントスペース ID を渡します。完全なAgentSpaceArn値ではなくabc123、 などの ID を使用します。

new ContentStack(app, 'ContentStack', {
  env: { account: MONITORING_ACCOUNT_ID, region: process.env.CDK_DEFAULT_REGION },
  agentSpaceId: '<AGENT_SPACE_ID>',
});

ステップ 3: スタックをデプロイする

次のコマンドを実行して、モニタリングアカウントの認証情報を使用してスタックを構築およびデプロイします。

npm run build
cdk deploy ContentStack --profile monitoring

アセットの agentSpaceIdおよび assetTypeプロパティは、トリガーの agentSpaceId、type、condition、 actionプロパティと同様に、作成専用です。いずれかを変更すると、リソースが置き換えられます。トリガーの status (Active または Inactive) を所定の位置に更新できます。 に設定するとInactive、トリガーを削除せずに一時停止できます。他のアセットタイプと完全なプロパティリファレンスの詳細については、「」を参照してくださいアセットの管理。

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

アセットとトリガーが作成されたことを確認するには、次の 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>

トラブルシューティング

このセクションでは、一般的な問題とその解決方法について説明します。

CfnAsset または CfnTrigger は からエクスポートされません aws-cdk-lib/aws-devopsagent

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

IAM ロールの作成に失敗しました

クロスアカウントデプロイが「ターゲットアカウントでロールを引き受けることができませんでした」で失敗する

IAM 伝達の遅延

クリーンアップ

すべてのリソースを削除するには、スタックを逆の順序で破棄します。

スタックを破棄するには、次のコマンドを実行します。

# If you deployed the Part 3 ContentStack, destroy it first
cdk destroy ContentStack --profile monitoring
# If you deployed the ServiceStack, destroy it next
cdk destroy ServiceStack --profile service
# Then destroy the DevOpsAgentStack
cdk destroy DevOpsAgentStack --profile monitoring

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

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

次の手順

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

その他のリソース