重大な成功要件

移行の出力は以下をすべて満たす必要があります:

1. リソースカバレッジの完全性

   • CDK によって合成されたすべての CloudFormation リソースは:
     • Pulumi プログラムで表現される または
     • 最終レポートで明確に正当化される必要があります。

2. デプロイの成功

   • 生成された Pulumi プログラムは構造的に妥当で、pulumi up が正常に実行できる能力を備えている必要があります (適切な設定と仮定)。

3. 最終移行レポート

   • 常に Pull Request に適した正式な移行レポートを出力します。
   • 以下を含めます:
     • CDK → Pulumi リソースマッピング
     • プロバイダーの選択 (aws-native vs aws)
     • 動作の違い
     • 不足していることまたは手動で必要な手順
     • 検証手順

情報が不足している場合

ユーザーが提供する CDK プロジェクトが不完全、曖昧、または成果物 (cdk.out など) が不足している場合は、Pulumi コードを生成する前に ターゲット化された質問 をしてください。

移行ワークフロー

このワークフローを 正確にこの順で 従ってください:

1. 情報収集

1.1 AWS 認証を確認 (ESC)

AWS コマンド (例: aws cloudformation list-stack-resources) と CDK コマンド (例: cdk synth) を実行するには、Pulumi ESC を通じて読み込まれた認証情報が必要です。

• ユーザーが既に ESC 環境を提供している場合は、それを使用します。
• ESC 環境が指定されていない場合は、AWS コマンドに進む前に ユーザーに使用する ESC 環境を確認 してください。

AWS リージョンをユーザーに確認する 必須 です。cdk synth の結果は間違った AWS リージョンで実行されると不正になる可能性があります。

1.2 CDK を合成

実行/検査:

npx cdk synth --quiet

• synth は常に --quiet で実行してテンプレートが stdout に出力されないようにしてください。

失敗する場合は、cdk.json または package.json でカスタム synth 動作を検査してください。

1.3 CDK スタックと環境を特定

cdk.out/manifest.json を読みます:

jq '.artifacts | to_entries | map(select(.value.type == "aws:cloudformation:stack") | {displayName: .key, environment: .value.environment}) | .[]' cdk.out/manifest.json

出力例:

{
  "displayName": "DataStack-dev",
  "environment": "aws://616138583583/us-east-2"
}
{
  "displayName": "AppStack-dev",
  "environment": "aws://616138583583/us-east-2"
}

作成する Pulumi スタックでは aws:region と aws-native:region の両方の設定変数を設定する 必須 です。例えば:

pulumi config set aws-native:region us-east-2 --stack dev
pulumi config set aws:region us-east-2 --stack dev

1.4 リソースインベントリを構築

各スタックに対して:

aws cloudformation list-stack-resources \
  --region <region> \
  --stack-name <stack> \
  --output json

1.5 CDK 構造を分析

抽出:

• 環境固有の条件
• スタック依存関係とクロススタック参照
• ランタイム設定 (context/環境変数)
• コンストラクトタイプ (L1, L2, L3)

2. コード変換 (CDK → PULUMI)

• cdk2pulumi ツールを使用して初期変換を実行します。cdk-convert.md に従って変換を実行してください。
• 変換レポートを読み、任意のギャップを埋めます。例えば、変換がリソースの変換に失敗した場合は、自分でそれを手動で変換する必要があります。

2.1 カスタムリソース処理

CDK は CloudFormation で利用できない機能に対して Lambda ベースのカスタムリソースを使用します。合成された CloudFormation では、これらは以下として表示されます:

• リソースタイプ: AWS::CloudFormation::CustomResource または Custom::<name>
• メタデータには aws:cdk:path が含まれ、ハンドラー名があります (例: aws-s3/auto-delete-objects-handler)

デフォルト動作: cdk2pulumi はカスタムリソースを aws-native:cloudformation:CustomResourceEmulator に書き直します。これは元の Lambda を呼び出します。これは機能しますがトレードオフがあります (Lambda 依存、コールドスタート、結果整合性)。

ハンドラータイプ別の移行戦略:

ハンドラー	戦略
aws-certificatemanager/dns-validated-certificate-handler	aws.acm.Certificate、aws.route53.Record、aws.acm.CertificateValidation に置き換える
aws-ec2/restrict-default-security-group-handler	aws.ec2.DefaultSecurityGroup リソースを空の ingress/egress ルールに置き換える
aws-ecr/auto-delete-images-handler	aws-native:ecr:Repository を aws.ecr.Repository に forceDelete: true で置き換える
aws-s3/auto-delete-objects-handler	aws-native:s3:Bucket を aws.s3.Bucket に forceDestroy: true で置き換える
aws-s3/notifications-resource-handler	aws.s3.BucketNotification に置き換える
aws-logs/log-retention-handler	aws.cloudwatch.LogGroup に明示的な retentionInDays で置き換える
aws-iam/oidc-handler	aws.iam.OpenIdConnectProvider に置き換える
aws-route53/delete-existing-record-set-handler	aws.route53.Record を allowOverwrite: true で置き換える
aws-dynamodb/replica-handler	aws.dynamodb.TableReplica に置き換える

クロスアカウント/リージョンハンドラー:

• aws-cloudfront/edge-function → region: "us-east-1" で aws.lambda.Function を使用
• aws-route53/cross-account-zone-delegation-handler → クロスアカウントロール前提条件を使用する別の aws プロバイダーを使用

不明なハンドラーの段階的な低下:

1. CustomResourceEmulator を保持 (デフォルト動作)
2. 移行レポートのカスタムリソースを以下と共に記録:
   • 元のハンドラー名と目的 (CDK パスから判断可能な場合)
   • ランタイムで Lambda 呼び出しを使用することに注意
   • ネイティブ置き換えの可能性をユーザーがレビューすることを推奨

2.2 プロバイダー戦略

• デフォルト: リソースタイプが利用可能な場合は常に aws-native を使用します。
• フォールバック: aws-native が同等の機能をサポートしない場合は aws を使用します。

2.3 アセットとバンドル

CDK はアセットとバンドルを使用してデプロイメントアーティファクトを処理します。これらは CloudFormation デプロイの前に CDK CLI によって処理され、*.assets.json メタデータファイルと一緒に cdk.out ディレクトリに表示されます。CloudFormation テンプレートには、アセットの場所へのハードコードされた参照が含まれます (S3 バケット/キーまたは ECR リポジトリ/タグ)。

# アセット定義を検査
jq '.files, .dockerImages' cdk.out/*.assets.json

アセットタイプ別の移行戦略:

アセットタイプ	検出	Pulumi 移行
Docker イメージ	assets.json の dockerImages	docker-build.Image を使用してビルドとプッシュを実行。ハードコードされた ECR URI をイメージ出力に置き換える。
ビルドコマンド付きファイル	files に executable フィールド	ユーザーにフラグ - ビルドコマンドは Pulumi でセットアップが必要
静的ファイル	files に executable なし、CDK ソースでバンドルなし	pulumi.FileArchive または pulumi.FileAsset を使用
バンドルされたファイル	files に executable なし、CDK ソースでバンドル使用あり	ユーザーにフラグ - バンドルは Pulumi でセットアップが必要

CDK ソースでのバンドル検出:

CDK ソースコードでバンドルコンストラクト (NodejsFunction、PythonFunction、GoFunction、またはバンドル オプションを使用するリソース) をチェックします。バンドルが使用されている場合、ビルドステップは継続的な開発のために Pulumi で複製する必要があります - そうでなければ、ソース変更には cdk synth の手動再実行が必要になるでしょう。

バンドルが検出された場合、ユーザーに通知:

ビルドステップ検出: この CDK アプリケーションは <BUNDLING_TYPE> を使用しており、これは synth 時にデプロイ可能なアーティファクトを構築します。このビルドステップは継続的な開発のために Pulumi で複製される必要があります。

オプション:

1. CI/CD パイプライン (推奨): ビルドステップを CI パイプラインに移動し、Pulumi で事前構築アーティファクトを参照
2. Pulumi Command プロバイダー: command.local.Command を使用して pulumi up 中にビルドコマンドを実行
3. 事前ビルドスクリプト: pulumi up の前に実行し、既知の場所に出力するビルドスクリプトを作成

各オプションはキャッシング、再現性、デプロイ速度についてトレードオフがあります。本番ワークロードの場合、通常オプション 1 が推奨されます。

2.4 aws-native 用 TypeScript 処理

aws-native 出力には undefined が含まれることがよくあります。! 非 null アサーションを避けてください。常に .apply() で安全にアンラップします:

// ❌ 間違い - TypeScript エラーが発生します
functionName: lambdaFunction.functionName!,

// ✅ 正しい - undefined を安全に処理
functionName: lambdaFunction.functionName.apply(name => name || ""),

2.5 環境ロジック保持

すべての条件付き動作を持ち越します:

if (currentEnv.createVpc) {
  // リソースを作成
} else {
  const vpcId = pulumi.output(currentEnv.vpcId);
}

3. リソースインポート (オプション)

変換後、既存のリソースを Pulumi で管理されるようにオプションでインポートできます。ユーザーがこれをリクエストしない場合は、これを変換の次のステップとして提案する必要があります。

• 常に cdk-importer ツールを使用した自動インポートで開始します。cdk-importer.md に従って自動インポートを実行してください。
• 自動ツールでインポートに失敗したリソースについては、手動でインポートします。

リソースを手動でインポートする必要がある場合:

• cloudformation-id-lookup.md に従って CloudFormation インポート識別子を検索します。

• Web フェッチツールを使用して公式 Pulumi ドキュメントからコンテンツを取得します。

• AWS インポート ID を検索 -> https://www.pulumi.com/docs/iac/guides/migration/aws-import-ids/

• 手動移行アプローチ -> https://www.pulumi.com/docs/iac/guides/migration/migrating-to-pulumi/migrating-from-cdk/migrating-existing-cdk-app/#approach-b-manual-migration

3.1 インポート後のプレビュー実行

インポート後、pulumi preview を実行して変更がないことを確認する必要があります。変更がないことは:

• アップデートなし
• 置き換えなし
• 作成なし
• 削除なし

変更がある場合は、変更がなくなるまでプログラムを調査および更新する必要があります。

ユーザーとの作業

ユーザーが CDK から Pulumi への移行の計画または実行についてサポートをリクエストする場合は、上記の情報を使用して自動化された移行アプローチに向かうようにユーザーをガイドしてください。

詳細なドキュメント

ユーザーが推奨パスから逸脱したいと言う場合は、web フェッチツールを使用して公式 Pulumi ドキュメントからコンテンツを取得してください -> https://www.pulumi.com/docs/iac/guides/migration/migrating-to-pulumi/migrating-from-cdk/migrating-existing-cdk-app

このドキュメントはトピックをカバーしています:

• 移行戦略
  • 変換対リライト
  • インポート対リハイドレート
  • ベストプラクティス
• 複数の CDK スタックの処理
• CDK ステージの処理
• コード構成
• CDK コンストラクトの変換
• 実行戦略
  • 自動化移行 (推奨)
  • 手動移行

出力形式 (必須)

移行を実行する場合は、常に以下を生成してください:

1. 概要 (高レベルの説明)
2. 移行計画概要
3. Pulumi コード出力 (TypeScript; ファイルごとに構造化)
4. リソースマッピング表 (CDK → Pulumi)
5. カスタムリソース概要 (ある場合):
   • ネイティブ Pulumi リソースに移行されたハンドラー
   • CustomResourceEmulator として保持されたハンドラーと理由
   • ユーザー注意が必要なハンドラー
6. アセットとバンドル概要 (ある場合):
   • 移行: 正常に変換されたアセット (例: Docker イメージ → docker-build.Image、静的ファイル → pulumi.FileArchive)
   • 注意が必要: バンドルステップを使用したアセット、提示されたオプション、決定が行われた場合
7. 最終移行レポート (PR 対応)
8. 次のステップ (オプションのリファクタリング)

コードを構文的に有効で、ファイルごとに明確に分離した状態に保ってください。