Raw CloudFormation Resources

Stacktape's cloudformationResources config property adds raw AWS CloudFormation resources directly to your stack's template. Use this escape hatch when you need an AWS service that Stacktape doesn't offer as a built-in resource type — the resources merge into the generated CloudFormation template as-is and do not count toward your Stacktape resource limit.

When to use

Raw CloudFormation resources are the right tool when Stacktape's built-in resource types don't cover an AWS service you need. Common examples include AWS SES email identities, Cognito Identity Pools, CloudWatch Dashboards, AWS Glue jobs, and AppSync APIs — services that many teams need but that don't have a dedicated Stacktape abstraction.

Choose this approach when:

  • You need an AWS service Stacktape doesn't cover. Stacktape offers 30+ built-in resource types, but AWS has hundreds of CloudFormation resource types. The cloudformationResources property bridges the gap.
  • You need precise control over CloudFormation resource attributes. Raw resources follow standard CloudFormation resource syntax — you write the same structure you'd write in a CloudFormation template directly.
  • You're migrating from an existing CloudFormation stack. Move resources incrementally into Stacktape's managed resources while keeping some as raw CloudFormation during the transition.

When NOT to use

Three situations where a different approach is better:

  • Stacktape has a built-in resource type for what you need. Built-in resources defined in the resources map are the documented path for connectTo, alarms, dev mode, and Stacktape Console integration. Raw CloudFormation resources are not Stacktape resource definitions, so they do not get the typed connectTo behavior documented for Stacktape resources. Check the resource catalog first.
  • You need to modify a property on a Stacktape-managed resource. Use overrides instead. Overrides let you change specific properties on CloudFormation resources that Stacktape already manages, without replacing the Stacktape abstraction.
  • You want higher-level CDK abstractions. CDK constructs provide L2/L3 construct libraries with built-in best practices, sensible defaults, and inter-resource wiring. Raw CloudFormation is lower-level and requires you to specify every property explicitly.

Basic example

The cloudformationResources property sits alongside resources at the top level of your config. Each entry is a named CloudFormation resource following standard AWS CloudFormation resource syntax. At minimum, each resource needs a Type string. Most also include Properties specific to that resource type.

This example adds an AWS SES email identity for sending transactional emails alongside a Stacktape-managed Lambda function:

export default defineConfig(() => {
  const emailSender = new LambdaFunction({
    packaging: new JsBundleLambdaPackaging({
      entryfilePath: './src/send-email.ts'
    }),
    environment: { SENDER_DOMAIN: 'notifications.example.com' },
    iamRoleStatements: [
      {
        Effect: 'Allow',
        Action: ['ses:SendEmail', 'ses:SendRawEmail'],
        Resource: ['*']
      }
    ]
  });

  return {
    resources: { emailSender },
    cloudformationResources: {
      sesEmailIdentity: {
        Type: 'AWS::SES::EmailIdentity',
        Properties: {
          EmailIdentity: 'notifications.example.com'
        }
      }
    }
  };
});

The example uses Resource: ['*'] for brevity, granting SES permissions across all identities. Scope the IAM resource to a specific ARN pattern according to your security requirements, especially when managing multiple SES identities. The map key (e.g. sesEmailIdentity) is the CloudFormation logical ID for that raw resource — reference it directly from other resources with Ref or Fn::GetAtt. To inspect logical names that Stacktape generates for its managed resources (so you can avoid collisions), run stacktape status.

Resource attributes

Each raw resource follows the standard AWS CloudFormation resource structure — at minimum a Type string, usually paired with Properties for that resource type. Standard CloudFormation resource attributes like DependsOn, DeletionPolicy, CreationPolicy, UpdatePolicy, Metadata, and Condition are passed through to the generated template.

For example, setting DeletionPolicy: 'Retain' tells AWS CloudFormation to preserve a resource when the stack is deleted — useful for data stores you want to keep even after tearing down infrastructure. The DependsOn attribute controls creation ordering when one resource must exist before another. In the example below, RetentionInDays: 365 keeps log data for one year before AWS automatically expires it.

export default defineConfig(() => {
  const api = new LambdaFunction({
    packaging: new JsBundleLambdaPackaging({
      entryfilePath: './src/api.ts'
    })
  });

  return {
    resources: { api },
    cloudformationResources: {
      appConfig: {
        Type: 'AWS::SSM::Parameter',
        Properties: {
          Type: 'String',
          Value: 'v2.1.0',
          Description: 'Current application version'
        }
      },
      auditLogGroup: {
        Type: 'AWS::Logs::LogGroup',
        DeletionPolicy: 'Retain',
        Properties: {
          LogGroupName: '/custom/audit-trail',
          RetentionInDays: 365
        }
      }
    }
  };
});

Using intrinsic functions

Because raw CloudFormation resources are merged into the template as-is, you can use any CloudFormation intrinsic function — Ref, Fn::Sub, Fn::GetAtt, Fn::Join, Fn::If, and others. In the TypeScript config, represent intrinsic functions as objects.

This example creates an SNS topic and an SNS subscription that uses Ref to reference the topic's ARN by logical ID, and DependsOn to control creation ordering:

export default defineConfig(() => {
  const notificationHandler = new LambdaFunction({
    packaging: new JsBundleLambdaPackaging({
      entryfilePath: './src/handle-notification.ts'
    })
  });

  return {
    resources: { notificationHandler },
    cloudformationResources: {
      alertTopic: {
        Type: 'AWS::SNS::Topic',
        Properties: {
          TopicName: 'deployment-alerts',
          DisplayName: 'Deployment Alerts'
        }
      },
      alertSubscription: {
        Type: 'AWS::SNS::Subscription',
        DependsOn: 'alertTopic',
        Properties: {
          Protocol: 'email',
          Endpoint: 'ops-team@example.com',
          TopicArn: { Ref: 'alertTopic' }
        }
      }
    }
  };
});

Common intrinsic function patterns in TypeScript config:

CloudFormation syntaxTypeScript object form
!Ref LogicalId{ Ref: 'LogicalId' }
!GetAtt LogicalId.Attr{ 'Fn::GetAtt': ['LogicalId', 'Attr'] }
!Sub "string"{ 'Fn::Sub': 'string' }
!Join [",", [...]]{ 'Fn::Join': [',', [...]] }

To reference Stacktape-managed resources by logical ID in intrinsic functions, run stacktape status to discover the logical names Stacktape generates. These are internal naming conventions and may change between Stacktape versions — always verify before hardcoding references.

Granting workload access to raw resources

Raw CloudFormation resources are not Stacktape resource definitions, so they do not get the typed connectTo behavior documented for Stacktape resources. To grant a Stacktape-managed workload access to a raw CloudFormation resource, add raw IAM policy statements with iamRoleStatements. Each statement's Resource field is an array of string ARNs — you supply the correct AWS actions and the ARN pattern for the resource you're granting access to.

export default defineConfig(() => {
  const processor = new LambdaFunction({
    packaging: new JsBundleLambdaPackaging({
      entryfilePath: './src/processor.ts'
    }),
    iamRoleStatements: [
      {
        Effect: 'Allow',
        Action: ['sqs:SendMessage', 'sqs:GetQueueAttributes'],
        Resource: ['arn:aws:sqs:*:*:custom-dlq']
      }
    ]
  });

  return {
    resources: { processor },
    cloudformationResources: {
      customDeadLetterQueue: {
        Type: 'AWS::SQS::Queue',
        Properties: {
          QueueName: 'custom-dlq',
          MessageRetentionPeriod: 1209600
        }
      }
    }
  };
});

The iamRoleStatements property is available on all Stacktape compute resources (Lambda functions, web services, worker services, batch jobs, and multi-container workloads). In the example, MessageRetentionPeriod: 1209600 sets the SQS message retention to 14 days (the maximum), meaning unprocessed messages stay in the queue for two weeks before being discarded. When the raw resource uses a fixed name (as with QueueName: 'custom-dlq' above), an ARN pattern with wildcard region and account (arn:aws:sqs:*:*:custom-dlq) keeps the policy portable across stages and AWS accounts.

Avoiding naming conflicts

Stacktape generates CloudFormation logical names for its managed resources internally. If a raw CloudFormation resource uses a name that collides with a Stacktape-generated one, the deployment will fail.

To inspect the logical names Stacktape has assigned, run:

stacktape status

Use descriptive, unique prefixes (like Custom or your team name) for your cloudformationResources keys to reduce collision risk. If your CLI build supports stacktape synth, it can also be used to preview the full generated CloudFormation template before deploying.

Stacktape's internal naming conventions are implementation details and may change between versions. Always verify logical names with stacktape status rather than guessing or hardcoding references to Stacktape-managed names.

Choosing an escape hatch

Stacktape offers three escape hatches for going beyond built-in resource types. Each solves a different problem — picking the wrong one leads to unnecessary complexity.

FeatureRaw CloudFormationCDK ConstructsOverrides
Adds new AWS resources to the stack✓✓✕
Modifies existing Stacktape-managed resources✕✕✓
Participates in connectTo resource graph✕✕N/A
Counted toward resource limit✕✓N/A
Requires CDK knowledge✕✓✕
Abstraction levelL1 (raw CF)L1–L3Property path

Recommendation:

  • Overrides — try first when the resource is already Stacktape-managed but needs one property tweaked.
  • Raw CloudFormation resources (this page) — for simple, self-contained resources with zero dependencies beyond CloudFormation knowledge.
  • CDK constructs — for complex multi-resource setups that benefit from L2/L3 abstractions handling IAM, networking, and cross-resource wiring automatically.

Most teams should try overrides first, then raw CloudFormation, then CDK constructs.

API reference

Each raw CloudFormation resource follows standard AWS CloudFormation resource syntax. The required property is Type (the CloudFormation resource type string, e.g. AWS::SES::EmailIdentity). Optional standard attributes include Properties, DependsOn, DeletionPolicy (Delete, Retain, or Snapshot), CreationPolicy, UpdatePolicy, Metadata, and Condition. See the AWS CloudFormation resource type reference for the full attribute list per resource type.

Raw CloudFormation Resources FAQ

Do raw CloudFormation resources count toward the Stacktape resource limit?

No. The cloudformationResources property is explicitly excluded from the Stacktape resource limit. You can add as many raw CloudFormation resources as the underlying CloudFormation stack supports. AWS CloudFormation allows up to 500 resources per stack by default, with the option to request a limit increase.

Are raw CloudFormation resources deleted when I delete the stack?

Yes. Raw CloudFormation resources are part of the stack's template. When you delete the stack, AWS CloudFormation deletes all resources in the template — both Stacktape-managed and raw. To preserve a resource after stack deletion, set DeletionPolicy: 'Retain' on that resource.

How do I reference a Stacktape-managed resource from a raw resource?

Run stacktape status to discover the logical name Stacktape assigned, then reference it with Ref, Fn::GetAtt, or DependsOn (which all accept the logical name of any resource in the stack, including Stacktape-generated ones). Stacktape's internal naming is an implementation detail that can change between versions, so verify the name before each major Stacktape upgrade rather than hardcoding it.

Can I use connectTo with raw CloudFormation resources?

Raw CloudFormation resources are not Stacktape resource definitions, so they do not get the typed connectTo behavior documented for Stacktape resources. For workloads that need access to a raw resource, grant access explicitly with iamRoleStatements — supply the correct AWS actions and the resource's ARN. See Granting workload access above for an example.

Raw CloudFormation vs. overrides vs. CDK constructs — which escape hatch should I use?

Use overrides when the resource already exists in your resources config and you just need to tweak one property (for example, a storage encryption setting on a Stacktape-managed relational database) — overrides modify existing resources rather than adding new ones. Use raw CloudFormation for one or two simple, self-contained AWS resources that Stacktape doesn't manage, when you don't want to add CDK as a dependency. Use CDK constructs for complex multi-resource setups that benefit from L2/L3 abstractions handling IAM, networking, and cross-resource wiring automatically. See Choosing an escape hatch above for the full comparison.

How much do raw CloudFormation resources cost?

AWS CloudFormation itself is free — you pay only for the underlying AWS resources you provision. A raw SES email identity costs nothing; an ALB, RDS instance, or NAT Gateway has its own pricing. Check the AWS CloudFormation pricing page and the pricing for the specific AWS service you're adding.