既存のリソースと AWS CloudFormation テンプレートを AWS CDK に移行する - AWS クラウド開発キット (AWS CDK) v2
移行の仕組みCDK 移行の利点考慮事項前提条件CDK Migrate の使用を開始する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 スタック、および local AWS CloudFormation テンプレートを AWS CDK に移行します。

移行の仕組み

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

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

  • Deployed AWS CloudFormation スタック。

  • Local AWS CloudFormation テンプレート。

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

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

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

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

Deployed AWS CloudFormation スタック

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

Local AWS CloudFormation テンプレート

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

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

CDK 移行の利点

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

考慮事項

一般的な考慮事項

CDK 移行と CDK インポート

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

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

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

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

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

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

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

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

アセットの移行

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

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

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

ステートフルリソースを移行して保持するには、以下を実行します。

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

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

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

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

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

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

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

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

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

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

スキャンの制限

環境のリソースをスキャンする場合、IaC ジェネレーターには、スキャン時に取得できるデータおよびクォータの制限に特定の制限があります。詳細については、 AWS CloudFormation ユーザーガイド」の「考慮事項」を参照してください。

前提条件

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

CDK Migrate の使用を開始する

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

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

以下は、指定が必要となる重要なオプションです。

スタック名

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

[言語]

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

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

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

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

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

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

移行ソース

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

  • --from-path – local 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 スタックの更新として識別します。一致する論理 ID を持つリソースが更新されます。デプロイの詳細については、「CDK アプリの管理とデプロイ」を参照してください。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

フィルターを使用する

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

IaC ジェネレーターを使用したリソースのスキャン

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

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

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

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

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

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

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

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

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

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

移行後、新しい CDK アプリで書き込み専用プロパティ値を指定する必要があります。 AWS CDK CLI は、CDK プロジェクトの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 CLI は、移行中に AWS CDK プロジェクトにmigrate.jsonファイルを作成します。このファイルには、デプロイされたリソースのリファレンス情報が含まれています。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 を使用して環境を準備します。詳細については、AWS 「CDK ブートストラップ」を参照してください。

CDK アプリをデプロイする

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

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

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

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

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

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

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

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

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

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

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