pulumi-cdk-to-pulumi
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseCRITICAL SUCCESS REQUIREMENTS
关键成功要求
The migration output MUST meet all of the following:
-
Complete Resource Coverage
- Every CloudFormation resource synthesized by CDK MUST:
- Be represented in the Pulumi program OR
- Be explicitly justified in the final report.
- Every CloudFormation resource synthesized by CDK MUST:
-
Successful Deployment
- The produced Pulumi program must be structurally valid and capable of a successful (assuming proper config).
pulumi up
- The produced Pulumi program must be structurally valid and capable of a successful
-
Final Migration Report
- Always output a formal migration report suitable for a Pull Request.
- Include:
- CDK → Pulumi resource mapping
- Provider decisions (aws-native vs aws)
- Behavioral differences
- Missing or manually required steps
- Validation instructions
迁移输出必须满足以下所有条件:
-
完整资源覆盖
- CDK合成的每个CloudFormation资源必须:
- 在Pulumi程序中得到体现 或者
- 在最终报告中给出明确的理由说明。
- CDK合成的每个CloudFormation资源必须:
-
部署成功
- 生成的Pulumi程序必须结构有效,并且能够成功执行(假设配置正确)。
pulumi up
- 生成的Pulumi程序必须结构有效,并且能够成功执行
-
最终迁移报告
- 始终输出一份适合用于Pull Request的正式迁移报告。
- 报告需包含:
- CDK → Pulumi资源映射表
- 提供商决策(aws-native vs aws)
- 行为差异
- 缺失或需要手动执行的步骤
- 验证说明
WHEN INFORMATION IS MISSING
当信息缺失时
If a user-provided CDK project is incomplete, ambiguous, or missing artifacts (such as ), ask targeted questions before generating Pulumi code.
cdk.out如果用户提供的CDK项目不完整、模糊或缺少构件(如),在生成Pulumi代码之前,要提出针对性问题。
cdk.outMIGRATION WORKFLOW
迁移工作流
Follow this workflow exactly and in this order:
严格按照以下顺序执行此工作流:
1. INFORMATION GATHERING
1. 信息收集
1.1 Verify AWS Credentials (ESC)
1.1 验证AWS凭证(ESC)
Running AWS commands (e.g., ) and CDK commands (e.g. ) requires credentials loaded via Pulumi ESC.
aws cloudformation list-stack-resourcescdk synth- If the user has already provided an ESC environment, use it.
- If no ESC environment is specified, ask the user which ESC environment to use before proceeding with AWS commands.
You MUST confirm the AWS region with the user. The results may be incorrect if ran with the wrong AWS Region.
cdk synth运行AWS命令(如)和CDK命令(如)需要通过Pulumi ESC加载凭证。
aws cloudformation list-stack-resourcescdk synth- 如果用户已提供ESC环境,请使用该环境。
- 如果未指定ESC环境,在执行AWS命令之前,询问用户要使用哪个ESC环境。
必须与用户确认AWS区域。如果使用错误的AWS Region运行,结果可能不正确。
cdk synth1.2 Synthesize CDK
1.2 合成CDK
Run/inspect:
bash
npx cdk synth --quiet- ALWAYS run with
synthto prevent the template from being output on stdout.--quiet
If failing, inspect or for custom synth behavior.
cdk.jsonpackage.json运行/检查:
bash
npx cdk synth --quiet- 始终使用参数运行
--quiet,以防止模板输出到标准输出。synth
如果执行失败,检查或中的自定义合成行为。
cdk.jsonpackage.json1.3 Identify CDK Stacks & Environments
1.3 识别CDK栈与环境
Read :
cdk.out/manifest.jsonbash
jq '.artifacts | to_entries | map(select(.value.type == "aws:cloudformation:stack") | {displayName: .key, environment: .value.environment}) | .[]' cdk.out/manifest.jsonExample output:
json
{
"displayName": "DataStack-dev",
"environment": "aws://616138583583/us-east-2"
}
{
"displayName": "AppStack-dev",
"environment": "aws://616138583583/us-east-2"
}In the Pulumi stack you create you MUST set both the and config variables. For example:
aws:regionaws-native:regionbash
pulumi config set aws-native:region us-east-2 --stack dev
pulumi config set aws:region us-east-2 --stack dev读取:
cdk.out/manifest.jsonbash
jq '.artifacts | to_entries | map(select(.value.type == "aws:cloudformation:stack") | {displayName: .key, environment: .value.environment}) | .[]' cdk.out/manifest.json示例输出:
json
{
"displayName": "DataStack-dev",
"environment": "aws://616138583583/us-east-2"
}
{
"displayName": "AppStack-dev",
"environment": "aws://616138583583/us-east-2"
}在创建的Pulumi栈中,必须设置和配置变量。例如:
aws:regionaws-native:regionbash
pulumi config set aws-native:region us-east-2 --stack dev
pulumi config set aws:region us-east-2 --stack dev1.4 Build Resource Inventory
1.4 构建资源清单
For each stack:
bash
aws cloudformation list-stack-resources \
--region <region> \
--stack-name <stack> \
--output json针对每个栈:
bash
aws cloudformation list-stack-resources \
--region <region> \
--stack-name <stack> \
--output json1.5 Analyze CDK Structure
1.5 分析CDK结构
Extract:
- Environment-specific conditionals
- Stack dependencies & cross-stack references
- Runtime config (context/env vars)
- Construct types (L1, L2, L3)
提取:
- 环境相关的条件语句
- 栈依赖与跨栈引用
- 运行时配置(上下文/环境变量)
- 构造类型(L1、L2、L3)
2. CODE CONVERSION (CDK → PULUMI)
2. 代码转换(CDK → PULUMI)
- Perform the initial conversion using the tool. Follow cdk-convert.md to perform the conversion.
cdk2pulumi - Read the conversion report and fill in any gaps. For example, if the conversion fails to convert a resource you have to convert it manually yourself.
- 使用工具执行初始转换。遵循cdk-convert.md进行转换。
cdk2pulumi - 阅读转换报告并填补任何空白。例如,如果转换工具未能转换某个资源,你需要手动转换它。
2.1 Custom Resources Handling
2.1 自定义资源处理
CDK uses Lambda-backed Custom Resources for functionality not available in CloudFormation. In synthesized CloudFormation, these appear as:
- Resource type: or
AWS::CloudFormation::CustomResourceCustom::<name> - Metadata contains with the handler name (e.g.,
aws:cdk:path)aws-s3/auto-delete-objects-handler
Default behavior: rewrites custom resources to , which invokes the original Lambda. This works but has tradeoffs (Lambda dependency, cold starts, eventual consistency).
cdk2pulumiaws-native:cloudformation:CustomResourceEmulatorMigration strategies by handler type:
| Handler | Strategy |
|---|---|
| Replace with |
| Replace with |
| Replace |
| Replace |
| Replace with |
| Replace with |
| Replace with |
| Replace with |
| Replace with |
Cross-account/region handlers:
- → Use
aws-cloudfront/edge-functionwithaws.lambda.Functionregion: "us-east-1" - → Use separate aws provider with cross-account role assumption
aws-route53/cross-account-zone-delegation-handler
Graceful degradation for unknown handlers:
- Keep the (default behavior)
CustomResourceEmulator - Document the custom resource in the migration report with:
- Original handler name and purpose (if discernible from CDK path)
- Note that it uses Lambda invocation at runtime
- Recommend user review for potential native replacement
CDK使用Lambda支持的自定义资源来处理CloudFormation中未提供的功能。在合成的CloudFormation中,这些资源表现为:
- 资源类型:或
AWS::CloudFormation::CustomResourceCustom::<name> - 元数据包含字段,其中包含处理程序名称(如
aws:cdk:path)aws-s3/auto-delete-objects-handler
默认行为:会将自定义资源重写为,它会调用原始Lambda。这种方式可行,但存在一些权衡(Lambda依赖、冷启动、最终一致性)。
cdk2pulumiaws-native:cloudformation:CustomResourceEmulator按处理程序类型划分的迁移策略:
| 处理程序 | 策略 |
|---|---|
| 替换为 |
| 替换为具有空入站/出站规则的 |
| 将 |
| 将 |
| 替换为 |
| 替换为设置了显式 |
| 替换为 |
| 替换为设置了 |
| 替换为 |
跨账户/区域处理程序:
- → 使用设置了
aws-cloudfront/edge-function的region: "us-east-1"aws.lambda.Function - → 使用带有跨账户角色假设的独立aws提供商
aws-route53/cross-account-zone-delegation-handler
未知处理程序的降级策略:
- 保留(默认行为)
CustomResourceEmulator - 在迁移报告中记录该自定义资源:
- 原始处理程序名称和用途(如果可从CDK路径推断)
- 注意它在运行时会调用Lambda
- 建议用户检查是否有原生替代方案
2.2 Provider Strategy
2.2 提供商策略
- Default: Use whenever the resource type is available.
aws-native - Fallback: Use when aws-native does not support equivalent features.
aws
- 默认:只要资源类型可用,就使用。
aws-native - 回退:当aws-native不支持等效功能时,使用。
aws
2.3 Assets & Bundling
2.3 资产与打包
CDK uses Assets and Bundling to handle deployment artifacts. These are processed by the CDK CLI before CloudFormation deployment and appear in the directory alongside metadata files. CloudFormation templates contain hard-coded references to asset locations (S3 bucket/key or ECR repo/tag).
cdk.out*.assets.jsonbash
undefinedCDK使用Assets和Bundling来处理部署构件。这些构件在CloudFormation部署前由CDK CLI处理,并与元数据文件一起出现在目录中。CloudFormation模板包含对资产位置的硬编码引用(S3存储桶/键或ECR仓库/标签)。
*.assets.jsoncdk.outbash
undefinedInspect asset definitions
检查资产定义
jq '.files, .dockerImages' cdk.out/*.assets.json
**Migration strategies by asset type:**
| Asset Type | Detection | Pulumi Migration |
|------------|-----------|------------------|
| **Docker Image** | `dockerImages` in assets.json | Use `docker-build.Image` to build and push. Replace hard-coded ECR URI with image output. |
| **File with build command** | `files` with `executable` field | **Flag to user** - build command needs setup in Pulumi |
| **Static file** | `files` without `executable`, no bundling in CDK source | Use `pulumi.FileArchive` or `pulumi.FileAsset` |
| **Bundled file** | `files` without `executable`, but CDK source uses bundling | **Flag to user** - bundling needs setup in Pulumi |
**Detecting Bundling in CDK Source:**
Check the CDK source code for bundling constructs (`NodejsFunction`, `PythonFunction`, `GoFunction`, or resources using the `bundling` option). If bundling is used, the build step needs to be replicated in Pulumi for ongoing development - otherwise source changes would require manually re-running `cdk synth`.
**When bundling is detected, inform the user:**
> **Build Step Detected**: This CDK application uses <BUNDLING_TYPE> which builds deployable artifacts during synthesis. This build step needs to be replicated in Pulumi for ongoing development.
>
> **Options:**
>
> 1. **CI/CD Pipeline** (Recommended): Move the build step to your CI pipeline and reference the pre-built artifact in Pulumi
> 2. **Pulumi Command Provider**: Use `command.local.Command` to run the build command during `pulumi up`
> 3. **Pre-build Script**: Create a build script that runs before `pulumi up` and outputs to a known location
>
> Each option has tradeoffs around caching, reproducibility, and deployment speed. For production workloads, option 1 is typically preferred.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`或使用`bundling`选项的资源)。如果使用了打包,为了后续开发需要在Pulumi中复现构建步骤——否则源码变更需要手动重新运行`cdk synth`。
**检测到打包时,通知用户:**
> **检测到构建步骤**:此CDK应用使用<BUNDLING_TYPE>,在合成过程中构建可部署构件。为了后续开发,需要在Pulumi中复现此构建步骤。
>
> **选项:**
>
> 1. **CI/CD流水线**(推荐):将构建步骤移至CI流水线,并在Pulumi中引用预构建的构件
> 2. **Pulumi命令提供商**:使用`command.local.Command`在`pulumi up`期间运行构建命令
> 3. **预构建脚本**:创建一个在`pulumi up`之前运行的构建脚本,并输出到指定位置
>
> 每个选项在缓存、可重复性和部署速度方面各有权衡。对于生产工作负载,通常首选选项1。2.4 TypeScript Handling for aws-native
2.4 aws-native的TypeScript处理
aws-native outputs often include undefined. Avoid non-null assertions. Always safely unwrap with :
!.apply()ts
// ❌ WRONG - Will cause TypeScript errors
functionName: lambdaFunction.functionName!,
// ✅ CORRECT - Handle undefined safely
functionName: lambdaFunction.functionName.apply(name => name || ""),aws-native的输出通常包含undefined。避免使用非空断言,始终使用安全解包:
!.apply()ts
// ❌ 错误 - 会导致TypeScript错误
functionName: lambdaFunction.functionName!,
// ✅ 正确 - 安全处理undefined
functionName: lambdaFunction.functionName.apply(name => name || ""),2.5 Environment Logic Preservation
2.5 保留环境逻辑
Carry forward all conditional behaviors:
ts
if (currentEnv.createVpc) {
// create resources
} else {
const vpcId = pulumi.output(currentEnv.vpcId);
}保留所有条件行为:
ts
if (currentEnv.createVpc) {
// 创建资源
} else {
const vpcId = pulumi.output(currentEnv.vpcId);
}3. Resource Import (optional)
3. 资源导入(可选)
After conversion you can optionally import the existing resources to now be managed by Pulumi. If the user does not request this you should suggest this as a follow up step to conversion.
- Always start with automated import using the tool. Follow cdk-importer.md to perform the automated import.
cdk-importer - For any resources that fail to import with the automated tool, import them manually.
If you need to manually import resources:
-
Follow cloudformation-id-lookup.md to look up CloudFormation import identifiers.
-
Use the web-fetch tool to get content from the official Pulumi documentation.
-
Finding AWS import IDs -> https://www.pulumi.com/docs/iac/guides/migration/aws-import-ids/
转换完成后,可以选择将现有资源导入到Pulumi进行管理。如果用户未请求此操作,你应将其作为转换后的后续步骤建议。
- 始终先使用工具执行自动导入。遵循cdk-importer.md执行自动导入。
cdk-importer - 对于任何自动导入失败的资源,手动导入它们。
如果需要手动导入资源:
-
遵循cloudformation-id-lookup.md查找CloudFormation导入标识符。
-
使用web-fetch工具从Pulumi官方文档获取内容。
3.1 Running preview after import
3.1 导入后运行预览
After performing an import you need to run to ensure there are no changes. No changes means:
pulumi preview- NO updates
- NO replaces
- NO creates
- NO deletes
If there are changes you must investigate and update the program until there are no changes.
导入完成后,需要运行以确保没有变更。无变更意味着:
pulumi preview- 无更新
- 无替换
- 无创建
- 无删除
如果存在变更,必须调查并更新程序直到没有变更为止。
Working with the User
与用户协作
If the user asks for help planning or performing a CDK to Pulumi migration use the information above to guide the user towards the automated migration approach.
如果用户请求帮助规划或执行CDK到Pulumi的迁移,使用上述信息引导用户采用自动迁移方法。
For Detailed Documentation
详细文档参考
When the user wants to deviate from the recommended path detailed above, use the web-fetch tool to get content from the official Pulumi documentation -> https://www.pulumi.com/docs/iac/guides/migration/migrating-to-pulumi/migrating-from-cdk/migrating-existing-cdk-app
This documentation covers topics:
- Migration Strategy
- Convert vs. Rewrite
- Import vs. Rehydrate
- Best Practices
- Handling Multiple CDK Stacks
- Handling CDK Stages
- Code organization
- Converting CDK Constructs
- Execution Strategies
- Automated Migration (recommended)
- Manual Migration
当用户希望偏离上述推荐路径时,使用web-fetch工具从Pulumi官方文档获取内容 -> https://www.pulumi.com/docs/iac/guides/migration/migrating-to-pulumi/migrating-from-cdk/migrating-existing-cdk-app
该文档涵盖以下主题:
- 迁移策略
- 转换 vs 重写
- 导入 vs 重构
- 最佳实践
- 处理多个CDK栈
- 处理CDK阶段
- 代码组织
- 转换CDK构造
- 执行策略
- 自动迁移(推荐)
- 手动迁移
OUTPUT FORMAT (REQUIRED)
输出格式(必填)
When performing a migration, always produce:
- Overview (high-level description)
- Migration Plan Summary
- Pulumi Code Outputs (TypeScript; structured by file)
- Resource Mapping Table (CDK → Pulumi)
- Custom Resources Summary (if any):
- Handlers migrated to native Pulumi resources
- Handlers kept as with rationale
CustomResourceEmulator - Any handlers requiring user attention
- Assets & Bundling Summary (if any):
- Migrated: Assets successfully converted (e.g., Docker images → , static files →
docker-build.Image)pulumi.FileArchive - Requires attention: Assets with bundling steps, options presented, and decision if made
- Migrated: Assets successfully converted (e.g., Docker images →
- Final Migration Report (PR-ready)
- Next Steps (optional refactors)
Keep code syntactically valid and clearly separated by files.
执行迁移时,必须生成以下内容:
- 概述(高层描述)
- 迁移计划摘要
- Pulumi代码输出(TypeScript;按文件结构化)
- 资源映射表(CDK → Pulumi)
- 自定义资源摘要(如有):
- 已迁移为Pulumi原生资源的处理程序
- 保留为的处理程序及理由
CustomResourceEmulator - 任何需要用户注意的处理程序
- 资产与打包摘要(如有):
- 已迁移:成功转换的资产(如Docker镜像 → ,静态文件 →
docker-build.Image)pulumi.FileArchive - 需要注意:带有打包步骤的资产、提供的选项及已做出的决策
- 已迁移:成功转换的资产(如Docker镜像 →
- 最终迁移报告(适合PR)
- 后续步骤(可选重构)
保持代码语法有效,并按文件清晰分隔。