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.
-
Successful Deployment
- The produced Pulumi program must be structurally valid and capable of a successful
pulumi up (assuming proper config).
-
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
synth with --quiet to 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
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.
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::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:
| 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 → 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:
- 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-native whenever the resource type is available.
- Fallback: Use
aws when aws-native does not support equivalent features.
2.3 Assets & Bundling
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).
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:
- 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.Command to run the build command during pulumi up
- 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.
2.4 TypeScript Handling for aws-native
aws-native outputs often include undefined. Avoid ! non-null assertions. Always safely unwrap with .apply():
functionName: lambdaFunction.functionName!,
functionName: lambdaFunction.functionName.apply(name => name || ""),
2.5 Environment Logic Preservation
Carry forward all conditional behaviors:
if (currentEnv.createVpc) {
} else {
const vpcId = pulumi.output(currentEnv.vpcId);
}
3. Resource Import (optional)
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:
3.1 Running preview after import
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.
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.
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
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
CustomResourceEmulator with rationale
- Any handlers requiring user attention
- 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
- Final Migration Report (PR-ready)
- Next Steps (optional refactors)
Keep code syntactically valid and clearly separated by files.
