Introduction
As organizations grow, the need to separate and isolate environments for security, management, and workloads becomes increasingly important. AWS Organizations provides a framework to achieve this, but it also introduces new challenges – especially when it comes to managing infrastructure consistently across multiple accounts and Regions.
When you’re practicing Infrastructure as Code, this complexity only increases. You often need to deploy the same set of resources across many accounts, and doing so manually is both error-prone and inefficient. This is where CloudFormation StackSets comes in. With StackSets, you can deploy CloudFormation templates to multiple accounts and Regions at once, and even ensure that new accounts automatically receive the same infrastructure.
In this blog post, we’ll start by covering the basics of AWS Organizations to understand its structure and key concepts, and then dive into how to use CloudFormation StackSets effectively in a multi-account environment.
AWS Organizations structure
Before we dive into the infrastructure management with CloudFormation Stacksets, let’s look at some key concepts of the AWS Organization.
An organization is a collection of AWS accounts that are managed centrally and are organized in a hierarchical, tree-like structure with a root at the top. Under the root, you can have accounts or Organizational units. Each organization consists of one management account, zero or more member accounts, zero or more organizational units (OUs), and zero or more policies.
The administrative root is automatically created when you create an organization in AWS and is the starting point for organizing the AWS accounts. Under the root, you can create and organize organizational units (OUs). If you apply a management policy to the root, it will apply to all accounts and OUs, including the management account, but if you apply an authorization policy (a service control policy, for example) to the root, it will be applied to all accounts and OUs except the management account.
An organizational unit (OU) is a group of AWS accounts and/or other OUs. OUs are useful when you need to apply the same controls to a subset of accounts in your organization.
The management account is the AWS account that you use to create the organization. Once designated, you cannot choose another account to be the management account. From this account, you can create other accounts, invite already existing accounts to join the organization, and remove accounts from the organization. All services that can work organization-wide can be deployed in the management account, but if we want separation of duties and to offload the management account, we can designate delegated administrator accounts for the different AWS services. From the management account, you can also attach policies to either the root, a single account, or an OU within the organization.
A member account is an AWS account, other than the management account, that is part of an organization. A member account can belong to only one organization at a time. You can designate member accounts to be delegated administrator accounts.
A delegated administrator is a member account that was designated by the management account to be an administrator either for one or more AWS services or for AWS Organizations.
- Delegated administrator for an AWS service: From these accounts, you can manage AWS services that work organization-wide. These accounts have administrative permissions for a specific service, as well as permissions for AWS Organizations read-only actions.
- Delegated administrator for AWS Organizations: From these accounts, you can manage organization policies and attach them to the root, the OUs, or the accounts within the organization. The management account can control delegation permissions at granular levels.
It is highly recommended to deploy the AWS services in member accounts and not in the management one because the security features like organization service control policies (SCPs) do not restrict any users or roles in the management account.
AWS Services that integrate with AWS Organizations
Here, you can find a list of all AWS services that need to work with AWS Organizations:
AWS services that you can use with AWS Organizations
If you intend to use any of these services, it is recommended to give them trusted access via the management account. By doing that, you let the specified AWS service perform actions on your behalf across multiple accounts in the organization. When a service becomes trusted, it can create an IAM role called a service-linked role in every account in your organization whenever that role is needed.
That role allows the trusted service to do its job. The trusted service only creates service-linked roles when it needs to perform management actions on accounts, and not necessarily in all accounts of the organization. If you want to use the service without giving it trusted access, you will have to manage all the required initialization and creation of IAM roles.
For example, if you want to use AWS Backup to create an organization-wide backup policy, which you want to attach to only one of the OUs in the organization, you will need to give Backup trusted access. This will create a service-linked role in the management account. When you apply the policy to the specified accounts, the same service-linked IAM role will automatically be created only in those accounts. This will allow AWS Backup to operate in those accounts as well.
You can enable/disable trusted access directly in the AWS Organizations console in the management account, but it is highly recommended that you do that in the console of the service that you want to use or with its AWS CLI or API operation equivalents. This lets the trusted service perform any required initialization when enabling trusted access, such as creating any required resources and any required cleanup of resources when disabling trusted access.
Delegated administrator for AWS services
By default, all services that can be used organization-wide can be deployed only in the management account. However, as we already mentioned, it is a best practice to keep the management of AWS services out of the management account. To do that, you have to delegate administrator accounts for each service. You should check the AWS documentation on how many accounts can be assigned as administrators for each service.
By registering a member account as a delegated administrator for an AWS service, you enable that account to have some administrative permissions for that service, as well as permissions for AWS Organizations read-only actions. Also, you have to first enable trusted access for the service that you want to create a delegated administrator for.
To use the example with AWS Backup, when you enable trusted access, you will be able to deploy a backup policy in the management account, which will be able to create backups in member accounts. But if you enable some other account to be the delegated administrator for AWS Backup, you will be able to deploy the backup policy in that account and manage it from there.
Resource-based delegation policies
Sometimes, some of the services that work with AWS Organizations need to execute AWS Organizations API actions (e.g., organizations: AttachPolicy, organizations: ListAccounts). For example, AWS Backup service needs permissions such as organizations: CreatePolicy and organizations: AttachPolicy. To grant those permissions, you need to create a resource-based delegation policy in the management account in the AWS Organization service’s settings. There you have to edit the Delegated administrator for AWS Organizations section and add a JSON-based policy that allows the delegated administrator to perform those actions.
CloudFormation Stack Sets
When you are using AWS Organizations, it quickly becomes visible that you need to deploy resources to more than one account and to more than one region. When you have many accounts or are using a few different regions (either for compliance or for high availability purposes), this can become a daunting task. If you are already making use of CloudFormation as an infrastructure-as-code solution, you will find it useful to start using CloudFormation’s Stack Sets.
AWS CloudFormation StackSets extends the capability of stacks by allowing you to create/update/delete stacks across multiple accounts and AWS Regions with a single operation. From an administrator account, you have to define a CloudFormation template and use it as the basis for provisioning stacks into selected target accounts across specified AWS Regions.
CloudFormation StackSets is a separate service listed in the AWS Services that integrate with AWS Organizations list.
As such, it needs trusted access, and you can assign a delegated administrator for it. This lets you deploy stacksets from member accounts in your organization.
Enabling trusted access for StackSets lets you deploy stack instances to member accounts in your organization. You don’t have to create the necessary AWS Identity and Access Management roles; StackSets creates the IAM role in each member account on your behalf.
You can assign up to 5 delegated administrators for StackSets.
Key Concepts of StackSets
An administrator account is the AWS account in which you create StackSets. You can manage a StackSet from the AWS administrator account that created the StackSet.
A target account is the account into which you create, update, or delete one or more stacks in your StackSet.
A StackSet serves as a container for multiple stacks that are deployed across specified AWS accounts and Regions. Each stack is based on the same CloudFormation template, but you can customize individual stacks using parameters.
A stack instance is a reference to a stack in a target account within a region. A stack instance can exist without a stack. For example, if the stack couldn’t be created for some reason, the stack instance shows the reason for the stack creation failure. A stack instance is associated with only one StackSet.
StackSet Operations
The following picture illustrates the possible stackset operations.
You create stacks by specifying a CloudFormation template body (what stack you want to deploy in each stack instance), the target accounts or OUs, and the regions that you want to deploy the stack to.
You update stacks by changing settings in the template body, adding/deleting target accounts, and adding/deleting more regions.
You can delete stacks by removing target accounts and regions. Also, by choosing the Retain Stacks option, you can remove a stack from your stack set and manage it separately.
You can delete your StackSet only when there are no stack instances in it.
Each stack instance has a status code. You can check each status code’s meaning here: Stack instance status codes.
The status code for a stack instance can be seen in the StackSets console > choose your stackset > Stack instances tab. Sometimes, when a stack instance is in INOPERABLE state, for example, you might have to troubleshoot why and manually delete the instance to continue updating your StackSet.
Permission models for StackSets
There are two permission models for stacksets – service-managed and self-managed. Each of them comes with its own set of restrictions and considerations, and comes in handy in different use cases. We will dive into each of them separately.
Service-managed Stack sets
With service-managed permissions, you can deploy stack instances to accounts managed by AWS Organizations. Using this permissions model, you don’t have to create the necessary IAM roles; StackSets creates the IAM roles on your behalf. With this model, you can also turn on automatic deployments to accounts that you add to your organization in the future.
Before deploying a service-managed stackset, you have to be aware of the considerations. Some of the more important ones are:
- Stacksets with this permission model are created in the management account, even if they are created by the delegated administrators.
- CloudFormation doesn’t deploy stacks to the organization’s management account, even if the management account is in your organization or in an OU in your organization.
- With service-managed stacksets, you must target an OU or the whole organization. You can target both Accounts and OUs by using the AccountFilterType property. It has the following values:
- INTERSECTION: StackSet deploys to the accounts specified in the Accounts property.
- DIFFERENCE: StackSet deploys to the OU, excluding the accounts specified in the Accounts property.
- UNION: StackSet deploys to the OU, and the accounts specified in the Accounts property.
However, UNION is not supported for create operations when using StackSet as a resource or the CreateStackInstances API. If that is the case, and you want to deploy some resources in all accounts, including the management account, it will be impossible to achieve this with a service-managed stackset only. You will have to use a self-managed stack set, which we cover later in this post.
Here is an example of a CloudFormation template that creates a service-managed stackset that deploys AWS Config Recorder and Delivery channel across all member accounts in the following regions: eu-central-1 and eu-west-1.
Resources:
ConfigStackSet:
Type: AWS::CloudFormation::StackSet
Properties:
StackSetName: ConfigStackSet
Description: StackSet to deploy AWS Config recorder and delivery channel in each acc
ount in each region.
PermissionMode: SERVICE_MANAGED
Parameters:
- ParameterKey: ConfigBucketName
ParameterValue: <configBucketName>
AutoDeployment:
Enabled: true
RetainStacksOnAccountRemoval: false
ManagedExecution:
Active: true
StackInstancesGroup:
- DeploymentTargets:
OrganizationalUnitIds:
- <RootID>
Regions:
- eu-central-1
- eu-west-1
CallAs: DELEGATED_ADMIN
TemplateBody: |
Parameters:
ConfigBucketName:
Type: String
Description: The S3 bucket for AWS Config.
Resources:
ConfigDeliveryChannel:
Type: AWS::Config::DeliveryChannel
Properties:
Name: ConfigDeliveryChannel
S3BucketName: !Ref ConfigBucketName
ConfigRecorder:
Type: AWS::Config::ConfigurationRecorder
Properties:
Name: ConfigRecorder
RoleARN:
Fn::Sub:
"arn:${AWS::Partition}:iam::${AWS::AccountId}:role/aws-service-role/config.amazonaws.com/AWSServiceRoleForConfig"In this example of a service-managed stackset, we are deploying AWS Config in all accounts (except for the management account), in the specified regions.
Some important notes:
- When you are creating a stackset from the delegated admin for StackSets, you should use that property: CallAs: DELEGATED_ADMIN .
- The property AutoDeployment can only be used when the permission model is SERVICE_MANAGED. You can specify whether you want to automatically create a stack instance for newly added member accounts, as well as whether to retain stacks on account removal.
- When creating a service-managed stackset, you must specify the OrganizationalUnitIds property.
Self-managed Stack sets
With service-managed stacksets, you cannot always target specific accounts, only OUs and the whole organization. If you want to target a specific account, and you cannot use service-managed stacksets, this is when self-managed stacksets come in handy. However, self-managed stacksets come with a new set of restrictions. While service-managed stacksets create all the necessary IAM roles, with self-managed ones, you have to deal with this yourself.
Execution and Administration Roles
To deploy a self-managed stackset, you need two types of IAM roles: execution and administration roles.
In the administrator account, you need to create an IAM role named AWSCloudFormationStackSetAdministrationRole. You can use the role that Amazon documentation provides:
Resources:
AdministrationRole:
Type: AWS::IAM::Role
Properties:
RoleName: !Ref AdministrationRoleName
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Principal:
Service: cloudformation.amazonaws.com
Action:
- sts:AssumeRole
Path: /
Policies:
- PolicyName: AssumeRole-AWSCloudFormationStackSetExecutionRole
PolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Action:
- sts:AssumeRole
Resource:
- !Sub 'arn:*:iam::*:role/${ExecutionRoleName}'This role is assumed by CloudFormation in the administrator account, and it is allowed to assume the execution role in each target account. The execution role is the one that has the actual permissions to create/update/delete AWS resources in the target account.
In each target account, you have to create a service role named AWSCloudFormationStackSetExecutionRole that trusts the administrator account. The role must have this exact name.
Amazon documentation provides the following role:
Resources:
ExecutionRole:
Type: AWS::IAM::Role
Properties:
RoleName: !Ref ExecutionRoleName
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Principal:
AWS:
- !Ref AdministratorAccountId
Action:
- sts:AssumeRole
Path: /
ManagedPolicyArns:
- !Sub arn:${AWS::Partition}:iam::aws:policy/AdministratorAccessThe target account service role requires permissions to perform any operations that are specified in your CloudFormation template. Your target account always needs full CloudFormation permissions, which include permissions to create, update, delete, and describe stacks.
Be aware that this template grants administrator access. After you use the template to create a target account execution role, you must scope the permissions in the policy statement to the types of resources that you are creating by using StackSets.
Now that we know what IAM roles we need, let’s look at an example of a self-managed stackset template that deploys SNS Topics in only one account but in different regions. (SNS topics can work cross-account, but not cross-region.)
In this template, we have added DependsOn: StackSetAdministrationRole because self-managed stacksets need to be given execution and administration roles.
Resources:
SNSStackSet:
Type: AWS::CloudFormation::StackSet
DependsOn: StackSetAdministrationRole
Properties:
StackSetName: SNSStackSet
Description: StackSet to deploy SNS Topics in different regions.
PermissionModel: SELF_MANAGED
AdministrationRoleARN: <stacksetAdminRoleArn>
ExecutionRoleName: <stacksetExecRoleName>
Parameters:
- ParameterKey: SnsKmsKeyArn
ParameterValue: <snsKmsKeyArn>
ManagedExecution:
Active: true
StackInstancesGroup:
- DeploymentTargets:
Accounts:
- <target account ID>
Regions:
- eu-central-1
- eu-west-1
TemplateBody: |
Parameters:
SnsKmsKeyArn:
Type: String
Description: The KMS key for encrypting the SNS topic.
Resources:
SNSTopic:
Type: AWS::SNS::Topic
Properties:
TopicName: !Sub "Notifications-${AWS::Region}"
KmsMasterKeyId: !Ref SnsKmsKeyArnAs opposed to service-managed stacksets, where you must use the OrganizationalUnitIds property, with self-managed ones, you must specify either the Accounts or AccountsUrl property, but not both.
Also, since self-managed stacksets target specific accounts, AutoDeployment property is not applicable here, therefore not used.
There are two properties of the StackSet resource that we haven’t seen in those examples. One of them is the Capabilities property. It can take the following values – CAPABILITY_IAM or CAPABILITY_NAMED_IAM. If your template includes IAM resources, you can specify either capability. If your template includes custom names for IAM resources, you must specify CAPABILITY_NAMED_IAM.
The other one is the OperationPreferences property. With it, you can specify your preferences for the following options on how CloudFormation should perform a StackSet operation:
- ConcurrencyMode
- FailureToleranceCount
- FailureTolerancePercentage
- MaxConcurrentCount
- MaxConcurrentPercentag
- RegionConcurrencyType
- RegionOrder
Conclusion
CloudFormation StackSets is a powerful service for deploying consistent infrastructure across multiple AWS accounts and Regions. Like many AWS tools, it comes with its own specifics – and choosing between service-managed and self-managed StackSets depends on your use case.
- Service-managed StackSets let you target OUs or the entire organization, automatically include new accounts, and have AWS handle IAM role management – but they cannot deploy to the management account.
- Self-managed StackSets require you to target accounts explicitly and set up IAM roles yourself, but they provide more flexibility, including the ability to deploy to the management account.
By understanding these differences and aligning them with your organizational structure, you can strike the right balance between automation and control. Together with AWS Organizations, StackSets give you the scalability and consistency needed to manage infrastructure across a large, multi-account AWS environment – reducing manual effort while improving security and governance.
Read more about CloudFormation in our blog: Infrastructure as Code on AWS: An Introduction to CloudFormation.