aws-cdk-lib.StackSynthesizer

class StackSynthesizer

LanguageType name
.NETAmazon.CDK.StackSynthesizer
Gogithub.com/aws/aws-cdk-go/awscdk/v2#StackSynthesizer
Javasoftware.amazon.awscdk.StackSynthesizer
Pythonaws_cdk.StackSynthesizer
TypeScript (source)aws-cdk-lib » StackSynthesizer

Implements IStackSynthesizer

Implemented by AppStagingSynthesizer, BootstraplessSynthesizer, CliCredentialsStackSynthesizer, DefaultStackSynthesizer, LegacyStackSynthesizer, NestedStackSynthesizer

Base class for implementing an IStackSynthesizer.

This class needs to exist to provide public surface area for external implementations of stack synthesizers. The protected methods give access to functions that are otherwise @_internal to the framework and could not be accessed by external implementors.

Initializer

new StackSynthesizer()

Properties

NameTypeDescription
boundStackStackRetrieve the bound stack.
bootstrapQualifier?stringThe qualifier used to bootstrap this stack.
lookupRole?stringThe role used to lookup for this stack.

boundStack

Type: Stack

Retrieve the bound stack.

Fails if the stack hasn't been bound yet.


bootstrapQualifier?

Type: string (optional)

The qualifier used to bootstrap this stack.


lookupRole?

Type: string (optional)

The role used to lookup for this stack.

Methods

NameDescription
addDockerImageAsset(asset)Register a Docker Image Asset.
addFileAsset(asset)Register a File Asset.
bind(stack)Bind to the stack this environment is going to be used on.
synthesize(session)Synthesize the associated stack to the session.
protected addBootstrapVersionRule(requiredVersion, bootstrapStackVersionSsmParameter)Add a CfnRule to the bound stack that checks whether an SSM parameter exceeds a given version.
protected cloudFormationLocationFromDockerImageAsset(dest)Turn a docker asset location into a CloudFormation representation of that location.
protected cloudFormationLocationFromFileAsset(location)Turn a file asset location into a CloudFormation representation of that location.
protected emitArtifact(session, options?)Write the CloudFormation stack artifact to the session.
protected emitStackArtifact(stack, session, options?)⚠️Write the stack artifact to the session.
protected synthesizeStackTemplate(stack, session)⚠️Have the stack write out its template.
protected synthesizeTemplate(session, lookupRoleArn?)Write the stack template to the given session.

addDockerImageAsset(asset)

public addDockerImageAsset(asset: DockerImageAssetSource): DockerImageAssetLocation

Parameters

  • asset DockerImageAssetSource

Returns

  • 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.


addFileAsset(asset)

public addFileAsset(asset: FileAssetSource): FileAssetLocation

Parameters

  • asset FileAssetSource

Returns

  • 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.


bind(stack)

public bind(stack: Stack): void

Parameters

  • stack Stack

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

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


synthesize(session)

public synthesize(session: ISynthesisSession): void

Parameters

  • session ISynthesisSession

Synthesize the associated stack to the session.


protected addBootstrapVersionRule(requiredVersion, bootstrapStackVersionSsmParameter)

protected addBootstrapVersionRule(requiredVersion: number, bootstrapStackVersionSsmParameter: string): void

Parameters

  • requiredVersion number
  • bootstrapStackVersionSsmParameter string

Add a CfnRule to the bound stack that checks whether an SSM parameter exceeds a given version.

This will modify the template, so must be called before the stack is synthesized.


protected cloudFormationLocationFromDockerImageAsset(dest)

protected cloudFormationLocationFromDockerImageAsset(dest: DockerImageDestination): DockerImageAssetLocation

Parameters

  • dest DockerImageDestination

Returns

  • DockerImageAssetLocation

Turn a docker asset location into a CloudFormation representation of that location.

If any of the fields contain placeholders, the result will be wrapped in a Fn.sub.


protected cloudFormationLocationFromFileAsset(location)

protected cloudFormationLocationFromFileAsset(location: FileDestination): FileAssetLocation

Parameters

  • location FileDestination

Returns

  • FileAssetLocation

Turn a file asset location into a CloudFormation representation of that location.

If any of the fields contain placeholders, the result will be wrapped in a Fn.sub.


protected emitArtifact(session, options?)

protected emitArtifact(session: ISynthesisSession, options?: SynthesizeStackArtifactOptions): void

Parameters

  • session ISynthesisSession
  • options SynthesizeStackArtifactOptions

Write the CloudFormation stack artifact to the session.

Use default settings to add a CloudFormationStackArtifact artifact to the given synthesis session. The Stack artifact will control the settings for the CloudFormation deployment.


protected emitStackArtifact(stack, session, options?)⚠️

protected emitStackArtifact(stack: Stack, session: ISynthesisSession, options?: SynthesizeStackArtifactOptions): void

⚠️ Deprecated: Use emitArtifact instead

Parameters

  • stack Stack
  • session ISynthesisSession
  • options SynthesizeStackArtifactOptions

Write the stack artifact to the session.

Use default settings to add a CloudFormationStackArtifact artifact to the given synthesis session.


protected synthesizeStackTemplate(stack, session)⚠️

protected synthesizeStackTemplate(stack: Stack, session: ISynthesisSession): void

⚠️ Deprecated: Use synthesizeTemplate instead

Parameters

  • stack Stack
  • session ISynthesisSession

Have the stack write out its template.


protected synthesizeTemplate(session, lookupRoleArn?)

protected synthesizeTemplate(session: ISynthesisSession, lookupRoleArn?: string): FileAssetSource

Parameters

  • session ISynthesisSession
  • lookupRoleArn string

Returns

  • FileAssetSource

Write the stack template to the given session.

Return a descriptor that represents the stack template as a file asset source, for adding to an asset manifest (if desired). This can be used to have the asset manifest system (cdk-assets) upload the template to S3 using the appropriate role, so that afterwards only a CloudFormation deployment is necessary.

If the template is uploaded as an asset, the stackTemplateAssetObjectUrl property should be set when calling emitArtifact.

If the template is NOT uploaded as an asset first and the template turns out to be >50KB, it will need to be uploaded to S3 anyway. At that point the credentials will be the same identity that is doing the UpdateStack call, which may not have the right permissions to write to S3.