Deploy AWS CloudFormation StackSet Instances

The aws:cloudformation/stackSetInstance:StackSetInstance resource, part of the Pulumi AWS provider, deploys a CloudFormation stack instance from a StackSet into target accounts and regions. This guide focuses on two capabilities: single-account deployment and organization-wide deployment via OUs.

Stack instances depend on an existing StackSet and require IAM execution roles in all target accounts. These roles must trust the administrative account and have 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

Most deployments target a specific AWS account and region, creating a single stack instance that provisions the StackSet’s resources there.

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. CloudFormation creates the stack in the target account using the execution role configured in the StackSet definition.

Deploy across organizational units automatically

Organizations with multiple accounts often deploy infrastructure across entire organizational units rather than individual 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 automatically provisions stacks to all accounts within the specified OUs. This approach scales to hundreds of accounts without listing each one individually.

Beyond these examples

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

The examples require pre-existing infrastructure such as CloudFormation StackSets, IAM execution roles in target accounts, and AWS Organizations with organizational units. They focus on deploying stack instances rather than creating the underlying StackSets or IAM configuration.

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

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

These omissions are intentional: the goal is to illustrate how stack instance deployment is wired, 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?

Each target account must have an IAM execution role matching the name configured in the StackSet’s executionRoleName. This role needs a trust relationship with the administrative account and permissions to manage the resources defined in your template. The schema includes a complete IAM setup example showing the required trust policy and minimum execution permissions.

Stack Lifecycle & Retention

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

Set retainStack to true and apply the change before running the destroy operation. This removes the instance from StackSet management while keeping the underlying CloudFormation stack and its resources.

Can I reassociate a retained stack with a StackSet?

No, retained stacks cannot be reassociated with their original StackSet or added to a new StackSet. Once retained, they’re permanently detached from StackSet management.

Configuration & Deployment

How do I deploy StackSet instances across multiple AWS accounts using Organizations?

Use deploymentTargets with organizationalUnitIds to specify which organizational units should receive the stack instances. Note that StackSets won’t deploy to the organization management account, even if it’s included in the specified OUs.

Should I use region or stackSetInstanceRegion?

Use stackSetInstanceRegion. The region property is deprecated and will be removed in a future version.

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.

Property Constraints

What properties can't be changed after creating a StackSet instance?

The following properties are immutable: accountId, stackSetInstanceRegion, stackSetName, and deploymentTargets. Changing any of these requires recreating the instance.

Can I override parameters from the parent StackSet?

Yes, use parameterOverrides to provide a key-value map of parameters that override the StackSet’s default values for this specific instance.

Using a different cloud?

Explore integration guides for other cloud providers:

Azure Guides GCP Guides