or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

change-sets.mdclient-configuration.mddrift-detection.mdgenerated-templates.mdindex.mdpagination-waiters.mdresource-type-registry.mdstack-information.mdstack-management.mdstack-refactoring.mdstack-sets.mdtemplate-operations.md
tile.json

stack-sets.mddocs/

Stack Sets

Multi-account and multi-region stack management through CloudFormation StackSets.

Capabilities

Create Stack Set

Creates a stack set for deploying stacks across multiple accounts and regions.

/**
 * Creates a stack set for multi-account and multi-region deployments
 * Defines template and permissions for stack instances
 */
class CreateStackSetCommand {
  constructor(input: CreateStackSetCommandInput);
}

interface CreateStackSetCommandInput {
  /** Unique name for the stack set */
  StackSetName: string;
  
  /** CloudFormation template as JSON/YAML string */
  TemplateBody?: string;
  
  /** S3 URL containing the CloudFormation template */
  TemplateURL?: string;
  
  /** Stack set description */
  Description?: string;
  
  /** Template parameters */
  Parameters?: Parameter[];
  
  /** IAM capabilities required by template */
  Capabilities?: Capability[];
  
  /** Resource tags for all stack instances */
  Tags?: Tag[];
  
  /** IAM service role for stack set operations */
  AdministrationRoleARN?: string;
  
  /** Execution role name for target accounts */
  ExecutionRoleName?: string;
  
  /** Permission model for stack set operations */
  PermissionModel?: PermissionModels;
  
  /** Auto-deployment configuration */
  AutoDeployment?: AutoDeployment;
  
  /** Call context for Organizations integration */
  CallAs?: CallAs;
  
  /** Unique identifier for idempotency */
  ClientRequestToken?: string;
  
  /** Managed execution configuration */
  ManagedExecution?: ManagedExecution;
}

interface CreateStackSetCommandOutput {
  /** Unique stack set identifier */
  StackSetId?: string;
}

interface AutoDeployment {
  /** Enable automatic deployment to new accounts */
  Enabled?: boolean;
  
  /** Retain stacks when accounts are removed from OU */
  RetainStacksOnAccountRemoval?: boolean;
}

interface ManagedExecution {
  /** Enable managed execution */
  Active?: boolean;
}

type PermissionModels = 
  | "SERVICE_MANAGED"
  | "SELF_MANAGED";

type CallAs = 
  | "SELF"
  | "DELEGATED_ADMIN";

Usage Examples:

import { 
  CloudFormationClient, 
  CreateStackSetCommand,
  CreateStackInstancesCommand
} from "@aws-sdk/client-cloudformation";

const client = new CloudFormationClient({ region: "us-east-1" });

// Create self-managed stack set
const createStackSetCommand = new CreateStackSetCommand({
  StackSetName: "cross-account-vpc",
  Description: "VPC configuration for multiple accounts",
  TemplateBody: JSON.stringify({
    AWSTemplateFormatVersion: "2010-09-09",
    Parameters: {
      VpcCidr: {
        Type: "String",
        Default: "10.0.0.0/16"
      }
    },
    Resources: {
      MyVPC: {
        Type: "AWS::EC2::VPC",
        Properties: {
          CidrBlock: { Ref: "VpcCidr" }
        }
      }
    }
  }),
  Parameters: [
    { ParameterKey: "VpcCidr", ParameterValue: "10.0.0.0/16" }
  ],
  PermissionModel: "SELF_MANAGED",
  AdministrationRoleARN: "arn:aws:iam::123456789012:role/AWSCloudFormationStackSetAdministrationRole",
  ExecutionRoleName: "AWSCloudFormationStackSetExecutionRole",
  Tags: [
    { Key: "Purpose", Value: "NetworkingInfrastructure" }
  ]
});

const stackSet = await client.send(createStackSetCommand);
console.log("Stack Set ID:", stackSet.StackSetId);

// Create service-managed stack set with Organizations
const orgStackSetCommand = new CreateStackSetCommand({
  StackSetName: "org-security-baseline",
  Description: "Security baseline for all Organization accounts",
  TemplateURL: "https://my-bucket.s3.amazonaws.com/security-baseline.yaml",
  PermissionModel: "SERVICE_MANAGED",
  AutoDeployment: {
    Enabled: true,
    RetainStacksOnAccountRemoval: false
  },
  ManagedExecution: {
    Active: true
  },
  CallAs: "DELEGATED_ADMIN"
});

await client.send(orgStackSetCommand);

Update Stack Set

Updates an existing stack set template, parameters, or configuration.

/**
 * Updates stack set template, parameters, or operational settings
 * Changes apply to future stack instance operations
 */
class UpdateStackSetCommand {
  constructor(input: UpdateStackSetCommandInput);
}

interface UpdateStackSetCommandInput {
  /** Name of the stack set to update */
  StackSetName: string;
  
  /** Updated CloudFormation template */
  TemplateBody?: string;
  
  /** S3 URL containing updated template */
  TemplateURL?: string;
  
  /** Use previous template if no new template provided */
  UsePreviousTemplate?: boolean;
  
  /** Updated parameters */
  Parameters?: Parameter[];
  
  /** Updated capabilities */
  Capabilities?: Capability[];
  
  /** Updated tags */
  Tags?: Tag[];
  
  /** Preference for operational settings */
  OperationPreferences?: StackSetOperationPreferences;
  
  /** Updated administration role */
  AdministrationRoleARN?: string;
  
  /** Updated execution role name */
  ExecutionRoleName?: string;
  
  /** Deployment targets for update */
  DeploymentTargets?: DeploymentTargets;
  
  /** Permission model changes */
  PermissionModel?: PermissionModels;
  
  /** Auto-deployment configuration updates */
  AutoDeployment?: AutoDeployment;
  
  /** Call context */
  CallAs?: CallAs;
  
  /** Updated managed execution */
  ManagedExecution?: ManagedExecution;
  
  /** Accounts for update operation */
  Accounts?: string[];
  
  /** Regions for update operation */
  Regions?: string[];
  
  /** Operation ID for idempotency */
  OperationId?: string;
}

interface UpdateStackSetCommandOutput {
  /** Operation ID for the update */
  OperationId?: string;
}

interface StackSetOperationPreferences {
  /** Order of region deployment */
  RegionConcurrencyType?: RegionConcurrencyType;
  
  /** Regions to deploy in order */
  RegionOrder?: string[];
  
  /** Failure tolerance count */
  FailureToleranceCount?: number;
  
  /** Failure tolerance percentage */
  FailureTolerancePercentage?: number;
  
  /** Maximum concurrent accounts */
  MaxConcurrentCount?: number;
  
  /** Maximum concurrent percentage */
  MaxConcurrentPercentage?: number;
  
  /** Concurrency mode */
  ConcurrencyMode?: ConcurrencyMode;
}

interface DeploymentTargets {
  /** Target accounts */
  Accounts?: string[];
  
  /** Filter for accounts */
  AccountsUrl?: string;
  
  /** Organizational units */
  OrganizationalUnitIds?: string[];
  
  /** Account filter type */
  AccountFilterType?: AccountFilterType;
}

type RegionConcurrencyType = 
  | "SEQUENTIAL"
  | "PARALLEL";

type ConcurrencyMode = 
  | "STRICT_FAILURE_TOLERANCE"
  | "SOFT_FAILURE_TOLERANCE";

type AccountFilterType = 
  | "NONE"
  | "INTERSECTION"
  | "DIFFERENCE"
  | "UNION";

Delete Stack Set

Deletes a stack set after all stack instances have been deleted.

/**
 * Deletes a stack set and its configuration
 * All stack instances must be deleted first
 */
class DeleteStackSetCommand {
  constructor(input: DeleteStackSetCommandInput);
}

interface DeleteStackSetCommandInput {
  /** Name of the stack set to delete */
  StackSetName: string;
  
  /** Call context */
  CallAs?: CallAs;
}

Describe Stack Set

Retrieves detailed information about a stack set.

/**
 * Retrieves detailed information about a stack set
 * Includes configuration, status, and drift information
 */
class DescribeStackSetCommand {
  constructor(input: DescribeStackSetCommandInput);
}

interface DescribeStackSetCommandInput {
  /** Name of the stack set */
  StackSetName: string;
  
  /** Call context */
  CallAs?: CallAs;
}

interface DescribeStackSetCommandOutput {
  /** Stack set details */
  StackSet?: StackSet;
}

interface StackSet {
  /** Stack set name */
  StackSetName?: string;
  
  /** Stack set ID */
  StackSetId?: string;
  
  /** Description */
  Description?: string;
  
  /** Stack set status */
  Status?: StackSetStatus;
  
  /** Template body */
  TemplateBody?: string;
  
  /** Parameters */
  Parameters?: Parameter[];
  
  /** Capabilities */
  Capabilities?: Capability[];
  
  /** Tags */
  Tags?: Tag[];
  
  /** Stack set ARN */
  StackSetARN?: string;
  
  /** Administration role ARN */
  AdministrationRoleARN?: string;
  
  /** Execution role name */
  ExecutionRoleName?: string;
  
  /** Drift information */
  StackSetDriftDetectionDetails?: StackSetDriftDetectionDetails;
  
  /** Auto-deployment configuration */
  AutoDeployment?: AutoDeployment;
  
  /** Permission model */
  PermissionModel?: PermissionModels;
  
  /** Organizational unit IDs */
  OrganizationalUnitIds?: string[];
  
  /** Managed execution */
  ManagedExecution?: ManagedExecution;
  
  /** Regions */
  Regions?: string[];
}

interface StackSetDriftDetectionDetails {
  /** Drift detection status */
  DriftStatus?: StackSetDriftStatus;
  
  /** Drift detection status */
  DriftDetectionStatus?: StackSetDriftDetectionStatus;
  
  /** Last drift check timestamp */
  LastDriftCheckTimestamp?: Date;
  
  /** Total stack instances checked */
  TotalStackInstancesCount?: number;
  
  /** Drifted stack instances count */
  DriftedStackInstancesCount?: number;
  
  /** In sync stack instances count */
  InSyncStackInstancesCount?: number;
  
  /** In progress count */
  InProgressStackInstancesCount?: number;
  
  /** Failed count */
  FailedStackInstancesCount?: number;
}

type StackSetStatus = 
  | "ACTIVE"
  | "DELETED";

type StackSetDriftStatus = 
  | "DRIFTED"
  | "IN_SYNC"
  | "UNKNOWN";

type StackSetDriftDetectionStatus = 
  | "COMPLETED"
  | "FAILED"
  | "PARTIAL_SUCCESS"
  | "IN_PROGRESS"
  | "STOPPED";

List Stack Sets

Lists all stack sets in the account.

/**
 * Lists stack sets with optional filtering and pagination
 * Returns summary information for each stack set
 */
class ListStackSetsCommand {
  constructor(input: ListStackSetsCommandInput);
}

interface ListStackSetsCommandInput {
  /** Token for pagination */
  NextToken?: string;
  
  /** Maximum number of results */
  MaxResults?: number;
  
  /** Stack set status filter */
  Status?: StackSetStatus;
  
  /** Call context */
  CallAs?: CallAs;
}

interface ListStackSetsCommandOutput {
  /** Stack set summaries */
  Summaries?: StackSetSummary[];
  
  /** Token for next page */
  NextToken?: string;
}

interface StackSetSummary {
  /** Stack set name */
  StackSetName?: string;
  
  /** Stack set ID */
  StackSetId?: string;
  
  /** Description */
  Description?: string;
  
  /** Status */
  Status?: StackSetStatus;
  
  /** Auto-deployment settings */
  AutoDeployment?: AutoDeployment;
  
  /** Permission model */
  PermissionModel?: PermissionModels;
  
  /** Drift status */
  DriftStatus?: StackSetDriftStatus;
  
  /** Last drift check */
  LastDriftCheckTimestamp?: Date;
  
  /** Managed execution */
  ManagedExecution?: ManagedExecution;
}

Stack Instance Management

Create Stack Instances

Creates stack instances in specified accounts and regions.

/**
 * Creates stack instances for specified accounts and regions
 * Deploys the stack set template to target locations
 */
class CreateStackInstancesCommand {
  constructor(input: CreateStackInstancesCommandInput);
}

interface CreateStackInstancesCommandInput {
  /** Stack set name */
  StackSetName: string;
  
  /** Target accounts (for self-managed) */
  Accounts?: string[];
  
  /** Deployment targets (for service-managed) */
  DeploymentTargets?: DeploymentTargets;
  
  /** Target regions */
  Regions: string[];
  
  /** Parameter overrides for instances */
  ParameterOverrides?: Parameter[];
  
  /** Operation preferences */
  OperationPreferences?: StackSetOperationPreferences;
  
  /** Operation ID for idempotency */
  OperationId?: string;
  
  /** Call context */
  CallAs?: CallAs;
}

interface CreateStackInstancesCommandOutput {
  /** Operation ID */
  OperationId?: string;
}

Update Stack Instances

Updates existing stack instances with new parameters or settings.

/**
 * Updates stack instances with parameter overrides
 * Applies changes to specified accounts and regions
 */
class UpdateStackInstancesCommand {
  constructor(input: UpdateStackInstancesCommandInput);
}

interface UpdateStackInstancesCommandInput {
  /** Stack set name */
  StackSetName: string;
  
  /** Target accounts */
  Accounts?: string[];
  
  /** Deployment targets */
  DeploymentTargets?: DeploymentTargets;
  
  /** Target regions */
  Regions: string[];
  
  /** Updated parameter overrides */
  ParameterOverrides?: Parameter[];
  
  /** Operation preferences */
  OperationPreferences?: StackSetOperationPreferences;
  
  /** Operation ID */
  OperationId?: string;
  
  /** Call context */
  CallAs?: CallAs;
}

interface UpdateStackInstancesCommandOutput {
  /** Operation ID */
  OperationId?: string;
}

Delete Stack Instances

Deletes stack instances from specified accounts and regions.

/**
 * Deletes stack instances from specified accounts and regions
 * Removes deployed resources in target locations
 */
class DeleteStackInstancesCommand {
  constructor(input: DeleteStackInstancesCommandInput);
}

interface DeleteStackInstancesCommandInput {
  /** Stack set name */
  StackSetName: string;
  
  /** Target accounts */
  Accounts?: string[];
  
  /** Deployment targets */
  DeploymentTargets?: DeploymentTargets;
  
  /** Target regions */
  Regions: string[];
  
  /** Resources to retain during deletion */
  RetainStacks: boolean;
  
  /** Operation preferences */
  OperationPreferences?: StackSetOperationPreferences;
  
  /** Operation ID */
  OperationId?: string;
  
  /** Call context */
  CallAs?: CallAs;
}

interface DeleteStackInstancesCommandOutput {
  /** Operation ID */
  OperationId?: string;
}

List Stack Instances

Lists stack instances for a stack set.

/**
 * Lists stack instances with filtering and pagination
 * Returns status and configuration for each instance
 */
class ListStackInstancesCommand {
  constructor(input: ListStackInstancesCommandInput);
}

interface ListStackInstancesCommandInput {
  /** Stack set name */
  StackSetName: string;
  
  /** Token for pagination */
  NextToken?: string;
  
  /** Maximum results per page */
  MaxResults?: number;
  
  /** Filter by stack instance account */
  StackInstanceAccount?: string;
  
  /** Filter by stack instance region */
  StackInstanceRegion?: string;
  
  /** Call context */
  CallAs?: CallAs;
  
  /** Filter criteria */
  Filters?: StackInstanceFilter[];
}

interface ListStackInstancesCommandOutput {
  /** Stack instance summaries */
  Summaries?: StackInstanceSummary[];
  
  /** Pagination token */
  NextToken?: string;
}

interface StackInstanceSummary {
  /** Stack set ID */
  StackSetId?: string;
  
  /** Stack instance region */
  Region?: string;
  
  /** Stack instance account */
  Account?: string;
  
  /** Stack ID */
  StackId?: string;
  
  /** Status */
  Status?: StackInstanceStatus;
  
  /** Status reason */
  StatusReason?: string;
  
  /** Organizational unit ID */
  OrganizationalUnitId?: string;
  
  /** Drift status */
  DriftStatus?: StackDriftStatus;
  
  /** Last drift check */
  LastDriftCheckTimestamp?: Date;
  
  /** Last operation ID */
  LastOperationId?: string;
}

interface StackInstanceFilter {
  /** Filter name */
  Name?: StackInstanceFilterName;
  
  /** Filter values */
  Values?: string;
}

type StackInstanceFilterName = 
  | "DETAILED_STATUS"
  | "LAST_OPERATION_ID";

type StackInstanceStatus = 
  | "CURRENT"
  | "OUTDATED"
  | "INOPERABLE";

type StackDriftStatus = 
  | "DRIFTED"
  | "IN_SYNC"
  | "UNKNOWN"
  | "NOT_CHECKED";

Describe Stack Instance

Retrieves detailed information about a specific stack instance.

/**
 * Retrieves detailed information about a stack instance
 * Includes status, parameters, and drift information
 */
class DescribeStackInstanceCommand {
  constructor(input: DescribeStackInstanceCommandInput);
}

interface DescribeStackInstanceCommandInput {
  /** Stack set name */
  StackSetName: string;
  
  /** Stack instance account */
  StackInstanceAccount: string;
  
  /** Stack instance region */
  StackInstanceRegion: string;
  
  /** Call context */
  CallAs?: CallAs;
}

interface DescribeStackInstanceCommandOutput {
  /** Stack instance details */
  StackInstance?: StackInstance;
}

interface StackInstance {
  /** Stack set ID */
  StackSetId?: string;
  
  /** Region */
  Region?: string;
  
  /** Account */
  Account?: string;
  
  /** Stack ID */
  StackId?: string;
  
  /** Parameter overrides */
  ParameterOverrides?: Parameter[];
  
  /** Status */
  Status?: StackInstanceStatus;
  
  /** Status reason */
  StatusReason?: string;
  
  /** Organizational unit ID */
  OrganizationalUnitId?: string;
  
  /** Drift status */
  DriftStatus?: StackDriftStatus;
  
  /** Last drift check */
  LastDriftCheckTimestamp?: Date;
  
  /** Last operation ID */
  LastOperationId?: string;
}

Stack Set Operations

Stop Stack Set Operation

Stops an in-progress stack set operation.

/**
 * Stops a running stack set operation
 * Halts further processing of stack instances
 */
class StopStackSetOperationCommand {
  constructor(input: StopStackSetOperationCommandInput);
}

interface StopStackSetOperationCommandInput {
  /** Stack set name */
  StackSetName: string;
  
  /** Operation ID to stop */
  OperationId: string;
  
  /** Call context */
  CallAs?: CallAs;
}

List Stack Set Operations

Lists operations for a stack set.

/**
 * Lists operations performed on a stack set
 * Includes status and timing information
 */
class ListStackSetOperationsCommand {
  constructor(input: ListStackSetOperationsCommandInput);
}

interface ListStackSetOperationsCommandInput {
  /** Stack set name */
  StackSetName: string;
  
  /** Pagination token */
  NextToken?: string;
  
  /** Maximum results */
  MaxResults?: number;
  
  /** Call context */
  CallAs?: CallAs;
}

interface ListStackSetOperationsCommandOutput {
  /** Operation summaries */
  Summaries?: StackSetOperationSummary[];
  
  /** Pagination token */
  NextToken?: string;
}

interface StackSetOperationSummary {
  /** Operation ID */
  OperationId?: string;
  
  /** Action performed */
  Action?: StackSetOperationAction;
  
  /** Operation status */
  Status?: StackSetOperationStatus;
  
  /** Creation timestamp */
  CreationTimestamp?: Date;
  
  /** End timestamp */
  EndTimestamp?: Date;
  
  /** Status reason */
  StatusReason?: string;
  
  /** Status details */
  StatusDetails?: StackSetOperationStatusDetails;
  
  /** Operation preferences */
  OperationPreferences?: StackSetOperationPreferences;
}

type StackSetOperationAction = 
  | "CREATE"
  | "UPDATE"
  | "DELETE"
  | "DETECT_DRIFT";

type StackSetOperationStatus = 
  | "RUNNING"
  | "SUCCEEDED"
  | "FAILED"
  | "STOPPING"
  | "STOPPED"
  | "QUEUED";

interface StackSetOperationStatusDetails {
  /** Failed stack instances count */
  FailedStackInstancesCount?: number;
}

Usage Examples:

// Create stack instances across multiple accounts and regions
const createInstancesCommand = new CreateStackInstancesCommand({
  StackSetName: "cross-account-vpc",
  Accounts: ["111111111111", "222222222222", "333333333333"],
  Regions: ["us-east-1", "us-west-2", "eu-west-1"],
  ParameterOverrides: [
    { ParameterKey: "VpcCidr", ParameterValue: "10.1.0.0/16" }
  ],
  OperationPreferences: {
    RegionConcurrencyType: "PARALLEL",
    MaxConcurrentPercentage: 50,
    FailureTolerancePercentage: 10
  }
});

const operation = await client.send(createInstancesCommand);
console.log("Operation ID:", operation.OperationId);

// List stack instances to check deployment status
const listInstancesCommand = new ListStackInstancesCommand({
  StackSetName: "cross-account-vpc"
});

const instances = await client.send(listInstancesCommand);
console.log("Stack instances:", instances.Summaries);

// Delete specific stack instances
const deleteInstancesCommand = new DeleteStackInstancesCommand({
  StackSetName: "cross-account-vpc",
  Accounts: ["111111111111"],
  Regions: ["us-east-1"],
  RetainStacks: false
});

await client.send(deleteInstancesCommand);

Supporting Types

interface Tag {
  /** Tag key */
  Key: string;
  
  /** Tag value */
  Value: string;
}

interface Parameter {
  /** Parameter key */
  ParameterKey?: string;
  
  /** Parameter value */
  ParameterValue?: string;
  
  /** Use previous value */
  UsePreviousValue?: boolean;
  
  /** Resolved value */
  ResolvedValue?: string;
}

type Capability = 
  | "CAPABILITY_IAM"
  | "CAPABILITY_NAMED_IAM"
  | "CAPABILITY_AUTO_EXPAND";

Best Practices

Stack Set Design

  • Use parameter overrides for environment-specific configuration
  • Implement proper IAM permissions for cross-account access
  • Design templates for multi-region compatibility
  • Consider resource naming conventions across accounts

Operation Management

  • Monitor operation progress and handle failures gracefully
  • Use appropriate failure tolerance settings
  • Implement rollback strategies for failed deployments
  • Set reasonable concurrency limits to avoid throttling

Security and Permissions

  • Follow least-privilege principles for execution roles
  • Use service-managed permissions when possible with Organizations
  • Audit cross-account access regularly
  • Implement proper resource tagging for compliance

Monitoring and Maintenance

  • Enable drift detection for stack instances
  • Monitor stack set operations and their outcomes
  • Implement automated remediation for configuration drift
  • Regular review of stack set configurations and permissions