pulumi-cdk-to-pulumi

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CRITICAL SUCCESS REQUIREMENTS

关键成功要求

The migration output MUST meet all of the following:
  1. Complete Resource Coverage
    • Every CloudFormation resource synthesized by CDK MUST:
      • Be represented in the Pulumi program OR
      • Be explicitly justified in the final report.
  2. Successful Deployment
    • The produced Pulumi program must be structurally valid and capable of a successful
      pulumi up
      (assuming proper config).
  3. 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
迁移输出必须满足以下所有条件:
  1. 完整资源覆盖
    • CDK合成的每个CloudFormation资源必须:
      • 在Pulumi程序中得到体现 或者
      • 在最终报告中给出明确的理由说明。
  2. 部署成功
    • 生成的Pulumi程序必须结构有效,并且能够成功执行
      pulumi up
      (假设配置正确)。
  3. 最终迁移报告
    • 始终输出一份适合用于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
cdk.out
), ask targeted questions before generating Pulumi code.
如果用户提供的CDK项目不完整、模糊或缺少构件(如
cdk.out
),在生成Pulumi代码之前,要提出针对性问题

MIGRATION 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.,
aws cloudformation list-stack-resources
) and CDK commands (e.g.
cdk synth
) requires credentials loaded via Pulumi ESC.
  • 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
cdk synth
results may be incorrect if ran with the wrong AWS Region.
运行AWS命令(如
aws cloudformation list-stack-resources
)和CDK命令(如
cdk synth
)需要通过Pulumi ESC加载凭证。
  • 如果用户已提供ESC环境,请使用该环境。
  • 如果未指定ESC环境,在执行AWS命令之前,询问用户要使用哪个ESC环境
必须与用户确认AWS区域。如果使用错误的AWS Region运行
cdk synth
,结果可能不正确。

1.2 Synthesize CDK

1.2 合成CDK

Run/inspect:
bash
npx cdk synth --quiet
  • ALWAYS run
    synth
    with
    --quiet
    to prevent the template from being output on stdout.
If failing, inspect
cdk.json
or
package.json
for custom synth behavior.
运行/检查:
bash
npx cdk synth --quiet
  • 始终使用
    --quiet
    参数运行
    synth
    ,以防止模板输出到标准输出。
如果执行失败,检查
cdk.json
package.json
中的自定义合成行为。

1.3 Identify CDK Stacks & Environments

1.3 识别CDK栈与环境

Read
cdk.out/manifest.json
:
bash
jq '.artifacts | to_entries | map(select(.value.type == "aws:cloudformation:stack") | {displayName: .key, environment: .value.environment}) | .[]' cdk.out/manifest.json
Example 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
aws:region
and
aws-native:region
config variables. For example:
bash
pulumi config set aws-native:region us-east-2 --stack dev
pulumi config set aws:region us-east-2 --stack dev
读取
cdk.out/manifest.json
bash
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:region
aws-native:region
配置变量。例如:
bash
pulumi config set aws-native:region us-east-2 --stack dev
pulumi config set aws:region us-east-2 --stack dev

1.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 json

1.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
    cdk2pulumi
    tool. Follow cdk-convert.md to perform the conversion.
  • 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.
  • 使用
    cdk2pulumi
    工具执行初始转换。遵循cdk-convert.md进行转换。
  • 阅读转换报告并填补任何空白。例如,如果转换工具未能转换某个资源,你需要手动转换它。

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:
    AWS::CloudFormation::CustomResource
    or
    Custom::<name>
  • Metadata contains
    aws:cdk:path
    with the handler name (e.g.,
    aws-s3/auto-delete-objects-handler
    )
Default behavior:
cdk2pulumi
rewrites custom resources to
aws-native:cloudformation:CustomResourceEmulator
, which invokes the original Lambda. This works but has tradeoffs (Lambda dependency, cold starts, eventual consistency).
Migration strategies by handler type:
HandlerStrategy
aws-certificatemanager/dns-validated-certificate-handler
Replace with
aws.acm.Certificate
,
aws.route53.Record
, and
aws.acm.CertificateValidation
aws-ec2/restrict-default-security-group-handler
Replace with
aws.ec2.DefaultSecurityGroup
resource with empty ingress/egress rules
aws-ecr/auto-delete-images-handler
Replace
aws-native:ecr:Repository
with
aws.ecr.Repository
with
forceDelete: true
aws-s3/auto-delete-objects-handler
Replace
aws-native:s3:Bucket
with
aws.s3.Bucket
with
forceDestroy: true
aws-s3/notifications-resource-handler
Replace with
aws.s3.BucketNotification
aws-logs/log-retention-handler
Replace with
aws.cloudwatch.LogGroup
with explicit
retentionInDays
aws-iam/oidc-handler
Replace with
aws.iam.OpenIdConnectProvider
aws-route53/delete-existing-record-set-handler
Replace with
aws.route53.Record
with
allowOverwrite: true
aws-dynamodb/replica-handler
Replace with
aws.dynamodb.TableReplica
Cross-account/region handlers:
  • aws-cloudfront/edge-function
    → Use
    aws.lambda.Function
    with
    region: "us-east-1"
  • aws-route53/cross-account-zone-delegation-handler
    → Use separate aws provider with cross-account role assumption
Graceful degradation for unknown handlers:
  1. Keep the
    CustomResourceEmulator
    (default behavior)
  2. 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::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
资源
aws-ecr/auto-delete-images-handler
aws-native:ecr:Repository
替换为设置了
forceDelete: true
aws.ecr.Repository
aws-s3/auto-delete-objects-handler
aws-native:s3:Bucket
替换为设置了
forceDestroy: true
aws.s3.Bucket
aws-s3/notifications-resource-handler
替换为
aws.s3.BucketNotification
aws-logs/log-retention-handler
替换为设置了显式
retentionInDays
aws.cloudwatch.LogGroup
aws-iam/oidc-handler
替换为
aws.iam.OpenIdConnectProvider
aws-route53/delete-existing-record-set-handler
替换为设置了
allowOverwrite: true
aws.route53.Record
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 Provider Strategy

2.2 提供商策略

  • Default: Use
    aws-native
    whenever the resource type is available.
  • Fallback: Use
    aws
    when aws-native does not support equivalent features.
  • 默认:只要资源类型可用,就使用
    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
cdk.out
directory alongside
*.assets.json
metadata files. CloudFormation templates contain hard-coded references to asset locations (S3 bucket/key or ECR repo/tag).
bash
undefined
CDK使用Assets和Bundling来处理部署构件。这些构件在CloudFormation部署前由CDK CLI处理,并与
*.assets.json
元数据文件一起出现在
cdk.out
目录中。CloudFormation模板包含对资产位置的硬编码引用(S3存储桶/键或ECR仓库/标签)。
bash
undefined

Inspect 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
    cdk-importer
    tool. Follow cdk-importer.md to perform the automated import.
  • For any resources that fail to import with the automated tool, import them manually.
If you need to manually import resources:
转换完成后,可以选择将现有资源导入到Pulumi进行管理。如果用户未请求此操作,你应将其作为转换后的后续步骤建议。
  • 始终先使用
    cdk-importer
    工具执行自动导入。遵循cdk-importer.md执行自动导入。
  • 对于任何自动导入失败的资源,手动导入它们。
如果需要手动导入资源:

3.1 Running preview after import

3.1 导入后运行预览

After performing an import you need to run
pulumi preview
to ensure there are no changes. No changes means:
  • 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:
  1. Overview (high-level description)
  2. Migration Plan Summary
  3. Pulumi Code Outputs (TypeScript; structured by file)
  4. Resource Mapping Table (CDK → Pulumi)
  5. Custom Resources Summary (if any):
    • Handlers migrated to native Pulumi resources
    • Handlers kept as
      CustomResourceEmulator
      with rationale
    • Any handlers requiring user attention
  6. Assets & Bundling Summary (if any):
    • Migrated: Assets successfully converted (e.g., Docker images →
      docker-build.Image
      , static files →
      pulumi.FileArchive
      )
    • Requires attention: Assets with bundling steps, options presented, and decision if made
  7. Final Migration Report (PR-ready)
  8. Next Steps (optional refactors)
Keep code syntactically valid and clearly separated by files.
执行迁移时,必须生成以下内容:
  1. 概述(高层描述)
  2. 迁移计划摘要
  3. Pulumi代码输出(TypeScript;按文件结构化)
  4. 资源映射表(CDK → Pulumi)
  5. 自定义资源摘要(如有):
    • 已迁移为Pulumi原生资源的处理程序
    • 保留为
      CustomResourceEmulator
      的处理程序及理由
    • 任何需要用户注意的处理程序
  6. 资产与打包摘要(如有):
    • 已迁移:成功转换的资产(如Docker镜像 →
      docker-build.Image
      ,静态文件 →
      pulumi.FileArchive
    • 需要注意:带有打包步骤的资产、提供的选项及已做出的决策
  7. 最终迁移报告(适合PR)
  8. 后续步骤(可选重构)
保持代码语法有效,并按文件清晰分隔。