@venturekit/infra

Warning: This package is in active development and not production-ready. APIs may change without notice.

Infrastructure package for VentureKit — CDK constructs for AWS.

Installation

npm install @venturekit/infra@dev

Overview

@venturekit/infra provides the defineVenture() function, which is the main entry point for all VentureKit applications. It:

• Validates your configuration
• Discovers file-based routes
• Translates infrastructure intents into AWS CDK constructs
• Creates Lambda functions, API Gateway, VPC, WebSocket API, and more
• Hides all CDK complexity behind a clean, declarative API

Consumers never interact with CDK directly — @venturekit/infra is the abstraction layer.

Usage

Create a vk.config.ts at your project root:

import { defineVenture } from '@venturekit/infra';
import { base } from './config/base';
import { security } from './config/security';
import { dev } from './config/dev';
import { prod } from './config/prod';

export default defineVenture({
  base,
  security,
  envs: { dev, prod },
  routesDir: 'src/routes',
});

With Infrastructure Intents

export default defineVenture({
  base,
  security,
  envs: { dev, prod },
  routesDir: 'src/routes',
  infrastructure: {
    databases: [
      { id: 'main', type: 'postgres', size: 'small', name: 'mydb' },
    ],
    storage: [
      { id: 'uploads', purpose: 'uploads', cdn: true },
    ],
    auth: [
      { id: 'users', signInWith: ['email'], allowSignUp: true },
    ],
  },
});

File-Based Routing

Routes are auto-discovered from routesDir:

| File | Route | |------|-------| | src/routes/health/get.ts | GET /health | | src/routes/projects/post.ts | POST /projects | | src/routes/projects/[id]/get.ts | GET /projects/{id} | | src/routes/projects/[id]/delete.ts | DELETE /projects/{id} |

Environment Selection

The current environment is determined by the VENTURE_STAGE environment variable:

VENTURE_STAGE=prod vk deploy   # Uses prod config
VENTURE_STAGE=stage vk deploy  # Uses stage config
vk dev                         # Defaults to dev

Database migrations on deploy

When infrastructure.databases declares a Postgres database and the project has at least one .sql file in db/migrations/, VentureKit provisions an in-VPC AWS CodeBuild project alongside the RDS instance and invokes it via a CloudFormation custom resource on every stack update. The buildspec literally runs vk migrate --seed — the same command operators use locally — so what's tested in development is what runs on deploy.

project/
├── db/
│   ├── migrations/         ← auto-applied (tracked in __vk_migrations)
│   │   └── 0001_init.sql
│   └── seeds/              ← auto-applied alongside migrations (tracked in __vk_seeds)
│       └── 0001_seed.sql
└── vk.config.ts            ← databases: [{ id: 'main', type: 'postgres', name: 'mydb' }]

The runner:

• Lives in the same VPC + private subnets as the DB. The DB SG accepts ingress on the engine port from the runner SG only.
• Reads DB credentials fresh from the auto-generated Secrets Manager secret on each build, so password rotation doesn't require a redeploy.
• Installs the same @venturekit/cli version the operator has locally (resolved from node_modules/@venturekit/cli/package.json).
• Serializes concurrent deploys via concurrentBuildLimit: 1 to prevent builds racing on the __vk_migrations tracking table.
• Throws on FAILED / STOPPED / TIMED_OUT with the build's CloudWatch log stream URL in the error message → CFN rolls the entire stack back, making migrations atomic with vk deploy.

When the runner is not provisioned

• Free-tier preset (preset: 'free') — uses DynamoDB instead of RDS, no SQL migrations needed.
• db/migrations/ is missing or contains no .sql files.
• databases[i].type === 'mysql' — @venturekit/data doesn't ship a MySQL runner yet; a synth-time console.warn reminds you to run migrations manually until that lands.
• infrastructure.vpc.natType === 'none' (explicit opt-out) — the runner needs outbound egress to npm install @venturekit/cli and ship build logs. Without a NAT provider it can't function, so we skip provisioning and warn with instructions to run vk migrate manually via an SSM tunnel.

Inspecting a failed build

CloudWatch log group: /venturekit/<projectName>/<stage>/migrate-<dbId>. The custom resource's failure message contains a deep link straight to the failing build's log stream — copy-paste it into the AWS console.

NAT provider selection

Private subnets need an egress path for Lambda + CodeBuild to reach the public internet (AWS APIs, npm, third-party services). VentureKit exposes two knobs under infrastructure.vpc:

• natType: 'gateway' | 'instance' | 'none'
• natInstanceType: EC2 instance type (only used when natType: 'instance')

Per-preset defaults

| Preset | natType | natInstanceType | natGateways | Approx. monthly NAT cost | |---|---|---|---|---| | free | 'none' | — | 0 | $0 (DynamoDB-only, no VPC) | | nano | 'instance' | 't4g.nano' | 1 | ~$3.70 (1 × t4g.nano fck-nat) | | micro | 'instance' | 't4g.nano' | 1 | ~$3.70 (saves ~$29/mo vs NAT GW) | | medium | 'instance' | 't4g.medium' | 1 | ~$24.50 (saves ~$8/mo + $0.045/GB) | | large | 'gateway' | — | 2 | ~$66 (managed, 2 AZs) + $0.045/GB processed |

All instance-mode presets use fck-nat, the community-maintained AL2023 NAT AMI (AWS account 568608671756). It's published in every commercial region including eu-west-3, enforces IMDSv2, and is actively maintained — unlike the AWS NAT-AMI, which was EOL'd in 2020.

When to override

• Heavy-egress workloads (> 1 TB/mo): NAT GW's $0.045/GB processing fee adds up fast. Override to natType: 'instance' with natInstanceType: 'c6gn.large' (~$63/mo, 12 Gbps sustained) — beats NAT GW on both cost and throughput at that volume.

• Strict SLA / compliance regimes: natType: 'gateway' gives you sub-second intra-AZ failover and AWS-managed operations. Recommended for PCI-DSS / HIPAA / FedRAMP even at the micro size.

• DynamoDB-only or manual-migration workflows: natType: 'none' disables egress entirely. The migration runner is skipped with a warning; you run vk migrate via an SSM tunnel when needed.

// vk.config.ts — override the preset default
export default defineVenture({
  // ...
  infrastructure: {
    vpc: {
      natType: 'instance',
      natInstanceType: 'c6gn.large',
    },
    databases: [{ id: 'main', type: 'postgres', name: 'mydb' }],
  },
});

Operational trade-offs

| | NAT Gateway | NAT Instance (fck-nat) | |---|---|---| | Failover | Sub-second (AWS-managed, AZ-redundant) | 1–2 min (CDK instance replacement on ASG termination) | | Throughput | 5–100 Gbps | 5 Gbps burst; sustained depends on instance type | | Data fee | $0.045/GB processed | None (pay only EC2 bandwidth) | | Ops surface | Zero | You own patching via AMI updates | | AWS support SLA | Full | EC2 instance only (not NAT config) |

Changing natType on an existing deployment causes CloudFormation to replace the NAT resource (brief data-plane outage during deploy). The VPC itself is not replaced and all other resources stay put.

API

defineVenture(definition)

Creates a VentureKit application from a VentureDefinition:

• base — BaseConfig (project identity)
• security — SecurityConfig (scopes, clients)
• envs — { dev?, stage?, prod? } environment configurations
• routesDir — path to file-based routes directory
• infrastructure? — VentureIntent for declarative infrastructure

getResolvedConfig(base, security, envInput)

Returns the fully resolved ResolvedConfig for the current environment. Useful for accessing config values in handler code.

API Reference

See the API reference for full documentation.

License

Apache-2.0 — see LICENSE for details.