AWS CDK TypeScript

概要

TypeScript で AWS インフラストラクチャを構築し、再利用可能なコンストラクト、安全なデフォルト設定、検証ファーストのデリバリーループを実現するには、このスキルを使用してください。

使用時期

以下の場合にこのスキルを使用してください:

• TypeScript で CDK アプリ、スタック、または再利用可能なコンストラクトを作成または リファクタリングする場合
• L1、L2、L3 コンストラクト間で選択する場合
• サーバーレス、ネットワーク、またはセキュリティに重点を置いた AWS インフラストラクチャを構築する場合
• マルチスタック アプリケーションと環境別デプロイメントを組み合わせる場合
• cdk synth、テスト、cdk diff、cdk deploy でインフラストラクチャ変更を検証する場合

指示

1. プロジェクト初期化

# 新しい CDK アプリを作成
npx cdk init app --language typescript

# プロジェクト構造
my-cdk-app/
├── bin/
│   └── my-cdk-app.ts          # アプリエントリーポイント (スタックをインスタンス化)
├── lib/
│   └── my-cdk-app-stack.ts    # スタック定義
├── test/
│   └── my-cdk-app.test.ts     # テスト
├── cdk.json                    # CDK 設定
├── tsconfig.json
└── package.json

2. コアアーキテクチャ

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

// 再利用可能なスタックを定義
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 });
  }
}

// アプリエントリーポイント
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. コンストラクトレベル

レベル	説明	使用条件
L1 (Cfn*)	CloudFormation への直接マッピング、完全な制御	L2 で公開されていないプロパティが必要な場合
L2	妥当なデフォルト設定とヘルパーメソッド付き	標準的なリソースプロビジョニング (推奨)
L3 (パターン)	マルチリソース アーキテクチャ	LambdaRestApi のような一般的なパターン

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

// L2 — 妥当なデフォルト + グラントヘルパー
const bucket = new s3.Bucket(this, 'L2Bucket', { versioned: true });
bucket.grantRead(myLambda);

// L3 — マルチリソース パターン
new apigateway.LambdaRestApi(this, 'Api', { handler: myLambda });

4. CDK ライフサイクルコマンド

cdk synth          # CloudFormation テンプレートを合成
cdk diff           # デプロイ済みとローカルの変更を比較
cdk deploy         # スタックを AWS にデプロイ
cdk deploy --all   # すべてのスタックをデプロイ
cdk destroy        # スタックを削除
cdk ls             # アプリ内のすべてのスタックをリスト
cdk doctor         # 環境のセットアップをチェック

5. 推奨デリバリーループ

1. スタックをモデル化

   • L2 コンストラクトから始め、繰り返されるロジックをカスタム コンストラクトに抽出します。

2. cdk synth を実行

   • チェックポイント: インポートの不足、無効なプロパティ、不足しているコンテキスト、未解決の参照がなく合成が成功します。
   • 失敗した場合: コンストラクト設定またはコンテキスト値を修正してから、cdk synth を再実行します。

3. インフラストラクチャテストを実行

   • チェックポイント: アサーションが IAM スコープ、ステートフルリソース、重要な出力をカバーします。
   • テストが失敗した場合: スタックまたはテスト期待値を更新してから、テストスイートを再実行します。

4. cdk diff を実行

   • チェックポイント: IAM 拡張、リソース置換、エクスポート変更、ステートフルリソースへの削除を確認します。
   • diff がリスクをもたらす場合: 名前、依存関係、または RemovalPolicy を調整してから、cdk diff を再実行します。

5. cdk deploy を実行

   • チェックポイント: スタックが CREATE_COMPLETE または UPDATE_COMPLETE に到達します。
   • デプロイが失敗した場合: CloudFormation イベントを検査して、クォータ、権限、エクスポート競合、またはブートストラップの問題を修正してから、cdk deploy を再試行します。

6. ランタイム結果を検証

   • 次に進む前に、スタック出力、エンドポイント、アラーム、統合が期待どおりに動作することを確認します。

6. クロススタック参照

// スタック A は値をエクスポート
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 });
  }
}

// スタック B は 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,
    });
  }
}

// 組み合わせ
const network = new NetworkStack(app, 'Network');
new AppStack(app, 'App', { vpc: network.vpc });

例

例 1: サーバーレス API

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 });
  }
}

例 2: CDK アサーション テスト

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);
});

ベストプラクティス

1. スタックごとに 1 つの関心事 — ネットワーク、コンピュート、ストレージ、監視を分離します。
2. L2 コンストラクトを優先 — サポートされていないプロパティが必要な場合のみ Cfn* に下げます。
3. 明示的な環境を設定 — env にアカウントとリージョンを渡し、暗黙的な本番環境ターゲットを避けます。
4. グラント ヘルパーを使用 — 可能な場合は手書きの IAM より .grant*() を優先します。
5. デプロイ前に diff を確認 — IAM 拡張、置換、削除を必須チェックポイントとして扱います。
6. インフラストラクチャをテスト — 重要なリソースを細かい粒度のアサーションでカバーします。
7. ハードコードされた値を避ける — コンテキスト、パラメータ、環境変数を使用します。
8. 適切な RemovalPolicy を使用 — 本番データは RETAIN、使い捨て環境のみ DESTROY。

制約と警告

• CloudFormation の制限 — スタックあたり最大 500 リソース、大規模なアプリは複数スタックに分割します
• 合成はデプロイではない — cdk synth はテンプレートのみを生成し、cdk deploy が変更を適用します
• クロススタック参照 は CloudFormation エクスポートを作成します。削除には慎重な順序付けが必要です
• ステートフルリソース (RDS、DynamoDB、データ付き S3) — 本番環境では常に removalPolicy: RETAIN を設定します
• ブートストラップが必要 — 最初のデプロイ前に、アカウント/リージョンごとに 1 回 cdk bootstrap を実行します
• アセット バンドリング — Lambda コードと Docker イメージは CDK ブートストラップ バケットにアップロードされます

参考資料

詳細な実装ガイドは references/ ディレクトリにあります:

• Core Concepts — アプリライフサイクル、スタック、コンストラクト、環境、アセット
• Serverless Patterns — Lambda、API Gateway、DynamoDB、S3 イベント、Step Functions
• Networking & VPC — VPC 設計、サブネット、NAT、セキュリティグループ、VPC エンドポイント
• Security Hardening — IAM、KMS、Secrets Manager、WAF、コンプライアンス
• Testing Strategies — アサーション、スナップショット、統合テスト、CDK Nag