Stacktape generates AWS CloudFormation templates from your configuration. When you need to customize the underlying AWS resources beyond what Stacktape exposes — set a parameter Stacktape doesn't surface, tune a database engine setting, or add an AWS resource type Stacktape doesn't natively support — overrides and escape hatches give you direct access to the CloudFormation layer without leaving your Stacktape project.
Why this exists
Stacktape covers the high-signal 80% of AWS resource configuration through its typed properties. But AWS services expose hundreds of settings, and Stacktape intentionally doesn't surface every one. Overrides and escape hatches close the gap: you keep Stacktape's deployment, observability, and lifecycle management while reaching through to any CloudFormation property or resource type.
When to use escape hatches
Use overrides and escape hatches when:
- You need a CloudFormation property Stacktape doesn't expose (e.g., reserved concurrency on a Lambda function, enhanced monitoring on RDS)
- You need to add an AWS resource Stacktape doesn't have a built-in type for (e.g., a custom CloudWatch dashboard, an SES configuration set)
- You need to compute or dynamically modify CloudFormation properties based on existing values (transforms)
- You need full CDK-level control for complex infrastructure (CDK constructs)
When NOT to use escape hatches
Check Stacktape's built-in properties first. Overrides bypass Stacktape's validation and auto-configuration, so they're harder to maintain and can conflict with future Stacktape updates. If a property is available directly on the resource (like memory on a Lambda function or scaling on a web service), use the native property instead.
Understanding child resources
Each Stacktape resource creates one or more CloudFormation resources internally — called "child resources." For example, a Lambda function creates an AWS::Lambda::Function, an AWS::IAM::Role, and an AWS::Logs::LogGroup. A web service creates an ECS task definition, an ECS service, IAM roles, security groups, and potentially load balancer resources.
Overrides and transforms name a child resource by its CloudFormation logical ID: the key it has under Resources in the generated template. The logical ID combines the Stacktape resource name with the child's kind, so a Lambda function named api has the child ApiFunction.
Finding child resource names
Run stacktape synth to generate the CloudFormation template locally and find the logical ID of the child resource you want to change:
This writes a compiled-template.yaml file. Use it to verify that your overrides produce the expected CloudFormation properties. For a deployed stack, stacktape status lists the child resources too:
Common child resource names
The table below lists commonly overridden child resources of a resource named api (or db, uploads, mainTable). Replace the first part of the logical ID with the PascalCase name of your resource.
| Stacktape resource type | Logical ID of the child resource | AWS resource type |
|---|---|---|
Lambda function api | ApiFunction | AWS::Lambda::Function |
Lambda function api | ApiRole | AWS::IAM::Role |
Lambda function api | ApiLogGroup | AWS::Logs::LogGroup |
Web service api | ApiTaskDefinition | AWS::ECS::TaskDefinition |
Web service api | ApiRole | AWS::IAM::Role |
Relational database db | DbDbInstance | AWS::RDS::DBInstance |
Relational database db | DbDbParameterGroup | AWS::RDS::DBParameterGroup |
Bucket uploads | UploadsBucket | AWS::S3::Bucket |
DynamoDB table mainTable | MainTableGlobalTable | AWS::DynamoDB::GlobalTable |
HTTP API Gateway api | ApiApi | AWS::ApiGatewayV2::Api |
The table above is not exhaustive, and the children of a resource depend on its configuration. An override whose target is not a child of the resource is rejected, and the error lists the valid logical IDs.
Overrides
Stacktape resource overrides let you set specific CloudFormation properties on child resources. The overrides property accepts an object where each key is the logical ID of a child resource (such as ApiFunction) and the value is an object of CloudFormation properties to set.
The properties are relative to the child resource's Properties: write ReservedConcurrentExecutions, not Properties.ReservedConcurrentExecutions. For nested properties, use a nested object or a dot-notation path such as TimeToLiveSpecification.Enabled. Overrides apply your specified keys on top of what Stacktape generates for each child resource.
Basic override example
This example sets reserved concurrent executions on a Lambda function's underlying AWS::Lambda::Function resource:
The key ApiFunction is the logical ID of the function's AWS::Lambda::Function child resource. This example uses an override to set the CloudFormation ReservedConcurrentExecutions property directly on that child resource.
Override with nested properties
For a nested CloudFormation property, use a dot-notation path or a nested object. This example enables time-to-live on a DynamoDB table; the path starts at the table's properties, without Properties.:
A nested object works the same way. This example configures an RDS parameter group:
DbDbParameterGroup is the logical ID of the database's AWS::RDS::DBParameterGroup child resource. The Parameters key is the CloudFormation property that accepts database engine parameters. The valid keys are RDS engine parameters for the selected PostgreSQL version and instance family — check the AWS RDS parameter group documentation for available parameters.
S3 bucket override example
Transforms
Transforms are functions that receive the current CloudFormation properties of a child resource and return modified properties. They're more flexible than overrides because you can compute values, conditionally modify properties, or append to arrays without knowing the full existing configuration.
In TypeScript configs using defineConfig, transforms are native JavaScript functions — the recommended approach because you get IDE autocomplete and type safety. The legacy curated examples show YAML transforms as inline JavaScript function body strings; prefer TypeScript configs for transforms because the function is native code.
How transforms work
Each transform function receives the Properties object of a CloudFormation resource and must return the modified properties:
Basic transform example
This appends a Lambda layer ARN to whatever layers Stacktape already configured. With a plain override, you'd need to specify the complete final list of layers — with a transform, you append to the existing value safely.
Transform for container workloads
The ApiTaskDefinition transform modifies the ECS task definition to add file descriptor limits to all containers. This is useful for high-connection workloads (WebSocket servers, connection pools) where the default Linux nofile limit is too low.
When to use transforms over overrides
Use transforms when you need to:
- Append to arrays — add layers, environment variables, or mount points without clobbering existing entries
- Conditionally modify — change a property only if it meets a condition
- Compute derived values — set a property based on another property's current value
Use overrides when you know the exact final value and it doesn't depend on existing configuration.
Overrides vs transforms
| Aspect | Overrides | Transforms |
|---|---|---|
| Syntax | Static key-value pairs | JavaScript function |
| Config format | TypeScript and YAML | TypeScript (native functions) and YAML (function strings) |
| Use case | Set known property values | Compute, append, or conditionally modify |
| Merge behavior | Recursive merge for existing top-level objects; directly assigned arrays replace their target | Full control — you return the final object |
| Stacktape validation | CloudFormation property values are not Stacktape-validated; verify with synth | No Stacktape validation on returned properties; verify with synth |
Raw CloudFormation resources
The cloudformationResources top-level config property lets you add any AWS CloudFormation resource directly to your stack. This is the escape hatch for AWS services Stacktape doesn't have a built-in resource type for — SES configuration sets, custom CloudWatch dashboards, Secrets Manager secrets, or any of the 750+ CloudFormation resource types.
Raw CloudFormation resources are merged into the final template as-is. They don't benefit from Stacktape's automatic IAM permissions, connectTo integration, or simplified configuration.
Adding a raw CloudFormation resource
Each key in cloudformationResources (such as AlertTopic above) becomes the CloudFormation logical name. The value uses standard CloudFormation syntax with Type and Properties keys, as shown in the AWS CloudFormation Resource Reference. You can add multiple resources in the same block.
Referencing CloudFormation resources from Stacktape
Use the $CfResourceParam directive to reference attributes of raw CloudFormation resources. Import $CfResourceParam from stacktape and call it with the logical resource name and the CloudFormation attribute to retrieve — for example, $CfResourceParam('AlertTopic', 'TopicArn') to get the ARN of an SNS topic. The available attributes depend on the CloudFormation resource type — check the AWS CloudFormation Resource Reference for each resource type's return values. To get the value Ref returns, such as the physical ID, use that value's name rather than Ref: $CfResourceParam('ImageFunction', 'FunctionName') for an AWS::Lambda::Function, or BucketName for an AWS::S3::Bucket. An unknown attribute fails with an error that lists the accepted names. The CodeBlock example above shows this pattern in a complete defineConfig config.
Referencing Stacktape resources from CloudFormation
Use the $ResourceParam directive inside cloudformationResources to reference attributes of Stacktape-managed resources. For example, to create a Lambda invocation permission that references both a Stacktape-managed Lambda function and a raw CloudFormation SNS topic, use $ResourceParam('processor', 'arn') to get the function ARN and $CfResourceParam('AlertTopic', 'TopicArn') to get the topic ARN. Both directives are importable from the stacktape package and can be used as values in cloudformationResources property definitions.
DependsOn for ordering
Use the standard CloudFormation DependsOn property to control creation order between raw resources. Add DependsOn: ['AlertTopic'] to a resource definition within cloudformationResources to ensure it is created after the specified dependency. This follows standard CloudFormation ordering semantics.
Limitations of raw CloudFormation resources
- No automatic IAM permissions — you must manage roles and policies yourself
- No
connectTosupport — environment variables and security group rules aren't injected automatically - No Stacktape-level validation — CloudFormation errors surface only at deploy time
- Property updates may require resource replacement — some CloudFormation properties can't be updated in-place
For more complex raw CloudFormation usage patterns, see Raw CloudFormation resources.
AWS CDK constructs
For complex escape-hatch scenarios where raw CloudFormation is too verbose, Stacktape supports embedding AWS CDK constructs directly in your stack using the AwsCdkConstruct resource type. Write a CDK construct class in TypeScript or JavaScript, and Stacktape synthesizes and deploys it alongside your other resources.
CDK constructs are the right choice when you need multiple interrelated AWS resources with complex logic — for example, a custom CloudWatch monitoring dashboard with dynamic widgets, a VPC peering setup, or a multi-step Step Functions workflow that Stacktape's built-in state machine doesn't cover. For a single additional resource (like an SNS topic or a Secrets Manager secret), raw CloudFormation in cloudformationResources is simpler.
CDK construct example
First, write a construct class that extends Construct from the constructs package and uses AWS CDK modules from aws-cdk-lib as needed:
Then reference it in your Stacktape config:
The AwsCdkConstruct class accepts three properties: entryfilePath (required, path to the file containing the construct class), exportName (optional, defaults to "default", names the exported class), and constructProperties (optional, object passed as the third argument to the construct's constructor). Use $ResourceParam and $CfResourceParam inside constructProperties to pass dynamic values from other resources. For the full property reference and advanced patterns, see AWS CDK constructs.
Inspecting the generated template
To verify that your overrides, transforms, and raw resources produce the expected CloudFormation output, use stacktape synth:
This writes the final CloudFormation template to compiled-template.yaml. Inspect it before deploying to catch errors early — CloudFormation deployment failures are slower to debug than template inspection.
Best practices
- Try native properties first. Overrides are a last resort. Check the resource's API reference for the property you need before reaching for an override.
- Use transforms for array modifications. If you need to append to an existing array (layers, environment variables, mount points), a transform is safer than an override because it preserves whatever Stacktape already configured.
- Keep overrides minimal. Each override is a maintenance obligation — Stacktape may change its internal resource structure in future versions.
- Validate with
synth. Always inspect the compiled output after adding overrides or transforms. Overrides bypass Stacktape's validation, so errors only surface at deploy time if you skip this step. - Prefer CDK constructs for multi-resource setups. If you need more than 2-3 related raw CloudFormation resources with cross-references, a CDK construct is cleaner and benefits from CDK's type-safe APIs.
- Document why, not what. When using overrides, add a code comment explaining why the override is needed — the code already shows what it does.
Overrides and Escape Hatches FAQ
Should I use overrides or transforms?
An object override for an existing top-level object recursively merges into it. A directly assigned array replaces that array, and a dot path sets its target. Nested arrays inside merged objects follow lodash merge semantics. Use transforms when you need explicit control over nested arrays, appending entries or removing existing keys.
Can I use overrides and transforms in YAML configs?
Both work in YAML, but transforms are awkward there: YAML transforms are written as inline JavaScript function body strings, while overrides are plain objects keyed by child resource name. Prefer TypeScript configs — transforms become native functions with IDE autocomplete and type safety, and overrides get intellisense for child resource keys.
Will overrides break when Stacktape updates?
Possibly. If Stacktape changes how it structures a child resource internally, your override could target a property that no longer exists or behaves differently. This is rare in patch updates but can happen in major versions. Pin your Stacktape version in production and test overrides after upgrading. Running synth after an upgrade shows whether your overrides still produce the expected output.
What attributes can I reference with $CfResourceParam?
Use the name of the value returned by CloudFormation Ref, such as FunctionName for AWS::Lambda::Function or BucketName for AWS::S3::Bucket; do not pass the literal Ref. Other return-value names depend on the resource type. Invalid names are rejected with the accepted names. See the CloudFormation resource reference for each type's return values.
Do raw CloudFormation resources get automatic IAM permissions?
No. Unlike Stacktape-managed resources — which get baseline IAM permissions automatically and support connectTo integration — raw CloudFormation resources require you to manage IAM roles and policies manually. You'll need to add your own AWS::IAM::Role or AWS::IAM::Policy resources in cloudformationResources, or use overrides on existing Stacktape-managed roles to add additional policy statements.
When should I use a CDK construct instead of raw CloudFormation?
Use CDK constructs when you need multiple interrelated resources with complex configuration logic — for example, a CloudWatch dashboard with dynamic widgets, a custom VPC peering setup, or a Step Functions state machine with many states. CDK provides type-safe APIs, intelligent defaults, and handles cross-resource references cleanly. For a single additional resource (like an SNS topic or a Secrets Manager secret), raw CloudFormation is simpler and has less tooling overhead.
Can I override resources conditionally based on the stage?
Yes. Since TypeScript configs are executable code, you can use standard conditionals. Access the stage name via deploy-time parameters or environment variables, then conditionally include overrides. For example, you might enable enhanced RDS monitoring only in production by checking the stage name before adding the MonitoringInterval override.