Deploy AWS CloudFormation StackSet Instances

The aws:cloudformation/stackSetInstance:StackSetInstance resource, part of the Pulumi AWS provider, deploys a CloudFormation StackSet to specific accounts and regions, creating stack instances that provision the StackSet’s resources. This guide focuses on two capabilities: single-account deployment and organizational unit targeting.

Stack instances require an existing StackSet and IAM execution roles in target accounts. All target accounts must have an execution role that trusts the administrator account and has permissions to create the resources defined in the StackSet template. The examples are intentionally small. Combine them with your own StackSets and IAM configuration.

Deploy a stack instance to a specific account and region

Most deployments target a specific AWS account and region, creating a single stack instance in that location.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const example = new aws.cloudformation.StackSetInstance("example", {
    accountId: "123456789012",
    stackSetInstanceRegion: "us-east-1",
    stackSetName: exampleAwsCloudformationStackSet.name,
});

import pulumi
import pulumi_aws as aws

example = aws.cloudformation.StackSetInstance("example",
    account_id="123456789012",
    stack_set_instance_region="us-east-1",
    stack_set_name=example_aws_cloudformation_stack_set["name"])

package main

import (
	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/cloudformation"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := cloudformation.NewStackSetInstance(ctx, "example", &cloudformation.StackSetInstanceArgs{
			AccountId:              pulumi.String("123456789012"),
			StackSetInstanceRegion: pulumi.String("us-east-1"),
			StackSetName:           pulumi.Any(exampleAwsCloudformationStackSet.Name),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() => 
{
    var example = new Aws.CloudFormation.StackSetInstance("example", new()
    {
        AccountId = "123456789012",
        StackSetInstanceRegion = "us-east-1",
        StackSetName = exampleAwsCloudformationStackSet.Name,
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.cloudformation.StackSetInstance;
import com.pulumi.aws.cloudformation.StackSetInstanceArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var example = new StackSetInstance("example", StackSetInstanceArgs.builder()
            .accountId("123456789012")
            .stackSetInstanceRegion("us-east-1")
            .stackSetName(exampleAwsCloudformationStackSet.name())
            .build());

    }
}

resources:
  example:
    type: aws:cloudformation:StackSetInstance
    properties:
      accountId: '123456789012'
      stackSetInstanceRegion: us-east-1
      stackSetName: ${exampleAwsCloudformationStackSet.name}

The stackSetName references an existing StackSet. The accountId and stackSetInstanceRegion specify where to deploy the stack. CloudFormation provisions the StackSet’s resources in the target account using the execution role configured in that account.

Deploy across organizational units automatically

Organizations with multiple accounts can target entire organizational units, automatically provisioning stacks in all member accounts.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const example = new aws.cloudformation.StackSetInstance("example", {
    deploymentTargets: {
        organizationalUnitIds: [exampleAwsOrganizationsOrganization.roots[0].id],
    },
    stackSetInstanceRegion: "us-east-1",
    stackSetName: exampleAwsCloudformationStackSet.name,
});

import pulumi
import pulumi_aws as aws

example = aws.cloudformation.StackSetInstance("example",
    deployment_targets={
        "organizational_unit_ids": [example_aws_organizations_organization["roots"][0]["id"]],
    },
    stack_set_instance_region="us-east-1",
    stack_set_name=example_aws_cloudformation_stack_set["name"])

package main

import (
	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/cloudformation"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := cloudformation.NewStackSetInstance(ctx, "example", &cloudformation.StackSetInstanceArgs{
			DeploymentTargets: &cloudformation.StackSetInstanceDeploymentTargetsArgs{
				OrganizationalUnitIds: pulumi.StringArray{
					exampleAwsOrganizationsOrganization.Roots[0].Id,
				},
			},
			StackSetInstanceRegion: pulumi.String("us-east-1"),
			StackSetName:           pulumi.Any(exampleAwsCloudformationStackSet.Name),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() => 
{
    var example = new Aws.CloudFormation.StackSetInstance("example", new()
    {
        DeploymentTargets = new Aws.CloudFormation.Inputs.StackSetInstanceDeploymentTargetsArgs
        {
            OrganizationalUnitIds = new[]
            {
                exampleAwsOrganizationsOrganization.Roots[0].Id,
            },
        },
        StackSetInstanceRegion = "us-east-1",
        StackSetName = exampleAwsCloudformationStackSet.Name,
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.cloudformation.StackSetInstance;
import com.pulumi.aws.cloudformation.StackSetInstanceArgs;
import com.pulumi.aws.cloudformation.inputs.StackSetInstanceDeploymentTargetsArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var example = new StackSetInstance("example", StackSetInstanceArgs.builder()
            .deploymentTargets(StackSetInstanceDeploymentTargetsArgs.builder()
                .organizationalUnitIds(exampleAwsOrganizationsOrganization.roots()[0].id())
                .build())
            .stackSetInstanceRegion("us-east-1")
            .stackSetName(exampleAwsCloudformationStackSet.name())
            .build());

    }
}

resources:
  example:
    type: aws:cloudformation:StackSetInstance
    properties:
      deploymentTargets:
        organizationalUnitIds:
          - ${exampleAwsOrganizationsOrganization.roots[0].id}
      stackSetInstanceRegion: us-east-1
      stackSetName: ${exampleAwsCloudformationStackSet.name}

The deploymentTargets property replaces accountId when deploying to organizational units. CloudFormation creates stack instances in all accounts within the specified OUs. The organizationalUnitIds array can include multiple OUs; StackSets automatically handles account discovery and deployment.

Beyond these examples

These snippets focus on specific stack instance features: single-account deployment and organizational unit targeting. They’re intentionally minimal rather than full multi-account infrastructure modules.

The examples require pre-existing infrastructure such as CloudFormation StackSets with defined templates, IAM execution roles in target accounts with trust relationships, and AWS Organizations structure for OU deployments. They focus on deploying stack instances rather than creating StackSets or configuring IAM.

To keep things focused, common stack instance patterns are omitted, including:

Parameter overrides (parameterOverrides)
Stack retention during destroy (retainStack)
Delegated administrator mode (callAs)
Operation preferences for deployment control

These omissions are intentional: the goal is to illustrate how stack instances are deployed, not provide drop-in multi-account modules. See the CloudFormation StackSetInstance resource reference for all available configuration options.

Let's deploy AWS CloudFormation StackSet Instances

Get started with Pulumi Cloud, then follow our quick setup guide to deploy this infrastructure.

Try Pulumi Cloud for FREE

Frequently Asked Questions

IAM & Permissions

What IAM setup is required in target accounts for StackSet instances?

Each target account must have an IAM execution role with a trust relationship to the administrative account. The role name must match the execution_role_name configured in the StackSet resource. The execution role needs permissions to manage resources defined in the template, plus CloudFormation StackSets permissions (cloudformation:, s3:, sns:* at minimum).

Can StackSets deploy to the organization management account?

No, StackSets doesn’t deploy stack instances to the organization management account, even if it’s included in an OU in your organization.

Deployment & Configuration

How do I deploy StackSet instances across AWS Organizations?

Use deploymentTargets with organizationalUnitIds instead of specifying individual account IDs. This deploys to all accounts in the specified OUs.

What's the difference between SELF and DELEGATED_ADMIN for callAs?

SELF (default) means you’re acting as an account administrator in the organization’s management account. DELEGATED_ADMIN means you’re acting as a delegated administrator in a member account.

Can I override StackSet parameters for a specific instance?

Yes, use parameterOverrides to provide a key-value map of parameters that override the StackSet defaults for this instance.

Lifecycle & State Management

How do I retain the Stack when destroying a StackSet instance?

Set retainStack to true and apply the change before running the destroy operation. This removes the instance from the StackSet while keeping the Stack and its resources. Note that you cannot reassociate a retained Stack with a StackSet later.

What properties can't I change after creating a StackSet instance?

The following properties are immutable and require resource recreation if changed: accountId, stackSetInstanceRegion, stackSetName, and deploymentTargets.

Why should I use stackSetInstanceRegion instead of region?

The region property is deprecated. Use stackSetInstanceRegion instead to specify the target AWS Region for the Stack.

Import & Troubleshooting

How do I import existing StackSet instances?

Import format depends on deployment type:

Account deployment: stackSetName,accountId,region
Organizations deployment: stackSetName,ou-id1/ou-id2,region
Delegated admin: Add ,DELEGATED_ADMIN to either format above

Using a different cloud?

Explore integration guides for other cloud providers:

Azure Guides GCP Guides