AWS CloudFormation ExecModule

Overview

AwsCloudFormationModule brings governed infrastructure-as-code operations into ValkyrAI workflows. It validates templates, discovers stacks and resources, stages reviewable change sets, initiates explicitly confirmed stack lifecycle operations, and starts and inspects drift detection. It uses ValkyrAI's native map ABI and a verified IntegrationAccount; credentials never belong in workflow input.

The connector implements twelve operations:

• list_stacks, describe_stack, and list_stack_resources inspect bounded infrastructure state.
• validate_template checks a JSON/YAML body or an AWS-hosted template URL without changing a stack.
• create_change_set, describe_change_set, and execute_change_set separate infrastructure planning, review, and execution.
• create_stack, update_stack, and delete_stack initiate explicitly confirmed stack lifecycle changes.
• detect_stack_drift starts an asynchronous scan; describe_stack_drift reads its status and result.

n8n's AWS credential model provides useful workflow patterns—one reusable credential, region-aware calls, and composable outputs—but its current built-in integration catalog does not provide a dedicated CloudFormation node. ValkyrAI adds a native connector centered on review-first change sets, strict operation-specific fields, template and collection bounds, client tokens, explicit confirmations, read-only retry, and deterministic reconciliation after ambiguous mutations.

Usage

1. Identify the exact stack, region, template source, and CloudFormation actions the workflow needs.
2. Create a least-privilege IAM principal restricted to those actions, stack ARNs, template buckets, service roles, and downstream resource actions.
3. Store its access key ID and secret access key in an AWS IntegrationAccount; verify it and keep it in READY status.
4. Add AwsCloudFormationModule and bind the account through ExecModuleConfig.authConfig.integrationAccount.
5. Prefer validate_template followed by create_change_set and describe_change_set before any execute_change_set or direct stack mutation.
6. Supply only the fields accepted by the selected operation. Unexpected fields fail before provider access.
7. Use a stable clientToken for supported mutations and reconcile the exact stack or change set before replaying a timeout.

Never place an AWS access key, secret key, session token, or credentials object in module input. Those fields are rejected before any network request. Templates, parameter values, stack outputs, physical resource IDs, and provider tokens are classified confidential and belong only in ACL-scoped workflow state.

Inputs

Name	Type	Required for	Default	Constraints
operation	string	Every execution	None	One of the twelve documented operations.
region	string	Every execution	None	AWS region such as us-west-2; custom endpoints are not accepted.
stackName	string	Stack, change-set, and drift operations	None	Stack name or CloudFormation stack ARN whose region matches region.
changeSetName	string	Change-set operations	None	Change-set name or CloudFormation change-set ARN whose region matches region.
changeSetType	string	Optional create_change_set field	UPDATE	CREATE or UPDATE; previous templates/values are invalid for CREATE.
stackDriftDetectionId	string	describe_stack_drift	None	UUID returned by detect_stack_drift.
nextToken	string	Optional list/change-set field	None	Opaque provider token, at most 4,096 characters.
limit	integer	Optional list/change-set field	100	Total result bound from 1 through 10,000.
returnAll	boolean	Optional list/change-set field	false	Follow pages until limit, exhaustion, or the 100-page guard.
stackStatusFilters	array	Optional list_stacks field	Empty	Up to 23 unique CloudFormation stack status values.
templateBody	object or string	Template operations	None	JSON object or JSON/YAML string; 1-51,200 UTF-8 bytes.
templateUrl	string	Template operations	None	HTTPS URL on an amazonaws.com or amazonaws.com.cn host, at most 2,048 characters.
usePreviousTemplate	boolean	Optional update/change-set field	false	Mutually exclusive with templateBody and templateUrl; UPDATE only.
parameters	array	Optional stack/change-set field	Empty	Up to 200 unique {key,value} or {key,usePreviousValue:true} objects.
capabilities	array	Optional stack/change-set field	Empty	Unique CAPABILITY_IAM, CAPABILITY_NAMED_IAM, or CAPABILITY_AUTO_EXPAND values.
tags	array	Optional stack/change-set field	Empty	Up to 50 unique {key,value} objects; aws: keys are rejected.
roleArn	string	Optional stack/change-set/delete field	None	IAM role ARN used by CloudFormation.
clientToken	string	Optional supported mutation field	None	Stable 1-128 character token using letters, digits, and hyphens.
description	string	Optional create_change_set field	None	Safe text up to 1,024 characters.
includeNestedStacks	boolean	Optional create_change_set field	false	Include nested stacks when AWS supports the requested change-set shape.
retainResources	array	Optional delete_stack field	Empty	Up to 200 unique logical resource IDs to retain.
logicalResourceIds	array	Optional detect_stack_drift field	Empty	Up to 100 unique logical IDs; empty asks AWS to inspect the full stack.
confirmCreate	boolean	create_stack	false	Must be exactly true.
confirmUpdate	boolean	update_stack	false	Must be exactly true.
confirmDelete	boolean	delete_stack	false	Must be exactly true.
confirmCreateChangeSet	boolean	create_change_set	false	Must be exactly true.
confirmExecuteChangeSet	boolean	execute_change_set	false	Must be exactly true.
confirmDetectDrift	boolean	detect_stack_drift	false	Must be exactly true.

Template operations require exactly one of templateBody, templateUrl, or—only for UPDATE paths—usePreviousTemplate=true. CloudFormation parameters that reuse an existing value must omit value and set usePreviousValue=true. Parameters supplied for CREATE operations must provide a value.

Outputs

Every call returns stable status, operation, and attempts fields.

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation.
attempts	integer	Always	Provider calls including pages and retry-safe reads.
resultType	string	Success	stacks, stack, stack_resources, template_validation, change_set_changes, change_set_lifecycle, stack_lifecycle, or stack_drift.
items	array	List, validation, or change-set success	Bounded normalized records.
count	integer	Items are present	Number of returned items.
pages	integer	Paginated success	Provider pages consumed.
hasMore	boolean	Paginated success	Whether AWS returned another token.
nextToken	string	Another page exists	Opaque continuation token.
data	object	Success	Stack, validation, change-set, lifecycle, or drift receipt.
requestId	string	AWS supplies one	Bounded request reference for reconciliation.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

Stack discovery returns status, lifecycle timestamps, drift state, outputs, tags, and parameter keys. Parameter values are intentionally omitted. Validation omits default values for NoEcho parameters. Change-set inspection returns bounded resource actions, logical/physical IDs, resource types, replacement behavior, and scope without unbounded property diffs.

IntegrationAccount Requirements

Bind one AWS IntegrationAccount through the normalized ExecModule authentication relationship:

Field	Requirement
Provider	Amazon Web Services / CloudFormation
status	Must be READY.
verified	Must be true.
apiKey SecureField	AWS access key ID.
password SecureField	AWS secret access key.

Grant only the actions enabled for the workflow:

• Discovery: cloudformation:ListStacks, cloudformation:DescribeStacks, and cloudformation:ListStackResources.
• Templates: cloudformation:ValidateTemplate plus read access to the exact S3 template objects where URLs are used.
• Change sets: cloudformation:CreateChangeSet, cloudformation:DescribeChangeSet, and cloudformation:ExecuteChangeSet only as needed.
• Stack lifecycle: cloudformation:CreateStack, cloudformation:UpdateStack, and cloudformation:DeleteStack only for reviewed stacks.
• Drift: cloudformation:DetectStackDrift and cloudformation:DescribeStackDriftDetectionStatus.
• Service roles: iam:PassRole restricted to the exact approved roleArn and CloudFormation service condition.
• Template resources can require downstream service permissions even when the workflow calls only CloudFormation.

The connector currently supports a long-lived access-key pair. STS session credentials, role assumption, workload identity, custom endpoints, StackSets, imports, resource scans, hooks, registry types, stack policies, rollback triggers, waiters, and termination-protection changes are deferred.

Configuration

The awsAccount relationship is the only credential configuration. Operation, region, template, stack, change-set, parameter, and safety fields belong in mapped input or module parameters.

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:aws-cloudformation-production"
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"create_change_set\",\"region\":\"us-west-2\"}"
  }
}

The relationship value is illustrative. Persisted workflows bind the generated IntegrationAccount relationship, never plaintext credentials.

Operations

Operation	Provider behavior	Side effect and retry behavior
list_stacks	Lists bounded stack summaries with optional status filters.	Read-only; each page retries transient failures.
describe_stack	Reads one stack's state, outputs, tags, parameter keys, and drift summary.	Read-only; bounded retry.
list_stack_resources	Lists bounded logical and physical resource summaries.	Read-only; opaque pagination and bounded retry.
validate_template	Validates one bounded body or AWS-hosted URL and returns parameter/capability requirements.	Read-only; bounded retry. The template is never echoed by the connector.
create_change_set	Stages a CREATE or UPDATE plan under a stable name/token.	Confirmed mutation; exactly one provider attempt. Poll describe_change_set.
describe_change_set	Reads bounded proposed resource changes and execution readiness.	Read-only; opaque pagination and bounded retry.
execute_change_set	Starts execution of the reviewed change set.	Confirmed infrastructure mutation; exactly one attempt.
create_stack	Starts asynchronous stack creation.	Confirmed infrastructure mutation; exactly one attempt.
update_stack	Starts asynchronous stack update.	Confirmed infrastructure mutation; exactly one attempt.
delete_stack	Starts deletion, optionally retaining named logical resources.	Destructive; confirmation and exactly one attempt.
detect_stack_drift	Starts asynchronous drift detection for the full stack or a logical-ID subset.	Confirmed provider job; exactly one attempt.
describe_stack_drift	Reads drift detection progress, final stack drift state, and count.	Read-only; bounded retry.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing/malformed region, ARN, template, parameter, tag, capability, token, pagination value, confirmation, or unexpected field.	No	Correct the named input; no provider request was sent.
UNSUPPORTED_OPERATION	Unknown operation.	No	Select a documented operation.
INTEGRATION_ACCOUNT_ERROR	Account missing, unverified, not READY, or missing key material.	No	Repair and bind the AWS account.
AWS_CLOUDFORMATION_HTTP_400	Template error, invalid stack state, no updates, capability omission, duplicate token, or provider limit.	Reads may retry selected transient codes	Inspect operation, provider state, and request ID.
AWS_CLOUDFORMATION_HTTP_403	IAM, S3, service-role, KMS, or downstream resource permission denied.	No	Grant only the missing action/resource/condition.
AWS_CLOUDFORMATION_HTTP_404	Stack, change set, template, or drift receipt no longer exists.	No	Reconcile the exact immutable identifier.
AWS_CLOUDFORMATION_HTTP_429 / 500 / 503	Throttle or transient provider pressure.	Reads retry; mutations report ambiguity	Inspect stack/change-set/drift state and client token before replay.
NETWORK_ERROR	DNS, TLS, timeout, or connectivity failure.	Reads retry; mutations report ambiguity	Treat provider acceptance as unknown until exact state is checked.
EXECUTION_ERROR	Unexpected bounded runtime failure.	No automatic replay	Preserve operation and request evidence for investigation.

Provider exception messages are never copied into workflow output. This prevents credentials, template bodies, parameter values, role ARNs, stack output data, and provider details from leaking through errors.

Example

Create a reviewable update change set:

{
  "operation": "create_change_set",
  "region": "us-west-2",
  "stackName": "customer-portal",
  "changeSetName": "release-2026-09-07",
  "changeSetType": "UPDATE",
  "templateUrl": "https://approved-templates.s3.us-west-2.amazonaws.com/customer-portal.yaml",
  "parameters": [
    {"key": "ImageId", "value": "ami-0123456789abcdef0"},
    {"key": "InstanceType", "usePreviousValue": true}
  ],
  "capabilities": ["CAPABILITY_NAMED_IAM"],
  "tags": [{"key": "Environment", "value": "production"}],
  "clientToken": "customer-portal-release-20260907",
  "confirmCreateChangeSet": true
}

Expected result shape:

{
  "status": "success",
  "operation": "create_change_set",
  "attempts": 1,
  "resultType": "change_set_lifecycle",
  "data": {
    "accepted": true,
    "expectedStatus": "CREATE_PENDING",
    "stackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/customer-portal/uuid",
    "changeSetId": "arn:aws:cloudformation:us-west-2:123456789012:changeSet/release-2026-09-07/uuid"
  },
  "requestId": "aws-request-reference"
}

The receipt proves only that AWS accepted creation of the change set. Poll describe_change_set until status=CREATE_COMPLETE, inspect every resource action and replacement, then separately approve execute_change_set.

Notes

• Pagination: list_stacks, list_stack_resources, and describe_change_set return one page unless returnAll=true; the connector follows opaque tokens with unchanged filters and stops at limit, exhaustion, or 100 pages.
• Rate limits: CloudFormation quotas vary by account, region, action, and concurrent stack operations. Read calls use at most five configured attempts with bounded backoff. Template, change-set, drift, and stack mutations never retry automatically.
• API limits: template bodies are capped at 51,200 UTF-8 bytes; remote templates must use HTTPS AWS hosts; parameters at 200; tags at 50; retained resources at 200; drift logical IDs at 100; list results at 10,000; and pages at 100. AWS can impose tighter account- or operation-specific limits.
• Idempotency: stable client tokens help AWS recognize supported repeated requests, but they do not make a timeout safe to replay blindly. Reconcile the exact stack or change set and token before another mutation.
• Change-set review: a successful create_change_set response does not mean the plan is ready or valid. Poll describe_change_set, require CREATE_COMPLETE and an executable status, review replacements and IAM capabilities, then execute once.
• Asynchronous behavior: stack creation, update, deletion, change-set creation/execution, and drift detection continue after acceptance. Poll the relevant read operation for terminal state; never interpret the acceptance response as completion.
• Destructive behavior: delete_stack can permanently remove all managed resources and data. retainResources changes which resources survive but can leave separately billable infrastructure. execute_change_set and update_stack can replace resources even when their names remain stable.
• Rollback and no-updates: CloudFormation can roll back failed operations. An update with no changes is commonly rejected by AWS and should be treated as a reconciled no-op only after the exact stack/template/parameters are verified.
• Security: template bodies, parameter values, outputs, physical IDs, role ARNs, and tokens are confidential. NoEcho reduces display but does not make a value a safe secret store. Prefer Secrets Manager or Parameter Store dynamic references and explicit ACLs around workflow state.
• Deferred operations: StackSets, imports, exports, stack events, resource scans, drift details, generated templates, hooks, registry types, waiters, rollback configuration, notification ARNs, stack policies, termination protection, forced deletion, and custom endpoints are intentionally not implemented.
• Provider verification boundary: deterministic tests cover validation, template selection, URL allowlisting, parameters/tags/capabilities, pagination, operation families, retry boundaries, confirmations, credential/template redaction, error normalization, registration, and metadata. Live AWS behavior remains unverified until an authorized AWS account, reviewed stack, and approved template are supplied.
• Functional reference: n8n's AWS credential model informs reusable credentials and regional workflow ergonomics. AWS CloudFormation API reference defines provider operations. ValkyrAI adds the review, confirmation, redaction, and retry boundaries described above.
• Runtime boundary: merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsCloudFormationModule through /v1/modules/metadata.

Related Documentation

• ExecModule catalog
• AWS CloudFormation API reference
• AWS Step Functions ExecModule
• AWS EventBridge ExecModule
• AWS Kinesis Data Streams ExecModule
• AWS Lambda ExecModule
• Integration Account Console