BTC Embedded CDK Extensions

@btc-embedded/cdk-extensions

A collection of reusable AWS CDK (Cloud Development Kit) extensions and constructs for building cloud infrastructure with TypeScript.

Features

• CDK Constructs: Includes ready-to-use constructs for API Gateway, Application Load Balancer, Cognito, VPC, DocumentDB, and more.
• ECS Service Extensions: Provides ECS service extensions for advanced container orchestration.
• Utilities: Common utilities and helpers for stack parameters, value imports, and configuration parsing.
• Modular Extensions: Easily extend AWS resources with features like logging, OpenTelemetry, EFS, Cloud Map, and custom containers.

Installation

yarn install @btc-embedded/cdk-extensions

Usage Example

Basic Usage

import { ApiGateway } from "@btc-embedded/cdk-extensions";

// Use constructs and extensions in your CDK app

Using ApplicationStack for Simplified Configuration

For application-level stacks that reference a base platform stack, use ApplicationStack to ensure consistent use of the base platform stack name:

import { ApplicationStack } from "@btc-embedded/cdk-extensions";

export class MyAppStack extends ApplicationStack {
  constructor(scope: Construct, id: string) {
    super(scope, id, {
      basePlatformStackName: "my-platform-stack",
      env: {
        account: "123456789012",
        region: "eu-central-1",
      },
    });

    // Constructs and extensions automatically resolve the platform stack name
    // No need to pass basePlatformStackName repeatedly
  }
}

Config-Driven Deployments

Use createApplicationApp for configuration-driven deployments:

import {
  createApplicationApp,
  ApplicationStack,
} from "@btc-embedded/cdk-extensions";
import { z } from "zod";

const configSchema = z.object({
  env: z.object({ account: z.string(), region: z.string() }),
  basePlatformStackName: z.string(),
});

createApplicationApp({
  directory: "./config",
  schema: configSchema,
  createStack: (scope, config) => new MyAppStack(scope, "MyApp", config),
});

CLI Commands

catnip — Cloud Toolkit by the CAT Department

catnip provides operational helpers for CloudFormation, ECS, and Cognito.

Global options (apply to all commands):

• --region <region> — AWS region (defaults to AWS_DEFAULT_REGION / AWS_REGION)
• --profile <profile> — AWS named profile

stack-diagnose

Diagnose failed CloudFormation deployments and show ECS failure context.

Usage:

catnip stack-diagnose
catnip stack-diagnose --stack-name my-stack
catnip stack-diagnose --stage prod
catnip stack-diagnose --stack-name my-stack --tail 200 --tasks 10

Options:

• --stack-name <name> — stack to diagnose (optional; auto-detects last failed stack if omitted)
• --stage <name> — stage filter for auto-detection (ignored if --stack-name is provided)
• --tail <n> — Number of log lines to show per container (default: 100)
• --tasks <n> — Number of recent stopped tasks to inspect (default: 5)

ecs-logs

Stream live logs from running ECS services in a CloudFormation stack.

Usage:

catnip ecs-logs --stack-name my-stack
catnip ecs-logs --stack-name my-stack --follow
catnip ecs-logs --stack-name my-stack --service api --tail 50
catnip ecs-logs --stack-name my-stack --output raw
catnip ecs-logs --stack-name my-stack --output pretty

Options:

• --stack-name <name> — CloudFormation stack name (required)
• --tail <n> — Lines of history to show per container (default: 100)
• -f, --follow — Keep polling for new log events
• --service <name> — Filter services by name
• -o, --output <mode> — Output mode: text, raw, or pretty (default: text)

oidc-token

Fetch a Cognito token using CloudFormation exports from a stack.

Usage:

catnip oidc-token --stack-name my-stack
catnip oidc-token --stack-name my-stack --output json

Options:

• --stack-name <name> — stack that exported Cognito resources (required)
• --output <token|json> — print token only, or full response JSON (default: token)
  • token output is the access_token

pg-tunnel

Open a secure Session Manager tunnel to Aurora PostgreSQL and launch a local client.

Usage:

catnip pg-tunnel --stack-name my-stack
catnip pg-tunnel --stack-name my-stack --exec "psql"
catnip pg-tunnel --stack-name my-stack --database app
catnip pg-tunnel --stack-name my-stack --no-auto-launch
catnip pg-tunnel --stage prod

Options:

• --stack-name <name> — stack where the Aurora cluster is deployed (typically the base platform stack; optional when auto-discovery works)
• --stage <name> — stage filter used during stack auto-discovery
• --local-port <port> — preferred local port (default: 5432)
• --database <name> — overrides PGDATABASE for launched client/shell
• --exec <command> — explicit command to run after tunnel starts
• --no-auto-launch — keep tunnel attached without launching a client/shell
• --tunnel-instance-id <id> — fallback EC2 instance ID when stack export is missing

Database selection behavior:

• if --database is provided, that value is used
• if omitted, catnip infers database names from deployed ECS service task definitions (POSTGRES_DATABASE)
• if exactly one database is inferred, it is applied as PGDATABASE
• if multiple databases are inferred, they are printed with source stack/service and PGDATABASE remains unset

Prerequisite:

• session-manager-plugin must be installed and available in PATH

Documentation

• API Reference

License

Apache-2.0 © BTC Embedded Systems AG