aws-cdk

Documento Skill originale

Contenuto dal repository con titoli, esempi, codice, tabelle, link e immagini preservati.

AWS CDK TypeScript

Overview

Use this skill to build AWS infrastructure in TypeScript with reusable constructs, safe defaults, and a validation-first delivery loop.

When to Use

Use this skill when:

Creating or refactoring a CDK app, stack, or reusable construct in TypeScript
Choosing between L1, L2, and L3 constructs
Building serverless, networking, or security-focused AWS infrastructure
Wiring multi-stack applications and environment-aware deployments
Validating infrastructure changes with cdk synth, tests, cdk diff, and cdk deploy

Instructions

1. Project Initialization

bash

# Create a new CDK app
npx cdk init app --language typescript

# Project structure
my-cdk-app/
├── bin/
│   └── my-cdk-app.ts          # App entry point (instantiates stacks)
├── lib/
│   └── my-cdk-app-stack.ts    # Stack definition
├── test/
│   └── my-cdk-app.test.ts     # Tests
├── cdk.json                    # CDK configuration
├── tsconfig.json
└── package.json

2. Core Architecture

typescript

import { App, Stack, StackProps, CfnOutput, RemovalPolicy } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as s3 from 'aws-cdk-lib/aws-s3';

// Define a reusable stack
class StorageStack extends Stack {
  public readonly bucketArn: string;

  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const bucket = new s3.Bucket(this, 'DataBucket', {
      versioned: true,
      encryption: s3.BucketEncryption.S3_MANAGED,
      removalPolicy: RemovalPolicy.RETAIN,
      blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
    });

    this.bucketArn = bucket.bucketArn;
    new CfnOutput(this, 'BucketName', { value: bucket.bucketName });
  }
}

// App entry point
const app = new App();

new StorageStack(app, 'DevStorage', {
  env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: 'us-east-1' },
  tags: { Environment: 'dev' },
});

new StorageStack(app, 'ProdStorage', {
  env: { account: '123456789012', region: 'eu-west-1' },
  tags: { Environment: 'prod' },
  terminationProtection: true,
});

app.synth();

3. Construct Levels

Level	Description	Use When
L1 (`Cfn*`)	Direct CloudFormation mapping, full control	Need properties not exposed by L2
L2	Curated with sensible defaults and helper methods	Standard resource provisioning (recommended)
L3 (Patterns)	Multi-resource architectures	Common patterns like `LambdaRestApi`

typescript

// L1 — Raw CloudFormation
new s3.CfnBucket(this, 'L1Bucket', { bucketName: 'my-l1-bucket' });

// L2 — Sensible defaults + grant helpers
const bucket = new s3.Bucket(this, 'L2Bucket', { versioned: true });
bucket.grantRead(myLambda);

// L3 — Multi-resource pattern
new apigateway.LambdaRestApi(this, 'Api', { handler: myLambda });

4. CDK Lifecycle Commands

bash

cdk synth          # Synthesize CloudFormation template
cdk diff           # Compare deployed vs local changes
cdk deploy         # Deploy stack(s) to AWS
cdk deploy --all   # Deploy all stacks
cdk destroy        # Tear down stack(s)
cdk ls             # List all stacks in the app
cdk doctor         # Check environment setup

5. Recommended Delivery Loop

Model the stack

Start with L2 constructs and extract repeated logic into custom constructs.

Run `cdk synth`

Checkpoint: synthesis succeeds with no missing imports, invalid props, missing context, or unresolved references.
If it fails: fix the construct configuration or context values, then rerun cdk synth.

Run infrastructure tests

Checkpoint: assertions cover IAM scope, stateful resources, and critical outputs.
If tests fail: update the stack or test expectations, then rerun the test suite.

Run `cdk diff`

Checkpoint: review IAM broadening, resource replacement, export changes, and deletes on stateful resources.
If the diff is risky: adjust names, dependencies, or RemovalPolicy, then rerun cdk diff.

Run `cdk deploy`

Checkpoint: the stack reaches CREATE_COMPLETE or UPDATE_COMPLETE.
If deploy fails: inspect CloudFormation events, fix quotas, permissions, export conflicts, or bootstrap issues, then retry cdk deploy.

Verify runtime outcomes

Confirm stack outputs, endpoints, alarms, and integrations behave as expected before moving on.

6. Cross-Stack References

typescript

// Stack A exports a value
class NetworkStack extends Stack {
  public readonly vpc: ec2.Vpc;
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);
    this.vpc = new ec2.Vpc(this, 'Vpc', { maxAzs: 2 });
  }
}

// Stack B imports it via props
interface AppStackProps extends StackProps {
  vpc: ec2.Vpc;
}
class AppStack extends Stack {
  constructor(scope: Construct, id: string, props: AppStackProps) {
    super(scope, id, props);
    new lambda.Function(this, 'Fn', {
      runtime: lambda.Runtime.NODEJS_20_X,
      handler: 'index.handler',
      code: lambda.Code.fromAsset('lambda'),
      vpc: props.vpc,
    });
  }
}

// Wire them together
const network = new NetworkStack(app, 'Network');
new AppStack(app, 'App', { vpc: network.vpc });

Examples

Example 1: Serverless API

typescript

import * as cdk from 'aws-cdk-lib';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as apigateway from 'aws-cdk-lib/aws-apigateway';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';

class ServerlessApiStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const table = new dynamodb.Table(this, 'Items', {
      partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING },
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
      removalPolicy: cdk.RemovalPolicy.DESTROY,
    });

    const fn = new lambda.Function(this, 'Handler', {
      runtime: lambda.Runtime.NODEJS_20_X,
      handler: 'index.handler',
      code: lambda.Code.fromAsset('lambda'),
      environment: { TABLE_NAME: table.tableName },
    });

    table.grantReadWriteData(fn);

    new apigateway.LambdaRestApi(this, 'Api', { handler: fn });
  }
}

Example 2: CDK Assertion Test

typescript

import { Template } from 'aws-cdk-lib/assertions';
import { App } from 'aws-cdk-lib';
import { ServerlessApiStack } from '../lib/serverless-api-stack';

test('creates DynamoDB table with PAY_PER_REQUEST', () => {
  const app = new App();
  const stack = new ServerlessApiStack(app, 'TestStack');
  const template = Template.fromStack(stack);

  template.hasResourceProperties('AWS::DynamoDB::Table', {
    BillingMode: 'PAY_PER_REQUEST',
  });

  template.resourceCountIs('AWS::Lambda::Function', 1);
});

Best Practices

One concern per stack — Separate network, compute, storage, and monitoring.
Prefer L2 constructs — Drop to Cfn* only when you need unsupported properties.
Set explicit environments — Pass env with account and region; avoid implicit production targets.
Use grant helpers — Prefer .grant*() over handwritten IAM where possible.
Review the diff before deploy — Treat IAM expansion, replacement, and deletes as mandatory checkpoints.
Test infrastructure — Cover critical resources with fine-grained assertions.
Avoid hardcoded values — Use context, parameters, or environment variables.
Use the right `RemovalPolicy` — RETAIN for production data, DESTROY only for disposable environments.

Constraints and Warnings

CloudFormation limits — Max 500 resources per stack; split large apps into multiple stacks
Synthesis is not deployment — cdk synth only generates templates; cdk deploy applies changes
Cross-stack references create CloudFormation exports; removing them requires careful ordering
Stateful resources (RDS, DynamoDB, S3 with data) — Always set removalPolicy: RETAIN in production
Bootstrap required — Run cdk bootstrap once per account/region before first deploy
Asset bundling — Lambda code and Docker images are uploaded to the CDK bootstrap bucket

References

Detailed implementation guides are available in the references/ directory:

Core Concepts — App lifecycle, stacks, constructs, environments, assets
Serverless Patterns — Lambda, API Gateway, DynamoDB, S3 events, Step Functions
Networking & VPC — VPC design, subnets, NAT, security groups, VPC endpoints
Security Hardening — IAM, KMS, Secrets Manager, WAF, compliance
Testing Strategies — Assertions, snapshots, integration tests, CDK Nag

AWS CDK TypeScript

Overview

When to Use

Instructions

1. Project Initialization

2. Core Architecture

3. Construct Levels

4. CDK Lifecycle Commands

5. Recommended Delivery Loop

6. Cross-Stack References

Examples

Example 1: Serverless API

Example 2: CDK Assertion Test

Best Practices

Constraints and Warnings

References

Altri Skills

clean-architecture

nextjs-authentication

adr-drafting

dynamodb-toolbox-patterns