Menu
AWS CloudFormation
User Guide (API Version 2010-05-15)

Prerequisites: Granting Permissions for Stack Set Operations

To start working with AWS CloudFormation StackSets, you should understand how AWS CloudFormation works, and have some experience working with AWS CloudFormation templates and stacks.

Because stack sets perform stack operations across multiple accounts, before you can get started creating your first stack set you need to have the necessary permissions defined in your AWS accounts. To set up the necessary permissions:

  1. Determine which AWS account is the administrator account.

    Stack sets are created in this administator account. A target account is the account in which you create individual stacks that belong to a stack set.

  2. Determine how you want to structure permissions for the administrator account:

    • Define permissions for the administrator account itself.

      Give all users in the administrator account the ability to create and update all the stack sets managed through the administrator account.

    • Define permissions for multiple administrators.

      Restrict specific sets of users to creating and updating only certain stack sets managed in the administrator account. For example, you might want multiple groups of users to manage stack sets using the same administrator account, but control which stack sets each group can create or update.

  3. Follow the instructions in next sections to create the necessary roles.

    These roles will set up the correct administrator and target account trust relationship, based on which permissions structure you need.

    Ensure that the roles that you create in the target account has permissions for AWS CloudFormation to work on the resources that you have defined in your template.

Define Permissions for the Administrator Account

To give all users in the administrator account the ability to create and update all the stack sets managed through that account, create IAM service roles for your administrator and target accounts.

Your administrator account and target accounts must have service roles configured that create a trust relationship between the accounts, and grant the target accounts permission to create and manage the resources described in your template.

If you structure your permissions this way, users do not pass an administrator role when creating or updating stack sets.


                 Set up a trust relationship between the administrator account and the target accounts. Any user in the adminstrator account can then create any stack set.

Set up required service roles

  1. In the administrator account, create an IAM role named AWSCloudFormationStackSetAdministrationRole. You can do this by creating a stack from the following AWS CloudFormation template, available online at https://s3.amazonaws.com/cloudformation-stackset-sample-templates-us-east-1/AWSCloudFormationStackSetAdministrationRole.yml. The role created by this template enables the following policy on your administrator account.

    { "Version": "2012-10-17", "Statement": [ { "Action": [ "sts:AssumeRole" ], "Resource": [ "arn:aws:iam::*:role/AWSCloudFormationStackSetExecutionRole" ], "Effect": "Allow" } ] }

    The following trust relationship is created by the preceding template.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "cloudformation.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }
  2. In each target account, create a service role named AWSCloudFormationStackSetExecutionRole that trusts the administrator account. You can do this by creating a stack from the following AWS CloudFormation template, available online at https://s3.amazonaws.com/cloudformation-stackset-sample-templates-us-east-1/AWSCloudFormationStackSetExecutionRole.yml. When you use this template, you are prompted to provide the name of the administrator account with which your target account must have a trust relationship.

    Important

    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.

    The target account service role requires permissions to perform any operations that are specified in your AWS CloudFormation template. For example, if your template is creating an S3 bucket, then you need permissions to create new objects for S3. Your target account always needs full AWS CloudFormation permissions, which include permissions to create, update, delete, and describe stacks. The role created by this template enables the following policy on a target account.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "*", "Resource": "*" } ] }

    The following example shows a policy statement with the minimum permissions for StackSets to work. To create stacks in target accounts that use resources from services other than AWS CloudFormation, you must add those service actions and resources to the AWSCloudFormationStackSetExecutionRole policy statement for each target account.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "cloudformation:*", "s3:*", "sns:*" ], "Resource": "*" } ] }

    The following trust relationship is created by the template. The administrator account's ID is shown as admin_account_id.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::admin_account_id:root" }, "Action": "sts:AssumeRole" } ] }

    You can configure the trust relationship of an existing target account execution role to trust a specific role in the administrator account. If you delete the role in the administrator account, and create a new one to replace it, you must configure your target account trust relationships with the new administrator account role, represented by admin_account_id in the preceding example.

Define Permissions for Multiple Administrators

Use customized administrator roles to control which users can perform stack set operations in which target accounts. You might want to control which users of the administrator account can perform stack set operations in which target accounts. To do this, you create a trust relationship between each target account and a specific customized administration role, rather than the administrator account itself. You then enable specific users to use the appropriate customized administration role when performing stack set operations in a specific target account.

For example, you can create Role A and Role B within your administrator account. You can give Role A permissions to access target account 1 through account 8. You can give Role B permissions to access target account 9 through account 16.


                 Set up a trust relationship between a customized administrator role and the target accounts. The user then passes that role when creating the stack set.

Setting up the necessary permissions involves defining a customized administrator role, creating a service role for the target account, and granting users permission to pass the customized administrator role when performing stack set operations.

In general, here's how it works once you have the necessary permissions in place: When creating a stack set, the user must specify a customized administrator role to associate with the stack set. The user must have permission to pass the role to AWS CloudFormation. In addition, the customized administrator role must have a trust relationship with the target accounts specified for the stack set. AWS CloudFormation creates the stack set and associates the customized administrator role with it. When updating a stack set, the user has the choice of specifying a customized administrator role. If they specify a customized administrator role, AWS CloudFormation uses that role to update the stack, subject to the requirements above. If the user does not specify a customized administrator role, AWS CloudFormation performs the update using the customized administrator role previously associated with the stack set, so long as the user has permissions to perform operations on that stack set.

Set up permissions for multiple administrators

  1. For each stack set, create a customized administrator role with permissions to assume the AWSCloudFormationStackSetExecutionRole service role in the target accounts.

    Create an IAM service role with a custom name, using the following permissions policy:

    { "Version": "2012-10-17", "Statement": [ { "Action": [ "sts:AssumeRole" ], "Resource": [ "arn:aws:iam::target_account_id:role/AWSCloudFormationStackSetExecutionRole" ], "Effect": "Allow" } ] }

    Or, if you want to specify all target accounts, use the following permissions policy:

    { "Version": "2012-10-17", "Statement": [ { "Action": [ "sts:AssumeRole" ], "Resource": [ "arn:aws:iam::*:role/AWSCloudFormationStackSetExecutionRole" ], "Effect": "Allow" } ] }

    You must provide the following trust policy when you create the role to define the trust relationship:

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "cloudformation.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }
  2. In each target account, create a service role named AWSCloudFormationStackSetExecutionRole that trusts the customized administration role you want to use with this account.

    Important

    You must scope the permissions in the policy statement to the types of resources that you are creating by using StackSets.

    The target account service role requires permissions to perform any operations that are specified in your AWS CloudFormation template. For example, if your template is creating an S3 bucket, then you need permissions to create new objects in S3. Your target account always needs full AWS CloudFormation permissions, which include permissions to create, update, delete, and describe stacks.

    The following example shows a policy statement with the minimum permissions for StackSets to work. To create stacks in target accounts that use resources from services other than AWS CloudFormation, you must add those service actions and resources to the AWSCloudFormationStackSetExecutionRole permissions policy statement for each target account.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "cloudformation:*", "s3:*", "sns:*" ], "Resource": "*" } ] }

    You must provide the following trust policy when you create the role to define the trust relationship:

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::admin_account_id:role/customized_admin_role" }, "Action": "sts:AssumeRole" } ] }
  3. Allow users to pass the customized administrator role when performing stack set operations.

    Attach an IAM permissions policy to users or groups that allows them to pass the appropriate customized administrator role when creating or updating specific stack sets. For more information, see Granting a User Permissions to Pass a Role to an AWS Service. In the example below, customized_admin_role refers to the administrator role the user needs to pass.

    { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iam:GetRole", "iam:PassRole" ], "Resource": "arn:aws:iam::*:role/customized_admin_role" }] }