feat(core): add CDK-level VPC support

[svidgen]

CDK-Level VPC Support (Phase 1)

Customer DX

import * as ec2 from 'aws-cdk-lib/aws-ec2';

const vpc = new ec2.Vpc(app, 'AppVpc', { maxAzs: 2, natGateways: 1 });

export const blocksStack = await BlocksStack.create(app, stackName, {
  backendHandlerPath: join(__dirname, 'index.handler.ts'),
  backendCDKPath: join(__dirname, 'index.ts'),
  vpc: { vpc },
});

That's it. Blocks handles:

• Lambda placement in private subnets
• Security group creation
• VPC endpoint provisioning (based on which BBs are in scope)
• SG wiring (e.g., Lambda → Aurora on 5432)

// Bring-your-own VPC (shared/platform-managed):
const sharedVpc = ec2.Vpc.fromLookup(app, 'SharedVpc', { vpcId: 'vpc-abc123' });
await BlocksStack.create(app, stackName, {
  ...,
  vpc: { vpc: sharedVpc, provisionEndpoints: false },
});

How it works

1. Each BB registers its VPC requirements in its CDK constructor:

   this.registerVpcGatewayEndpoint(ec2.GatewayVpcEndpointAwsService.DYNAMODB);
   this.registerVpcInterfaceEndpoint(ec2.InterfaceVpcEndpointAwsService.SECRETS_MANAGER);

2. At finalization (after all BBs are constructed), the framework walks the scope tree, collects registered endpoints, deduplicates, and provisions them against the VPC. SSM + CloudWatch Logs are always included.

3. bb-data (Aurora) detects the VPC context on its scope chain. If present, it places Aurora in the shared VPC's isolated subnets and wires SG rules. If absent, it falls back to creating its own standalone VPC (existing behavior preserved).

API

interface BlocksVpcOptions {
  vpc: ec2.IVpc;
  subnets?: ec2.SubnetSelection;    // default: PRIVATE_WITH_EGRESS
  provisionEndpoints?: boolean;      // default: true
}

What's included

• vpc prop on BlocksStack and BlocksBackend
• registerVpcGatewayEndpoint / registerVpcInterfaceEndpoint on CDK Scope
• Endpoint registration in all BB CDK constructors
• bb-data VPC context detection + shared VPC placement
• test-infra/ persistent test VPC stack
• test-apps/vpc-smoke/ E2E smoke suite
• docs/design/VPC-DESIGN.md

What's NOT included (Phase 2, after configurable compute)

• VpcNetwork Building Block (per-handler VPC opt-in)
• Per-namespace subnet selection

See docs/design/VPC-DESIGN.md for the full design.

[changeset-bot]

🦋 Changeset detected

Latest commit: 4213fe6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 22 packages

Name	Type
@aws-blocks/core	Minor
@aws-blocks/bb-kv-store	Patch
@aws-blocks/bb-distributed-table	Patch
@aws-blocks/bb-file-bucket	Patch
@aws-blocks/bb-data	Patch
@aws-blocks/bb-distributed-data	Patch
@aws-blocks/bb-async-job	Patch
@aws-blocks/bb-agent	Patch
@aws-blocks/bb-knowledge-base	Patch
@aws-blocks/bb-email-client	Patch
@aws-blocks/bb-app-setting	Patch
@aws-blocks/bb-realtime	Patch
@aws-blocks/bb-auth-cognito	Patch
@aws-blocks/bb-auth-oidc	Patch
@aws-blocks/auth-common	Patch
@aws-blocks/bb-auth-basic	Patch
@aws-blocks/bb-dashboard	Patch
@aws-blocks/bb-cron-job	Patch
@aws-blocks/bb-logger	Patch
@aws-blocks/bb-tracer	Patch
@aws-blocks/bb-metrics	Patch
@aws-blocks/blocks	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR