これは AWS CDK v2 デベロッパーガイドです。旧版の CDK v1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。
翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# CDK Toolkit のプログラムによるアクションの設定
AWS CDK Toolkit Library は、合成、デプロイ、スタック管理などのアプリケーションライフサイクルアクション用のプログラムによるインターフェイスを提供します。このガイドでは、コードで各アクションを使用する方法について説明します。
## synth を使用したクラウドアセンブリの生成
`synth` アクションは、クラウドアセンブリソースからクラウドアセンブリを生成します。合成の詳細については、「[CDK スタック合成を設定して実行する](configure-synth.md)」を参照してください。クラウドアセンブリには、CDK アプリからの次のデプロイアーティファクトが含まれています。
+ インフラストラクチャを定義する AWS CloudFormation テンプレート。
+ Lambda 関数コードや Docker イメージなどのアセット。
+ デプロイメタデータと設定。
`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;
```
**ヒント**
クラウドアセンブリを使用すると、合成が 1 回だけ行われるため、複数のオペレーションを実行する必要がある場合のパフォーマンスを最適化できます。キャッシュや廃棄など、クラウドアセンブリの管理の詳細については、「[クラウドアセンブリを作成して管理する](toolkit-library-configure-ca.md#toolkit-library-configure-ca-cache)」を参照してください。
## リストを含むスタック情報の表示
`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.md)」を参照してください。スタックの選択、パラメータ値、ロールバック動作などのデプロイオプションを制御できます。
```
// 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"
}
}
]
}
});
```
**重要**
リファクタリングオペレーションは、新しいリソースの追加、リソースの削除、リソースプロパティの変更など、他のアクションとは別に実行する必要があります。このような変更が必要な場合は、まずそれらの変更を個別にデプロイしてから、リファクタリングを使用してリソースを再編成する必要があります。
**ヒント**
CDK リファクタリングの仕組みや使用のタイミングなどの詳細については、「[CDK コードのリファクタリング時にデプロイされたリソースを保持する](refactor.md)」を参照してください。
## 失敗したデプロイをロールバックで元に戻す
デプロイが失敗し、自動的に元に戻すことができない場合、`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 アプリのローカルファイルの変更を継続的にモニタリングし、デプロイまたはホットスワップを自動的に実行します。これにより、コードが終了するまで実行されるファイルウォッチャーが作成されます。
**警告**
ホットスワップデプロイは、可能な場合は CloudFormation を経由せずにリソースを直接更新するため、開発中の更新がより迅速になります。これは、`watch` コマンドでデフォルトで有効になっています。これにより開発サイクルが高速化されますが、CloudFormation テンプレートとデプロイされたリソースの間にドリフトが生じます。したがって、ホットスワップは本番稼働用環境で使用しないことをお勧めします。
```
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 から削除します。このアクションを使用して、不要になったリソースをクリーンアップします。
**重要**
破棄アクションは、このコマンドの CLI バージョンとは異なり、確認を求めることなくリソースを完全に削除します。スタックを破棄する前に、重要なデータのバックアップがあることを確認してください。
```
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
}
});
```