既存のリソースと AWS CloudFormation テンプレートを に移行する AWS CDK - AWS Cloud Development Kit (AWS CDK) v2
移行の仕組みCDK 移行の利点考慮事項前提条件CDK 移行の開始方法AWS CloudFormation スタックからの移行AWS CloudFormation テンプレートからの移行デプロイされたリソースからの移行CDK アプリケーションの管理とデプロイ

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

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

既存のリソースと AWS CloudFormation テンプレートを に移行する AWS CDK

CDK 移行機能は のプレビューリリースであり、変更 AWS CDK される可能性があります。

AWS Cloud Development Kit (AWS CDK) コマンドラインインターフェイス (AWS CDK CLI) を使用して、デプロイされた AWS リソース、デプロイされた AWS CloudFormation スタック、およびローカル AWS CloudFormation テンプレートを に移行します AWS CDK。

移行の仕組み

cdk migrate コマンドを使用して AWS CDK CLI、次のソースから移行します。

  • デプロイされた AWS リソース。

  • デプロイされた AWS CloudFormation スタック。

  • ローカル AWS CloudFormation テンプレート。

デプロイされた AWS リソース

AWS CloudFormation スタックに関連付けられていない特定の環境 (AWS アカウント および AWS リージョン) からデプロイされた AWS リソースを移行できます。

は、IaC AWS CDK CLIジェネレーターサービスを利用して AWS 環境内のリソースをスキャンし、リソースの詳細を収集します。 IaC IaC ジェネレーターの詳細については、AWS CloudFormation 「 ユーザーガイド」の「既存のリソースのテンプレートの生成」を参照してください。

リソースの詳細を AWS CDK CLI収集した後、 は、移行されたリソースを含む単一のスタックを含む新しい CDK アプリケーションを作成します。

デプロイされた AWS CloudFormation スタック

1 つの AWS CloudFormation スタックを新しい AWS CDK アプリケーションに移行できます。 AWS CDK CLI はスタックのテンプレートを取得し AWS CloudFormation 、新しい CDK アプリを作成します。CDK アプリは、移行されたスタックを含む単一の AWS CloudFormation スタックで構成されます。

ローカル AWS CloudFormation テンプレート

ローカル AWS CloudFormation テンプレートから移行できます。ローカルテンプレートには、デプロイされたリソースが含まれている場合と含まれない場合があります。CLI は、 リソースに 1 AWS CDK つのスタックを含む新しい CDK アプリを作成します。

移行後、CDK アプリケーションを に管理、変更、デプロイ AWS CloudFormation して、 リソースをプロビジョニングまたは更新できます。

CDK 移行の利点

リソースを に移行する AWS CDK のは、これまで手動プロセスであり、開始 AWS CDK するには AWS CloudFormation および との時間と専門知識が必要です。CDK Migrate を使用すると AWS CDK CLI、 は移行作業の大部分をわずかな時間で容易にします。CDK 移行では、 を使用して で新規および既存のアプリケーションの開発と管理 AWS CDK をすぐに開始できます AWS。

考慮事項

一般的な考慮事項

CDK 移行と CDK インポート

cdk import コマンドは、デプロイされたリソースを新規または既存の CDK アプリケーションにインポートできます。インポートする場合、各リソースはアプリで L1 コンストラクトとして手動で定義する必要があります。を使用してcdk import、一度に 1 つ以上のリソースを新規または既存の CDK アプリにインポートすることをお勧めします。詳細については、「スタックへの既存リソースのインポート」を参照してください。

cdk migrate コマンドは、デプロイされたリソース、デプロイされた AWS CloudFormation スタック、またはローカル AWS CloudFormation テンプレートから新しい CDK アプリケーションに移行します。移行中、 は AWS CDK CLI cdk importを使用してリソースを新しい CDK アプリにインポートします。は、リソースごとに L1 コンストラクト AWS CDK CLIも生成します。サポートされている移行ソースから新しい AWS CDK アプリケーションにインポートcdk migrateする場合は、 を使用することをお勧めします。

CDK Migrate は L1 コンストラクトのみを作成します

新しく作成された CDK アプリには L1 コンストラクトのみが含まれます。移行後にアプリに上位レベルのコンストラクトを追加できます。

CDK Migrate は、単一のスタックを含む CDK アプリケーションを作成します。

新しく作成された CDK アプリには、1 つのスタックが含まれます。

デプロイされたリソースを移行する場合、移行されたすべてのリソースは新しい CDK アプリの 1 つのスタックに含まれます。

AWS CloudFormation スタックを移行する場合、新しい CDK アプリでは 1 つの AWS CloudFormation スタックのみを 1 つのスタックに移行できます。

アセットの移行

AWS Lambda コードなどのプロジェクトアセットは、新しい CDK アプリに直接移行されません。移行後、アセット値を指定して CDK アプリに含めることができます。

ステートフルリソースの移行

データベースや Amazon Simple Storage Service (Amazon S3) バケットなどのステートフルリソースを移行する場合、新しいリソースを作成する代わりに、ほとんどの場合、既存のリソースを移行する必要があります。

ステートフルリソースを移行して保持するには、次の手順を実行します。

  • ステートフルリソースがインポートをサポートしていることを確認します。詳細については、「 ユーザーガイド」の「リソースタイプのサポートAWS CloudFormation 」を参照してください。

  • 移行後、新しい CDK アプリで移行されたリソースの論理 ID が、デプロイされたリソースの論理 ID と一致することを確認します。

  • AWS CloudFormation スタックから移行する場合は、新しい CDK アプリのスタック名がスタックと一致する AWS CloudFormation ことを確認します。

  • 移行したリソースの同じ AWS アカウントと を使用して CDK AWS リージョン アプリケーションをデプロイします。

AWS CloudFormation テンプレートから移行する際の考慮事項

CDK 移行が単一テンプレート移行をサポート

AWS CloudFormation テンプレートを移行するときは、移行するテンプレートを 1 つ選択できます。ネストされたテンプレートはサポートされていません。

組み込み関数を使用したテンプレートの移行

組み込み関数を使用する AWS CloudFormation テンプレートから移行する場合、 AWS CDK CLI は Fn クラスを使用してロジックを CDK アプリに移行しようとします。詳細については、「 API リファレンス」の「クラス Fn」を参照してください。 AWS Cloud Development Kit (AWS CDK)

デプロイされたリソースから移行する際の考慮事項

スキャンの制限

環境のリソースをスキャンする場合、IaC ジェネレーターには、スキャン時に取得できるデータとクォータの制限に特定の制限があります。詳細については、「 AWS CloudFormation ユーザーガイドhttps://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/generate-IaC.html#generate-template-considerations」の「考慮事項」を参照してください。

前提条件

cdk migrate コマンドを使用する前に、「」のすべてのセットアップステップを完了してくださいの開始方法 AWS CDK。

CDK 移行の開始方法

開始するには、選択したディレクトリから cdk migrate コマンドを実行します AWS CDK CLI。実行する移行のタイプに応じて、必須オプションとオプションを指定します。

で使用できるオプションの完全なリストと説明については、cdk migrate「」を参照してくださいcdk migrate。

以下は、提供すべき重要なオプションです。

スタックの名前

唯一の必須オプションは です--stack-name。このオプションを使用して、移行後に AWS CDK アプリ内で作成されるスタックの名前を指定します。スタック名は、デプロイ時に AWS CloudFormation スタックの名前としても使用されます。

[言語]

を使用して--language、新しい CDK アプリケーションのプログラミング言語を指定します。

AWS アカウントと AWS リージョン

は、デフォルトのソースから AWS アカウントと AWS リージョン 情報 AWS CDK CLIを取得します。詳細については、「環境」を参照してください。--account および --regionオプションを で使用cdk migrateして、他の値を指定できます。

新しい CDK プロジェクトの出力ディレクトリ

デフォルトでは、 AWS CDK CLI は作業ディレクトリに新しい CDK プロジェクトを作成し、 で指定した値を使用してプロジェクトフォルダ--stack-nameに名前を付けます。同じ名前のフォルダが現在存在する場合、 AWS CDK CLIはそのフォルダを上書きします。

--output-path オプションを使用して、新しい CDK プロジェクトフォルダに別の出力パスを指定できます。

移行ソース

移行元のソースを指定するオプションを指定します。

  • --from-path – ローカル AWS CloudFormation テンプレートから移行します。

  • --from-scan – AWS アカウントと にデプロイされたリソースから移行します AWS リージョン。

  • --from-stack – AWS CloudFormation スタックから移行します。

移行ソースに応じて、cdk migrateコマンドをカスタマイズするための追加オプションを指定できます。

AWS CloudFormation スタックからの移行

デプロイされた AWS CloudFormation スタックから移行するには、 --from-stackオプションを指定します。でデプロイされた AWS CloudFormation スタックの名前を指定します--stack-name。以下に例を示します。

$ cdk migrate --from-stack --stack-name "myCloudFormationStack"

AWS CDK CLI は以下を実行します。

  1. デプロイされたスタックの AWS CloudFormation テンプレートを取得します。

  2. cdk init を実行して新しい CDK アプリケーションを初期化します。

  3. 移行したスタックを含む AWS CloudFormation スタックを CDK アプリ内に作成します。

デプロイされた AWS CloudFormation スタックから移行すると、 は AWS CDK CLIデプロイされたリソースIDs とデプロイされた AWS CloudFormation スタック名を、新しい CDK アプリの移行されたリソースとスタックと照合しようとします。

移行後、CDK アプリを正常に管理および変更できます。デプロイすると、 AWS CloudFormation は一致する AWS CloudFormation スタック名により、デプロイを AWS CloudFormation スタック更新として識別します。一致する論理 IDs を持つリソースが更新されます。デプロイの詳細については、「」を参照してくださいCDK アプリケーションの管理とデプロイ。

AWS CloudFormation テンプレートからの移行

CDK 移行では、 JSONまたは でフォーマットされた AWS CloudFormation テンプレートからの移行がサポートされていますYAML。

ローカル AWS CloudFormation テンプレートから移行するには、 --from-pathオプションを使用してローカルテンプレートへのパスを指定します。また、必要な--stack-nameオプションを指定する必要があります。以下に例を示します。

$ cdk migrate --from-path "./template.json" --stack-name "myCloudFormationStack"

AWS CDK CLI は以下を実行します。

  1. ローカル AWS CloudFormation テンプレートを取得します。

  2. cdk init を実行して新しい CDK アプリケーションを初期化します。

  3. 移行した AWS CloudFormation テンプレートを含むスタックを CDK アプリ内に作成します。

移行後、CDK アプリを正常に管理および変更できます。デプロイには、次のオプションがあります。

  • AWS CloudFormation スタックの更新 — ローカル AWS CloudFormation テンプレートが以前にデプロイされていた場合は、デプロイされた AWS CloudFormation スタックを更新できます。

  • 新しい AWS CloudFormation スタックをデプロイする – ローカル AWS CloudFormation テンプレートが一度もデプロイされなかった場合、または以前にデプロイされたテンプレートから新しいスタックを作成する場合は、新しい AWS CloudFormation スタックをデプロイできます。

AWS SAM テンプレートからの移行

AWS Serverless Application Model （AWS SAM) テンプレートから移行するには、まず AWS CloudFormation テンプレートに変換するか、 をデプロイして AWS CloudFormation スタックを作成する必要があります。

AWS SAM テンプレートを に変換するには AWS CloudFormation、 sam validate --debug コマンドを使用できます AWS SAM CLI。このコマンドを実行する前にlint、 samconfig.toml ファイルfalseで を に設定する必要がある場合があります。

AWS CloudFormation スタックに変換するには、 を使用して AWS SAM テンプレートをデプロイします AWS SAM CLI。次に、デプロイされたスタックから移行します。

デプロイされたリソースからの移行

デプロイされた AWS リソースから移行するには、 --from-scanオプションを指定します。また、必要な--stack-nameオプションを指定する必要があります。以下に例を示します。

$ cdk migrate --from-scan --stack-name "myCloudFormationStack"

AWS CDK CLI は以下を実行します。

  1. リソースとプロパティの詳細についてアカウントをスキャンします – AWS CDK は IaC ジェネレータCLIーを使用してアカウントをスキャンし、詳細を収集します。

  2. テンプレートの生成 AWS CloudFormation – スキャン後、 AWS CDK CLI は IaC ジェネレーターを使用して AWS CloudFormation テンプレートを作成します。

  3. 新しい CDK アプリケーションを初期化してテンプレートを移行する – AWS CDK は、新しい AWS CDK アプリケーションを初期化cdk initするためにCLI実行し、 AWS CloudFormation テンプレートを 1 つのスタックとして CDK アプリケーションに移行します。

フィルターを使用する

デフォルトでは、 AWS CDK CLI は AWS 環境全体をスキャンし、IaC ジェネレーターの最大クォータ制限までリソースを移行します。で AWS CDK CLIフィルターを指定して、リソースをアカウントから新しい CDK アプリに移行する基準を指定できます。詳細については、「--filter」を参照してください。

IaC ジェネレーターによるリソースのスキャン

アカウントのリソース数によっては、スキャンに数分かかる場合があります。スキャンプロセス中に進行状況バーが表示されます。

サポートされているリソースタイプ

は、IaC AWS CDK CLIジェネレーターでサポートされているリソースを移行します。詳細なリストについては、「 ユーザーガイド」の「リソースタイプのサポートAWS CloudFormation 」を参照してください。

書き込み専用プロパティの解決

サポートされているリソースには、書き込み専用プロパティが含まれているものがあります。これらのプロパティは、 プロパティを設定するために に書き込むことができますが、IaC ジェネレーターが読み取ることも、 値を取得 AWS CloudFormation することもできません。例えば、データベースパスワードの指定に使用されるプロパティは、セキュリティ上の理由から書き込み専用である場合があります。

移行中にリソースをスキャンする場合、IaC ジェネレーターは書き込み専用プロパティを含む可能性のあるリソースを検出し、次のいずれかのタイプに分類します。

  • MUTUALLY_EXCLUSIVE_PROPERTIES – これらは、交換可能で同様の目的を果たす特定のリソースの書き込み専用プロパティです。リソースを設定するには、相互に排他的なプロパティの 1 つが必要です。例えば、 AWS::Lambda::Functionリソースの S3Bucket、ImageUri、および ZipFileプロパティは、相互に排他的な書き込み専用プロパティです。これらのいずれかを使用して関数アセットを指定できますが、いずれかを使用する必要があります。

  • MUTUALLY_EXCLUSIVE_TYPES – これらは、複数の設定タイプを受け入れる書き込み専用プロパティとして必要です。例えば、 AWS::ApiGateway::RestApiリソースの Bodyプロパティは、オブジェクトまたは文字列タイプを受け入れます。

  • UNSUPPORTED_PROPERTIES – これらは書き込み専用プロパティであり、他の 2 つのカテゴリには含まれません。オブジェクトの配列を受け入れるオプションプロパティまたは必須プロパティのいずれかです。

書き込み専用プロパティと、デプロイされたリソースをスキャンして AWS CloudFormation テンプレートを作成するときに IaC ジェネレーターがそれらを管理する方法の詳細については、AWS CloudFormation 「 ユーザーガイド」のIaC ジェネレーターと書き込み専用プロパティ」を参照してください。

移行後、新しい CDK アプリで書き込み専用プロパティ値を指定する必要があります。は CDK AWS CDK CLIプロジェクトの ReadMe ファイルに警告セクションを追加して、IaC ジェネレーターによって識別された書き込み専用プロパティを文書化します。以下に例を示します。

# Welcome to your CDK TypeScript project
...
## Warnings
### Write-only properties
Write-only properties are resource property values that can be written to but can't be read by AWS CloudFormation or CDK Migrate. For more information, see [IaC generator and write-only properties](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/generate-IaC-write-only-properties.html).

Write-only properties discovered during migration are organized here by resource ID and categorized by write-only property type. Resolve write-only properties by providing property values in your CDK app. For guidance, see [Resolve write-only properties](https://docs.aws.amazon.com/cdk/v2/guide/migrate.html#migrate-resources-writeonly).
### MyLambdaFunction
- **UNSUPPORTED_PROPERTIES**: 
  - SnapStart/ApplyOn: Applying SnapStart setting on function resource type.Possible values: [PublishedVersions, None]
This property can be replaced with other types
  - Code/S3ObjectVersion: For versioned objects, the version of the deployment package object to use.
This property can be replaced with other exclusive properties
- **MUTUALLY_EXCLUSIVE_PROPERTIES**: 
  - Code/S3Bucket: An Amazon S3 bucket in the same AWS Region as your function. The bucket can be in a different AWS account.
This property can be replaced with other exclusive properties
  - Code/S3Key: The Amazon S3 key of the deployment package.
This property can be replaced with other exclusive properties

  • 警告は、関連付けられているリソースの論理 ID を識別する見出しの下に整理されます。

  • 警告はタイプ別に分類されます。これらのタイプは IaC ジェネレーターから直接取得されます。

書き込み専用プロパティを解決するには

  1. CDK プロジェクトのReadMeファイルの警告セクションから解決する書き込み専用プロパティを特定します。ここでは、書き込み専用プロパティを含む可能性のある CDK アプリのリソースをメモし、検出された書き込み専用プロパティタイプを特定できます。

    1. の場合MUTUALLY_EXCLUSIVE_PROPERTIES、 AWS CDK アプリで設定する相互に排他的なプロパティを決定します。

    2. ではMUTUALLY_EXCLUSIVE_TYPES、プロパティの設定に使用する受け入れたタイプを決定します。

    3. の場合UNSUPPORTED_PROPERTIES、 プロパティがオプションか必須かを判断します。次に、必要に応じて を設定します。

  2. IaC ジェネレーターと書き込み専用プロパティのガイダンスを使用して、警告タイプの意味を参照してください。

  3. CDK アプリでは、解決する書き込み専用プロパティ値もアプリの Propsセクションで指定されます。ここに正しい値を入力します。プロパティの説明とガイダンスについては、 AWS CDK API リファレンス を参照してください。

    以下は、解決する 2 つの書き込み専用プロパティを持つ、移行された CDK アプリ内の Propsセクションの例です。

    export interface MyTestAppStackProps extends cdk.StackProps {
  /**
   * The Amazon S3 key of the deployment package.
   */
  readonly lambdaFunction00asdfasdfsadf008grk1CodeS3Keym8P82: string;
  /**
   * An Amazon S3 bucket in the same AWS Region as your function. The bucket can be in a different AWS account.
   */
  readonly lambdaFunction00asdfasdfsadf008grk1CodeS3Bucketzidw8: string;
}

書き込み専用プロパティ値をすべて解決したら、デプロイの準備が整います。

migrate.json ファイル

は、移行中に AWS CDK プロジェクトに migrate.json ファイル AWS CDK CLIを作成します。このファイルには、デプロイされたリソースに関するリファレンス情報が含まれています。CDK アプリケーションを初めてデプロイすると、 AWS CDK CLI はこのファイルを使用してデプロイされたリソースを参照し、リソースを新しい AWS CloudFormation スタックに関連付けて、ファイルを削除します。

CDK アプリケーションの管理とデプロイ

に移行する場合 AWS CDK、新しい CDK アプリはすぐにデプロイできない場合があります。このトピックでは、新しい CDK アプリケーションの管理とデプロイ時に考慮すべきアクション項目について説明します。

デプロイの準備

デプロイする前に、CDK アプリを準備する必要があります。

アプリを合成する

cdk synth コマンドを使用して、CDK アプリケーションのスタックを テンプレートに AWS CloudFormation 合成します。

デプロイされた AWS CloudFormation スタックまたはテンプレートから移行した場合は、合成されたテンプレートと移行されたテンプレートを比較して、リソースとプロパティの値を確認できます。

cdk synth の詳細については、「スタックの合成」を参照してください。

差分を実行する

デプロイされた AWS CloudFormation スタックから移行した場合は、cdk diff コマンドを使用して、新しい CDK アプリケーションのスタックと比較できます。

cdk 差分の詳細については、「」を参照してくださいスタックの比較。

環境のブートストラップ

AWS 環境から初めてデプロイする場合は、 cdk bootstrapを使用して環境を準備します。詳細については、「ブートストラッピング」を参照してください。

CDK アプリをデプロイする

CDK アプリケーションをデプロイすると、 AWS CDK CLIは AWS CloudFormation サービスを利用してリソースをプロビジョニングします。リソースは CDK アプリの 1 つのスタックにバンドルされ、1 つの AWS CloudFormation スタックとしてデプロイされます。

移行元に応じて、 をデプロイして新しい AWS CloudFormation スタックを作成するか、既存の AWS CloudFormation スタックを更新できます。

デプロイして新しい AWS CloudFormation スタックを作成する

デプロイされたリソースから移行した場合、 AWS CDK CLIはデプロイ時に新しい AWS CloudFormation スタックを自動的に作成します。デプロイされたリソースは新しい AWS CloudFormation スタックに含まれます。

一度もデプロイされなかったローカル AWS CloudFormation テンプレートから移行した場合、 AWS CDK CLIはデプロイ時に新しい AWS CloudFormation スタックを自動的に作成します。

以前にデプロイされたデプロイ済み AWS CloudFormation スタックまたはローカル AWS CloudFormation テンプレートから移行した場合は、 をデプロイして新しい AWS CloudFormation スタックを作成できます。新しいスタックを作成するには、次の手順を実行します。

  • 新しい AWS 環境にデプロイします。これは、別の AWS アカウントを使用するか、別の にデプロイすることで構成されます AWS リージョン。

  • 移行したスタックまたはテンプレートと同じ AWS 環境に新しいスタックをデプロイする場合は、CDK アプリのスタック名を新しい値に変更する必要があります。また、CDK アプリでリソースのすべての論理 IDsを変更する必要があります。その後、同じ環境にデプロイして、新しいスタックと新しいリソースを作成できます。

デプロイして既存の AWS CloudFormation スタックを更新する

以前にデプロイされたデプロイ済み AWS CloudFormation スタックまたはローカル AWS CloudFormation テンプレートから移行した場合は、 をデプロイして既存の AWS CloudFormation スタックを更新できます。

CDK アプリのスタック名がデプロイされたスタックの AWS CloudFormation スタック名と一致していることを検証し、同じ AWS 環境にデプロイします。