Integrating with existing infrastructure
AWS CDK Blocks is designed to work with existing AWS infrastructure. Whether you have an existing CDK application, pre-deployed resources, or a mix of both, you can adopt CDK Blocks incrementally without rewriting your infrastructure.
Choosing a pattern
CDK Blocks provides five patterns for integrating with existing infrastructure. Choose based on your situation:
| Pattern | Effort | Use when | Local support |
|---|---|---|---|
|
CDK in CDK Blocks |
Low |
No CDK Block exists for the resource you need |
❌ Manual |
|
|
Lowest |
A CDK Block exists and you have a pre-deployed resource |
✅ Automatic |
|
Custom CDK Block |
Medium |
You’re repeating the same resource pattern in multiple places |
✅ Automatic |
|
Vendorize |
Low |
A CDK Block that AWS provides is almost right but needs CDK changes |
✅ Automatic |
|
Infrastructure outside the AWS CDK |
High |
Your team has to manage a resource, or the whole backend, with Terraform or another tool it already uses |
✅ Automatic |
Pattern 1: CDK in CDK Blocks
Use raw CDK Constructs alongside CDK Blocks. CDK Blocks gives you two shapes for this:
BlocksStack
: A standalone CloudFormation stack containing the CDK Blocks Lambda and API Gateway. Use for new projects or when you want CDK Blocks isolated in its own deployment unit.
BlocksBackend
: A CDK Construct you drop into an existing stack. Use when you already have stacks and want CDK Blocks to live alongside your other resources.
Both expose executionRole, the one IAM role that all CDK Blocks compute in the app shares. Grant permissions to it. To pass a value such as a resource ARN to your code, call registerConfig(scope, key, value) from aws-cdk-blocks/cdk. At runtime, the value is available as process.env[key].
Example: BlocksStack with an SNS topic
This example adds an Amazon Simple Notification Service (Amazon SNS) topic, a resource that has no CDK Block.
// cdk-blocks/index.cdk.ts import * as cdk from 'aws-cdk-lib'; import * as sns from 'aws-cdk-lib/aws-sns'; import { dirname, join } from 'node:path'; import { fileURLToPath } from 'node:url'; import { BlocksPresets, BlocksStack, registerConfig } from 'aws-cdk-blocks/cdk'; const __dirname = dirname(fileURLToPath(import.meta.url)); const app = new cdk.App(); const stack = await BlocksStack.create(app, 'my-app', { backendHandlerPath: join(__dirname, 'index.handler.ts'), backendCDKPath: join(__dirname, 'index.ts'), defaults: BlocksPresets.production, }); const topic = new sns.Topic(stack, 'alerts'); topic.grantPublish(stack.executionRole); registerConfig(stack, 'ALERTS_TOPIC_ARN', topic.topicArn);
// cdk-blocks/index.ts import { Scope, ApiNamespace } from 'aws-cdk-blocks'; import { SNSClient, PublishCommand } from '@aws-sdk/client-sns'; const scope = new Scope('my-app'); const sns = new SNSClient({}); export const api = new ApiNamespace(scope, 'api', (context) => ({ async sendAlert(message: string) { await sns.send(new PublishCommand({ TopicArn: process.env.ALERTS_TOPIC_ARN, Message: message, })); return { ok: true }; }, }));
Like every ApiNamespace method, sendAlert is a public endpoint until you add an auth check.
For background work, don’t wire up a raw queue or schedule. Use AsyncJob or CronJob, which provision the infrastructure and run locally.
Example: BlocksBackend inside an existing stack
Use a static factory method because BlocksBackend.create() is asynchronous and constructors cannot use await:
// my-existing-stack.ts import * as cdk from 'aws-cdk-lib'; import * as sns from 'aws-cdk-lib/aws-sns'; import { BlocksBackend, BlocksPresets, registerConfig } from 'aws-cdk-blocks/cdk'; export class MyApiStack extends cdk.Stack { static async create(scope: cdk.App, id: string, props?: cdk.StackProps) { const stack = new MyApiStack(scope, id, props); // Your existing resources const topic = new sns.Topic(stack, 'alerts'); // Drop Blocks in as a Construct const blocks = await BlocksBackend.create(stack, 'BlocksApi', { backendHandlerPath: './cdk-blocks/index.handler.ts', backendCDKPath: './cdk-blocks/index.ts', defaults: BlocksPresets.production, }); topic.grantPublish(blocks.executionRole); registerConfig(blocks, 'ALERTS_TOPIC_ARN', topic.topicArn); return stack; } }
Relative backendHandlerPath and backendCDKPath values resolve against the directory you run synth from.
Run synth with the cdk condition, for example "app": "npx tsx -C cdk bin/app.ts" in cdk.json, or NODE_OPTIONS="--conditions=cdk" npx cdk synth. The npm run deploy and npm run sandbox scripts set it for you. Without it, every CDK Block import resolves to its local implementation and produces no infrastructure, so create() stops with a Missing --conditions=cdk error.
Tradeoffs
-
✅ Full access to any AWS resource with plain CDK and SDK
-
❌ No local implementation.
npm run devwill call real AWS unless you stub the SDK yourself -
❌ No type-level guarantee that config values such as
process.env.ALERTS_TOPIC_ARNexist
If you find yourself repeating this pattern, consider creating a custom CDK Block instead.
Pattern 2: fromExisting
Some CDK Blocks can wrap a pre-deployed AWS resource. The CDK Block provides its typed API and local implementation, but skips provisioning. You keep ownership of the resource.
These CDK Blocks support it. Pass the factory method’s result as the option in the Factory method column, such as table for KVStore. AppSetting.fromExisting is different: it returns the setting itself.
| Block | Factory method | Wraps |
|---|---|---|
|
|
|
Existing DynamoDB table. Pass a |
|
|
|
Existing S3 bucket |
|
|
|
Existing PostgreSQL database, with its tables and data. |
|
|
|
Existing Cognito user pool. CDK Blocks adds its own app client to the pool. With |
|
|
|
Existing AWS Systems Manager Parameter Store parameter |
|
|
|
Existing Secrets Manager secret |
|
|
|
Existing CloudWatch namespace |
Example
// cdk-blocks/index.ts import { Scope, KVStore, ApiNamespace } from 'aws-cdk-blocks'; import { z } from 'zod'; const scope = new Scope('my-app'); const sessions = new KVStore(scope, 'sessions', { schema: z.object({ sessionId: z.string(), userId: z.string() }), key: { partitionKey: 'sessionId' }, table: KVStore.fromExisting('my-legacy-sessions-table'), }); export const api = new ApiNamespace(scope, 'api', (context) => ({ async getSession(token: string) { return sessions.get({ sessionId: token }); }, }));
Tradeoffs
-
✅ Local development still works.
npm run devkeeps data in files under.bb-data/, not in the real resource. ADatabaseon an existing database is the exception: it connects to that database -
✅ IAM permissions are granted automatically to the shared execution role
-
✅ Same typed API as a resource that CDK Blocks manages
-
❌ Limited to the CDK Block’s API surface. If you need features the CDK Block doesn’t expose, use Pattern 1
-
❌ Cross-account resources require manual IAM (fall back to Pattern 1)
The wrapped resource can come from any tool.
Pattern 3: Custom CDK Block
When you’re repeating Pattern 1 for the same resource type, wrap it in a custom CDK Block. This gives you a typed API, a local implementation, and reusability.
See Creating custom CDK Blocks for a complete guide to authoring CDK Blocks.
When to use
-
You have ≥2 callers using the same resource pattern
-
You want
npm run devto work without AWS for this resource -
You want type-safe call sites instead of raw
process.env+ SDK
Pattern 4: Vendorize
If a CDK Block that AWS provides is almost right but needs CDK changes you can’t get upstream quickly, you can copy its source into your project:
npm run vendorize -- @aws-cdk-blocks/bb-kv-store
This copies the CDK Block source into your monorepo. You now own it. Modify the CDK, runtime, or local implementation as needed.
Tradeoffs
-
✅ Full control over the CDK Block implementation
-
✅ Local implementations, types, and API surface all still work
-
❌ You’re responsible for maintenance. Upstream updates require manual re-sync
-
❌ Only use when a custom CDK Block (Pattern 3) or an upstream pull request won’t solve the problem
You can also vendorize a CDK Block without fromExisting to point it at a resource that the CDK did not create. Change its index.cdk.ts to import the resource instead of creating it.
Pattern 5: Infrastructure outside the AWS CDK
Each CDK Block’s CDK code (index.cdk.ts) creates its resources and grants the shared execution role access. It then either names each resource from the CDK Block’s fullId, so the runtime can derive the same name, or passes names and ARNs to the runtime as config. Nothing else in the CDK Block depends on the CDK: the runtime entry (index.aws.ts), the local implementation, local development and the typed client work the same whoever created the infrastructure. So a tool other than the CDK can provide the infrastructure, as long as it provides the same contract.
Two shapes work:
| Shape | CDK still owns | Your tool owns |
|---|---|---|
|
Hybrid |
The app shell (execution role, Lambda function, API Gateway) and most CDK Blocks |
One or more CDK Blocks' resources, through |
|
No CDK |
Nothing |
The app shell and every CDK Block’s resources, grants and config |
The contract differs by CDK Block. A KVStore needs only a table with the right name and the key schema of its key option (or the string partition key _bkv_pk without one), which the execution role can read and write. An AsyncJob needs a queue, config, and an event source mapping on the backend function with settings that match its options. A Database needs config and its migrations run.
When to use
-
A resource, or the whole backend, has to be managed by Terraform or another tool your team already uses
-
You want to keep the CDK Blocks app code, local implementations and typed client without deploying through the CDK
When not to use
-
fromExisting(Pattern 2) already covers the resource and the CDK can keep deploying everything else -
You are not prepared to keep names, config keys, IAM grants, and CDK Block options in sync by hand
Tradeoffs
-
✅ Your infrastructure tool manages the resources, with its own state, review and drift detection
-
✅ App code, local implementations and the typed client do not change
-
❌ You keep the contract in sync by hand: derived names, config keys, IAM grants, and options such as AsyncJob’s
maxRetries. A mismatch usually shows up at runtime as an error in the function’s logs, not at deploy time -
❌ With no CDK, you replace
npm run deploy,npm run sandboxandnpm run destroywith your own steps -
❌ When a CDK Block changes its contract in a new version, you update your infrastructure to match
Raw HTTP routes and webhooks
ApiNamespace methods are JSON-RPC calls from your frontend. When another system must call a fixed URL, such as a payment provider sending webhooks, use RawRoute. You get the request and set the response yourself.
// cdk-blocks/index.ts import { createHmac, timingSafeEqual } from 'node:crypto'; import { ApiError, RawRoute, Scope, Secret } from 'aws-cdk-blocks'; const scope = new Scope('my-app'); const signingKey = new Secret(scope, 'webhook-signing-key'); new RawRoute(scope, 'payments-webhook', { method: 'POST', path: '/webhooks/payments', handler: async ({ request, response }) => { const body = await request.text(); const key = await signingKey.get(); if (!key) throw new ApiError('Webhook signing key is not set', 503); const expected = Buffer.from(createHmac('sha256', key).update(body).digest('hex')); const received = Buffer.from(request.headers.get('x-signature') ?? ''); if (received.length !== expected.length || !timingSafeEqual(received, expected)) { throw new ApiError('Invalid signature', 401); } const event = JSON.parse(body) as { type: string }; console.log('Payment event:', event.type); response.status = 200; response.send({ received: true }); }, });
RawRoute takes these options:
-
method:GET,POST,PUT,DELETE,PATCH,HEAD, orOPTIONS. -
path:/healthmatches exactly,/users/{id}captures one segment intorequest.params.id, and/files/captures the rest of the path intorequest.params['. If you omitpath, it is built from the IDs of any scopes between your top-level scope and the route, plus the route ID. Setpathexplicitly for URLs that other systems depend on. -
handler: Receivesrequest(headers,text(),json(),url,params) andresponse(status,headers,send()). The responseContent-Typedefaults toapplication/json.
CDK Blocks serves the route from the same origin as your API, both in npm run dev and when deployed. It needs no extra infrastructure. You cannot register /, /aws-blocks, or a path under /aws-blocks/api, and you cannot register the same method and path twice.
A raw route has no auth of its own, so check a signature or token in the handler. If the handler throws an ApiError, the response uses its status and the body { "error": message }. An error that you create with blocksError() keeps its message and adds its name to the body. Any other error becomes an HTTP 500 with the body { "error": "Internal error" }, and the full error goes only to the server log.