CloudFormation StackSets operation progress can now be checked by stage and by Region, so I tried it out

CloudFormation StackSets operation progress can now be checked by stage and by Region, so I tried it out

I checked AWS CloudFormation StackSets operation progress by stage and by Region using the AWS CLI. In a 3-Region deployment, the progress rate and stack instance counts changed during execution, and final values were available after completion.
2026.11.23

This page has been translated by machine translation. View original

Introduction

On November 19, 2026, it became possible to check the progress of AWS CloudFormation StackSets operations by stage and by Region.

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

In this article, I use the AWS CLI to retrieve the progress of an operation both while it is running and after it completes, and check the items returned and how their values change.

Test environment

  • StackSet: self-managed (the management account and the target account are the same)
  • Regions: ap-northeast-1, us-east-1, us-west-2
  • Region processing: one at a time, in order (RegionConcurrencyType=SEQUENTIAL)
  • Maximum number of accounts processed concurrently: 1 (MaxConcurrentCount=1)
  • AWS CLI: 2.41.2

Times in the text are in JST (API output is in UTC).

Preparation

A template that keeps an operation waiting

To see the progress values change midway, I use a template that keeps an operation running for several minutes. It has just one ACM certificate with DNS validation specified. If the domain's hosted zone is not in Route 53 in the target account, the stack stays in CREATE_IN_PROGRESS, waiting until the validation CNAME is added.

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

The hosted zone for the domain used this time was in a different account, and I did not specify DomainValidationOptions in the template. I used a different subdomain for each operation.

Save it as acm-wait.yaml.

AWSTemplateFormatVersion: '2010-09-09'
Parameters:
  DomainName:
    Type: String
Resources:
  Certificate:
    Type: AWS::CertificateManager::Certificate
    Properties:
      DomainName: !Ref DomainName
      ValidationMethod: DNS

To release the wait, get the certificate's validation record and add it as a CNAME to the DNS you manage.

aws acm describe-certificate \
  --certificate-arn <certificate-arn> \
  --region ap-northeast-1 \
  --query 'Certificate.{Domain:DomainName,Status:Status,Record:DomainValidationOptions[0].ResourceRecord}'

This time I issued certificates for the same domain in three Regions. The ResourceRecord of the three certificates had the same Name and Value. After I added one CNAME, all three certificates became ISSUED.

Creating the StackSet and starting the operation

A self-managed StackSet requires two roles: AWSCloudFormationStackSetAdministrationRole in the management account, and AWSCloudFormationStackSetExecutionRole in each account where stack instances are created.

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

Replace the domain with one that you manage.

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

When creating the stack instances, I specified that Regions be processed one at a time, in order, so that the progress changes in steps.

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

How progress appears

Items returned

You retrieve progress with describe-stack-set-operation.

aws cloudformation describe-stack-set-operation \
  --stack-set-name progress-demo \
  --operation-id <operation-id>

The following is an excerpt from a response during execution, showing all of StatusDetails and the ap-northeast-1 part of RegionalStatusDetails.

    "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
                    }
                }
            },

There are two stages.

  • RoleProvisioning: for service-managed StackSets, the stage that prepares access to the target accounts
  • StackInstancesDeployment: the stage that deploys the stack instances

The progress items are located as follows for the per-stage and per-Region views.

Where progress is TotalStackInstancesCount
Per stage Stages in StatusDetails Directly under StatusDetails
Per Region Under each Region in RegionalStatusDetails Inside Stages of each Region

The item names for counts such as Succeeded and Pending, and for PercentageCompleted, are the same for the per-stage and per-Region views.

For self-managed operations, the Status of RoleProvisioning was NOT_APPLICABLE in every response I retrieved.

Changes during execution

I extracted only the points where values changed. Each row is one of 35 retrievals taken at roughly 10-second intervals.

Retrieval time Operation Status StackInstancesDeployment (Status / Succeeded / Pending / Completed / PercentageCompleted) Per-Region Status
02:38:47 RUNNING NOT_STARTED (no counts) No RegionalStatusDetails
02:38:58 RUNNING IN_PROGRESS / 0 / 3 / 0 / 0.0 All three Regions IN_PROGRESS
02:43:36 RUNNING IN_PROGRESS / 1 / 2 / 1 / 33.3 ap-northeast-1 is SUCCEEDED, the others are IN_PROGRESS
02:44:19 RUNNING IN_PROGRESS / 2 / 1 / 2 / 66.6 ap-northeast-1 and us-east-1 are SUCCEEDED, us-west-2 is IN_PROGRESS
02:44:51 SUCCEEDED SUCCEEDED / 3 / 0 / 3 / 100.0 All three Regions SUCCEEDED

The value stayed at 0.0 for 26 retrievals from 02:38:58 to 02:43:25. During this time the operation was waiting for domain validation, and the counts first advanced about 3 minutes after I added the CNAME at 02:40:41.

I had specified that Regions be processed one at a time, but in the retrieval at 02:38:58, when counts were first returned, all three Regions showed IN_PROGRESS, Pending 1, and Completed 0. Only one Region is being processed, so the other two should be waiting their turn. However, you cannot tell which one is being processed from the per-Region Status and counts. To find out, look at DetailedStatus in list-stack-instances.

aws cloudformation list-stack-instances \
  --stack-set-name progress-demo \
  --query 'Summaries[].[Region,Status,StackInstanceStatus.DetailedStatus,StatusReason]' \
  --output text

The following is a result retrieved during execution of an operation on a different StackSet that also processes Regions one at a time. Only the ap-northeast-1 and us-east-1 rows are shown.

ap-northeast-1	OUTDATED	RUNNING	User Initiated
us-east-1	OUTDATED	PENDING	User initiated operation

The Region being processed is RUNNING, and the Region waiting its turn is PENDING.

Unit of the progress rate

I also checked a case where one stack has multiple resources. I created, in parallel in ap-northeast-1 and us-east-1, a template with three SNS topics and one ACM certificate waiting for DNS validation. At 02:57:08, in the ap-northeast-1 stack the three topics were CREATE_COMPLETE and the certificate was CREATE_IN_PROGRESS, but in the retrievals before and after (02:57:00 and 02:57:11), it stayed at Completed 0, Pending 2, and PercentageCompleted 0.0. The progress rate takes only two values, 0.0 and 100.0, and it became 100.0 in the retrieval at 03:01:16, when the operation completed.

The progress rate is calculated from the number of completed stack instances (CompletedStackInstancesCount). It does not move when only some of the resources in a stack have completed.

Retrieving again after completion

You can retrieve the final values of a completed operation with the same command. The following is a result retrieved at 02:46:21, about a minute and a half after the operation's EndTimestamp (02:44:50).

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
        }
    }
}

The same Stages as in describe-stack-set-operation are also included in StatusDetails of each element of Summaries in list-stack-set-operations. RegionalStatusDetails is not included, so retrieve per-Region values with describe-stack-set-operation.

A stopped operation

I stopped a different operation, which created instances in multiple Regions without specifying the Region order, with stop-stack-set-operation at 02:35:12. The sequence of events for ap-northeast-1 and us-east-1 is as follows.

  • 02:35:18: The operation was STOPPING. Both Regions had Status IN_PROGRESS, Pending 1, and Cancelled 0
  • 02:35:41: I added the validation CNAME to the ap-northeast-1 stack instance, which was being processed, to let it complete
  • 02:38:01: The operation was still STOPPING. Both Regions had the same values as at 02:35:18
  • 02:38:06: The operation ended
  • 02:38:17: The operation was STOPPED

The rows for the two Regions in the retrieval after it became STOPPED (02:38:17) are as follows.

Region 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

The Region affected by the stop was us-east-1, which had not started processing. Failed stayed at 0, Cancelled became 1, and Status was FAILED. A Region affected by a stop cannot be found from the Failed count, so look at the per-Region Cancelled count. PercentageCompleted is 100.0, the same as for ap-northeast-1, which is SUCCEEDED, so the two cannot be distinguished by the progress rate.

How to extract progress

You can extract just the parts you need with --query and jq.

Get only the progress rate

aws cloudformation describe-stack-set-operation \
  --stack-set-name progress-demo \
  --operation-id <operation-id> \
  --query StackSetOperation.StatusDetails.Stages.StackInstancesDeployment.PercentageCompleted

Narrow down to running operations

aws cloudformation list-stack-set-operations \
  --stack-set-name progress-demo \
  --query "Summaries[?Status=='RUNNING'].{Id:OperationId,Stages:StatusDetails.Stages}"

Get progress per Region

Specify Region names enclosed in double quotes.

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
    ]
}

To list all Regions, you can produce tab-separated output with 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

Summary

You can now check the progress of StackSets operations by stage and by Region. This should make it easier than before to avoid situations where progress is unclear and things end up rolling back due to a forced timeout or the like.

If you use StackSets where waiting occurs because of dependencies and similar causes, and not noticing timeouts has been a problem, please take advantage of this update.

Share this article

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