cloudformation-to-pulumi

重要: プラン調整が必要です

このスキルを読み込む前に既に移行プランを作成している場合は:

1. 既存のプランをこのスキルのワークフローと要件に対して見直してください
2. ギャップ、漏れたステップ、または不正確な仮定を特定してください
3. このスキルのガイダンスに合わせてプランを更新および修正してください
4. 進める前に調整されたプランをユーザーに伝えてください

重大な成功要件

移行の成果物は以下のすべてを満たす必要があります:

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

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

2. CloudFormation Logical ID をリソース名として使用

   • 重大: すべての Pulumi リソースは CloudFormation Logical ID をリソース名として使用する必要があります。
   • これにより、cdk-importer ツールが自動的にインポート ID を見つけることができます。
   • リソースの名前を変更しないでください。論理 ID を変更するとインポートが失敗します。

3. デプロイの成功

   • 生成された Pulumi プログラムは構造的に有効で、(適切な設定を前提として) 成功した pulumi preview が可能である必要があります。

4. ゼロデルタ インポート検証 (既存リソースをインポートする場合)

   • インポート後、pulumi preview は更新、置換、作成、または削除を表示してはいけません。

5. 最終的な移行レポート

   • 常に Pull Request に適した形式の移行レポートを出力してください。

情報が不足している場合

ユーザーが CloudFormation テンプレートを提供していない場合は、スタック名を使用して AWS から取得する必要があります。

移行ワークフロー

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

1. 情報収集

1.1 AWS 認証情報を確認する (ESC)

AWS コマンドを実行するには、Pulumi ESC を介して読み込まれた認証情報が必要です。

• ユーザーが既に ESC 環境を提供している場合は、それを使用してください。
• ESC 環境が指定されていない場合は、進める前にどの ESC 環境を使用するかをユーザーに尋ねてください。

詳細な ESC 情報については: スキル pulumi-esc を使用してください。

AWS リージョンをユーザーに確認する必要があります。

1.2 CloudFormation テンプレートを取得する

ユーザーがテンプレート ファイルを提供している場合: テンプレートを直接読みます。

ユーザーがスタック名のみを提供している場合: AWS からテンプレートを取得します:

aws cloudformation get-template \
  --region <region> \
  --stack-name <stack-name> \
  --query 'TemplateBody' \
  --output json > template.json

1.3 リソース インベントリを構築する

スタック内のすべてのリソースをリストアップします:

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

これにより以下が提供されます:

• LogicalResourceId - これを Pulumi リソース名として使用してください
• PhysicalResourceId - 実際の AWS リソース ID
• ResourceType - CloudFormation リソース タイプ

1.4 テンプレート構造を分析する

テンプレートから以下を抽出します:

• パラメータとそのデフォルト値
• マッピング
• 条件
• 出力
• リソースの依存関係 (Ref、GetAtt、DependsOn)

2. コード変換 (CloudFormation → Pulumi)

重要: CloudFormation の自動変換ツールはありません。各リソースを手動で変換する必要があります。

2.1 リソース名の規約 (重大)

すべての Pulumi リソースは CloudFormation Logical ID を名前として使用する必要があります。

// CloudFormation:
// "MyAppBucketABC123": { "Type": "AWS::S3::Bucket", ... }

// Pulumi - 正しい方法:
const myAppBucket = new aws.s3.Bucket("MyAppBucketABC123", { ... });

// Pulumi - 間違った方法 (これをしないでください - インポートが失敗します):
const myAppBucket = new aws.s3.Bucket("my-app-bucket", { ... });

この名前付け規約は、cdk-importer ツールが名前でリソースをマッチングするため、必須です。

2.2 プロバイダー戦略

⚠️ 重大: デフォルトでは常に aws-native を使用してください ⚠️

• 特に理由がない限り、すべてのリソースに aws-native を使用してください。
• CloudFormation タイプは aws-native に直接マップされます (例: AWS::S3::Bucket → aws-native.s3.Bucket)。
• aws-native が必要な機能をサポートしていない場合にのみ、aws (クラシック) を使用してください。

これは cdk-importer でのインポートの成功に必須です。 cdk-importer は CloudFormation リソースを Pulumi リソースにマッチングすることで動作し、CloudFormation は aws-native に 1:1 でマップされます。クラシック aws プロバイダーを使用するとインポート失敗の原因になります。

2.3 CloudFormation 組み込み関数

CloudFormation 組み込み関数を Pulumi の同等のものにマップします:

CloudFormation	Pulumi の同等のもの
!Ref (リソース)	リソース出力 (例: bucket.id)
!Ref (パラメータ)	Pulumi config
!GetAtt Resource.Attr	リソース プロパティ出力
!Sub "..."	pulumi.interpolate
!Join [delim, [...]]	pulumi.interpolate または .apply()
!If [cond, true, false]	三項演算子
!Equals [a, b]	=== 比較
!Select [idx, list]	.apply() を使用した配列のインデックス付け
!Split [delim, str]	.apply(v => v.split(...))
Fn::ImportValue	スタック参照またはconfig

例: !Sub

// CloudFormation: !Sub "arn:aws:s3:::${MyBucket}/*"
// Pulumi:
const bucketArn = pulumi.interpolate`arn:aws:s3:::${myBucket.bucket}/*`;

例: !GetAtt

// CloudFormation: !GetAtt MyFunction.Arn
// Pulumi:
const functionArn = myFunction.arn;

2.4 CloudFormation 条件

CloudFormation 条件を TypeScript ロジックに変換します:

// CloudFormation:
// "Conditions": {
//   "CreateProdResources": { "Fn::Equals": [{ "Ref": "Environment" }, "prod"] }
// }

// Pulumi:
const config = new pulumi.Config();
const environment = config.require("environment");
const createProdResources = environment === "prod";

if (createProdResources) {
  // 本番環境のみのリソースを作成
}

2.5 CloudFormation パラメータ

パラメータを Pulumi config に変換します:

// CloudFormation:
// "Parameters": {
//   "InstanceType": { "Type": "String", "Default": "t3.micro" }
// }

// Pulumi:
const config = new pulumi.Config();
const instanceType = config.get("instanceType") || "t3.micro";

2.6 CloudFormation マッピング

マッピングを TypeScript オブジェクトに変換します:

// CloudFormation:
// "Mappings": {
//   "RegionMap": {
//     "us-east-1": { "AMI": "ami-12345" },
//     "us-west-2": { "AMI": "ami-67890" }
//   }
// }

// Pulumi:
const regionMap: Record<string, { ami: string }> = {
  "us-east-1": { ami: "ami-12345" },
  "us-west-2": { ami: "ami-67890" },
};
const ami = regionMap[aws.config.region!].ami;

2.7 カスタム リソース

CloudFormation カスタム リソース (AWS::CloudFormation::CustomResource または Custom::*) には特別な処理が必要です:

1. 目的を特定する: Lambda 関数コードを読んでその動作を理解する
2. ネイティブ置換を探す: Pulumi に同じ機能を提供するネイティブ リソースがあるかどうかを確認する
3. 置換がない場合: 移行レポートで手動実装が必要であることを記録する

2.8 TypeScript 出力処理

aws-native の出力には未定義が含まれることがあります。! null でない assert を避けてください。常に .apply() で安全にアンラップしてください:

// 間違った方法
functionName: lambdaFunction.functionName!,

// 正しい方法
functionName: lambdaFunction.functionName.apply(name => name || ""),

3. リソース インポート

変換後、Pulumi で管理するために既存リソースをインポートします。

3.0 インポート前検証 (必須)

インポートを進める前に、コードを検証してください:

1. プロバイダー使用を確認する: コードをスキャンして、すべてのリソースが aws-native を使用していることを確認する
2. 例外を記録する: aws (クラシック) プロバイダーの使用は正当化される必要があります
3. リソース名を確認する: すべてのリソースが CloudFormation Logical ID を名前として使用していることを確認する

3.1 cdk-importer でのインポートの自動化

CloudFormation Logical ID をリソース名として使用しているため、cdk-importer ツールを使用してリソースを自動的にインポートできます。

詳細なインポート手順については、cfn-importer.md に従ってください。

3.2 失敗したリソースの手動インポート

自動インポートに失敗したリソースの場合:

1. cloudformation-id-lookup.md に従ってインポート ID 形式を見つけます
2. pulumi import を使用します:

pulumi import <pulumi-resource-type> <logical-id> <import-id>

3.3 インポート後のプレビューを実行する

インポート後、pulumi preview を実行してください。以下のようなものはないはずです:

• 更新
• 置換
• 作成
• 削除

変更がある場合は、調査してプログラムを更新し、プレビューが完全になるまで修正します。

出力形式 (必須)

移行を実行するときは、常に以下を生成します:

1. 概要 (高レベルの説明)
2. 移行プランの概要
3. Pulumi コード出力 (TypeScript; ファイル別に編成)
4. リソース マッピング テーブル:

CloudFormation Logical ID	CFN タイプ	Pulumi タイプ	プロバイダー
MyAppBucketABC123	AWS::S3::Bucket	aws-native.s3.Bucket	aws-native
MyLambdaFunction456	AWS::Lambda::Function	aws-native.lambda.Function	aws-native

5. カスタム リソースの概要 (存在する場合)
6. 最終的な移行レポート (PR 対応)
7. 次のステップ (インポート手順)

詳細なドキュメントについては

公式 Pulumi ドキュメントからコンテンツを取得します:

• https://www.pulumi.com/docs/iac/adopting-pulumi/migrating-to-pulumi/from-aws/