CreateBacklogTask API経由でAWS DevOps Agentのインシデントレスポンス調査を開始する

少し前に↓の記事でAWS DevOps Agentのインシデントレスポンス調査をWebhook経由で起動する検証をしました。

「API経由で自動調査できたらなああ」と思って調べていたら、API経由で出来ることがわかりました。それも結構前からできるそうでした。（情報感度低い）
API経由のほうがシークレット管理が無くIAM権限で呼び出しが出来るため運用上良いと思います。この記事では、API経由でDevOps Agentの自動調査を開始してみます。

API経由でDevOps Agentの呼び出し方

CreateBacklogTask というAPIを呼び出して調査を起動します。
agentSpaceId、taskType、title、priority の4つが必須で、taskType に INVESTIGATION を指定すれば良いです。
その他項目は以下です。ドキュメントから抜粋して要約しています。

項目	内容	必須	その他
agentSpaceId	タスクが作成されるエージェントスペースの一意の識別子	必須	パターン：[a-zA-Z0-9-]{1,64}
clientToken	冪等操作のためのクライアント提供トークン	任意	指定しない場合は SDK が自動生成
description	タスクの詳細な説明	任意	長さの制約：最小長さは0、最大長さは10000
priority	タスクの優先度レベル	必須	有効な値: CRITICAL, HIGH, MEDIUM, LOW, MINIMAL
reference	タスクに関するオプションの参考情報	任意	渡すなら system, referenceId, referenceUrl, associationId が必須。title だけ任意（参考URL）
taskType	タスクの種別	必須	有効な値: INVESTIGATION, EVALUATION, RELEASE_READINESS_REVIEW, RELEASE_TESTING
title	タスクのタイトル	必須	長さの制約：最小長さは1、最大長さは400

検証環境の構成

CloudWatchAlarm→EventBridgeで検知→Lambda→DevOps Agentという流れで検証します。過去Webhookで検証した時と同じ環境を用意しています。
DevOps Agentの呼び出しをAPI経由に変更したことだけが前回検証時と異なります。環境の詳細などは過去記事を確認ください。

DevOps AgentをAPI経由で起動するLambda関数作成

EventBridgeのターゲットにLambda関数を設定します。次のコードでLambda関数を設定しています。
EventBridgeから届いたイベントをDevOps Agentに渡します。

"""CloudWatch アラームの状態変化を DevOps Agent の investigation に変換する。

EventBridge から届いたアラームイベントを CreateBacklogTask の引数に組み替えて呼ぶ。
"""

import json
import os

import boto3

AGENT_SPACE_ID = os.environ["AGENT_SPACE_ID"]

client = boto3.client("devops-agent")

def handler(event, context):
    print(json.dumps({"level": "INFO", "message": "received alarm event", "event": event}))

    detail = event["detail"]

    payload = {
        "agentSpaceId": AGENT_SPACE_ID,
        "taskType": "INVESTIGATION",
        "title": "CloudWatch Alarm: " + detail["alarmName"],
        "priority": "HIGH",
        "description": detail["state"]["reason"] + "\n\n" + json.dumps(event, indent=2),
    }

    response = client.create_backlog_task(**payload)

    print(json.dumps({
        "level": "INFO",
        "message": "task created",
        "task": response["task"],
    }, default=str))

API経由で自動調査の起動

CloudWatchアラームを意図的に発生させ、自動調査を開始します。

API経由でDevOps Agentを起動させるためのLambda関数のログには、指定した agentSpaceId や title に加えて、APIが返した taskId と executionId が入っていることが確認できます。

DevOps Agent側でも自動調査の開始が確認できました。過去記事と同じ構成で実施したのですが、調査結果に「過去の medaka-prod-order-notifier と同一パターンのIaC設定ミス」と書かれていて、前回の検証を憶えていました。前回の環境はすでに削除済みで、リソース名も変えてあるのですが、それでも同じ結論（sns:Publish 権限が不足）を指摘してくれました。

CreateBacklogTaskはLambdaレイヤー不要

AWSのre:Post記事に、EventBridgeからLambdaで CreateBacklogTask を呼ぶ構成が記載されています。
ほぼ今回と同じ構成なので参考にしたのですが、気になる注記がありました。

Note: At time of publication, the Python 3.13 Lambda runtime includes boto3 1.40.x, which doesn't include the devops-agent service client.（注: 公開時点では、Python 3.13 Lambda ランタイムには boto3 1.40.x が含まれていますが、これには devops-agent サービス クライアントは含まれていません。新しいLambda レイヤーを作成するには、次のコマンドを実行してください。）

Lambdaのマネージドランタイムに同梱されているboto3には devops-agent のクライアントが入っていないので、レイヤーで新しいboto3を持ち込む必要があるという話です。今回検証で使ったのはpython3.12で、3.13より古いので入っていないと思っていました。
ですが、レイヤー無しでそのまま動きました。python3.12のランタイム同梱のboto3で create_backlog_task が通っています。

ランタイムに同梱されるboto3はAWS側が随時更新しているために、re:post記事の執筆時点と今で中身が違うのだと思います。

この手の但し書きは執筆時点のものなので、レイヤーを用意する前に一度そのまま叩いてみるのが早いです。「このサービスは対応していないよー」という形のエラーが出たらレイヤーを足せば良いと思います。

DevOps Agentの新しいUI

インシデントレスポンスに「サマリー（プレビュー）」という項目が増えていました。
「インシデント概要」、「根本的な原因」、「緩和措置」という３項目で簡潔にまとめられていて見やすいのがGOODです！タイムラインなどは特に長くなって見づらいのでまとまって見やすいのは良きですね。

WebhookとAPI呼び出しどちらが良いか

個人的にはAPI呼び出しを推奨します。理由は管理するものが減るからです。
Webhookの場合にはWebhookURLやシークレット管理が必要で、そのためのSecretManagerやローテーションなどの手間が考えられます。その一方でIAM権限でアクセス制御出来るAPIの場合は手間が少なくなります。

また、Webhookはコンソール作業も必要です。過去記事を見るとわかりますが、WebhookURLとシークレットはDevOps Agentコンソールから発行しました。本番運用でIaC管理などが前提の場合、一部手作業が入ることになります。この点、API経由呼び出しの場合はIaCでIAMロールを書けば良く、手作業が減ります。

AWSドキュメントでのWebhook記述

AWSドキュメントには、Webhookを使うと外部システムとの連携がしやすくなるような文言が記載されていました。DatadogやNewRelic、Slackといった外部サービスとの連携がしたい場合はWebhookを使うと良いのかもしれません。

Webhook を使用すると、外部システムが AWS DevOps エージェント調査を自動的にトリガーできます。これにより、インシデントが発生したときに HTTP リクエストを送信できるチケットシステム、モニタリングツール、その他のプラットフォームとの統合が可能になります。

まとめ

API経由でDevOps Agentを呼び出すことができました。AWS内で完結するならAPI経由でDevOps Agentを呼び出す構成が良いと思います。ただ、どの構成（Webhook・API）であってもDevOps Agentを起動するためのLambda関数が必要です。運用者目線ではなるべくマネージドサービスを使いたいので、今後EventBridgeから直接API呼び出しできるようになることを待ちたいと思います！

StepFunctionsからは呼び出せそう

気になって調べてみたらStepFunctionsからはAPI呼び出しできそうでした！

CreateBacklogTaskもStepFunctionsでサポートされていたので試してみたいです！そのうちEventBridgeにも来るでしょう！