pulumi-cdk-to-pulumi
Load this skill when a user wants to migrate, convert, port, translate, or move an AWS CDK application (including CDK stacks, constructs, or CloudFormation-synthesized templates) to Pulumi. Phrases such as "convert CDK to Pulumi", "migrate CDK app", "port CDK stacks", "replace CDK with Pulumi", "stop using CDK". Do NOT load for general CDK questions, CDK-only help, or CDK vs Pulumi comparisons where no migration is requested.
pulumi · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add pulumi/agent-skills --skill pulumi-cdk-to-pulumi技能说明
name: pulumi-cdk-to-pulumi description: Load this skill when a user wants to migrate, convert, port, translate, or move an AWS CDK application (including CDK stacks, constructs, or CloudFormation-synthesized templates) to Pulumi. Phrases such as "convert CDK to Pulumi", "migrate CDK app", "port CDK stacks", "replace CDK with Pulumi", "stop using CDK". Do NOT load for general CDK questions, CDK-only help, or CDK vs Pulumi comparisons where no migration is requested.
CRITICAL 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
pulumi up(assuming proper config).
- 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
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.
MIGRATION WORKFLOW
Follow this workflow exactly and in this order:
1. INFORMATION GATHERING
1.1 Verify AWS Credentials (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.
1.2 Synthesize CDK
Run/inspect:
npx cdk synth --quiet
- ALWAYS run
synthwith--quietto prevent the template from being output on stdout.
If failing, inspect cdk.json or package.json for custom synth behavior.
1.3 Identify CDK Stacks & Environments
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
1.4 Build Resource Inventory
For each stack:
aws cloudformation list-stack-resources \
--region <region> \
--stack-name <stack> \
--output json
1.5 Analyze CDK Structure
Extract:
- Environment-specific conditionals
- Stack dependencies & cross-stack references
- Runtime config (context/env vars)
- Construct types (L1, L2, L3)
2. CODE CONVERSION (CDK → PULUMI)
- Perform the initial conversion using the
cdk2pulumitool. 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.
2.1 Custom Resources Handling
CDK uses Lambda-backed Custom Resources for functionality not available in CloudFormation. In synthesized CloudFormation, these appear as:
- Resource type:
AWS::CloudFormation::CustomResourceorCustom::<name> - Metadata contains
aws:cdk:pathwith 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 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→ Useaws.lambda.Functionwithregion: "us-east-1"aws-route53/cross-account-zone-delegation-handler→ Use separate aws provider with cross-account role assumption
Graceful degradation for unknown handlers:
- Keep the
CustomResourceEmulator(default behavior) - 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
2.2 Provider Strategy
- Default: Use
aws-nativewhen