Prerequisites:

Use a pair of client/secret keys of AWS credentials with the following IAM permissions:

• cloudformation:ValidateTemplate
• cloudformation:CreateStack
• cloudformation:UpdateStack
• cloudformation:DeleteStack
• cloudformation:DescribeStacks
• cloudformation:DescribeStackEvents
• cloudformation:ListStacks
• cloudformation:CreateChangeSet
• cloudformation:DescribeChangeSet
• cloudformation:ExecuteChangeSet
• cloudformation:DeleteChangeSet
• cloudformation:ListChangeSets

Actions available:

AWSCloudFormationConnector_ValidateTemplate

Validates the syntax and structure of a CloudFormation template without creating any resources. Returns the declared parameters, required capabilities, and any transforms. Use as a pre-flight check before calling CreateStack or UpdateStack.

Key inputs: TemplateBody or TemplateURL

Key outputs: Parameters list, Capabilities list, Description, DeclaredTransforms

Important: the returned Capabilities list should be stored and passed directly to CreateStack or UpdateStack. If a template requires CAPABILITY_NAMED_IAM and it is not passed at deploy time, the stack creation will fail with InsufficientCapabilitiesException.

AWSCloudFormationConnector_CreateStack

Creates a new CloudFormation stack from a template. Asynchronous — returns immediately with a StackId. Poll DescribeStacks until a terminal status is reached.

Key inputs: StackName, TemplateBody or TemplateURL, Parameters, Capabilities, OnFailure, TimeoutInMinutes, EnableTerminationProtection

Key outputs: StackId

Error to handle: AlreadyExistsException — switch to UpdateStack when received.

Recommended OnFailure values:

• ROLLBACK — default, undoes all changes on failure
• DO_NOTHING — leaves failed resources in place for debugging
• DELETE — rolls back and deletes the stack entirely

AWSCloudFormationConnector_UpdateStack

Applies a new template or updated parameter values to an existing stack. Asynchronous — returns immediately with a StackId. Poll DescribeStacks until a terminal status is reached.

Key inputs: StackName, TemplateBody, TemplateURL, or UsePreviousTemplate, Parameters, Capabilities

Key outputs: StackId

Errors to handle:

• ValidationError with message No updates are to be performed. — treat as success, the stack is already in the desired state
• ValidationError with message containing ROLLBACK_COMPLETE — stack must be deleted and recreated, it cannot be updated
• ValidationError with message does not exist — switch to CreateStack

Note on UsePreviousValue: use this on sensitive parameters (NoEcho: true) to avoid having to re-pass secrets on every update. Pass UsePreviousValue=true for any parameter whose value you do not want to change.

Note on tags: tags do not support UsePreviousValue. Always pass the complete desired tag set — omitting tags will remove them from the stack.

AWSCloudFormationConnector_DeleteStack

Initiates deletion of a stack and all its resources. Asynchronous — returns immediately with an empty response. Poll DescribeStacks until a ValidationError with "does not exist" is returned, which confirms full deletion.

Key inputs: StackName, ClientRequestToken, RetainResources

Key outputs: none (empty response)

Errors to handle:

• ValidationError with termination protection message — call SetTerminationProtect to disable protection before retrying
• DELETE_FAILED stack status — call DescribeStackEvents to identify the blocking resource, resolve the dependency, then retry DeleteStack

Note on RetainResources: only valid when retrying a DELETE_FAILED stack. Pass the logical resource IDs of resources that cannot be deleted so CloudFormation skips them and completes the stack deletion, leaving those resources orphaned in AWS.

AWSCloudFormationConnector_DescribeStacks

Returns the current status, parameters, outputs, and metadata for a stack. The primary polling action after CreateStack, UpdateStack, and ExecuteChangeSet.

Key inputs: StackName (name or ARN)

Key outputs: StackStatus, StackStatusReason, Outputs, Parameters, Tags, EnableTerminationProtection, DriftInformation

Terminal statuses — stop polling:

Note on deletion polling: after DeleteStack, DescribeStacks will eventually return ValidationError with "does not exist" rather than DELETE_COMPLETE. Treat this specific error as a successful deletion confirmation, not a real error.

AWSCloudFormationConnector_DescribeStackEvents

Returns the event log for a stack in reverse chronological order (newest first). Most useful for diagnosing failures — filter for events where ResourceStatus ends in _FAILED and read ResourceStatusReason for the root cause.

Key inputs: StackName (name or ARN), NextToken

Key outputs: list of events with ResourceType, LogicalResourceId, PhysicalResourceId, ResourceStatus, ResourceStatusReason, Timestamp

Failure diagnosis pattern: when DescribeStacks returns a failed terminal status, immediately call DescribeStackEvents and filter for ResourceStatus values ending in _FAILED. The ResourceStatusReason on those events contains the actual AWS error message.

AWSCloudFormationConnector_ListStacks

Returns a summary list of stacks filtered by one or more status values. Does not require a stack name. Can return deleted stacks. Does not return outputs, parameters, or tags — use DescribeStacks for full detail on a specific stack.

Key inputs: StackStatusFilter list, NextToken

Key outputs: list of stack summaries with StackName, StackId, StackStatus, CreationTime, LastUpdatedTime, DeletionTime, DriftInformation

Note: DELETE_COMPLETE stacks are excluded from results unless explicitly included in StackStatusFilter. This is the only status excluded by default.

AWSCloudFormationConnector_CreateChangeSet

Calculates the changes that would result from applying a new template or parameter values to an existing stack, without executing them. Asynchronous — poll DescribeChangeSet until Status reaches CREATE_COMPLETE before reading results or calling ExecuteChangeSet.

Key inputs: StackName, ChangeSetName, ChangeSetType, TemplateBody or TemplateURL or UsePreviousTemplate, Parameters, Capabilities, Description

Key outputs: Id (change set ARN), StackId

Note on ClientToken: this action uses ClientToken for idempotency, not ClientRequestToken as used by other actions. Passing the wrong key name will not produce an error but will not deduplicate requests.

Note on naming: change set names must be unique among active change sets for a stack. A reliable pattern is appending a timestamp, e.g. my-alb-cs-20240115-103000.

AWSCloudFormationConnector_DescribeChangeSet

Returns the status and full list of calculated resource changes for a change set. Poll until Status=CREATE_COMPLETE before reading changes or calling ExecuteChangeSet.

Key inputs: ChangeSetName (name or ARN), StackName, IncludePropertyValues, NextToken

Key outputs: Status, ExecutionStatus, StatusReason, Changes list, Parameters, Tags, Capabilities

ExecutionStatus values to act on:

The most important field in the Changes list is Replacement:

• False — resource updated in-place, no interruption
• True — resource will be destroyed and recreated — flag this prominently in any UI
• Conditional — replacement depends on runtime values — treat with the same caution as True

No-changes case: when CreateChangeSet was submitted with no differences, DescribeChangeSet returns Status=FAILED with StatusReason of The submitted information didn't contain changes. and an empty Changes list. Treat this as a success with a no-op result.

AWSCloudFormationConnector_ExecuteChangeSet

Applies a previously reviewed and approved change set to its target stack. Asynchronous — returns immediately with an empty response. Poll DescribeStacks until a terminal status is reached.

Key inputs: ChangeSetName (name or ARN), StackName, ClientRequestToken, DisableRollback

Key outputs: none (empty response)

Pre-flight check: always verify ExecutionStatus=AVAILABLE from DescribeChangeSet before calling this action. Any other ExecutionStatus will result in InvalidChangeSetStatusException.

Note on automatic deletion: after successful execution, the change set is automatically deleted by CloudFormation. Do not treat its absence from ListChangeSets as an error in post-execution checks.

Note on failure: if execution fails and the stack rolls back, the change set is NOT automatically deleted. You can retry execution after resolving the underlying issue, or delete it and create a new one.

AWSCloudFormationConnector_ListChangeSets

Returns a summary of all change sets for a given stack. Does not return the full changes list — use DescribeChangeSet for full detail on a specific change set.

Key inputs: StackName, NextToken

Key outputs: list of change set summaries with ChangeSetName, ChangeSetId, Status, ExecutionStatus, CreationTime, Description

Typical usage pattern: call ListChangeSets to populate a list of available change sets, then call DescribeChangeSet when the user selects one to review before deciding to execute or discard it.

Known Limitations

• TemplateBody has a maximum size of 51,200 bytes. For larger templates, upload the template to S3 and pass TemplateURL instead.
• This connector does not include S3 upload functionality. A separate S3 connector is needed for TemplateURL support.
• Stack Sets (multi-account / multi-region deployments) are not covered by this connector.