CloudFormation StackSets の操作の進捗が ステージ別・リージョン別に確認可能になったので試してみた

CloudFormation StackSets の操作の進捗が ステージ別・リージョン別に確認可能になったので試してみた

AWS CloudFormation StackSets の操作の進捗を、ステージ別・リージョン別に AWS CLI で確認しました。3リージョンへのデプロイでは、実行中に進捗率とスタックインスタンスの件数が変わり、完了後も最終値を取得できました。
2026.11.23

はじめに

2026年11月19日、AWS CloudFormation StackSets の操作の進捗を、ステージ別・リージョン別に確認できるようになりました。

https://aws.amazon.com/about-aws/whats-new/2026/11/cloudformation-stacksets-progress/

この記事では、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 のまま待機します。

https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-certificatemanager-certificate.html

今回のドメインのホストゾーンは別のアカウントにあり、テンプレートに 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 です。

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-prereqs-self-managed.html

ドメインは自分が管理するものに置き換えてください。

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 を利用していて、タイムアウトに気付けないことが課題だった場合は、今回のアップデートをご活用ください。

この記事をシェアする

AWSのお困り事はクラスメソッドへ

関連記事