Custom resources allow you to create resources with custom provisioning logic. This enables you to define the logic for creating, updating, and deleting resources, giving you the ability to provision any type of resource that is not natively supported by Stacktape or Cloudformation. This way, you can manage all your related resources in a single stack.
A common use case for custom resources is provisioning non-AWS resources. While AWS offers a vast array of services, a third-party solution may better fit your needs (e.g., using Auth0 instead of Cognito, or Algolia instead of OpenSearch).
If you are not provisioning a custom resource but are looking for a way to execute custom logic during the deployment process, see the deployment scripts documentation.
How to use custom resources
In Stacktape, a custom resource consists of two parts:
- Definition: A special type of Lambda function that contains the custom logic for creating, updating, and deleting the resource.
- Instance: An instantiation of a custom resource definition.
The following example shows a custom resource that seeds a MongoDB cluster.
Custom resource definition
A custom resource definition is similar to a function definition, as it uses a Lambda function to execute the custom logic.
CustomResourceDefinitionAPI referencetypeRequired
Type: string "custom-resource-definition"
properties.packagingRequired
How the Lambda function code is packaged and deployed.
Type: LambdaPackaging
properties.environment
Environment variables injected into the Lambda function. Use $ResourceParam() for dynamic values.
Type: Array of EnvironmentVar
properties.runtime
Lambda runtime. Auto-detected from file extension if not specified.
Type: string ENUM
Possible values: dotnet6dotnet7dotnet8java11java17java8java8.al2nodejs18.xnodejs20.xnodejs22.xnodejs24.xprovided.al2provided.al2023python3.10python3.11python3.12python3.13python3.8python3.9ruby3.3
properties.timeoutDefault: 10
Max execution time in seconds. Max: 900.
Type: number
properties.memory
Memory in MB (128–10,240). CPU scales proportionally — 1,769 MB = 1 vCPU.
Type: number
properties.connectTo
Give this resource access to other resources in your stack.
Type: Array of string
List the names of resources this workload needs to communicate with. Stacktape automatically:
- Grants IAM permissions (e.g., S3 read/write, SQS send/receive)
- Opens network access (security group rules for databases, Redis)
- Injects environment variables with connection details:
STP_[RESOURCE_NAME]_[PARAM]
Example: connectTo: ["myDatabase", "myBucket"] gives this workload full access to both
resources and injects STP_MY_DATABASE_CONNECTION_STRING, STP_MY_BUCKET_NAME, etc.
properties.iamRoleStatements
Raw IAM policy statements for permissions not covered by connectTo.
Type: Array of StpIamRoleStatement
Added as a separate policy alongside auto-generated permissions. Use this for accessing AWS services directly (e.g., Rekognition, Textract, Bedrock).
overrides
Escape hatch to modify the underlying CloudFormation resources Stacktape creates.
Type: Object
Use dot-notation paths to override specific properties on any child resource.
Find resource logical IDs with stacktape stack-info --detailed.
overrides:
MyDbInstance:
Properties.StorageEncrypted: true
Code of custom resource
The packaging property allows you to specify the path to your code and other packaging-related properties. The code is packaged and executed as a Lambda function. For more information, see the packaging documentation.
Code example
The following example shows the code for the MongoDB seeding custom resource. For more information on the types of requests (events) a custom resource receives and the response objects you should return, see the AWS documentation.
Accessing other resources
By default, resource-to-resource communication is not allowed in AWS. Access must be explicitly granted using IAM permissions. Stacktape automatically handles IAM permissions for the underlying AWS services it creates.
If your custom resource needs to communicate with other infrastructure components, you must grant the necessary permissions manually. You can do this in two ways:
connectTo
The connectTo property is a list of resource names or AWS services that the custom resource will be able to access. Stacktape will automatically grant the basic IAM permissions required for communication. This is useful if you do not want to manage IAM permissions yourself.
When you use the connectTo property, Stacktape also automatically injects information about the connected resource as environment variables into your custom resource's runtime.
List the names of resources this workload needs to communicate with. Stacktape automatically:
- Grants IAM permissions (e.g., S3 read/write, SQS send/receive)
- Opens network access (security group rules for databases, Redis)
- Injects environment variables with connection details:
STP_[RESOURCE_NAME]_[PARAM]
Example: connectTo: ["myDatabase", "myBucket"] gives this workload full access to both
resources and injects STP_MY_DATABASE_CONNECTION_STRING, STP_MY_BUCKET_NAME, etc.
In this example, we grant access to a MongoDB cluster. This will inject the necessary credentials into the custom resource's runtime, which are then used in the code example.
StpIamRoleStatementAPI referenceParent:CustomResourceDefinitionResourceRequired
ARNs of the AWS resources this statement applies to. Use "*" for all resources.
Type: Array of string
Sid
Optional identifier for this statement (for readability).
Type: string
EffectDefault: Allow
Whether to allow or deny the specified actions.
Type: string
Action
AWS actions to allow or deny (e.g., s3:GetObject, sqs:SendMessage).
Type: Array of string
Condition
Type: UNSPECIFIED
Environment variables
You can use environment variables to inject information that the resource needs during execution.
EnvironmentVarAPI referenceParent:CustomResourceDefinitionnameRequired
Environment variable name (e.g., DATABASE_URL, API_KEY).
Type: string
valueRequired
Environment variable value. Numbers and booleans are converted to strings.
Type: string or number or boolean
Custom resource instance
A custom resource instance creates an instance of a specified custom resource definition. Depending on the action being performed on the stack (create, update, or delete), the instance receives an event and executes the corresponding logic in the custom resource definition.
CustomResourceInstanceAPI referencetypeRequired
Type: string "custom-resource-instance"
properties.definitionNameRequired
Name of the custom-resource-definition in your config that provides the backing Lambda.
Type: string
properties.resourcePropertiesRequired
Key-value pairs passed to the Lambda function during create/update/delete events.
Type: Object
overrides
Escape hatch to modify the underlying CloudFormation resources Stacktape creates.
Type: Object
Use dot-notation paths to override specific properties on any child resource.
Find resource logical IDs with stacktape stack-info --detailed.
overrides:
MyDbInstance:
Properties.StorageEncrypted: true