AWS DevOps Agentのセカンダリリソース登録のステータス遷移を検証してみた
こんにちは。クラウド事業統括本部コンサルティング1部の桑野です。
皆さんはマルチアカウント環境のベースライン構築で、作業をひととおり終えたあとに「あれもやらないといけなかった」と戻る羽目になったことはありませんか？
私はあります。
AWS DevOps Agent でセカンダリリソース（他アカウント）を登録する場合、公式ドキュメントの手順は「セカンダリアカウント側で IAM ロールを作る」→「プライマリアカウントで登録する」という順序で書かれています。
ただ、クロスアカウントロールを StackSets で展開している場合、この順序だと困る場面があります。新規アカウントをセットアップ用の OU に作成し、ベースライン構築を終えてから本来の OU へ移動する、という運用をしているケースです。ロールが展開されるのは OU 移動のタイミングなので、ベースライン構築の作業中にはまだロールが存在しません。
そこで「先に登録だけ済ませておいて、ロールは後から用意する」という逆順が成立しないか検証してみました。
結果として、ステータスの遷移について公式ドキュメントに書かれていない挙動がいくつか見つかったので共有します。
前提
エージェントスペースがすでに作成済みであることを前提としています。作成手順は公式ドキュメントをご参照ください。
セカンダリリソースの追加については、すでに以下の記事で詳しく紹介されています。StackSets で IAM ロールを展開し、AWS CLI でまとめて登録するという流れで、本記事で想定している構成とほぼ同じです。
こちらはロールを展開したあとに登録する流れになっていますが、本記事ではその逆順、つまりロール展開前に登録を済ませておけるかを検証しています。
なお、本記事で扱うステータス遷移の挙動は公式ドキュメントでは確認ができませんでした。
（自分の探し方が悪いだけかもしれませんが。。。）
2026年8月19日時点での検証結果である点にご注意ください。
背景・課題
AWS Organizations でマルチアカウント環境を運用している場合、新規アカウントを払い出したあとにベースラインを構築する流れが発生します。クロスアカウントロールの展開に StackSets を使い、対象の OU へアカウントを移動したタイミングで自動展開される、という構成はよく見られるかと思います。
ここで問題になるのが、新規アカウントを一時的にセットアップ用の OU に作成しておき、ベースライン構築が終わってから本来の OU へ移動するというパターンです。
この場合、作業の順序はこうなります。
- セットアップ用 OU に新規アカウントを作成する
- ベースライン構築の作業を行う
- 本来の OU へ移動する → ここで StackSets によりクロスアカウントロールが展開される
クロスアカウントロールが用意されるのは 3 のタイミングです。つまり、2 の作業中にはまだロールが存在しません。
セカンダリリソースの登録を 2 に含めたくても、公式ドキュメントの手順どおりならロールが先に必要なので登録できません。結果として、3 が終わったあとにあらためて登録作業だけをしに戻ることになります。
ベースライン構築の作業をひととおり 2 で完結させたいのに、セカンダリリソースの登録だけが後工程に取り残されてしまうわけです。
これを避けたい理由は、単にアカウントを切り替える手間だけではありません。
作業が複数のアカウントにまたがると、いま自分がどのアカウントで作業しているのかを常に意識し続ける必要があります。そして意識が途切れたとき、意図しないアカウントで操作してしまうリスクがあります。
作業をひとつのフェーズに閉じ込められるなら、そのぶん考えることが減り、事故の余地も小さくなります。手数を減らすこと以上に、こちらのほうが重要だと考えています。
そこで、2 の時点で登録まで済ませてしまえないかと考えました。ロールがなくても登録だけ先に通しておければ、あとは OU を移動するだけで完結するはずです。
当然、ロールがない状態で登録するのでステータスは「保留中」になります。問題は、その保留中がどう解消されるのかです。ロールを後から用意したときに自動で有効になるのか、それとも何らかの操作が必要なのか。ここが分からないと、結局あとで確認しに戻ることになり、行き来を減らすという当初の目的が達成できません。
セカンダリリソースのステータスについて
検証に入る前に、ステータスの種類を整理しておきます。
マネジメントコンソール上では「有効」「無効」「保留中」の3つが表示されます。API のレスポンスでは以下の3値です。
| コンソール表示 | API レスポンス（status） |
意味 |
|---|---|---|
| 有効 | valid |
ロールの検証に成功している |
| 無効 | invalid |
検証に失敗している（ロールがない等） |
| 保留中 | pending-confirmation |
まだ検証されていない |
この enum は boto3 のドキュメントで確認できました。
また、検証を実行するための専用 API も用意されています。
こちらは「Validates an aws association and set status」と説明されており、検証してステータスを更新するという役割です。パラメータは agentSpaceId のみで、成功時は 204 No Content が返ります。個別のアソシエーションを指定するのではなく、AgentSpace 単位でまとめて検証する形になっている点は覚えておくと良さそうです。
検証1: ロール展開前に登録するとどうなるか
まず、クロスアカウントロールを用意していない状態でセカンダリリソースとして登録してみました。
想定どおり「保留中」になりました。登録自体は受け付けられています。
この状態で、エージェントは対象アカウントを認識できるのでしょうか。AgentSpace で聞いてみます。
残念ながら、xxxxxxxxxxxx はアソシエーションに登録されていないでヤンス…！
登録されていない、と言われてしまいました。コンソール上では確かに保留中として存在しているのに、エージェントからは見えていません。
念のため、登録されているはずだと伝えて再確認してもらいます。
うーん、何度確認しても xxxxxxxxxxxx は取得できていないでヤンス…。
エージェント自身も原因を推測してくれています。
- 保留中ステータスのアソシエーションは API で返ってこない仕様の可能性
- 登録処理がまだ完了していない（UI には表示されているが、バックエンドへの反映が遅延している）
- 別の AgentSpace に登録されている可能性
スクリーンショットを見せて確認してもらったところ、こう返ってきました。
自分の API 側からは「保留中」のアソシエーションは valid として返ってこないため、見えていない状態でヤンス。
保留中の状態では、エージェントは対象アカウントの存在すら認識できないことが分かりました。
これは運用上けっこう困りそうです。エージェントに「このアカウント見えてる？」と聞いても「登録されていない」と返ってくるため、作業者が登録し忘れたのか保留中なのかの区別がつきませんね。。。
検証2: 保留中の状態で検証を実行する
では、保留中をどう解消するか。コンソールのセカンダリリソース一覧で対象を選択し、「アクション」から検証を実行してみます。
画面上部に「Associations validated successfully」と表示されました。検証処理自体は成功しています。
その一方で「クラウドアカウントが無効です」というエラーも同時に出ています。一覧を見ると、対象アカウントのステータスが保留中から無効に変わりました。
紛らわしいのですが、この2つのメッセージは似ているようで若干異なります。検証処理は正常に完了しており、検証した結果ロールがなかったので無効と判定された状態であると言えますね。
一方で、保留中のステータスは検証を行う前の状態ということがわかります。
つまりこうなります。
- 保留中 + 有効なロールあり → 有効
- 保留中 + 有効なロールなし → 無効
ロール展開前に検証を実行しているので、当然ながら後者になりました。
検証3: 無効の状態はエージェントから見えるのか
無効になった状態で、あらためてエージェントに聞いてみます。
ズバリそのとおりでヤンス！
アカウント xxxxxxxxxxxx は AgentSpace にアソシエーション登録されてはいるでヤンスが、ステータスが invalid になってるでヤンス。
今度は認識してくれました。一覧にも invalid として表示されています。
保留中のときは存在すら見えなかったのに、無効になると見えるようになりました。保留中と無効では、エージェントからの可視性が違うということが言えそうです。
エージェントから見えるということは、エージェントに対して「このアカウントにアクセスできるか確認して」と調査依頼ができるということだと考えて良いですね。
検証4: ロールを用意したあと、どうすれば有効になるか
対象アカウントにクロスアカウントロールを作成しました。この状態で数分待ってみましたが、ステータスは無効のままでした。
そこで、エージェントに疎通確認を依頼してみました。
やったでヤンス！🎉 アクセス成功でヤンス！
DevOpsAgentRole-SecondaryAccountへの AssumeRole が正常に通ったでヤンス。
エージェントは sts.get_caller_identity を呼び出して、AssumeRole が通ることを確認してくれました。
このときエージェントは「AgentSpace のアソシエーションステータスはまだ invalid と表示されたままかもしれない」と言っていたのですが、コンソールを確認するとこうなっていました。
有効に変わっていました。
ステータスが変わった仕組みについて
気になったので、エージェントに何をしたのか聞いてみました。
実は私が呼び出したのは STS の
GetCallerIdentityだけでヤンス。専用の「validate エンドポイント」を呼んだわけではないでヤンス。
エージェント自身は検証 API を呼んでいないとのことです。
さらに validate_aws_associations を呼べないか聞いてみたところ、こう返ってきました。
うーん、残念ながら
validate_aws_associationsというツールは自分のツールレジストリには存在しないでヤンス…。
自分が現在アソシエーション関連で呼べる操作は 一覧取得 と 詳細取得 のみでヤンスね。
エージェントはアソシエーションの検証・有効化を実行できません。読み取り系の操作しか持っていないということです。
では何がステータスを更新したのか。エージェントの推測はこうでした。
おそらくマネコン側で「Association の状態を確認する操作」（ページ表示・リロード等）が行われた際に、バックエンドで
validate_aws_associationsが呼ばれ、その検証結果としてステータスが更新されたと考えられるでヤンス。
コンソールを開いたタイミングで検証が走った、という説です。
ここは現段階では私も断定できないなと考えています。確実に言えるのは「ロールを用意したあと、エージェントに疎通確認させ、コンソールを開いたら有効になっていた」という結果までです。残念ながら因果関係の特定には至っていないです。
ただ、運用上は「無効の状態からロールを用意すれば有効にできる」ことが確認できれば十分なので、ここでは深追いしないことにします。とても気になる部分ではありますね。
発見したこと
検証1でエージェントが「保留中は API で返ってこない仕様かもしれない」と推測していた件、気になったので AWS CLI で直接確認してみました。
別のアカウント（xxxxxxxxxxxx）を新たに保留中の状態で登録して、3つの経路から見比べます。
まずコンソールの表示です。
保留中として表示されています。
次に AWS CLI で一覧を取得します。
aws devops-agent list-associations \
--agent-space-id c97984cf-4ffa-4301-a61e-8de117495140 \
--region ap-northeast-1
結果がこちらです。
{
"agentSpaceId": "c97984cf-4ffa-4301-a61e-8de117495140",
"createdAt": "2026-08-19T05:49:06.572000+00:00",
"updatedAt": "2026-08-19T05:49:06.572000+00:00",
"status": "pending-confirmation",
"associationId": "e0c5e87d-bd37-40ba-935f-d7928ac0eb04",
"serviceId": "aws",
"configuration": {
"sourceAws": {
"accountId": "xxxxxxxxxxxx",
"accountType": "source",
"assumableRoleArn": "arn:aws:iam::xxxxxxxxxxxx:role/DevOpsAgentRole-AgentSpace-316xqi11"
}
}
}
普通に返ってきました。 pending-confirmation として、ロール ARN まで含めて記録されています。createdAt と updatedAt が同一なのは、登録以降まだ一度も検証されていないことを示しています。
最後に、同じタイミングでエージェントに聞いてみます。
ご質問のアカウント xxxxxxxxxxxx のアソシエーションは、現在の一覧には見当たらないでヤンス…！
エージェントの一覧には出てきません。
整理するとこうなります。
| 経路 | 保留中のアソシエーション |
|---|---|
| マネジメントコンソール | 表示される |
AWS CLI（list-associations） |
pending-confirmation で返ってくる |
| AgentSpace のエージェント | 一覧に出てこない |
API 側の制約ではなく、エージェントに渡されているツールが valid のみに絞っていると考えられます。
エージェントは検証1の時点で「ページネーションで取りこぼした」「バックエンドへの反映が遅延している」「別の AgentSpace に登録されている」と3つの可能性を挙げていましたが、いずれも実際の原因ではありませんでした。エージェント自身も、自分に見えていない範囲がなぜ見えないのかは分からないということですね。
エージェントの回答を鵜呑みにするのは結構危険だなと感じました。
念の為 CLI で確認しておく方が良さそうです。
ステータス遷移のまとめ
今回の検証で分かったステータスの遷移をまとめます。
[未登録]
│
│ セカンダリリソースとして登録
▼
[保留中 / pending-confirmation] ← エージェントからは見えない
│
│ 検証を実行（コンソール or validate-aws-associations）
│
├─ 有効なロールあり ──▶ [有効 / valid]
│
└─ 有効なロールなし ──▶ [無効 / invalid] ← エージェントから見える
│
│ ロールを用意して再検証
▼
[有効 / valid]
ポイントは以下の3点です。
- 保留中は、検証を一度実行しないと先に進まない
- 保留中と無効では、エージェントからの可視性が異なる
- 無効からでも、ロールを用意して再検証すれば有効になる
運用への落とし込み
冒頭の課題に戻ります。「ベースライン構築の作業をひとつのフェーズに閉じ込めたい」という目的に対して、今回の検証結果をどう使えるか。
私が考えたのは以下の手順です。
ベースライン構築の作業中（セットアップ用 OU にいる状態）
- ロール展開前にセカンダリリソースとして登録する → 保留中になる
- そのまま検証を実行して無効まで進めておく → 無効になる
作業完了後
- 本来の OU へ移動する → StackSets でロールが展開される
セカンダリリソースの登録がベースライン構築の作業に収まるので、OU 移動後に登録だけをしに戻る必要がなくなります。作業対象のアカウントを意識し分ける場面が減るぶん、操作ミスの余地も小さくできます。展開後にステータスを有効へ更新したい場合は、任意のタイミングで再検証すれば済みます。
ポイントとなるのは 2 です。保留中のまま放置せず、登録直後に検証を一度走らせて無効の状態にしておきます。
これによって何が変わるかというと、エージェントから対象アカウントの存在が見えるようになります。保留中のままだとエージェントは存在すら認識できないため、状況確認の手段がコンソールを開くことに限られてしまいます。無効まで進めておけば、エージェントに状態を聞けるようになります。
検証の実行は CLI でも可能です。
aws devops-agent validate-aws-associations \
--agent-space-id <AGENT_SPACE_ID> \
--region ap-northeast-1
前述のとおり AgentSpace 単位でまとめて検証されるため、対象を個別に指定することはできません。他のアソシエーションも同時に再検証される点は認識しておく必要があります。
AgentSpace ID が分からない場合は以下で確認できます。
aws devops-agent list-agent-spaces --region ap-northeast-1
ステータスの確認も CLI で完結します。
aws devops-agent list-associations \
--agent-space-id <AGENT_SPACE_ID> \
--region ap-northeast-1 \
--query 'associations[].{account:configuration.sourceAws.accountId,status:status}' \
--output table
なお、StackSets の展開自体に不安がないケース（他アカウントでの展開実績が十分にある場合）であれば、展開結果の確認そのものを省略する余地があるかと思っています。
セカンダリリソースの登録に必要な IAM ロールを展開するぐらいの内容であれば、失敗の可能性も低いと考えて私は省略する運用で問題ないと判断しています。
注意点
検証を進める中で気づいた点がいくつかありました。
本記事の挙動は公式ドキュメントに記載がありません
ステータスの enum は API リファレンスで確認できますが、遷移の条件や、保留中がエージェントから見えないという挙動はドキュメントでは確認できませんでした。2026年8月19日時点での検証結果としてご理解ください。
「無効から有効になった」仕組みは特定できていません
前述のとおり、エージェントの疎通確認とコンソール表示のどちらがトリガーになったのかは切り分けられていません。確実なのは「無効の状態からロールを用意すれば有効にできる」という結果までです。
まとめ
AWS DevOps Agent のセカンダリリソース登録について、ロール展開前に登録する逆順が成立するかを検証しました。
結論として、成立します。ただし登録しただけの保留中の状態では、エージェントから対象アカウントの存在が見えません。登録直後に検証を一度実行して無効まで進めておくことで、エージェントから状態を確認できるようになり、後からロールを展開して有効化する流れが取れます。
検証の途中で「保留中は API でも見えないのでは」という仮説が出ましたが、CLI で確認したところ pending-confirmation として普通に返ってきました。エージェントに見えていなかったのは、エージェント側のツールが絞り込んでいたためと考えられます。エージェントの回答も、疑わしいときは一次情報にあたるのが大事だなとあらためて思いました。
セカンダリリソースのステータスまわりで同じような疑問を持った方の参考になれば幸いです。
最後までご覧いただきありがとうございました。
