pulumi-cdk-to-pulumi by pulumi/agent-skills
npx skills add https://github.com/pulumi/agent-skills --skill pulumi-cdk-to-pulumi迁移输出必须满足以下所有条件:
pulumi up(假设配置正确)。如果用户提供的 CDK 项目不完整、存在歧义或缺少构件(例如 cdk.out),在生成 Pulumi 代码之前,请提出有针对性的问题。
请严格按照以下顺序遵循此工作流程:
运行 AWS 命令(例如 aws cloudformation list-stack-resources)和 CDK 命令(例如 )需要通过 Pulumi ESC 加载凭证。
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
cdk synth您必须与用户确认 AWS 区域。如果使用错误的 AWS 区域运行,cdk synth 的结果可能不正确。
运行/检查:
npx cdk synth --quiet
--quiet 参数运行 synth,以防止模板输出到标准输出。如果失败,请检查 cdk.json 或 package.json 以了解自定义合成行为。
读取 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
对于每个堆栈:
aws cloudformation list-stack-resources \
--region <region> \
--stack-name <stack> \
--output json
提取:
cdk2pulumi 工具执行初始转换。按照 cdk-convert.md 执行转换。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 → 使用 aws.lambda.Function 并设置 region: "us-east-1"aws-route53/cross-account-zone-delegation-handler → 使用具有跨账户角色假设的独立 aws provider未知处理程序的优雅降级:
CustomResourceEmulator(默认行为)aws-native。aws。CDK 使用资产和打包来处理部署构件。这些在 CloudFormation 部署之前由 CDK CLI 处理,并出现在 cdk.out 目录中,旁边是 *.assets.json 元数据文件。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 或使用 bundling 选项的资源)。如果使用了打包,则需要在 Pulumi 中复制构建步骤以进行持续开发 - 否则源代码更改将需要手动重新运行 cdk synth。
当检测到打包时,通知用户:
检测到构建步骤:此 CDK 应用程序使用了 <BUNDLING_TYPE>,在合成期间构建可部署构件。为了进行持续开发,需要在 Pulumi 中复制此构建步骤。
选项:
- CI/CD 管道(推荐):将构建步骤移到您的 CI 管道中,并在 Pulumi 中引用预构建的构件
- Pulumi Command Provider:使用
command.local.Command在pulumi up期间运行构建命令- 预构建脚本:创建一个在
pulumi up之前运行的构建脚本,并将输出到已知位置每个选项在缓存、可重现性和部署速度方面都有权衡。对于生产工作负载,通常首选选项 1。
aws-native 的输出通常包含 undefined。避免使用 ! 非空断言。始终使用 .apply() 安全地解包:
// ❌ 错误 - 会导致 TypeScript 错误
functionName: lambdaFunction.functionName!,
// ✅ 正确 - 安全地处理 undefined
functionName: lambdaFunction.functionName.apply(name => name || ""),
保留所有条件行为:
if (currentEnv.createVpc) {
// 创建资源
} else {
const vpcId = pulumi.output(currentEnv.vpcId);
}
转换后,您可以选择性地导入现有资源,以便由 Pulumi 管理。如果用户没有提出此要求,您应建议将此作为转换后的后续步骤。
cdk-importer 工具进行自动导入开始。按照 cdk-importer.md 执行自动导入。如果需要手动导入资源:
执行导入后,您需要运行 pulumi preview 以确保没有更改。没有更改意味着:
如果有更改,您必须进行调查并更新程序,直到没有更改为止。
如果用户请求帮助规划或执行从 CDK 到 Pulumi 的迁移,请使用上述信息指导用户采用自动迁移方法。
当用户希望偏离上述推荐路径时,请使用 web-fetch 工具从官方 Pulumi 文档获取内容 -> https://www.pulumi.com/docs/iac/guides/migration/migrating-to-pulumi/migrating-from-cdk/migrating-existing-cdk-app
该文档涵盖以下主题:
执行迁移时,始终生成:
CustomResourceEmulator 的处理程序及理由docker-build.Image,静态文件 → pulumi.FileArchive)保持代码语法有效,并按文件清晰分隔。
每周安装数
239
仓库
GitHub Stars
30
首次出现
2026年1月28日
安全审计
安装于
opencode210
codex208
github-copilot206
gemini-cli202
amp200
kimi-cli199
The migration output MUST meet all of the following:
Complete Resource Coverage
Successful Deployment
pulumi up (assuming proper config).Final Migration Report
If a user-provided CDK project is incomplete, ambiguous, or missing artifacts (such as cdk.out), ask targeted questions before generating Pulumi code.
Follow this workflow exactly and in this order:
Running AWS commands (e.g., aws cloudformation list-stack-resources) and CDK commands (e.g. cdk synth) requires credentials loaded via Pulumi ESC.
You MUST confirm the AWS region with the user. The cdk synth results may be incorrect if ran with the wrong AWS Region.
Run/inspect:
npx cdk synth --quiet
synth with --quiet to prevent the template from being output on stdout.If failing, inspect cdk.json or package.json for custom synth behavior.
Read cdk.out/manifest.json:
jq '.artifacts | to_entries | map(select(.value.type == "aws:cloudformation:stack") | {displayName: .key, environment: .value.environment}) | .[]' cdk.out/manifest.json
Example output:
{
"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:
pulumi config set aws-native:region us-east-2 --stack dev
pulumi config set aws:region us-east-2 --stack dev
For each stack:
aws cloudformation list-stack-resources \
--region <region> \
--stack-name <stack> \
--output json
Extract:
cdk2pulumi tool. Follow cdk-convert.md to perform the conversion.CDK uses Lambda-backed Custom Resources for functionality not available in CloudFormation. In synthesized CloudFormation, these appear as:
AWS::CloudFormation::CustomResource or Custom::<name>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:
| Handler | Strategy |
|---|---|
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 with with |
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 assumptionGraceful degradation for unknown handlers:
CustomResourceEmulator (default behavior)aws-native whenever the resource type is available.aws when aws-native does not support equivalent features.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).
# 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 |
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:
- CI/CD Pipeline (Recommended): Move the build step to your CI pipeline and reference the pre-built artifact in Pulumi
- Pulumi Command Provider : Use
command.local.Commandto run the build command duringpulumi up- Pre-build Script : Create a build script that runs before
pulumi upand outputs to a known location
Each option has tradeoffs around caching, reproducibility, and deployment speed. For production workloads, option 1 is typically preferred.
aws-native outputs often include undefined. Avoid ! non-null assertions. Always safely unwrap with .apply():
// ❌ WRONG - Will cause TypeScript errors
functionName: lambdaFunction.functionName!,
// ✅ CORRECT - Handle undefined safely
functionName: lambdaFunction.functionName.apply(name => name || ""),
Carry forward all conditional behaviors:
if (currentEnv.createVpc) {
// create resources
} else {
const vpcId = pulumi.output(currentEnv.vpcId);
}
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.
cdk-importer tool. Follow cdk-importer.md to perform the automated import.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/
Manual migration approaches -> https://www.pulumi.com/docs/iac/guides/migration/migrating-to-pulumi/migrating-from-cdk/migrating-existing-cdk-app/#approach-b-manual-migration
After performing an import you need to run pulumi preview to ensure there are no changes. No changes means:
If there are changes you must investigate and update the program until there are no changes.
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.
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:
When performing a migration, always produce:
CustomResourceEmulator with rationaledocker-build.Image, static files → pulumi.FileArchive)Keep code syntactically valid and clearly separated by files.
Weekly Installs
239
Repository
GitHub Stars
30
First Seen
Jan 28, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode210
codex208
github-copilot206
gemini-cli202
amp200
kimi-cli199
Azure Data Explorer (Kusto) 查询技能:KQL数据分析、日志遥测与时间序列处理
102,600 周安装
LangGraph智能体架构指南:构建生产级AI智能体的图结构与状态管理
234 周安装
Go函数式选项模式详解:Uber风格指南、实现示例与最佳实践
234 周安装
Markdown转PDF工具 - 专业PDF创建器,完美支持中文字体,批量转换文档
234 周安装
Lark Skill Maker 教程:基于飞书CLI创建AI技能,自动化工作流与API调用指南
16,700 周安装
营销活动执行指南:规划、跨渠道执行与效果分析全流程
234 周安装
Google Gemini CLI PR 评论处理助手 - 自动化审查 GitHub Pull Request 反馈
234 周安装
aws-native:ecr:Repositoryaws.ecr.RepositoryforceDelete: trueaws-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 |
Use pulumi.FileArchive or pulumi.FileAsset |
| Bundled file | files without executable, but CDK source uses bundling | Flag to user - bundling needs setup in Pulumi |