cloudformation-to-pulumi
Convert, migrate, or import AWS CloudFormation stacks or templates into Pulumi programs. Load this skill whenever a user wants to move from CloudFormation to Pulumi, convert a CFN template, import existing CloudFormation-managed resources into Pulumi, or asks about CloudFormation-to-Pulumi migration in any form. Also load when the user mentions cdk-importer in a migration context.
pulumi · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add pulumi/agent-skills --skill cloudformation-to-pulumi技能说明
name: cloudformation-to-pulumi description: Convert, migrate, or import AWS CloudFormation stacks or templates into Pulumi programs. Load this skill whenever a user wants to move from CloudFormation to Pulumi, convert a CFN template, import existing CloudFormation-managed resources into Pulumi, or asks about CloudFormation-to-Pulumi migration in any form. Also load when the user mentions cdk-importer in a migration context.
IMPORTANT: PLAN ADJUSTMENT REQUIRED
If you have already generated a migration plan before loading this skill, you MUST:
- Review your existing plan against the workflows and requirements in this skill
- Identify any gaps, missing steps, or incorrect assumptions
- Update and revise your plan to align with this skill's guidance
- Communicate the adjusted plan to the user before proceeding
CRITICAL SUCCESS REQUIREMENTS
The migration output MUST meet all of the following:
-
Complete Resource Coverage
- Every CloudFormation resource MUST be represented in the Pulumi program OR explicitly justified in the final report.
-
CloudFormation Logical ID as Resource Name
- CRITICAL: Every Pulumi resource MUST use the CloudFormation Logical ID as its resource name.
- This enables the
cdk-importertool to automatically find import IDs. - DO NOT rename resources. Automated import will FAIL if you change the logical IDs.
-
Successful Deployment
- The produced Pulumi program must be structurally valid and capable of a successful
pulumi preview(assuming proper config).
- The produced Pulumi program must be structurally valid and capable of a successful
-
Zero-Diff Import Validation (if importing existing resources)
- After import,
pulumi previewmust show NO updates, replaces, creates, or deletes.
- After import,
-
Final Migration Report
- Always output a formal migration report suitable for a Pull Request.
WHEN INFORMATION IS MISSING
If the user has not provided a CloudFormation template, you MUST fetch it from AWS using the stack name.
MIGRATION WORKFLOW
Follow this workflow exactly and in this order:
1. INFORMATION GATHERING
1.1 Verify AWS Credentials (ESC)
Running AWS commands 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.
For detailed ESC information: Use skill pulumi-esc.
You MUST confirm the AWS region with the user.
1.2 Get the CloudFormation Template
If user provided a template file: Read the template directly.
If user only provided a stack name: Fetch the template from AWS:
aws cloudformation get-template \
--region <region> \
--stack-name <stack-name> \
--query 'TemplateBody' \
--output json > template.json
1.3 Build Resource Inventory
List all resources in the stack:
aws cloudformation list-stack-resources \
--region <region> \
--stack-name <stack-name> \
--output json
This provides:
LogicalResourceId- Use this as the Pulumi resource namePhysicalResourceId- The actual AWS resource IDResourceType- The CloudFormation resource type
1.4 Analyze Template Structure
Extract from the template:
- Parameters and their defaults
- Mappings
- Conditions
- Outputs
- Resource dependencies (Ref, GetAtt, DependsOn)
2. CODE CONVERSION (CloudFormation → Pulumi)
IMPORTANT: There is NO automated conversion tool for CloudFormation. You MUST convert each resource manually.
2.1 Resource Name Convention (CRITICAL)
Every Pulumi resource MUST use the CloudFormation Logical ID as its name.
// CloudFormation:
// "MyAppBucketABC123": { "Type": "AWS::S3::Bucket", ... }
// Pulumi - CORRECT:
const myAppBucket = new aws.s3.Bucket("MyAppBucketABC123", { ... });
// Pulumi - WRONG (DO NOT do this - import will fail):
const myAppBucket = new aws.s3.Bucket("my-app-bucket", { ... });
This naming convention is REQUIRED because the cdk-importer tool matches resources by name.
2.2 Provider Strategy
⚠️ CRITICAL: ALWAYS USE aws-native BY DEFAULT ⚠️
- Use
aws-nativefor all resources unless there's a specific reason to useaws. - CloudFormation types map directly to aws-native (e.g.,
AWS::S3::Bucket→aws-native.s3.Bucket). - Only use
aws(classic) when aws-native doesn't support a required feature.
This is MANDATORY for successful imports with cdk-importer. The cdk-importer works by matching CloudFormation resources to Pulumi resources, and CloudFormation maps 1:1 to aws-native. Using the classic aws provider will cause import failures.
2.3 CloudFormation Intrinsic Functions
Map CloudFormation intrinsic functions to Pulumi equivalents:
| CloudFormation | Pulumi Equivalent |
|---|---|
!Ref (resource) | Resource output (e.g., bucket.id) |
!Ref (parameter) | Pulumi config |
!GetAtt Resource.Attr | Resource property output |
!Sub "..." | pulumi.interpolate |
!Join [delim, [...]] | pulumi.interpolate or .apply() |
!If [cond, true, false] | Ternary operator |
!Equals [a, b] | === comparison |
!Select [idx, list] | Array indexing with .apply() |
!Split [delim, str] | .apply(v => v.split(...)) |
Fn::ImportValue | Stack references or config |
Example: !Sub
// CloudFormation: !Sub "arn:aws:s3:::${MyBucket}/*"
// Pulumi:
const bucketArn = pulumi.interpolate`arn:aws:s3:::${myBucket.bucket}/*`;
Example: !GetAtt
// CloudFormation: !GetAtt MyFunction.Arn
// Pulumi:
const functionArn = myFunction.arn;
2.4 CloudFormation Conditions
Convert CloudFormation conditions to TypeScript logic:
// CloudFormation:
// "Conditions": {
// "CreateProdResources": { "Fn::Equals": [{ "Ref": "Environment" }, "prod"] }
// }
// Pulumi:
const config = new pulumi.Config();
const environment = config.require("environment");
const createProdResources
阅读完整来源 ↗