Skip to content

API.md

Latest commit

 

History

History
2427 lines (1502 loc) · 85.3 KB

API.md

File metadata and controls

2427 lines (1502 loc) · 85.3 KB
Raw

API Reference

Constructs

StackSet

Initializers 

import { StackSet } from 'cdk-stacksets'

new StackSet(scope: Construct, id: string, props: StackSetProps)
Name Type Description
scope constructs.Construct The scope in which to define this StackSet.
id string The ID of the StackSet.
props StackSetProps The properties of the StackSet.
scopeRequired
  • Type: constructs.Construct

The scope in which to define this StackSet.

idRequired
  • Type: string

The ID of the StackSet.

propsRequired

The properties of the StackSet.

Methods

Name Description
toString Returns a string representation of this construct.
applyRemovalPolicy Apply the given removal policy to this resource.
addTarget Adds a target to the StackSet.
toString 
public toString(): string

Returns a string representation of this construct.

applyRemovalPolicy 
public applyRemovalPolicy(policy: RemovalPolicy): void

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

policyRequired
  • Type: aws-cdk-lib.RemovalPolicy
addTarget 
public addTarget(target: StackSetTarget): void

Adds a target to the StackSet.

targetRequired

the target to add to the StackSet.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isOwnedResource Returns true if the construct was created by CDK, and false otherwise.
isResource Check whether the given construct is a Resource.
isConstruct 
import { StackSet } from 'cdk-stacksets'

StackSet.isConstruct(x: any)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.

isOwnedResource 
import { StackSet } from 'cdk-stacksets'

StackSet.isOwnedResource(construct: IConstruct)

Returns true if the construct was created by CDK, and false otherwise.

constructRequired
  • Type: constructs.IConstruct
isResource 
import { StackSet } from 'cdk-stacksets'

StackSet.isResource(construct: IConstruct)

Check whether the given construct is a Resource.

constructRequired
  • Type: constructs.IConstruct

Properties

Name Type Description
node constructs.Node The tree node.
env aws-cdk-lib.ResourceEnvironment The environment this resource belongs to.
stack aws-cdk-lib.Stack The stack in which this resource is defined.
role aws-cdk-lib.aws_iam.IRole Only available on self managed stacksets.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

envRequired 
public readonly env: ResourceEnvironment;
  • Type: aws-cdk-lib.ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

stackRequired 
public readonly stack: Stack;
  • Type: aws-cdk-lib.Stack

The stack in which this resource is defined.

roleOptional 
public readonly role: IRole;
  • Type: aws-cdk-lib.aws_iam.IRole

Only available on self managed stacksets.

The admin role that CloudFormation will use to perform stackset operations. This role should only have permissions to be assumed by the CloudFormation service and to assume the execution role in each individual account.

When you create the execution role it must have an assume role policy statement which allows sts:AssumeRole from this admin role.

To grant specific users/groups access to use this role to deploy stacksets they must have a policy that allows iam:GetRole & iam:PassRole on this role resource.

StackSetStack

A StackSet stack, which is similar to a normal CloudFormation stack with some differences.

This stack will not be treated as an independent deployment artifact (won't be listed in "cdk list" or deployable through "cdk deploy"), but rather only synthesized as a template and uploaded as an asset to S3.

Initializers 

import { StackSetStack } from 'cdk-stacksets'

new StackSetStack(scope: Construct, id: string, props?: StackSetStackProps)
Name Type Description
scope constructs.Construct The scope in which to define this StackSet.
id string The ID of the StackSet.
props StackSetStackProps The properties of the StackSet.
scopeRequired
  • Type: constructs.Construct

The scope in which to define this StackSet.

idRequired
  • Type: string

The ID of the StackSet.

propsOptional

The properties of the StackSet.

Methods

Name Description
toString Returns a string representation of this construct.
addDependency Add a dependency between this stack and another stack.
addMetadata Adds an arbitary key-value pair, with information you want to record about the stack.
addTransform Add a Transform to this stack. A Transform is a macro that AWS CloudFormation uses to process your template.
exportStringListValue Create a CloudFormation Export for a string list value.
exportValue Create a CloudFormation Export for a string value.
formatArn Creates an ARN from components.
getLogicalId Allocates a stack-unique CloudFormation-compatible logical identity for a specific resource.
regionalFact Look up a fact value for the given fact for the region of this stack.
renameLogicalId Rename a generated logical identities.
reportMissingContextKey Indicate that a context key was expected.
resolve Resolve a tokenized value in the context of the current stack.
splitArn Splits the provided ARN into its components.
toJsonString Convert an object, potentially containing tokens, to a JSON string.
toYamlString Convert an object, potentially containing tokens, to a YAML string.
toString 
public toString(): string

Returns a string representation of this construct.

addDependency 
public addDependency(target: Stack, reason?: string): void

Add a dependency between this stack and another stack.

This can be used to define dependencies between any two stacks within an app, and also supports nested stacks.

targetRequired
  • Type: aws-cdk-lib.Stack
reasonOptional
  • Type: string
addMetadata 
public addMetadata(key: string, value: any): void

Adds an arbitary key-value pair, with information you want to record about the stack.

These get translated to the Metadata section of the generated template.

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/metadata-section-structure.html

keyRequired
  • Type: string
valueRequired
  • Type: any
addTransform 
public addTransform(transform: string): void

Add a Transform to this stack. A Transform is a macro that AWS CloudFormation uses to process your template.

Duplicate values are removed when stack is synthesized.

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/transform-section-structure.html

Example

declare const stack: Stack;

stack.addTransform('AWS::Serverless-2016-10-31')
transformRequired
  • Type: string

The transform to add.

exportStringListValue 
public exportStringListValue(exportedValue: any, options?: ExportValueOptions): string[]

Create a CloudFormation Export for a string list value.

Returns a string list representing the corresponding Fn.importValue() expression for this Export. The export expression is automatically wrapped with an Fn::Join and the import value with an Fn::Split, since CloudFormation can only export strings. You can control the name for the export by passing the name option.

If you don't supply a value for name, the value you're exporting must be a Resource attribute (for example: bucket.bucketName) and it will be given the same name as the automatic cross-stack reference that would be created if you used the attribute in another Stack.

One of the uses for this method is to remove the relationship between two Stacks established by automatic cross-stack references. It will temporarily ensure that the CloudFormation Export still exists while you remove the reference from the consuming stack. After that, you can remove the resource and the manual export.

See exportValue for an example of this process.

exportedValueRequired
  • Type: any
optionsOptional
  • Type: aws-cdk-lib.ExportValueOptions
exportValue 
public exportValue(exportedValue: any, options?: ExportValueOptions): string

Create a CloudFormation Export for a string value.

Returns a string representing the corresponding Fn.importValue() expression for this Export. You can control the name for the export by passing the name option.

If you don't supply a value for name, the value you're exporting must be a Resource attribute (for example: bucket.bucketName) and it will be given the same name as the automatic cross-stack reference that would be created if you used the attribute in another Stack.

One of the uses for this method is to remove the relationship between two Stacks established by automatic cross-stack references. It will temporarily ensure that the CloudFormation Export still exists while you remove the reference from the consuming stack. After that, you can remove the resource and the manual export.

Example

Here is how the process works. Let's say there are two stacks, producerStack and consumerStack, and producerStack has a bucket called bucket, which is referenced by consumerStack (perhaps because an AWS Lambda Function writes into it, or something like that).

It is not safe to remove producerStack.bucket because as the bucket is being deleted, consumerStack might still be using it.

Instead, the process takes two deployments:

Deployment 1: break the relationship

  • Make sure consumerStack no longer references bucket.bucketName (maybe the consumer stack now uses its own bucket, or it writes to an AWS DynamoDB table, or maybe you just remove the Lambda Function altogether).
  • In the ProducerStack class, call this.exportValue(this.bucket.bucketName). This will make sure the CloudFormation Export continues to exist while the relationship between the two stacks is being broken.
  • Deploy (this will effectively only change the consumerStack, but it's safe to deploy both).

Deployment 2: remove the bucket resource

  • You are now free to remove the bucket resource from producerStack.
  • Don't forget to remove the exportValue() call as well.
  • Deploy again (this time only the producerStack will be changed -- the bucket will be deleted).
exportedValueRequired
  • Type: any
optionsOptional
  • Type: aws-cdk-lib.ExportValueOptions
formatArn 
public formatArn(components: ArnComponents): string

Creates an ARN from components.

If partition, region or account are not specified, the stack's partition, region and account will be used.

If any component is the empty string, an empty string will be inserted into the generated ARN at the location that component corresponds to.

The ARN will be formatted as follows:

arn:{partition}:{service}:{region}:{account}:{resource}{sep}{resource-name}

The required ARN pieces that are omitted will be taken from the stack that the 'scope' is attached to. If all ARN pieces are supplied, the supplied scope can be 'undefined'.

componentsRequired
  • Type: aws-cdk-lib.ArnComponents
getLogicalId 
public getLogicalId(element: CfnElement): string

Allocates a stack-unique CloudFormation-compatible logical identity for a specific resource.

This method is called when a CfnElement is created and used to render the initial logical identity of resources. Logical ID renames are applied at this stage.

This method uses the protected method allocateLogicalId to render the logical ID for an element. To modify the naming scheme, extend the Stack class and override this method.

elementRequired
  • Type: aws-cdk-lib.CfnElement

The CloudFormation element for which a logical identity is needed.

regionalFact 
public regionalFact(factName: string, defaultValue?: string): string

Look up a fact value for the given fact for the region of this stack.

Will return a definite value only if the region of the current stack is resolved. If not, a lookup map will be added to the stack and the lookup will be done at CDK deployment time.

What regions will be included in the lookup map is controlled by the @aws-cdk/core:target-partitions context value: it must be set to a list of partitions, and only regions from the given partitions will be included. If no such context key is set, all regions will be included.

This function is intended to be used by construct library authors. Application builders can rely on the abstractions offered by construct libraries and do not have to worry about regional facts.

If defaultValue is not given, it is an error if the fact is unknown for the given region.

factNameRequired
  • Type: string
defaultValueOptional
  • Type: string
renameLogicalId 
public renameLogicalId(oldId: string, newId: string): void

Rename a generated logical identities.

To modify the naming scheme strategy, extend the Stack class and override the allocateLogicalId method.

oldIdRequired
  • Type: string
newIdRequired
  • Type: string
reportMissingContextKey 
public reportMissingContextKey(report: MissingContext): void

Indicate that a context key was expected.

Contains instructions which will be emitted into the cloud assembly on how the key should be supplied.

reportRequired
  • Type: aws-cdk-lib.cloud_assembly_schema.MissingContext

The set of parameters needed to obtain the context.

resolve 
public resolve(obj: any): any

Resolve a tokenized value in the context of the current stack.

objRequired
  • Type: any
splitArn 
public splitArn(arn: string, arnFormat: ArnFormat): ArnComponents

Splits the provided ARN into its components.

Works both if 'arn' is a string like 'arn:aws:s3:::bucket', and a Token representing a dynamic CloudFormation expression (in which case the returned components will also be dynamic CloudFormation expressions, encoded as Tokens).

arnRequired
  • Type: string

the ARN to split into its components.

arnFormatRequired
  • Type: aws-cdk-lib.ArnFormat

the expected format of 'arn' - depends on what format the service 'arn' represents uses.

toJsonString 
public toJsonString(obj: any, space?: number): string

Convert an object, potentially containing tokens, to a JSON string.

objRequired
  • Type: any
spaceOptional
  • Type: number
toYamlString 
public toYamlString(obj: any): string

Convert an object, potentially containing tokens, to a YAML string.

objRequired
  • Type: any

Static Functions

Name Description
isConstruct Checks if x is a construct.
isStack Return whether the given object is a Stack.
of Looks up the first stack scope in which construct is defined.
isConstruct 
import { StackSetStack } from 'cdk-stacksets'

StackSetStack.isConstruct(x: any)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.

isStack 
import { StackSetStack } from 'cdk-stacksets'

StackSetStack.isStack(x: any)

Return whether the given object is a Stack.

We do attribute detection since we can't reliably use 'instanceof'.

xRequired
  • Type: any
of 
import { StackSetStack } from 'cdk-stacksets'

StackSetStack.of(construct: IConstruct)

Looks up the first stack scope in which construct is defined.

Fails if there is no stack up the tree.

constructRequired
  • Type: constructs.IConstruct

The construct to start the search from.

Properties

Name Type Description
node constructs.Node The tree node.
account string The AWS account into which this stack will be deployed.
artifactId string The ID of the cloud assembly artifact for this stack.
availabilityZones string[] Returns the list of AZs that are available in the AWS environment (account/region) associated with this stack.
bundlingRequired boolean Indicates whether the stack requires bundling or not.
dependencies aws-cdk-lib.Stack[] Return the stacks this stack depends on.
environment string The environment coordinates in which this stack is deployed.
nested boolean Indicates if this is a nested stack, in which case parentStack will include a reference to it's parent.
notificationArns string[] Returns the list of notification Amazon Resource Names (ARNs) for the current stack.
partition string The partition in which this stack is defined.
region string The AWS region into which this stack will be deployed (e.g. us-west-2).
stackId string The ID of the stack.
stackName string The concrete CloudFormation physical stack name.
synthesizer aws-cdk-lib.IStackSynthesizer Synthesis method for this stack.
tags aws-cdk-lib.TagManager Tags to be applied to the stack.
templateFile string The name of the CloudFormation template file emitted to the output directory during synthesis.
templateOptions aws-cdk-lib.ITemplateOptions Options for CloudFormation template (like version, transform, description).
urlSuffix string The Amazon domain suffix for the region in which this stack is defined.
nestedStackParent aws-cdk-lib.Stack If this is a nested stack, returns it's parent stack.
nestedStackResource aws-cdk-lib.CfnResource If this is a nested stack, this represents its AWS::CloudFormation::Stack resource.
terminationProtection boolean Whether termination protection is enabled for this stack.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

accountRequired 
public readonly account: string;
  • Type: string

The AWS account into which this stack will be deployed.

This value is resolved according to the following rules:

  1. The value provided to env.account when the stack is defined. This can either be a concrete account (e.g. 585695031111) or the Aws.ACCOUNT_ID token.
  2. Aws.ACCOUNT_ID, which represents the CloudFormation intrinsic reference { "Ref": "AWS::AccountId" } encoded as a string token.

Preferably, you should use the return value as an opaque string and not attempt to parse it to implement your logic. If you do, you must first check that it is a concrete value an not an unresolved token. If this value is an unresolved token (Token.isUnresolved(stack.account) returns true), this implies that the user wishes that this stack will synthesize into a account-agnostic template. In this case, your code should either fail (throw an error, emit a synth error using Annotations.of(construct).addError()) or implement some other region-agnostic behavior.

artifactIdRequired 
public readonly artifactId: string;
  • Type: string

The ID of the cloud assembly artifact for this stack.

availabilityZonesRequired 
public readonly availabilityZones: string[];
  • Type: string[]

Returns the list of AZs that are available in the AWS environment (account/region) associated with this stack.

If the stack is environment-agnostic (either account and/or region are tokens), this property will return an array with 2 tokens that will resolve at deploy-time to the first two availability zones returned from CloudFormation's Fn::GetAZs intrinsic function.

If they are not available in the context, returns a set of dummy values and reports them as missing, and let the CLI resolve them by calling EC2 DescribeAvailabilityZones on the target environment.

To specify a different strategy for selecting availability zones override this method.

bundlingRequiredRequired 
public readonly bundlingRequired: boolean;
  • Type: boolean

Indicates whether the stack requires bundling or not.

dependenciesRequired 
public readonly dependencies: Stack[];
  • Type: aws-cdk-lib.Stack[]

Return the stacks this stack depends on.

environmentRequired 
public readonly environment: string;
  • Type: string

The environment coordinates in which this stack is deployed.

In the form aws://account/region. Use stack.account and stack.region to obtain the specific values, no need to parse.

You can use this value to determine if two stacks are targeting the same environment.

If either stack.account or stack.region are not concrete values (e.g. Aws.ACCOUNT_ID or Aws.REGION) the special strings unknown-account and/or unknown-region will be used respectively to indicate this stack is region/account-agnostic.

nestedRequired 
public readonly nested: boolean;
  • Type: boolean

Indicates if this is a nested stack, in which case parentStack will include a reference to it's parent.

notificationArnsRequired 
public readonly notificationArns: string[];
  • Type: string[]

Returns the list of notification Amazon Resource Names (ARNs) for the current stack.

partitionRequired 
public readonly partition: string;
  • Type: string

The partition in which this stack is defined.

regionRequired 
public readonly region: string;
  • Type: string

The AWS region into which this stack will be deployed (e.g. us-west-2).

This value is resolved according to the following rules:

  1. The value provided to env.region when the stack is defined. This can either be a concrete region (e.g. us-west-2) or the Aws.REGION token.
  2. Aws.REGION, which is represents the CloudFormation intrinsic reference { "Ref": "AWS::Region" } encoded as a string token.

Preferably, you should use the return value as an opaque string and not attempt to parse it to implement your logic. If you do, you must first check that it is a concrete value an not an unresolved token. If this value is an unresolved token (Token.isUnresolved(stack.region) returns true), this implies that the user wishes that this stack will synthesize into a region-agnostic template. In this case, your code should either fail (throw an error, emit a synth error using Annotations.of(construct).addError()) or implement some other region-agnostic behavior.

stackIdRequired 
public readonly stackId: string;
  • Type: string

The ID of the stack.

Example

// After resolving, looks like
'arn:aws:cloudformation:us-west-2:123456789012:stack/teststack/51af3dc0-da77-11e4-872e-1234567db123'
stackNameRequired 
public readonly stackName: string;
  • Type: string

The concrete CloudFormation physical stack name.

This is either the name defined explicitly in the stackName prop or allocated based on the stack's location in the construct tree. Stacks that are directly defined under the app use their construct id as their stack name. Stacks that are defined deeper within the tree will use a hashed naming scheme based on the construct path to ensure uniqueness.

If you wish to obtain the deploy-time AWS::StackName intrinsic, you can use Aws.STACK_NAME directly.

synthesizerRequired 
public readonly synthesizer: IStackSynthesizer;
  • Type: aws-cdk-lib.IStackSynthesizer

Synthesis method for this stack.

tagsRequired 
public readonly tags: TagManager;
  • Type: aws-cdk-lib.TagManager

Tags to be applied to the stack.

templateFileRequired 
public readonly templateFile: string;
  • Type: string

The name of the CloudFormation template file emitted to the output directory during synthesis.

Example value: MyStack.template.json

templateOptionsRequired 
public readonly templateOptions: ITemplateOptions;
  • Type: aws-cdk-lib.ITemplateOptions

Options for CloudFormation template (like version, transform, description).

urlSuffixRequired 
public readonly urlSuffix: string;
  • Type: string

The Amazon domain suffix for the region in which this stack is defined.

nestedStackParentOptional 
public readonly nestedStackParent: Stack;
  • Type: aws-cdk-lib.Stack

If this is a nested stack, returns it's parent stack.

nestedStackResourceOptional 
public readonly nestedStackResource: CfnResource;
  • Type: aws-cdk-lib.CfnResource

If this is a nested stack, this represents its AWS::CloudFormation::Stack resource.

undefined for top-level (non-nested) stacks.

terminationProtectionRequired 
public readonly terminationProtection: boolean;
  • Type: boolean

Whether termination protection is enabled for this stack.

Structs

AccountsTargetOptions

Options for deploying a StackSet to a list of AWS accounts.

Initializer 

import { AccountsTargetOptions } from 'cdk-stacksets'

const accountsTargetOptions: AccountsTargetOptions = { ... }

Properties

Name Type Description
regions string[] A list of regions the Stack should be deployed to.
parameterOverrides {[ key: string ]: string} Parameter overrides that should be applied to only this target.
accounts string[] A list of AWS accounts to deploy the StackSet to.
regionsRequired 
public readonly regions: string[];
  • Type: string[]

A list of regions the Stack should be deployed to.

If {@link StackSetProps.operationPreferences.regionOrder } is specified then the StackSet will be deployed sequentially otherwise it will be deployed to all regions in parallel.

parameterOverridesOptional 
public readonly parameterOverrides: {[ key: string ]: string};
  • Type: {[ key: string ]: string}
  • Default: use parameter overrides specified in {@link StackSetProps.parameterOverrides }

Parameter overrides that should be applied to only this target.

accountsRequired 
public readonly accounts: string[];
  • Type: string[]

A list of AWS accounts to deploy the StackSet to.

OperationPreferences

CloudFormation operation preferences.

This maps to aws_cloudformation.CfnStackSet.OperationPreferencesProperty.

Initializer 

import { OperationPreferences } from 'cdk-stacksets'

const operationPreferences: OperationPreferences = { ... }

Properties

Name Type Description
failureToleranceCount number The number of stack instances that can fail before the operation is considered failed.
failureTolerancePercentage number The percentage of stack instances that can fail before the operation is considered failed.
maxConcurrentCount number The maximum number of stack instances that can be created or updated concurrently.
maxConcurrentPercentage number The maximum percentage of stack instances that can be created or updated concurrently.
regionConcurrencyType RegionConcurrencyType Whether to deploy multiple regions sequentially or in parallel.
regionOrder string[] The order in which to deploy the stack instances to the regions.
failureToleranceCountOptional 
public readonly failureToleranceCount: number;
  • Type: number

The number of stack instances that can fail before the operation is considered failed.

failureTolerancePercentageOptional 
public readonly failureTolerancePercentage: number;
  • Type: number

The percentage of stack instances that can fail before the operation is considered failed.

maxConcurrentCountOptional 
public readonly maxConcurrentCount: number;
  • Type: number

The maximum number of stack instances that can be created or updated concurrently.

maxConcurrentPercentageOptional 
public readonly maxConcurrentPercentage: number;
  • Type: number

The maximum percentage of stack instances that can be created or updated concurrently.

regionConcurrencyTypeOptional 
public readonly regionConcurrencyType: RegionConcurrencyType;

Whether to deploy multiple regions sequentially or in parallel.

regionOrderOptional 
public readonly regionOrder: string[];
  • Type: string[]

The order in which to deploy the stack instances to the regions.

OrganizationsTargetOptions

Options for deploying a StackSet to a set of Organizational Units (OUs).

Initializer 

import { OrganizationsTargetOptions } from 'cdk-stacksets'

const organizationsTargetOptions: OrganizationsTargetOptions = { ... }

Properties

Name Type Description
regions string[] A list of regions the Stack should be deployed to.
parameterOverrides {[ key: string ]: string} Parameter overrides that should be applied to only this target.
organizationalUnits string[] A list of organizational unit ids to deploy to.
additionalAccounts string[] A list of additional AWS accounts to deploy the StackSet to.
excludeAccounts string[] A list of AWS accounts to exclude from deploying the StackSet to.
regionsRequired 
public readonly regions: string[];
  • Type: string[]

A list of regions the Stack should be deployed to.

If {@link StackSetProps.operationPreferences.regionOrder } is specified then the StackSet will be deployed sequentially otherwise it will be deployed to all regions in parallel.

parameterOverridesOptional 
public readonly parameterOverrides: {[ key: string ]: string};
  • Type: {[ key: string ]: string}
  • Default: use parameter overrides specified in {@link StackSetProps.parameterOverrides }

Parameter overrides that should be applied to only this target.

organizationalUnitsRequired 
public readonly organizationalUnits: string[];
  • Type: string[]

A list of organizational unit ids to deploy to.

The StackSet will deploy the provided Stack template to all accounts in the OU. This can be further filtered by specifying either additionalAccounts or excludeAccounts.

If the deploymentType is specified with autoDeployEnabled then the StackSet will automatically deploy the Stack to new accounts as they are added to the specified organizationalUnits

additionalAccountsOptional 
public readonly additionalAccounts: string[];
  • Type: string[]
  • Default: Stacks will only be deployed to accounts that exist in the specified organizationalUnits

A list of additional AWS accounts to deploy the StackSet to.

This can be used to deploy the StackSet to additional AWS accounts that exist in a different OU than what has been provided in organizationalUnits

excludeAccountsOptional 
public readonly excludeAccounts: string[];
  • Type: string[]
  • Default: Stacks will be deployed to all accounts that exist in the OUs specified in the organizationUnits property

A list of AWS accounts to exclude from deploying the StackSet to.

This can be useful if there are accounts that exist in an OU that is provided in organizationalUnits, but you do not want the StackSet to be deployed.

SelfManagedOptions

Options for StackSets that are not managed by AWS Organizations.

Initializer 

import { SelfManagedOptions } from 'cdk-stacksets'

const selfManagedOptions: SelfManagedOptions = { ... }

Properties

Name Type Description
adminRole aws-cdk-lib.aws_iam.IRole The admin role that CloudFormation will use to perform stackset operations.
executionRoleName string The name of the stackset execution role that already exists in each target AWS account.
adminRoleOptional 
public readonly adminRole: IRole;
  • Type: aws-cdk-lib.aws_iam.IRole
  • Default: a default role will be created

The admin role that CloudFormation will use to perform stackset operations.

This role should only have permissions to be assumed by the CloudFormation service and to assume the execution role in each individual account.

When you create the execution role it must have an assume role policy statement which allows sts:AssumeRole from this admin role.

To grant specific users/groups access to use this role to deploy stacksets they must have a policy that allows iam:GetRole & iam:PassRole on this role resource.

executionRoleNameOptional 
public readonly executionRoleName: string;
  • Type: string
  • Default: AWSCloudFormationStackSetExecutionRole

The name of the stackset execution role that already exists in each target AWS account.

This role must be configured with a trust policy that allows sts:AssumeRole from the adminRole.

In addition this role must have the necessary permissions to manage the resources created by the stackset.

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-prereqs-self-managed.html#stacksets-prereqs-accountsetup

ServiceManagedOptions

Options for StackSets that are managed by AWS Organizations.

Initializer 

import { ServiceManagedOptions } from 'cdk-stacksets'

const serviceManagedOptions: ServiceManagedOptions = { ... }

Properties

Name Type Description
autoDeployEnabled boolean Whether or not the StackSet should automatically create/remove the Stack from AWS accounts that are added/removed from an organizational unit.
autoDeployRetainStacks boolean Whether stacks should be removed from AWS accounts that are removed from an organizational unit.
delegatedAdmin boolean Whether or not the account this StackSet is deployed from is the delegated admin account.
autoDeployEnabledOptional 
public readonly autoDeployEnabled: boolean;
  • Type: boolean
  • Default: true

Whether or not the StackSet should automatically create/remove the Stack from AWS accounts that are added/removed from an organizational unit.

This has no effect if {@link StackSetTarget.fromAccounts} is used

autoDeployRetainStacksOptional 
public readonly autoDeployRetainStacks: boolean;
  • Type: boolean
  • Default: true

Whether stacks should be removed from AWS accounts that are removed from an organizational unit.

By default the stack will be retained (not deleted)

This has no effect if {@link StackSetTarget.fromAccounts} is used

delegatedAdminOptional 
public readonly delegatedAdmin: boolean;
  • Type: boolean
  • Default: true

Whether or not the account this StackSet is deployed from is the delegated admin account.

Set this to false if you are using the AWS Organizations management account instead.

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-orgs-delegated-admin.html

StackSetProps

Initializer 

import { StackSetProps } from 'cdk-stacksets'

const stackSetProps: StackSetProps = { ... }

Properties

Name Type Description
target StackSetTarget Which accounts/OUs and regions to deploy the StackSet to.
template StackSetTemplate The Stack that will be deployed to the target.
capabilities Capability[] Specify a list of capabilities required by your stackset.
deploymentType DeploymentType The type of deployment for this StackSet.
description string An optional description to add to the StackSet.
managedExecution boolean If this is true then StackSets will perform non-conflicting operations concurrently and queue any conflicting operations.
operationPreferences OperationPreferences The operation preferences for the StackSet.
parameters {[ key: string ]: string} The input parameters for the stack set template.
stackSetName string The name of the stack set.
targetRequired 
public readonly target: StackSetTarget;

Which accounts/OUs and regions to deploy the StackSet to.

templateRequired 
public readonly template: StackSetTemplate;

The Stack that will be deployed to the target.

capabilitiesOptional 
public readonly capabilities: Capability[];
  • Type: Capability[]
  • Default: no specific capabilities

Specify a list of capabilities required by your stackset.

StackSets that contains certain functionality require an explicit acknowledgement that the stack contains these capabilities.

If you deploy a stack that requires certain capabilities and they are not specified, the deployment will fail with a InsufficientCapabilities error.

deploymentTypeOptional 
public readonly deploymentType: DeploymentType;

The type of deployment for this StackSet.

The deployment can either be managed by AWS Organizations (i.e. DeploymentType.serviceManaged()) or by the AWS account that the StackSet is deployed from.

In order to use DeploymentType.serviceManaged() the account needs to either be the organizations's management account or a delegated administrator account.

descriptionOptional 
public readonly description: string;
  • Type: string
  • Default: none

An optional description to add to the StackSet.

managedExecutionOptional 
public readonly managedExecution: boolean;
  • Type: boolean
  • Default: true

If this is true then StackSets will perform non-conflicting operations concurrently and queue any conflicting operations.

This means that you can submit more than one operation per StackSet and they will be executed concurrently. For example you can submit a single request that updates existing stack instances and creates new stack instances. Any conflicting operations will be queued for immediate processing once the conflict is resolved.

operationPreferencesOptional 
public readonly operationPreferences: OperationPreferences;

The operation preferences for the StackSet.

This allows you to control how the StackSet is deployed across the target accounts and regions.

parametersOptional 
public readonly parameters: {[ key: string ]: string};
  • Type: {[ key: string ]: string}

The input parameters for the stack set template.

stackSetNameOptional 
public readonly stackSetName: string;
  • Type: string
  • Default: CloudFormation generated name

The name of the stack set.

StackSetStackProps

StackSet stack props.

Initializer 

import { StackSetStackProps } from 'cdk-stacksets'

const stackSetStackProps: StackSetStackProps = { ... }

Properties

Name Type Description
assetBucketPrefix string The common prefix for the asset bucket names used by this StackSetStack.
assetBuckets aws-cdk-lib.aws_s3.IBucket[] An array of Buckets can be passed to store assets, enabling StackSetStack Asset support.
assetBucketPrefixOptional 
public readonly assetBucketPrefix: string;
  • Type: string
  • Default: No Buckets provided and Assets will not be supported.

The common prefix for the asset bucket names used by this StackSetStack.

Required if assetBuckets is provided.

assetBucketsOptional 
public readonly assetBuckets: IBucket[];
  • Type: aws-cdk-lib.aws_s3.IBucket[]
  • Default: No Buckets provided and Assets will not be supported.

An array of Buckets can be passed to store assets, enabling StackSetStack Asset support.

One Bucket is required per target region. The name must be ${assetBucketPrefix}-<region>, where <region> is the region targeted by the StackSet.

TargetOptions

Common options for deploying a StackSet to a target.

Initializer 

import { TargetOptions } from 'cdk-stacksets'

const targetOptions: TargetOptions = { ... }

Properties

Name Type Description
regions string[] A list of regions the Stack should be deployed to.
parameterOverrides {[ key: string ]: string} Parameter overrides that should be applied to only this target.
regionsRequired 
public readonly regions: string[];
  • Type: string[]

A list of regions the Stack should be deployed to.

If {@link StackSetProps.operationPreferences.regionOrder } is specified then the StackSet will be deployed sequentially otherwise it will be deployed to all regions in parallel.

parameterOverridesOptional 
public readonly parameterOverrides: {[ key: string ]: string};
  • Type: {[ key: string ]: string}
  • Default: use parameter overrides specified in {@link StackSetProps.parameterOverrides }

Parameter overrides that should be applied to only this target.

Classes

DeploymentType

Initializers 

import { DeploymentType } from 'cdk-stacksets'

new DeploymentType()
Name Type Description

Static Functions

Name Description
selfManaged StackSets deployed using the self managed model require you to create the necessary IAM roles in the source and target AWS accounts and to setup the required IAM permissions.
serviceManaged StackSets deployed using service managed permissions allow you to deploy StackSet instances to accounts within an AWS Organization.
selfManaged 
import { DeploymentType } from 'cdk-stacksets'

DeploymentType.selfManaged(options?: SelfManagedOptions)

StackSets deployed using the self managed model require you to create the necessary IAM roles in the source and target AWS accounts and to setup the required IAM permissions.

Using this model you can only deploy to AWS accounts that have the necessary IAM roles/permissions pre-created.

optionsOptional
serviceManaged 
import { DeploymentType } from 'cdk-stacksets'

DeploymentType.serviceManaged(options?: ServiceManagedOptions)

StackSets deployed using service managed permissions allow you to deploy StackSet instances to accounts within an AWS Organization.

Using this module AWS Organizations will handle creating the necessary IAM roles and setting up the required permissions.

This model also allows you to enable automated deployments which allows the StackSet to be automatically deployed to new accounts that are added to your organization in the future.

This model requires you to be operating in either the AWS Organizations management account or the delegated administrator account

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-concepts.html#stacksets-concepts-stackset-permission-models

optionsOptional

StackSetStackSynthesizer

Deployment environment for an AWS StackSet stack.

Interoperates with the StackSynthesizer of the parent stack.

Initializers 

import { StackSetStackSynthesizer } from 'cdk-stacksets'

new StackSetStackSynthesizer(assetBuckets?: IBucket[], assetBucketPrefix?: string)
Name Type Description
assetBuckets aws-cdk-lib.aws_s3.IBucket[] An array of S3 buckets to use for storing assets.
assetBucketPrefix string The prefix to use for the asset bucket names.
assetBucketsOptional
  • Type: aws-cdk-lib.aws_s3.IBucket[]

An array of S3 buckets to use for storing assets.

assetBucketPrefixOptional
  • Type: string

The prefix to use for the asset bucket names.

Methods

Name Description
addDockerImageAsset Register a Docker Image Asset.
addFileAsset Register a File Asset.
bind Bind to the stack this environment is going to be used on.
synthesize Synthesize the associated stack to the session.
addDockerImageAsset 
public addDockerImageAsset(_asset: DockerImageAssetSource): DockerImageAssetLocation

Register a Docker Image Asset.

Returns the parameters that can be used to refer to the asset inside the template.

The synthesizer must rely on some out-of-band mechanism to make sure the given files are actually placed in the returned location before the deployment happens. This can be by writing the instructions to the asset manifest (for use by the cdk-assets tool), by relying on the CLI to upload files (legacy behavior), or some other operator controlled mechanism.

_assetRequired
  • Type: aws-cdk-lib.DockerImageAssetSource
addFileAsset 
public addFileAsset(asset: FileAssetSource): FileAssetLocation

Register a File Asset.

Returns the parameters that can be used to refer to the asset inside the template.

The synthesizer must rely on some out-of-band mechanism to make sure the given files are actually placed in the returned location before the deployment happens. This can be by writing the instructions to the asset manifest (for use by the cdk-assets tool), by relying on the CLI to upload files (legacy behavior), or some other operator controlled mechanism.

assetRequired
  • Type: aws-cdk-lib.FileAssetSource
bind 
public bind(stack: Stack): void

Bind to the stack this environment is going to be used on.

Must be called before any of the other methods are called.

stackRequired
  • Type: aws-cdk-lib.Stack
synthesize 
public synthesize(session: ISynthesisSession): void

Synthesize the associated stack to the session.

sessionRequired
  • Type: aws-cdk-lib.ISynthesisSession

Properties

Name Type Description
bootstrapQualifier string The qualifier used to bootstrap this stack.
lookupRole string The role used to lookup for this stack.
assetBucketPrefix string The common prefix for the asset bucket names used by this StackSetStack.
assetBuckets aws-cdk-lib.aws_s3.IBucket[] An array of Buckets can be passed to store assets, enabling StackSetStack Asset support.
bootstrapQualifierOptional 
public readonly bootstrapQualifier: string;
  • Type: string

The qualifier used to bootstrap this stack.

lookupRoleOptional 
public readonly lookupRole: string;
  • Type: string

The role used to lookup for this stack.

assetBucketPrefixOptional 
public readonly assetBucketPrefix: string;
  • Type: string
  • Default: No Buckets provided and Assets will not be supported.

The common prefix for the asset bucket names used by this StackSetStack.

Required if assetBuckets is provided.

assetBucketsOptional 
public readonly assetBuckets: IBucket[];
  • Type: aws-cdk-lib.aws_s3.IBucket[]
  • Default: No Buckets provided and Assets will not be supported.

An array of Buckets can be passed to store assets, enabling StackSetStack Asset support.

One Bucket is required per target region. The name must be ${assetBucketPrefix}-<region>, where <region> is the region targeted by the StackSet.

StackSetTarget

Which organizational units and/or accounts the stack set should be deployed to.

fromAccounts can be used to deploy the stack set to specific AWS accounts

fromOrganizationalUnits can be used to deploy the stack set to specific organizational units and optionally include additional accounts from other OUs, or exclude accounts from the specified OUs

Example

// deploy to specific accounts
StackSetTarget.fromAccounts({
  accounts: ['11111111111', '22222222222'],
  regions: ['us-east-1', 'us-east-2'],
});

// deploy to OUs and 1 additional account
StackSetTarget.fromOrganizationalUnits({
  regions: ['us-east-1', 'us-east-2'],
  organizationalUnits: ['ou-1111111', 'ou-2222222'],
  additionalAccounts: ['33333333333'],
});

// deploy to OUs but exclude 1 account
StackSetTarget.fromOrganizationalUnits({
  regions: ['us-east-1', 'us-east-2'],
  organizationalUnits: ['ou-1111111', 'ou-2222222'],
  excludeAccounts: ['11111111111'],
});

Initializers 

import { StackSetTarget } from 'cdk-stacksets'

new StackSetTarget()
Name Type Description

Static Functions

Name Description
fromAccounts Deploy the StackSet to a list of accounts.
fromOrganizationalUnits Deploy the StackSet to a list of AWS Organizations organizational units.
fromAccounts 
import { StackSetTarget } from 'cdk-stacksets'

StackSetTarget.fromAccounts(options: AccountsTargetOptions)

Deploy the StackSet to a list of accounts.

Example

StackSetTarget.fromAccounts({
  accounts: ['11111111111', '22222222222'],
  regions: ['us-east-1', 'us-east-2'],
});
optionsRequired
fromOrganizationalUnits 
import { StackSetTarget } from 'cdk-stacksets'

StackSetTarget.fromOrganizationalUnits(options: OrganizationsTargetOptions)

Deploy the StackSet to a list of AWS Organizations organizational units.

You can optionally include/exclude individual AWS accounts.

Example

StackSetTarget.fromOrganizationalUnits({
  regions: ['us-east-1', 'us-east-2'],
  organizationalUnits: ['ou-1111111', 'ou-2222222'],
});
optionsRequired

StackSetTemplate

Represents a StackSet CloudFormation template.

Initializers 

import { StackSetTemplate } from 'cdk-stacksets'

new StackSetTemplate()
Name Type Description

Static Functions

Name Description
fromStackSetStack Creates a StackSetTemplate from a StackSetStack.
fromStackSetStack 
import { StackSetTemplate } from 'cdk-stacksets'

StackSetTemplate.fromStackSetStack(stack: StackSetStack)

Creates a StackSetTemplate from a StackSetStack.

stackRequired

the stack to use as the base for the stackset template.

Properties

Name Type Description
templateUrl string The S3 URL of the StackSet template.
templateUrlRequired 
public readonly templateUrl: string;
  • Type: string

The S3 URL of the StackSet template.

Protocols

IStackSet

Represents a CloudFormation StackSet.

Properties

Name Type Description
node constructs.Node The tree node.
env aws-cdk-lib.ResourceEnvironment The environment this resource belongs to.
stack aws-cdk-lib.Stack The stack in which this resource is defined.
role aws-cdk-lib.aws_iam.IRole Only available on self managed stacksets.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

envRequired 
public readonly env: ResourceEnvironment;
  • Type: aws-cdk-lib.ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

stackRequired 
public readonly stack: Stack;
  • Type: aws-cdk-lib.Stack

The stack in which this resource is defined.

roleOptional 
public readonly role: IRole;
  • Type: aws-cdk-lib.aws_iam.IRole

Only available on self managed stacksets.

The admin role that CloudFormation will use to perform stackset operations. This role should only have permissions to be assumed by the CloudFormation service and to assume the execution role in each individual account.

When you create the execution role it must have an assume role policy statement which allows sts:AssumeRole from this admin role.

To grant specific users/groups access to use this role to deploy stacksets they must have a policy that allows iam:GetRole & iam:PassRole on this role resource.

Enums

Capability

StackSets that contains certain functionality require an explicit acknowledgement that the stack contains these capabilities.

Members

Name Description
NAMED_IAM Required if the stack contains IAM resources with custom names.
IAM Required if the stack contains IAM resources.
AUTO_EXPAND Required if the stack contains macros.
NAMED_IAM

Required if the stack contains IAM resources with custom names.

IAM

Required if the stack contains IAM resources.

If the IAM resources also have custom names then specify {@link Capability.NAMED_IAM} instead.

AUTO_EXPAND

Required if the stack contains macros.

Not supported if deploying a service managed stackset.

RegionConcurrencyType

The type of concurrency to use when deploying the StackSet to regions.

Members

Name Description
SEQUENTIAL Deploy the StackSet to regions sequentially in the order specified in {@link StackSetProps.operationPreferences.regionOrder }.
PARALLEL Deploy the StackSet to all regions in parallel.
SEQUENTIAL

Deploy the StackSet to regions sequentially in the order specified in {@link StackSetProps.operationPreferences.regionOrder }.

This is the default behavior.

PARALLEL

Deploy the StackSet to all regions in parallel.