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

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

AWS CDK Toolkit Library クラウドアセンブリソースの管理

AWS CDK Toolkit Library を使用してクラウドアセンブリソースを設定し、CDK アプリケーションのデプロイ方法をカスタマイズします。このガイドでは、デプロイ要件とワークフローのニーズを満たすようにクラウドアセンブリソースを設定する方法について説明します。

CDK Toolkit を使用する前に、クラウドアセンブリソースを指定します。クラウドアセンブリソースは、CDK アプリからクラウドアセンブリを生成する手順を提供します。結果のクラウドアセンブリには、CDK Toolkit がデプロイする合成されたインフラストラクチャアーティファクトが含まれています AWS。

CDK Toolkit Library には、さまざまなシナリオやワークフローに適したクラウドアセンブリソースを設定するためのいくつかのアプローチが用意されています。

クラウドアセンブリソースの選択

クラウドアセンブリソースの設定

既存の CDK アプリから

fromCdkApp メソッドを使用して、サポートされている任意の言語で記述された CDK アプリを操作します。このアプローチは、既存の CDK アプリケーションがあり、プログラムでデプロイする場合に最適です。

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

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

// TypeScript app
const cloudAssemblySource = await toolkit.fromCdkApp("ts-node app.ts");

// Deploy a specific stack from the assembly
await toolkit.deploy(cloudAssemblySource, {
    stacks: ['MyStack']
});

// Other language examples:
// JavaScript app
// const cloudAssemblySource = await toolkit.fromCdkApp("node app.js");

// Python app
// const cloudAssemblySource = await toolkit.fromCdkApp("python app.py");

// Java app
// const cloudAssemblySource = await toolkit.fromCdkApp("mvn -e -q exec:java -Dexec.mainClass=com.mycompany.app.App");

インラインアセンブリビルダーから

アセンブリビルダー関数を使用して、コード内に CDK アプリを直接作成します。このアプローチは、インフラストラクチャをインラインで定義するシンプルなデプロイやテストシナリオに役立ちます。

import { App, Stack, RemovalPolicy, StackProps } from 'aws-cdk-lib';
import { Bucket } from 'aws-cdk-lib/aws-s3';
import { Toolkit } from '@aws-cdk/toolkit-lib';
import { Construct } from 'constructs';

// Create a cloud assembly source from an inline CDK app
const cloudAssemblySource = await toolkit.fromAssemblyBuilder(async () => {
    const app = new App();

    // Define a simple stack with an S3 bucket
    class MyStack extends Stack {
        constructor(scope: Construct, id: string, props?: StackProps) {
            super(scope, id, props);

            // Create an S3 bucket
            new Bucket(this, 'MyBucket', {
                versioned: true,
                removalPolicy: RemovalPolicy.DESTROY,
                autoDeleteObjects: true
            });
        }
    }

    // Instantiate the stack
    new MyStack(app, 'MyInlineStack');

    return app.synth();
});

// Deploy using the cloud assembly source
await toolkit.deploy(cloudAssemblySource, {
    stacks: ['MyInlineStack']
});

既存のアセンブリディレクトリから

合成されたクラウドアセンブリが既にある場合は、直接使用できます。これは、すでに を実行している場合cdk synthや、CI/CD パイプラインによって生成されたクラウドアセンブリを使用する場合に便利です。

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

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

// Use an existing cloud assembly directory
const cloudAssemblySource = await toolkit.fromAssemblyDirectory("cdk.out");

// Deploy using the cloud assembly source
await toolkit.deploy(cloudAssemblySource, {
    stacks: ['MyStack']
});

キャッシュされたクラウドアセンブリの使用

クラウドアセンブリを使用する場合は、次の 2 つのオプションがあります。

キャッシュされたアセンブリは、次の場合に使用します。

次の場合は、クラウドアセンブリソースを直接使用します。

クラウドアセンブリを作成、キャッシュ、再利用する方法

クラウドアセンブリソースを作成したら、クラウドアセンブリを合成することでクラウドアセンブリを生成できます。クラウドアセンブリには、デプロイに必要な AWS CloudFormation テンプレートとアセットが含まれています。

クラウドアセンブリを 1 回生成し、複数の Toolkit オペレーションに再利用することをお勧めします。このキャッシュアプローチは、オペレーションごとにアセンブリを再生成するよりも効率的です。ソースが頻繁に変更される場合にのみ、アセンブリを再生成することを検討してください。

キャッシュされたクラウドアセンブリを作成する方法は次のとおりです。

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

その後、、、 などdeploy()、キャッシュされたクラウドアセンブリでさまざまな Toolkit list()アクションを実行できますdiff()。クラウドアセンブリをキャッシュすることで、合成が 1 回だけ行われるため、後続の Toolkit アクションの実行が高速化されます。詳細については、「synth - Generate cloud assemblies」を参照してください。

クラウドアセンブリリソースの廃棄

クラウドアセンブリを使用して一時的なリソースをクリーンアップしたら、必ず廃棄してください。特に複数のオペレーションを実行する場合は、適切なクリーンアップを確保するために try/finally ブロックを使用することをお勧めします。

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

try {
    // Use the cloud assembly for multiple operations
    await toolkit.list(cloudAssembly);
    await toolkit.deploy(cloudAssembly);
} finally {
    // Always dispose when done
    await cloudAssembly.dispose();
}

キャッシュされたクラウドアセンブリを作成および破棄する方法の例を次に示します。

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

const toolkit = new Toolkit();

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

// Create cloud assembly from source
const cloudAssembly = await toolkit.synth(cloudAssemblySource);

try {
    // List stacks in the assembly
    await toolkit.list(cloudAssembly);

    // Check for changes
    await toolkit.diff(cloudAssembly);

    // Deploy if needed
    await toolkit.deploy(cloudAssembly);
} finally {
    // Always dispose when done
    await cloudAssembly.dispose();
}

クラウドアセンブリの有効期間について

を使用してキャッシュされたクラウドアセンブリを作成するとsynth()、読み取り可能な CloudAssemblyと の両方として機能する特殊なタイプが得られますCloudAssemblySource。このキャッシュされたアセンブリから生成されたクラウドアセンブリ (リストまたはデプロイオペレーションなど) は、親の存続期間に関連付けられます。

クラウドアセンブリソースのベストプラクティス

クラウドアセンブリソースを使用する場合は、以下のベストプラクティスを考慮してください。

次の例は、複数のオペレーションでクラウドアセンブリを再利用しながら、エラー処理と適切なクリーンアップを実装する方法を示しています。

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

// Example with error handling and proper cleanup
async function deployInfrastructure(): Promise<void> {
    let cloudAssembly;

    try {
        // Generate a cloud assembly once
        cloudAssembly = await toolkit.synth(cloudAssemblySource);

        // Reuse the same cloud assembly for multiple operations
        await toolkit.list(cloudAssembly);    // Uses existing assembly
        await toolkit.deploy(cloudAssembly);   // Uses existing assembly
        await toolkit.diff(cloudAssembly);     // Uses existing assembly
    } catch (error) {
        console.error("Failed to deploy:", error);
    } finally {
        // Always dispose when done
        if (cloudAssembly) {
            await cloudAssembly.dispose();
        }
    }
}

// Call the async function
deployInfrastructure().catch(error => {
    console.error("Deployment failed:", error);
    process.exit(1);
});

潜在的な問題の解決

クラウドアセンブリソースの潜在的な問題を解決するには、次の手順に従います。

Toolkit オペレーション中にエラーが発生した場合は、エラー処理をシンプルに保ち、ユーザーに明確なエラーメッセージを提供することに集中してください。クラウドアセンブリの使用が終了したら、必ず廃棄してください。適切なクリーンアップによる基本的なエラー処理の例を次に示します。

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

// Example with simple error handling
try {
    // Create the cloud assembly source
    const cloudAssemblySource = await toolkit.fromCdkApp("ts-node app.ts");

    // Synthesize the cloud assembly
    const cloudAssembly = await toolkit.synth(cloudAssemblySource);

    // Use the cloud assembly
    await toolkit.list(cloudAssembly);
} catch (error) {
    // Display the error message
    console.error("Operation failed:", error.message);
} finally {
    // Clean up resources
    await cloudAssembly.dispose();
}