hidekazu-konishi.com

Profile | Privacy Policy | Tech Blog  >  Summary of AWS CloudFormation StackSets Focusing on the Relationship between the Management Console and API, Account Filter, and the Role of Parameters

Summary of AWS CloudFormation StackSets Focusing on the Relationship between the Management Console and API, Account Filter, and the Role of Parameters

First Published:
Last Updated:

In this article, I summarize AWS CloudFormation StackSets, which are commonly used for multi-account management, focusing on features and characteristics, the relationship between the management console and API, deploy target account filters, and the meaning and role of parameters.
Note that what users define for AWS CloudFormation StackSets templates will be called "template parameters", while "StackSet parameters", which are set for AWS CloudFormation StackSets services, and " Stack instance parameters" that are set for AWS CloudFormation StackSets services.

What is AWS CloudFormation StackSets

AWS CloudFormation StackSets is a feature that allows you to Create, Update, and delete AWS CloudFormation stacks in multiple AWS accounts and multiple AWS regions within each AWS account, using AWS CloudFormation templates from a pre-specified management account.
When you create a StackSet, AWS CloudFormation stacks associated with the StackSet are deployed to the specified AWS accounts and AWS regions, creating, updating, and deleting AWS resources defined in the AWS CloudFormation templates and associations between AWS resources.
In StackSets, a combination of an AWS account and an AWS region (for example, AWS region ap-northeast-1 of AWS account 123456789012) is managed as a single stack instance.
Also, in StackSets, the progress and results of API executions such as StackSet create (CreateStackSet), update (UpdateStackSet), delete (DeleteStack), drift detection (DetectStackSetDrift), and create (CreateStackInstances), update (UpdateStackInstances), and delete (DeleteStackInstances) of each stack instance managed by StackSet are managed as Operations.

AWS CloudFormation StackSets Permission Model (Authorization Model)

AWS CloudFormation StackSets has two methods of managing and granting permissions to management accounts and AWS accounts to be deployed, called the "Permission Model" (PermissionModel).

SERVICE_MANAGED Type

The Service Managed type is a permission model that deploys stack instances to AWS accounts managed by AWS Organizations with all features enabled, on a per-organization unit (OU) or per-AWS account basis.
In the Service Managed type, you create the IAM roles required by the AWS CloudFormation StackSets feature, and manage StackSets from the management account of AWS Organizations (you can also delegate the management of StackSets to member accounts).
Also, you can enable settings to automatically deploy StackSets as stack instances to AWS accounts added to AWS Organizations at a later date.

SELF_MANAGED Type

The Self-Managed type is a permission model that deploys stack instances to any AWS account with the permission to create the required IAM roles, on a per-AWS account basis.
In the Self-Managed type, you create the necessary IAM roles using the AWS CloudFormation template provided by AWS or manually, and manage StackSets in the specified AWS account.

Concept Diagram of AWS CloudFormation StackSets in Service Managed Type

From here on, the article will mainly be written with the "Service Managed type (SERVICE_MANAGED)", which is used in combination with AWS Organizations for multi-account management, in mind.
The following concept diagram is an example of deploying stacks created from templates in AWS CloudFormation StackSets with the Service Managed permission model to two organization units (OUs) and two regions (us-east-1, ap-northeast-1).

Example of AWS CloudFormation StackSets Deployment in Service Managed Type
Example of AWS CloudFormation StackSets Deployment in Service Managed Type

You manage AWS CloudFormation StackSets from a specific region of the management account.
No matter from which region of the management account you create a StackSet, you can deploy stacks to multiple regions of multiple member accounts.
However, it is better to manage them so that you know which StackSet was created in which region of the management account.

AWS CloudFormation StackSets: The relationship between API (including AWS SDK & AWS CLI) operations and the AWS Management Console

This section summarizes the characteristics of the operations that can be executed with the AWS CloudFormation StackSets API (including AWS SDK & AWS CLI) and their relationship with the AWS Management Console.
It also describes the features of the account filter type (AccountFilterType) that can be used in deployment settings (DeploymentTargets) for specifying the target of StackSet deployment based on conditions.

Patterns of creating, updating, and deleting StackSet stack instances using APIs such as AWS SDK & AWS CLI

The following are some basic flow patterns when using AWS CloudFormation StackSets at the API level, such as AWS SDK and AWS CLI.
  • Create a StackSet with CreateStackSet. Then, Add stack instances to the created StackSet with CreateStackInstances
  • Add more stack instances to the created StackSet with CreateStackInstances
  • Add stack instances to the created StackSet with CreateStackInstances by overwriting the parameter values differently from the StackSet
  • Update the StackSet with UpdateStackSet (including updating templates and parameter keys) and reflect the update to some or all stack instances
  • Update some or all stack instances with UpdateStackInstances by overwriting the parameter values differently from the StackSet
  • Delete some of the stack instances associated with the StackSet with DeleteStackInstances
  • Delete all stack instances associated with the StackSet with DeleteStackInstances. Then, Delete the StackSet with DeleteStack
  • Detect drift (differences between the configuration managed by the stack and the actual AWS resource configuration) of all stack instances associated with the StackSet with DetectStackSetDrift

Key points of the deployment feature for understanding AWS CloudFormation StackSets

As stated above, there are certain usage patterns for the APIs used for creating, updating, etc. of AWS CloudFormation StackSets StackSets, and stack instances.
AWS CloudFormation StackSets has a feature to specify the Organizational Unit (OU), AWS account, and region for deploying StackSets with these APIs.
In this article, I will explain using the following terminology.
"Deployment Targets" (DeploymentTargets): Directly specify Organizational Units (OUs), AWS accounts, or filter accounts based on conditions.
"Deployment Scope": Targets that add regions to the above "Deployment Targets" (DeploymentTargets).
Particularly, the key points of the deployment feature for understanding AWS CloudFormation StackSets are as follows.
  • CreateStackSet only creates the configuration, template, and parameter settings for the StackSet, but does not create stack instances.
  • Only with CreateStackInstances can you add organizational units (OUs), AWS accounts, and AWS regions to the StackSet as stack instances.
  • UpdateStackSet updates the overall configuration of the StackSet (including parameters, template, template parameters), and reflects these changes in all or some of the already added stack instances by specifying organizational units (OUs), AWS accounts, and AWS regions.
  • UpdateStackInstances reflects overwritten parameters for the parameters set in the StackSet template in all or some of the already added stack instances by specifying organizational units (OUs), AWS accounts, and AWS regions.
  • Organizational units (OUs), AWS accounts, and deployment targets specified by the AccountFilterType filter condition (the DeploymentTargets parameter) can be used in CreateStackInstances, UpdateStackSet, UpdateStackInstances, and DeleteStackInstances (details will be discussed later).
  • In update-related APIs such as UpdateStackSet, UpdateStackInstances, new organizational units (OUs), AWS accounts, and AWS regions can't be added to the DeploymentTargets (including AccountFilterType) to create additional stack instances.
    * Addition of stack instances can only be done through CreateStackInstances.
    * UpdateStackSet, UpdateStackInstances can only deploy to already added stack instances (only for narrowing down).
  • If automatic deployment is enabled and you update the template by narrowing down the deployment target with DeploymentTargets (including AccountFilterType), the updated template will also be applied to AWS accounts added to the StackSet later in the latest Operation.
    * Only the latest template can be defined in the StackSet.
    * Stack instances that existed at the time of update and were not in the deployment range will maintain the resource state by the pre-update template.
    * Stack instances added after the update will have the post-update template applied.
  • To delete a StackSet with DeleteStack, you must first delete all stack instances associated with the StackSet using DeleteStackInstances.

AWS CloudFormation StackSets and the Relationship between AWS Management Console Actions and APIs

Looking at the event history of AWS CloudTrail, it can be seen that actions on the AWS Management Console typically use APIs related to the create, updating, and delete of StackSets and the stack instances associated with them as follows:
AWS Management Console Actions APIs executed within the action
Create StackSet CreateStackSet → CreateStackInstances
Add stacks to StackSet CreateStackInstances
Edit StackSet details UpdateStackSet (Excluding changes to AutoDeployment parameters)
Override StackSet parameters UpdateStackInstances
Delete stacks from StackSet DeleteStackInstances
Editing automatic deployment
* The operation to enable/disable automatic deployment (Automatic deployment), and to set stack delete/retention for account removal behavior. 		UpdateStackSet (Changes to AutoDeployment's Enabled and RetainStacksOnAccountRemoval parameters)
Detect drift DetectStackSetDrift
Delete StackSet DeleteStack
In this way, with the AWS Management Console, you can simultaneously configure the StackSet template and add the OU or AWS account that will deploy the template in the "Create StackSet" action.
However, after creating the StackSet, it is necessary to be aware that the APIs corresponding to the actions on the AWS Management Console are separate in the scene of StackSet update.
Especially, as of writing this article, it is not possible to simultaneously update the StackSet template and add organizational units (OU) or AWS accounts as stack instances, so you need to execute them separately.

Deployment Target (DeploymentTargets) and Account Filter Type (AccountFilterType)

Having organized the relationship between AWS Management Console actions and APIs in AWS CloudFormation StackSets, let's explain about the Account Filter Type (AccountFilterType) in particular, which is specified in both for Deployment Target (DeploymentTargets).
As mentioned in the "Important Points of Deployment Function to Understand AWS CloudFormation StackSets", in the following AWS Management Console actions corresponding to CreateStackInstances, UpdateStackSet, UpdateStackInstances, DeleteStackInstances APIs, you can specify the Deployment Target (DeploymentTargets), including the Account Filter Type (AccountFilterType).
  • Create StackSet (the part executing CreateStackInstances)
  • Add stacks to StackSet (CreateStackInstances)
  • Edit StackSet details (UpdateStackSet)
  • Override StackSet parameters (UpdateStackInstances)
  • Delete stacks from StackSet (DeleteStackInstances)
Next, let's summarize the application scope of AccountFilterType (see the list of parameters for details), which can be applied when the permission model is "Service Managed," in the overview of "Add stacks to StackSet", "Edit StackSet details", "Override StackSet parameters", and "Delete stacks from StackSet".
Action (Corresponding API) Overview Examples of application scope when using AccountFilterType with Organizational Unit (OU)
Create StackSet
(Execution part of CreateStackInstances) 		Add stack instances (organizational units (OUs), AWS accounts, AWS regions) with the template and settings created by CreateStackSet. NONE: Add all AWS accounts within the newly specified organizational unit (OU).

INTERSECTION: Add only a portion of AWS accounts within the newly specified organizational unit (OU).

DIFFERENCE: Add AWS accounts within the newly specified organizational unit (OU), excluding a certain part.

UNION: * At the time of writing this article, account filtering with UNION is not allowed in the create operation.
Add stacks to StackSet
(CreateStackInstances)
Edit StackSet details
(UpdateStackSet) 		Within the range of stack instances (organizational units (OUs), AWS accounts, AWS regions) that are currently deploying the StackSet, update the settings of the StackSet template, etc., for the specified stack instances. NONE: Within the range of stack instances already added, update all AWS accounts within the specified organizational unit (OU).

INTERSECTION: Within the range of stack instances already added, update only a portion of AWS accounts within the specified organizational unit (OU).

DIFFERENCE: Within the range of stack instances already added, update AWS accounts within the specified organizational unit (OU), excluding a certain part.

UNION: Within the range of stack instances already added, update all AWS accounts within one of the specified organizational units (OUs), and some AWS accounts within a different organizational unit (OU).
Override StackSet parameters
(UpdateStackInstances) 		Within the range of stack instances (organizational units (OUs), AWS accounts, AWS regions) that are currently deploying the StackSet, overwrite and update the parameters of the StackSet template for the specified stack instances.
Delete stacks from StackSet
(DeleteStackInstances) 		Within the range of stack instances (organizational units (OUs), AWS accounts, AWS regions) that are currently deploying the StackSet, delete the specified stack instances. NONE: Within the range of stack instances already added, delete all AWS accounts within the specified organizational unit (OU).

INTERSECTION: Within the range of stack instances already added, delete only a portion of AWS accounts within the specified organizational unit (OU).

DIFFERENCE: Within the range of stack instances already added, delete AWS accounts within the specified organizational unit (OU), excluding a certain part.

UNION: Within the range of stack instances already added, delete all AWS accounts within one of the specified organizational units (OUs), and some AWS accounts within a different organizational unit (OU).
The ability to process StackSets and each Stack instance collectively in the AWS Management Console is convenient. However, the relationship between StackSets and Stack instances can be difficult to understand, so if you want to understand the scope of application to OUs and AWS accounts and the contents to be updated in detail, it is easier to check the specifications at the API level.

The types and characteristics of Account Filter Type (AccountFilterType) - A Concept Diagram

I will illustrate with a concept diagram the examples of filtering deployment targets with INTERSECTION, DIFFERENCE, and UNION among the Account Filter Types (AccountFilterType) mentioned above. Operations for updating, such as UpdateStackSet, UpdateStackInstances are used in this case.
Assume that the StackSet has already been deployed to two regions (us-east-1, ap-northeast-1) of "Organizational Unit (OU) X" member accounts (A, B, C) and "Organizational Unit (OU) Y" member accounts (D, E, F).

INTERSECTION

Here's an example of updating by deployment target, specifying "Member Accounts A" and "Member Accounts B", which are part of "Organizational Unit (OU) X", with the account filter INTERSECTION, targeting "Organizational Unit (OU) X".
"Member Accounts A" and "Member Accounts B" of "Organizational Unit (OU) X" will be updated.

Example of Deployment Target Using INTERSECTION
Example of Deployment Target Using INTERSECTION

Note: If you update by specifying "Member Accounts A" and "Member Accounts B", which are part of "Organizational Unit (OU) X", with the account filter INTERSECTION, targeting both "Organizational Unit (OU) X" and "Organizational Unit (OU) Y", only "Member Accounts A" and "Member Accounts B" of "Organizational Unit (OU) X" will be updated.

DIFFERENCE

Here's an example of updating by deployment target, specifying "Member Account A", which is part of "Organizational Unit (OU) X", with the account filter DIFFERENCE, targeting "Organizational Unit (OU) X".
All member accounts of "Organizational Unit (OU) X", excluding "Member Account A", will be updated.

Example of Deployment Target Using DIFFERENCE
Example of Deployment Target Using DIFFERENCE

Note: If you update by specifying "Member Account A", which is part of "Organizational Unit (OU) X", with the account filter DIFFERENCE, targeting both "Organizational Unit (OU) X" and "Organizational Unit (OU) Y", all member accounts of "Organizational Unit (OU) Y", in addition to all member accounts of "Organizational Unit (OU) X" excluding "Member Account A", will be updated.

UNION

Here's an example of updating by deployment target, specifying "Member Account D", which is part of "Organizational Unit (OU) Y", with the account filter UNION, targeting "Organizational Unit (OU) X".
In addition to all member accounts of "Organizational Unit (OU) X", "Member Account D", which is part of "Organizational Unit (OU) Y", will be updated.

Example of Deployment Target Using UNION
Example of Deployment Target Using UNION

Note: If you update by specifying "Member Account D", which is part of "Organizational Unit (OU) Y", with the account filter UNION, targeting both "Organizational Unit (OU) X" and "Organizational Unit (OU) Y", all member accounts of "Organizational Unit (OU) X" and "Organizational Unit (OU) Y", including "Member Account D" of "Organizational Unit (OU) Y", will be updated.

List of parameters and their settings (meaning and role) when creating, updating, and referencing AWS CloudFormation StackSets

This section compiles a list of parameters, their meanings and roles, when creating, updating, or referring to AWS CloudFormation StackSets.
Parameters that are indented with spaces are defined as associative array elements (dictionary type, hash, map) of the parameter immediately before them without an indent.

Parameter (Setting Item) List to be Specified During StackSet Create (CreateStackSet), Update (UpdateStackSet), and Delete (DeleteStackSet)

Parameter Name Console Name
Additional Description 		Operations in which the User can Specify Values
StackSetName * StackSet name
The name of the StackSet, which is unique in the region where it is created. In update and delete operations, the StackSet is uniquely identified by its name. 		Create, Update, Delete
(Cannot be edited during update and delete)
StackId −
The stack ID (ARN) to be specified when importing a new stack set. 		Create
Description * Description of the StackSet
A description of the StackSet where the user can add any information. 		Create, Update
TemplateBody −
Used when specifying the StackSet template directly as a string. Either TemplateBody or TemplateURL must be specified, but not both. 		Create, Update
TemplateURL * Amazon S3 template URL
Used when specifying the URL of Amazon S3 where the StackSet template resides. Either TemplateBody or TemplateURL must be specified, but not both. 		Create, Update
Parameters * Parameters
The parameters of the template to be used in the StackSet. In general, these are specified according to the parameters of the user-defined template. 		Create, Update
  ParameterKey −
The key of the template parameter to be used in the StackSet. 		Create, Update
  ParameterValue −
Specify the value for the key of the template parameter to be used in the StackSet. 		Create, Update
  UsePreviousValue −
Specifies whether to use the existing parameter value that the stack is using for the parameter key during stack update.
True: Use the existing value.
False: Do not use the existing value. 		Create, Update
  ResolvedValue −
The value corresponding to the read-only SSM parameter key. This is used only for SSM parameter types in the template. 		Create, Update
Capabilities −
An item that must be specified to explicitly acknowledge that the template contains resources with specific features that affect the AWS account, such as creating an IAM user.
CAPABILITY_IAM: Create IAM resources (AWS::IAM::AccessKey, AWS::IAM::Group, AWS::IAM::InstanceProfile, AWS::IAM::Policy, AWS::IAM::Role, AWS::IAM::User, AWS::IAM::UserToGroupAddition, etc.).
CAPABILITY_NAMED_IAM: Create IAM resources (AWS::IAM::AccessKey, AWS::IAM::Group, AWS::IAM::InstanceProfile, AWS::IAM::Policy, AWS::IAM::Role, AWS::IAM::User, AWS::IAM::UserToGroupAddition, etc.) with a custom name.
CAPABILITY_AUTO_EXPAND: Includes macros hosted by CloudFormation (AWS::Include, AWS::Serverless). 		Create, Update
AdministrationRoleARN * IAM Admin Role ARN
The ARN of the IAM role used to create/update the StackSet in the StackSets admin account. It is used when specifying an IAM role that can manage a specific StackSet within the StackSets admin account. 		Create, Update
ExecutionRoleName * IAM Execution Role Name
The name of the IAM role that actually executes the stacks of the StackSet in each target AWS account where the StackSet is deployed. 		Create, Update
PermissionModel * Permission Model
The method of management and granting permissions to the management account and AWS accounts being deployed. It cannot be updated if stack instances are associated.
SERVICE_MANAGED: Service-managed permissions.
SELF_MANAGED: Self-managed permissions. 		Create, Update
AutoDeployment * Deployment Configuration
When the PermissionModel is SERVICE_MANAGED, it sets whether to automatically deploy the StackSet to AWS accounts added later to the organization or organizational unit (OU) specified as the target of the StackSet (set with the following Enabled).
It also sets whether to retain the stacks when an account is deleted (set with the following RetainStacksOnAccountRemoval). 		Create, Update
  Enabled * Automatic Deployment
True: Enable automatic deployment.
False: Disable automatic deployment. 		Create, Update
  RetainStacksOnAccountRemoval * Retain Stacks on Account Removal
True: Retain stacks when an account is deleted.
False: Do not retain stacks when an account is deleted. 		Create, Update
ManagedExecution * Managed Execution
Sets whether to run non-conflicting Operations concurrently at the time of StackSets execution, and whether to queue conflicting Operations (set with the following Active). 		Create, Update
  Active * Managed Execution
True: At the time of StackSets execution, run non-conflicting Operations concurrently and queue conflicting Operations.
False: At the time of StackSets execution, execute one Operation at a time in the order of request. 		Create, Update
ClientRequestToken −
A token that needs to be specified so that AWS CloudFormation StackSets can recognize that it is not trying to create another StackSet with the same name when there is a possibility of retrying the request. 		Create
Tags * Tags
Tags to attach to the StackSet (set with the following Key and Value). 		Create, Update
  Key * Key
The key of the tag to attach to the StackSet. 		Create, Update
  Value * Value
The value for the key of the tag to attach to the StackSet. 		Create, Update
DeploymentTargets * Deployment configuration
Set when partially changing the organizational unit (OU) or AWS account to reflect the StackSet updates when the PermissionModel is SERVICE_MANAGED (set with the following Accounts, AccountsUrl, OrganizationalUnitIds, AccountFilterType).
If there are updates to the StackSet template (or template parameters), all stack instance statuses become OUTDATED before the update, and the stack instances of the updated organizational unit (OU) or AWS account are updated.
If there are no updates to the StackSet template (or template parameters), the existing stack instances other than the updated organizational unit (OU) or AWS account remain in their current status. 		Update
  Accounts * Account numbers
An array of account numbers to be updated. Also used when specifying AccountFilterType. 		Update
  AccountsUrl −
Amazon S3 URL returning the account numbers to be updated. 		Update
  OrganizationalUnitIds * Organizational units (OUs)
An array of the organizational Root ID or Organizational Unit (OU) ID to be updated. 		Update
  AccountFilterType * Account filter type
Setting to filter the conditions of the AWS account or organizational unit (OU) to be updated.
NONE: Deploy to the AWS account of the specified organizational unit (OU).
INTERSECTION: Deploy to the AWS account specified by the Accounts parameter among the AWS accounts of the specified organizational unit (OU).
DIFFERENCE: Deploy to the AWS accounts of the specified organizational unit (OU), excluding those specified by the Accounts parameter (you can exclude suspended AWS accounts or specific AWS accounts within the OU).
UNION: Default setting of the API. Deploy to the AWS accounts of the specified organizational unit (OU) and to the AWS accounts in other organizational units (OUs) specified by the Accounts parameter (you can update individual AWS accounts in another OU in addition to the entire OU to be updated in one request). 		Update
Accounts * Account numbers
Specify the AWS account numbers to deploy the StackSet in an array when the PermissionModel is SELF_MANAGED. 		Update
Regions * Regions
An array of regions where you want to reflect the updates of the StackSet among the regions where you have already deployed.
If there are updates to the StackSet's template (or the template's parameters), all stack instances' statuses will become OUTDATED before updating, and the stack instances in the regions targeted for updates will be updated.
If there are no updates to the StackSet's template (or the template's parameters), existing stack instances in regions not targeted for updates will remain in their current status. 		Update
OperationPreferences * Deployment options
Settings for how to execute the StackSet's Operation (specified by the following RegionConcurrencyType, RegionOrder, FailureToleranceCount, FailureTolerancePercentage, MaxConcurrentCount, MaxConcurrentPercentage). 		Update
  RegionConcurrencyType * Region Concurrency
Setting whether to execute the StackSet's Operation concurrently in multiple regions.
SEQUENTIAL: Execute in sequence.
PARALLEL: Execute in parallel. 		Update
  RegionOrder * Specify regions
An array to set the order of regions where the StackSet's Operation is executed. 		Update
  FailureToleranceCount * Failure tolerance Number
The number of AWS accounts per region that tolerate the failure of the StackSet's Operation. If the number of Operation failures exceeds this threshold, and it stops in a region of an AWS account, the Operation will not be executed in subsequent regions. 		Update
  FailureTolerancePercentage * Failure tolerance Percentage
The percentage of AWS accounts per region that tolerate the failure of the StackSet's Operation. If the failure rate of the Operation exceeds this threshold, and it stops in a region of an AWS account, the Operation will not be executed in subsequent regions. 		Update
  MaxConcurrentCount * Maximum concurrent accounts Number
The maximum number of AWS accounts to execute the StackSet's Operation concurrently in parallel. 		Update
  MaxConcurrentPercentage * Maximum concurrent accounts Percentage
The maximum percentage of AWS accounts to execute the StackSet's Operation concurrently in parallel. 		Update
OperationId −
A token that ensures AWS CloudFormation StackSets isn't attempting to update the StackSet in a way that would be redundant if the request might be retried. If not specified, it is generated automatically. 		Update
CallAs −
Specifies whether the StackSets are being executed by the management account of AWS Organizations when the PermissionModel is SERVICE_MANAGED, or whether they are being executed by a member account that has been delegated permissions of the StackSets.
SELF(default): Executed by the management account of AWS Organizations.
DELEGATED_ADMIN: Executed by a member account that has been delegated permissions of the StackSets. 		Create, Update, Delete

List of parameters (configuration items) to specify when creating (CreateStackInstances), updating (UpdateStackInstances), or deleting (DeleteStackInstances) stack instances

Parameter Name Console Name
Additional Description 		Operations in which the User can Specify Values
StackSetName * StackSet name
A name for the StackSet that is unique in the region where it is being created. In the operations of creating, updating, and deleting stack instances, the target StackSet is uniquely identified by the StackSet name. 		Create, Update, Delete
(specification only, not editable)
ParameterOverrides * Specify overrides
When you need to override the parameters of the template used by the StackSet for each target stack instance, specify here. In general, specify according to the parameters of the template defined by the user. 		Create, Update
  ParameterKey * Name
Specify the key of the parameter to be overridden. 		Create, Update
  ParameterValue * Override value
Specify the value for the key of the parameter to be overridden. 		Create, Update
  UsePreviousValue −
Specifies whether to use the existing parameter value used by the stack for the parameter key during stack update.
True: Use the existing value, False: Do not use the existing value 		Create, Update
  ResolvedValue −
The value corresponding to the read-only SSM parameter key. Only used with the SSM parameter type in the template. 		Create, Update
DeploymentTargets * Deployment configuration
When the PermissionModel is SERVICE_MANAGED, set this when partially changing the organizational unit (OU) or AWS account that reflects the update of the StackSet(set with the following Accounts, AccountsUrl, OrganizationalUnitIds, AccountFilterType).
If there are updates to the StackSet's template (or the template's parameters), all stack instances' status becomes OUTDATED before the update, and the stack instances of the organizational unit (OU) or AWS account that will be updated are updated.
If there are no updates to the StackSet's template (or the template's parameters), the existing stack instances of the organizational unit (OU) or AWS account other than the one to be updated remain in their current status. 		Create, Update, Delete
  Accounts * Account numbers
An array of the account numbers to be updated. Also used when specifying AccountFilterType. 		Create, Update, Delete
  AccountsUrl −
Amazon S3 URL that returns the account numbers to be updated. 		Create, Update, Delete
  OrganizationalUnitIds * Organizational units (OUs)
An array of the organization's Root ID or Organizational Unit (OU) to be updated. 		Create, Update, Delete
  AccountFilterType * Account filter type
A setting that specifies the condition of the AWS account or Organizational Unit (OU) to be created or updated by a filter.
NONE(None): Deploy to the AWS accounts of the specified Organizational Unit (OU).
INTERSECTION(Intersection): Deploy to the AWS accounts specified by the Accounts parameter from among the AWS accounts of the specified Organizational Unit (OU).
DIFFERENCE(Difference): Deploy to the AWS accounts other than those specified by the Accounts parameter from among the AWS accounts of the specified Organizational Unit (OU). (You can exclude suspended AWS accounts and specific AWS accounts within the OU).
UNION(Union): Default setting of the API. In addition to the AWS accounts of the specified Organizational Unit (OU), deploy to the AWS accounts in other Organizational Units (OUs) specified by the Accounts parameter (You can update individual AWS accounts in another OU in addition to the entire target OU with one request. Account filtering by UNION is not permitted in the Create operation). 		Create, Update, Delete
Accounts * Account numbers
When the PermissionModel is SELF_MANAGED, specify the AWS account numbers where the StackSet will be deployed in an array. 		Create, Update, Delete
Regions * Regions
An array of regions where you are already deployed and want to reflect updates to the StackSet. If there are updates to the StackSet's template (or the template's parameters), all stack instances become OUTDATED before the update, and the stack instances in the regions to be updated are updated. If there are no updates to the StackSet's template (or the template's parameters), the existing stack instances in regions other than those to be updated remain in their current status. 		Create, Update, Delete
OperationPreferences * Deployment options
Settings for how to execute the StackSet's Operation (specified by the following RegionConcurrencyType, RegionOrder, FailureToleranceCount, FailureTolerancePercentage, MaxConcurrentCount, MaxConcurrentPercentage). 		Create, Update, Delete
  RegionConcurrencyType Region Concurrency
Setting whether the StackSet's Operation should be executed simultaneously and in parallel to multiple regions.
SEQUENTIAL: Execute sequentially.
PARALLEL: Execute in parallel. 		Create, Update, Delete
  RegionOrder * Specify regions
An array that sets the order of the regions in which the StackSet's Operation will be executed. 		Create, Update, Delete
  FailureToleranceCount * Failure tolerance Number
The number of AWS accounts per region that are allowed to fail the StackSet's Operation. If the number of failures of the StackSet's Operation exceeds this threshold and stops in a region of a certain AWS account, the Operation is not executed in the following regions. 		Create, Update, Delete
  FailureTolerancePercentage * Failure tolerance Percentage
The percentage of AWS accounts per region that are allowed to fail the StackSet's Operation. If the failure rate of the StackSet's Operation exceeds this threshold and stops in a region of a certain AWS account, the Operation is not executed in the following regions. 		Create, Update, Delete
  MaxConcurrentCount * Maximum concurrent accounts Number
The maximum number of AWS accounts that can execute the StackSet's Operation simultaneously and in parallel. 		Create, Update, Delete
  MaxConcurrentPercentage * Maximum concurrent accounts Percentage
The maximum percentage of AWS accounts that can execute the StackSet's Operation simultaneously and in parallel. 		Create, Update, Delete
OperationId −
An idempotent token that AWS CloudFormation StackSets can recognize to make sure they are not trying to perform the same operation on the StackSet more than once. It's useful when there is a possibility to retry the request. If not specified, it is auto-generated. 		Create, Update, Delete
CallAs −
Specify whether the StackSets are run from the AWS Organizations management account or from a member account that has been delegated permissions by StackSets, when the PermissionModel is SERVICE_MANAGED.
SELF(default): Execute with AWS Organizations management account.
DELEGATED_ADMIN: Execute with a member account that has been delegated permissions by StackSets. 		Create, Update, Delete

List of parameters (configuration items) that can be obtained when referencing a StackSet (DescribeStackSet)

Parameter Name Console Name
Additional Description 		Operations in which the User can Specify Values
StackSetARN * StackSet ARN
ARN of StackSet.arn:aws:cloudformation:[Region Name]:[AWS Account Number]:stackset/[StackSetName]:12345678-1234-1234-1234-123456789012 format.
StackSetId StackSet ID
ID of StackSet.[StackSetName]:12345678-1234-1234-1234-123456789012 format.
StackSetName * StackSet Name
Unique name of the StackSet in the created region. 		Create, Update, Delete
(Only specification for Update, Delete)
Description * StackSet Description
Description of StackSet where the user can note arbitrary information. 		Create, Update
Status * StackSet Status
ACTIVE: StackSet is in operation.
DELETED: StackSet is deleted.
TemplateBody * Template
Content of the template used in StackSet. 		Create, Update
Parameters * Parameters
Parameters of the template used in StackSet. 		Create, Update
  ParameterKey * Key
Key of the template parameters used in StackSet. 		Create, Update
  ParameterValue * Value
Value set for the key of the template parameters used in StackSet. 		Create, Update
  UsePreviousValue −
Specifies whether to use the existing parameter value used by the stack key during stack updates.
True: Use the existing value.
False: Do not use the existing value. 		Create, Update
  ResolvedValue * Resolved value
The value corresponding to the read-only SSM parameter key. Only used with the SSM parameter type of the template. 		Create, Update
Capabilities −
Items that need to be explicitly specified to recognize that the template contains resources with certain features that could affect the AWS account, such as creating IAM users.
CAPABILITY_IAM: Corresponds to the ability to create IAM resources (AWS::IAM::AccessKey, AWS::IAM::Group, AWS::IAM::InstanceProfile, AWS::IAM::Policy, AWS::IAM::Role, AWS::IAM::User, AWS::IAM::UserToGroupAddition etc.).
CAPABILITY_NAMED_IAM: Corresponds to the ability to create IAM resources (AWS::IAM::AccessKey, AWS::IAM::Group, AWS::IAM::InstanceProfile, AWS::IAM::Policy, AWS::IAM::Role, AWS::IAM::User, AWS::IAM::UserToGroupAddition etc.) with custom names.
CAPABILITY_AUTO_EXPAND: Corresponds to the ability to include macros hosted by CloudFormation (AWS::Include, AWS::Serverless). 		Create, Update
AdministrationRoleARN * StackSet admin role ARN
IAM admin role ARN
The ARN of the IAM role used to create and update StackSet in the StackSets admin account. It can be used to specify an IAM role within the StackSets admin account that can manage a specific StackSet. 		Create, Update
ExecutionRoleName −
The name of the IAM role that actually executes the StackSet stack in each target AWS account where the stack is deployed by StackSet. 		Create, Update
StackSetDriftDetectionDetails −
Detailed information about the drift status of the StackSet.
  DriftStatus * Drift status
The status result of drift detection.
DRIFTED: A state where drift (difference from StackSet configuration) has been detected for one or more resources in the stack running in the associated stack instances.
IN_SYNC: A state that matches the StackSet configuration without any drift.
UNKNOWN: A reserved parameter for future use.
NOT_CHECKED: A state where drift detection has not yet been performed.
  DriftDetectionStatus −
The status of the drift detection operation for the StackSet.
COMPLETED: The state in which drift detection was successful for all associated stack instances.
FAILED: The state where the failure of drift detection exceeded the set fault tolerance.
PARTIAL_SUCCESS: The state where the failure of drift detection partially succeeded without exceeding the set fault tolerance.
IN_PROGRESS: The state where drift detection is in progress.
STOPPED: The state where drift detection was stopped by the user.
  LastDriftCheckTimestamp * Last drift check time
Timestamp
  TotalStackInstancesCount −
The total number of stack instances for the StackSet.
  DriftedStackInstancesCount −
The number of stack instances where drift was detected for the StackSet.
  InSyncStackInstancesCount −
The number of stack instances where no drift was detected for the StackSet.
  InProgressStackInstancesCount −
The number of stack instances where drift detection is in progress for the StackSet.
  FailedStackInstancesCount −
The number of stack instances where drift detection failed for the StackSet.
AutoDeployment * Deployment configuration
When the PermissionModel is SERVICE_MANAGED, it sets whether to automatically deploy the StackSet to AWS accounts added later to the organization or organizational unit (OU) specified as the target of the StackSet (set in the following Enabled).
Also, it sets whether to retain the stacks at the time of account deletion (set in the following RetainStacksOnAccountRemoval). 		Create, Update
  Enabled * Automatic deployment
True: Enable automatic deployment.
False: Disable automatic deployment. 		Create, Update
  RetainStacksOnAccountRemoval * Retain stacks on account removal
True: Retain stacks when account is removed.
False: Do not retain stacks when account is removed. 		Create, Update
PermissionModel * Permission model
How to manage and grant permissions to the managing account and the AWS account to be deployed.
SERVICE_MANAGED: Service-managed permissions.
SELF_MANAGED: Self-managed permissions. 		Create, Update
OrganizationalUnitIds −
Array of Organization Root ID or Organizational Unit (OU) to be updated. 		Update
ManagedExecution * Managed execution
Set whether to execute non-conflicting operations simultaneously at the time of StackSets execution, and whether to queue conflicting operations (set in the following Active). 		Create, Update
  Active * Managed execution
True: Execute non-conflicting operations simultaneously at the time of StackSets execution, and queue conflicting operations.
False: Execute one operation at a time in the order requested during StackSets execution. 		Create, Update
Tags * Tags
Tags to attach to the StackSet (set with the following Key and Value). 		Create, Update
  Key * Key
The key of the tag to attach to the StackSet. 		Create, Update
  Value * Value
The value for the key of the tag to attach to the StackSet. 		Create, Update

List of parameters (setting items) that can be obtained when referring to a stack instance (DescribeStackInstance)

Parameter Name Console Name
Additional Description 		Operations in which the User can Specify Values
StackSetId * StackSet ID
ID of the StackSet.[StackSetName]:12345678-1234-1234-1234-123456789012 format.
StackId * Stack ID
ID of the stack instance.arn:aws:cloudformation:[region name]:[AWS account number]:stack/[StackSetName]-12345678-1234-1234-1234-123456789012/12345678-1234-1234-1234-123456789012 format.
Region * AWS Region
Name of the AWS region associated with the stack instance. 		Create, Update
Account * AWS Account
AWS account number associated with the stack instance. 		Create, Update
OrganizationalUnitId −
When the PermissionModel is SERVICE_MANAGED, the Root ID or Organizational Unit (OU) ID specified in DeploymentTargets during the Create or Update operation. 		Create, Update
ParameterOverrides −
Parameters of the template to be overwritten for each stack instance. 		Create, Update
  ParameterKey −
Key of the parameters of the template to be overwritten for each stack instance. 		Create, Update
  ParameterValue −
Value of the parameters of the template to be overwritten for each stack instance. 		Create, Update
  UsePreviousValue −
Specifies whether to use the existing parameter value that the stack is using for the parameter key during stack updates.
True: Use the existing value.
False: Do not use the existing value. 		Create, Update
  ResolvedValue −
Value corresponding to the read-only SSM parameter key. Used only with the SSM parameter type in the template. 		Create, Update
Status −
Status regarding synchronization of StackSet and stack instance.
CURRENT: Latest status in the StackSet.
OUTDATED: Not the latest status in the StackSet. Possible causes include a failure of the stack for the relevant stack instance during an operation (create, update), an operation (create, update) stopping before execution on the relevant stack instance due to a failure of another stack instance, or an operation (create, update) being in progress but not yet executed on the relevant stack instance.
INOPERABLE: The state after an operation (delete) has failed. The relevant stack instance is essentially excluded from subsequent operations (updates), but there may be cases where the stack instance needs to be manually deleted.
StackInstanceStatus −
As of the time of writing this article, it only holds detailed status.
  DetailedStatus * Detailed Status
Detailed status regarding the operation of the stack instance.
PENDING: The state where an operation is not yet executed on the relevant stack instance.
RUNNING: The state where an operation is being executed on the relevant stack instance.
SUCCEEDED: The state where an operation has been executed and succeeded on the relevant stack instance.
FAILED: The state where an operation has been executed and failed on the relevant stack instance.
CANCELLED: The state where an operation was cancelled before execution on the relevant stack instance. There may be reasons such as exceeding fault tolerance in the operation, or manually stopping the operation.
INOPERABLE: The state after an operation (delete) has failed. The relevant stack instance is essentially excluded from subsequent operations (updates), but there may be cases where the stack instance needs to be manually deleted.
StatusReason * Reason for Status
Reason for the status of the stack instance.
DriftStatus * Drift Status
Status of the results of performing drift detection.
DRIFTED: The state where drift (differences from StackSet configuration) has been detected for one or more resources in the stack running in the stack instance.
IN_SYNC: The state where there is no drift and it matches the StackSet configuration.
UNKNOWN: Reserved parameter for future use.
NOT_CHECKED: The state where drift detection has not yet been performed.
LastDriftCheckTimestamp * Last Drift Check Time
Time when the drift detection operation was last performed in the stack instance.
LastOperationId * Last Operation ID
Operation ID of the last performed StackSet operation in the stack instance.
If this value is different between stack instances, it indicates that operations were performed on some stack instances, such as adding stack instances or updating via DeploymentTargets (including AccountFilterType).

References:
Tech Blog with curated related content
AWS Documentation(Working with AWS CloudFormation StackSets - AWS CloudFormation)
AWS CloudFormation API Reference
CloudFormation — Boto3 Docs

Summary

In this article, I summarized the structure and functionality of AWS CloudFormation StackSets, the relationship between the management console and the API, the account filter for the deployment target, and the meaning and role of parameters.

AWS CloudFormation StackSets is a feature that improves the convenience of multi-account management and resource deployment in AWS, but it is important to know in advance the relationship between the AWS management console and API, and the meaning and roles of the parameters of StackSets and stack instances.

As a result, the AWSETs are now available in the AW Management Console, and the StackSet and StackInstance are now available in the AWSETs.

I believe that AWS CloudFormation StackSets have other features that are useful to know in depth in addition to what I have discussed in this article, and I expect that more useful features will be added in future updates.

I will continue to watch for the latest updates and utilization of AWS CloudFormation StackSets.


Written by Hidekazu Konishi

Profile | Privacy Policy | Tech Blog  >  Summary of AWS CloudFormation StackSets Focusing on the Relationship between the Management Console and API, Account Filter, and the Role of Parameters

Copyright © Hidekazu Konishi ( hidekazu-konishi.com ) All Rights Reserved.