これは AWS CDK v2 開発者ガイドです。旧版の CDK v1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。

CDK Toolkit のプログラムによるアクションの設定

AWS CDK Toolkit Library は、合成、デプロイ、スタック管理などのアプリケーションライフサイクルアクション用のプログラムによるインターフェイスを提供します。このガイドでは、コードで各アクションを使用する方法について説明します。

synth を使用したクラウドアセンブリの生成

synth アクションは、クラウドアセンブリソースからクラウドアセンブリを生成します。合成の詳細については、「CDK スタック合成を設定して実行する」を参照してください。クラウドアセンブリには、CDK アプリからの次のデプロイアーティファクトが含まれています。

synth アクションを使用してクラウドアセンブリを作成する方法は次のとおりです。

// Create a toolkit instance
const toolkit = new Toolkit();

// Create a cloud assembly source from a TypeScript app
const cloudAssemblySource = await toolkit.fromCdkApp("ts-node app.ts");

// Generate a cloud assembly
const cloudAssembly = await toolkit.synth(cloudAssemblySource);

// Use the cloud assembly for operations
await toolkit.list(cloudAssembly);
await toolkit.deploy(cloudAssembly);
await toolkit.diff(cloudAssembly);

// Query information from the cloud assembly
const template = cloudAssembly.getStack("my-stack").template;

リストを含むスタック情報の表示

list アクションは、依存関係や現在のステータスなど、CDK アプリケーションのスタックに関する情報を取得します。このアクションを使用して、デプロイ前にインフラストラクチャを検査するか、レポートを生成します。

import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';

// Get information about specific stacks
const stackDetails = await toolkit.list(cloudAssemblySource, {
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["my-stack"], // Only include stacks matching this pattern
  }
});

// Process the returned stack information
for (const stack of stackDetails) {
  console.log(`Stack: ${stack.id}, Dependencies: ${stack.dependencies}`);
}

デプロイによるインフラストラクチャのプロビジョニング

deploy アクションは、合成中に生成されたクラウドアセンブリを使用して、AWS のインフラストラクチャをプロビジョニングまたは更新します。デプロイの概要については、「AWS CDK アプリケーションのデプロイ」を参照してください。スタックの選択、パラメータ値、ロールバック動作などのデプロイオプションを制御できます。

// Deploy stacks with parameter values
await toolkit.deploy(cloudAssemblySource, {
  parameters: StackParameters.exactly({
    "MyStack": {
      "BucketName": "amzn-s3-demo-bucket"
    }
  })
});

デプロイアクションは、さまざまなワークフローに対応するためのさまざまなデプロイ方法をサポートします。ほとんどのシナリオ、特に本番環境では、CloudFormation 変更セットを使用するデフォルトのデプロイ方法を使用することをお勧めします。イテレーション速度が重要な開発環境では、ホットスワップなどの代替方法を使用できます。

import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';

// Deploy using default deployment method (recommended for production)
await toolkit.deploy(cloudAssemblySource, {
  parameters: StackParameters.exactly({
    "MyStack": {
      "BucketName": "amzn-s3-demo-bucket"
    }
  })
});

// For development environments only: Deploy with hotswap for faster iterations
// Note: We recommend using default deployment methods for production environments
await toolkit.deploy(cloudAssemblySource, {
  deploymentMethod: { method: "hotswap", fallback: true }, // Faster but introduces drift
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["dev-stack"]
  }
});

リファクタリングによるデプロイされたリソースの保持

refactor アクションは、コンストラクトの名前変更やスタック間の移動などの CDK コードのリファクタリング時に、デプロイされたリソースを保持します。この機能がないと、これらの変更により、CloudFormation がリソースを置き換え、サービスの中断やデータ損失につながる可能性があります。

リファクタリングアクションでは、現在のコードをデプロイされた状態と比較することで、マッピングを自動的に計算します。CDK アプリケーションにデプロイされた状態とまったく同じリソースセットが含まれ、コンストラクトツリー内の場所のみが異なることを確認します。リソースの追加、削除、または変更が検出されると、リファクタリングオペレーションはエラーメッセージ付きで拒否されます。

マッピングを計算すると、リファクタリングアクションでは CloudFormation のリファクタリング API を使用して、リソース ID を置き換えずに更新します。あいまいなマッピング (複数のマッピングが存在する) が発生した場合は、明示的な上書きを指定してこれらのあいまいさを解決できます。

// Perform refactoring operation to preserve resources
await toolkit.refactor(cloudAssemblySource);

// With optional overrides to resolve ambiguities
await toolkit.refactor(cloudAssemblySource, {
  overrides: {
    "environments": [
      {
        "account": "123456789012",
        "region": "us-east-2",
        "resources": {
          "StackA.OldName": "StackA.NewName"
        }
      }
    ]
  }
});

失敗したデプロイをロールバックで元に戻す

デプロイが失敗し、自動的に元に戻すことができない場合、rollback アクションはスタックを最後の安定状態に戻します。このアクションを使用して、手動による介入が必要な失敗したデプロイから復旧します。

import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';

// Roll back stacks to their last stable state
await toolkit.rollback(cloudAssemblySource, {
  orphanFailedResources: false, // When true, removes failed resources from CloudFormation management
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["failed-stack"]
  }
});

ウォッチによる変更のモニタリング

watch アクションは、CDK アプリのローカルファイルの変更を継続的にモニタリングし、デプロイまたはホットスワップを自動的に実行します。これにより、コードが終了するまで実行されるファイルウォッチャーが作成されます。

import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';

// Start watching for changes
const watcher = await toolkit.watch(cloudAssemblySource, {
  include: ["lib/**/*.ts"], // Only watch TypeScript files in the lib directory
  exclude: ["**/*.test.ts"], // Ignore test files
  deploymentMethod: { method: "hotswap" }, // This is the default, shown here for clarity
  stacks: {
    strategy: StackSelectionStrategy.ALL // Watch all stacks
  }
});

// Later in your code, you can explicitly stop watching:
// await watcher.dispose();

ウォッチ関数は、ウォッチを停止するタイミングを明示的に制御できる IWatcher オブジェクトを返します。ウォッチプロセスを終了するときに、このオブジェクトで dispose() メソッドを呼び出します。

破棄によるインフラストラクチャの削除

destroy アクションは、CDK スタックとそれらの関連付けられたリソースを AWS から削除します。このアクションを使用して、不要になったリソースをクリーンアップします。

import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';

// Remove specific stacks and their resources
await toolkit.destroy(cloudAssemblySource, {
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["dev-stack"], // Only destroy stacks matching this pattern
  }
});