
CloudFormation StackSets の操作の進捗が ステージ別・リージョン別に確認可能になったので試してみた
はじめに
2026年11月19日、AWS CloudFormation StackSets の操作の進捗を、ステージ別・リージョン別に確認できるようになりました。
この記事では、AWS CLI で操作の進捗を実行中と完了後に取得し、返ってくる項目と値の動きを確認します。
検証環境
- StackSet: self-managed(管理アカウントと対象アカウントは同じ)
- リージョン: ap-northeast-1、us-east-1、us-west-2
- リージョンの処理: 1つずつ順番に(
RegionConcurrencyType=SEQUENTIAL) - 同時に処理するアカウント数の上限: 1(
MaxConcurrentCount=1) - AWS CLI: 2.41.2
本文の時刻は JST です(API の出力は UTC)。
準備
操作を待機させるテンプレート
進捗の値が途中で変わる様子を見るため、操作が数分間実行中のままになるテンプレートを使います。DNS 検証を指定した ACM 証明書を1つだけ持つテンプレートで、ドメインのホストゾーンが対象アカウントの Route 53 に無いと、検証用の CNAME を追加するまでスタックは CREATE_IN_PROGRESS のまま待機します。
今回のドメインのホストゾーンは別のアカウントにあり、テンプレートに DomainValidationOptions は指定していません。操作ごとに別のサブドメインを使いました。
acm-wait.yaml として保存します。
AWSTemplateFormatVersion: '2010-09-09'
Parameters:
DomainName:
Type: String
Resources:
Certificate:
Type: AWS::CertificateManager::Certificate
Properties:
DomainName: !Ref DomainName
ValidationMethod: DNS
待機を解除するには、証明書の検証用レコードを取得し、管理している DNS に CNAME として追加します。
aws acm describe-certificate \
--certificate-arn <certificate-arn> \
--region ap-northeast-1 \
--query 'Certificate.{Domain:DomainName,Status:Status,Record:DomainValidationOptions[0].ResourceRecord}'
今回は同じドメインの証明書を3リージョンで発行しました。3つの証明書の ResourceRecord は、Name と Value が同じでした。CNAME を1つ追加すると、3つの証明書がすべて ISSUED になりました。
StackSet の作成と操作の開始
self-managed の StackSet には、2つのロールが必要です。管理アカウントの AWSCloudFormationStackSetAdministrationRole と、スタックインスタンスを作る各アカウントの AWSCloudFormationStackSetExecutionRole です。
ドメインは自分が管理するものに置き換えてください。
aws cloudformation create-stack-set \
--stack-set-name progress-demo \
--template-body file://acm-wait.yaml \
--parameters ParameterKey=DomainName,ParameterValue=stacksets-demo.example.com \
--permission-model SELF_MANAGED \
--administration-role-arn arn:aws:iam::123456789012:role/AWSCloudFormationStackSetAdministrationRole \
--execution-role-name AWSCloudFormationStackSetExecutionRole
スタックインスタンスの作成では、進捗が段階的に変わるように、リージョンを1つずつ順番に処理する指定にしました。
aws cloudformation create-stack-instances \
--stack-set-name progress-demo \
--accounts 123456789012 \
--regions ap-northeast-1 us-east-1 us-west-2 \
--operation-preferences RegionConcurrencyType=SEQUENTIAL,RegionOrder=ap-northeast-1,us-east-1,us-west-2,MaxConcurrentCount=1
進捗の見え方
返ってくる項目
進捗は describe-stack-set-operation で取得します。
aws cloudformation describe-stack-set-operation \
--stack-set-name progress-demo \
--operation-id <operation-id>
次は、実行中の応答から StatusDetails 全体と、RegionalStatusDetails の ap-northeast-1 の部分を抜き出したものです。
"StackSetOperation": {
"StatusDetails": {
"Stages": {
"RoleProvisioning": {
"Status": "NOT_APPLICABLE"
},
"StackInstancesDeployment": {
"Status": "IN_PROGRESS",
"SucceededStackInstancesCount": 0,
"FailedStackInstancesCount": 0,
"CompletedStackInstancesCount": 0,
"PendingStackInstancesCount": 3,
"CancelledStackInstancesCount": 0,
"SkippedStackInstancesCount": 0,
"PercentageCompleted": 0.0
}
},
"TotalAccountsCount": 1,
"TotalStackInstancesCount": 3,
"FailedStackInstancesCount": 0
},
"RegionalStatusDetails": {
"ap-northeast-1": {
"Stages": {
"RegionalStackInstancesDeployment": {
"Status": "IN_PROGRESS",
"SucceededStackInstancesCount": 0,
"FailedStackInstancesCount": 0,
"CompletedStackInstancesCount": 0,
"PendingStackInstancesCount": 1,
"CancelledStackInstancesCount": 0,
"SkippedStackInstancesCount": 0,
"TotalStackInstancesCount": 1,
"PercentageCompleted": 0.0
}
}
},
ステージは2つあります。
- RoleProvisioning: service-managed の StackSet で、対象アカウントへのアクセスを準備するステージ
- StackInstancesDeployment: スタックインスタンスをデプロイするステージ
進捗の項目は、ステージ別とリージョン別で次の場所にあります。
| 進捗の場所 | TotalStackInstancesCount | |
|---|---|---|
| ステージ別 | StatusDetails の Stages | StatusDetails の直下 |
| リージョン別 | RegionalStatusDetails の各リージョン配下 | 各リージョンの Stages の中 |
Succeeded や Pending などの件数と PercentageCompleted の項目名は、ステージ別とリージョン別で共通です。
self-managed の操作では、取得したすべての応答で RoleProvisioning の Status は NOT_APPLICABLE でした。
実行中の推移
値が変わった時点だけを抜き出します。各行は約10秒間隔で取得した35回のうちの1回です。
| 採取時刻 | 操作の Status | StackInstancesDeployment(Status / Succeeded / Pending / Completed / PercentageCompleted) | リージョン別 Status |
|---|---|---|---|
| 02:38:47 | RUNNING | NOT_STARTED(件数なし) | RegionalStatusDetails なし |
| 02:38:58 | RUNNING | IN_PROGRESS / 0 / 3 / 0 / 0.0 | 3リージョンとも IN_PROGRESS |
| 02:43:36 | RUNNING | IN_PROGRESS / 1 / 2 / 1 / 33.3 | ap-northeast-1 が SUCCEEDED、他は IN_PROGRESS |
| 02:44:19 | RUNNING | IN_PROGRESS / 2 / 1 / 2 / 66.6 | ap-northeast-1 と us-east-1 が SUCCEEDED、us-west-2 は IN_PROGRESS |
| 02:44:51 | SUCCEEDED | SUCCEEDED / 3 / 0 / 3 / 100.0 | 3リージョンとも SUCCEEDED |
02:38:58 から 02:43:25 までの26回は 0.0 のままでした。この間はドメインの検証待ちで、CNAME を追加した 02:40:41 の約3分後に件数が初めて進みました。
リージョンは1つずつ処理する指定でしたが、件数が初めて返った 02:38:58 の取得では、3リージョンとも IN_PROGRESS、Pending 1、Completed 0 でした。処理中のリージョンは1つだけなので、残りの2つは順番待ちのはずです。ただし、リージョン別の Status と件数からは、どれが処理中かを判別できません。判別するには、list-stack-instances の DetailedStatus を見ます。
aws cloudformation list-stack-instances \
--stack-set-name progress-demo \
--query 'Summaries[].[Region,Status,StackInstanceStatus.DetailedStatus,StatusReason]' \
--output text
次は、リージョンを1つずつ処理する別の StackSet の操作で、実行中に取得した結果です。ap-northeast-1 と us-east-1 の行だけを示します。
ap-northeast-1 OUTDATED RUNNING User Initiated
us-east-1 OUTDATED PENDING User initiated operation
処理中のリージョンが RUNNING、順番待ちのリージョンが PENDING です。
進捗率の単位
1つのスタックに複数のリソースがある場合も確認しました。SNS トピック3つと、DNS 検証待ちの ACM 証明書1つを持つテンプレートを、ap-northeast-1 と us-east-1 へ並列で作成しました。02:57:08 には、ap-northeast-1 のスタックでトピック3つが CREATE_COMPLETE、証明書が CREATE_IN_PROGRESS でしたが、その前後の取得(02:57:00、02:57:11)では、Completed 0、Pending 2、PercentageCompleted 0.0 のままでした。進捗率は 0.0 と 100.0 の2値だけで、100.0 になったのは操作が完了した 03:01:16 の取得でした。
進捗率は、スタックインスタンスの完了数(CompletedStackInstancesCount)から計算されます。スタック内の一部のリソースが完了しても動きません。
完了後の再取得
完了した操作も、同じコマンドで最終値を取得できます。次は、操作の EndTimestamp(02:44:50)の約1分半後(02:46:21)に取得した結果です。
aws cloudformation describe-stack-set-operation \
--stack-set-name progress-demo \
--operation-id <operation-id> \
--query 'StackSetOperation.{Status:Status,End:EndTimestamp,Stages:StatusDetails.Stages,Tokyo:RegionalStatusDetails."ap-northeast-1".Stages,Oregon:RegionalStatusDetails."us-west-2".Stages}'
{
"Status": "SUCCEEDED",
"End": "2026-11-20T17:44:50.175000+00:00",
"Stages": {
"RoleProvisioning": {
"Status": "NOT_APPLICABLE"
},
"StackInstancesDeployment": {
"Status": "SUCCEEDED",
"SucceededStackInstancesCount": 3,
"FailedStackInstancesCount": 0,
"CompletedStackInstancesCount": 3,
"PendingStackInstancesCount": 0,
"CancelledStackInstancesCount": 0,
"SkippedStackInstancesCount": 0,
"PercentageCompleted": 100.0
}
},
"Tokyo": {
"RegionalStackInstancesDeployment": {
"Status": "SUCCEEDED",
"SucceededStackInstancesCount": 1,
"FailedStackInstancesCount": 0,
"CompletedStackInstancesCount": 1,
"PendingStackInstancesCount": 0,
"CancelledStackInstancesCount": 0,
"SkippedStackInstancesCount": 0,
"TotalStackInstancesCount": 1,
"PercentageCompleted": 100.0
}
},
"Oregon": {
"RegionalStackInstancesDeployment": {
"Status": "SUCCEEDED",
"SucceededStackInstancesCount": 1,
"FailedStackInstancesCount": 0,
"CompletedStackInstancesCount": 1,
"PendingStackInstancesCount": 0,
"CancelledStackInstancesCount": 0,
"SkippedStackInstancesCount": 0,
"TotalStackInstancesCount": 1,
"PercentageCompleted": 100.0
}
}
}
describe-stack-set-operation と同じ Stages が、list-stack-set-operations の Summaries の各要素の StatusDetails にも入ります。RegionalStatusDetails は含まれないので、リージョン別の値は describe-stack-set-operation で取得します。
停止した操作
リージョンの順序を指定せずに複数リージョンへ作成した別の操作を、02:35:12 に stop-stack-set-operation で停止しました。ap-northeast-1 と us-east-1 の経過は次のとおりです。
- 02:35:18: 操作は STOPPING。どちらのリージョンも Status は IN_PROGRESS、Pending は 1、Cancelled は 0
- 02:35:41: 処理中だった ap-northeast-1 のスタックインスタンスに、検証用の CNAME を追加して完了させた
- 02:38:01: 操作はまだ STOPPING。どちらのリージョンも 02:35:18 と同じ値
- 02:38:06: 操作が終了
- 02:38:17: 操作は STOPPED
STOPPED になった後の取得(02:38:17)の2リージョンの行は次のとおりです。
| リージョン | Status | Succeeded | Failed | Completed | Cancelled | PercentageCompleted |
|---|---|---|---|---|---|---|
| ap-northeast-1 | SUCCEEDED | 1 | 0 | 1 | 0 | 100.0 |
| us-east-1 | FAILED | 0 | 0 | 1 | 1 | 100.0 |
停止の影響を受けたのは、処理に入らなかった us-east-1 です。Failed は 0 のままで、Cancelled が 1 になり、Status は FAILED でした。停止の影響を受けたリージョンは Failed の件数では見つからないので、リージョン別の Cancelled の件数を見ます。PercentageCompleted は SUCCEEDED の ap-northeast-1 と同じ 100.0 になるため、進捗率では区別できません。
進捗の取り出し方
進捗は --query と jq で必要な部分だけを取り出せます。
進捗率だけを取得する
aws cloudformation describe-stack-set-operation \
--stack-set-name progress-demo \
--operation-id <operation-id> \
--query StackSetOperation.StatusDetails.Stages.StackInstancesDeployment.PercentageCompleted
実行中の操作に絞る
aws cloudformation list-stack-set-operations \
--stack-set-name progress-demo \
--query "Summaries[?Status=='RUNNING'].{Id:OperationId,Stages:StatusDetails.Stages}"
リージョン別に取得する
リージョン名は二重引用符で囲んで指定します。
aws cloudformation describe-stack-set-operation \
--stack-set-name progress-demo \
--operation-id <operation-id> \
--query 'StackSetOperation.RegionalStatusDetails.{tokyo:"ap-northeast-1".Stages.RegionalStackInstancesDeployment.[Status,CompletedStackInstancesCount,TotalStackInstancesCount],virginia:"us-east-1".Stages.RegionalStackInstancesDeployment.[Status,CompletedStackInstancesCount,TotalStackInstancesCount],oregon:"us-west-2".Stages.RegionalStackInstancesDeployment.[Status,CompletedStackInstancesCount,TotalStackInstancesCount]}'
{
"tokyo": [
"IN_PROGRESS",
0,
1
],
"virginia": [
"IN_PROGRESS",
0,
1
],
"oregon": [
"IN_PROGRESS",
0,
1
]
}
全リージョンを一覧にするなら、jq でタブ区切りにできます。
aws cloudformation describe-stack-set-operation \
--stack-set-name progress-demo \
--operation-id <operation-id> \
--output json | jq -r '.StackSetOperation.RegionalStatusDetails | to_entries[] | [.key, .value.Stages.RegionalStackInstancesDeployment.Status, .value.Stages.RegionalStackInstancesDeployment.PercentageCompleted] | @tsv'
ap-northeast-1 IN_PROGRESS 0.0
us-east-1 IN_PROGRESS 0.0
us-west-2 IN_PROGRESS 0.0
まとめ
StackSets の操作の進捗を、ステージ別・リージョン別に確認できるようになりました。進捗が分からず、強制タイムアウトなどでロールバックに至るような事態を、従来より回避しやすくなると期待できます。
依存関係などで待機が発生する StackSets を利用していて、タイムアウトに気付けないことが課題だった場合は、今回のアップデートをご活用ください。








