-
Notifications
You must be signed in to change notification settings - Fork 258
Add cdk to pulumi migration guide #16740
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: master
Are you sure you want to change the base?
Conversation
This PR restructures the AWS CDK → Pulumi migration docs to separate the two major flows (“keep using CDK with Pulumi CDK adapter”
vs “migrate to a Pulumi program and import existing resources”) and introduces a shared AWS import-ID guide that both CDK and
CloudFormation content can reference.
**Key changes**
- AWS CDK landing page now a hub
- Simplified body to present the two main strategies:
- Coexist with CDK-managed stacks.
- Convert CDK to Pulumi (either via Pulumi CDK or full Pulumi migration).
- New guide: “Using Pulumi with AWS CDK” (Pulumi CDK adapter flow)
- Extracted the detailed content that used to live in from-cdk.md into a dedicated guide focused on staying on CDK constructs and
- New guide: “Migrating existing AWS CDK applications to Pulumi” (full migration flow)
- New shared guide: “AWS import IDs and special cases”
- CloudFormation guide now references the shared AWS import-ID guide
| "3.150.255.6|eipalloc-0a79aa2cb81750a49" | ||
| ``` | ||
|
|
||
| ## Special Cases |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll remove this section before merging. Just wanted to have a placeholder showing the types of things I plan on adding in the future.
Documentation ReviewI have reviewed PR #16740 and found several issues that need to be addressed before merging. Critical Issues1. Missing trailing newlines All three new files are missing the required trailing newline per AGENTS.md. 2. Incomplete content sections aws-import-ids-and-special-cases.md (lines 196-254) contains numerous incomplete sections with only headings and no content. Either complete these sections or remove them. 3. Code block formatting aws-import-ids-and-special-cases.md line 212 has a malformed list item with escaped backtick. Style Issues4. Ordered list formatting migrating-existing-cdk-app.md uses sequential numbers (1. 2. 3.) instead of all 1. as required by STYLE-GUIDE.md. 5. Inconsistent shell notation aws-import-ids-and-special-cases.md uses shell blocks without prompts while other guides use bash with dollar prompts. Content Issues6. Vague heading from-cdk.md uses generic Next steps heading instead of something more specific for a hub page. 7. Inconsistent terminology migrating-existing-cdk-app.md switches between Pulumi program, Pulumi application, and Pulumi code. 8. Link validation needed Verify all internal links resolve correctly. Action ItemsMust fix before merge:
Should fix:
Positive: Good use of aliases, clear separation of strategies, practical examples with AWS CLI and cdk2pulumi. Mention @claude if you would like help with fixes or another review. |
|
Your site preview for commit 2d8f598 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-16740-2d8f5989.s3-website.us-west-2.amazonaws.com. |
|
Your site preview for commit 4c2ebfe is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-16740-4c2ebfe4.s3-website.us-west-2.amazonaws.com. |
content/docs/iac/guides/migration/migrating-to-pulumi/migrating-from-cdk/using-pulumi-cdk.md
Show resolved
Hide resolved
|
Your site preview for commit 128f7d0 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-16740-128f7d0b.s3-website.us-west-2.amazonaws.com. |
|
Your site preview for commit 2e62e91 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-16740-2e62e912.s3-website.us-west-2.amazonaws.com. |
|
Your site preview for commit 2867d91 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-16740-2867d91f.s3-website.us-west-2.amazonaws.com. |
|
Your site preview for commit 1c73051 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-16740-1c73051b.s3-website.us-west-2.amazonaws.com. |
|
Your site preview for commit e505638 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-16740-e505638e.s3-website.us-west-2.amazonaws.com. |
|
Your site preview for commit 802cebc is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-16740-802cebcb.s3-website.us-west-2.amazonaws.com. |
Documentation ReviewI've reviewed the CDK migration guide restructuring. Overall, this is a valuable improvement that clearly separates the two migration paths. Here are my findings: Issues Found1. aws-import-ids.md - Inconsistent code fence language (lines throughout)The file mixes Lines 24, 28, 50, 80, 144, 158, 177, 194, 200: Change 2. aws-import-ids.md - Missing H1 title (line 5)The 3. aws-import-ids.md - Ordered list formatting (lines 20-21)Per AGENTS.md, ordered lists should use Line 20-21: 4. aws-import-ids.md - Inconsistent formatting (lines 37-42)The indented list under "functionName" uses Lines 37-42: 5. aws-import-ids.md - Heading capitalization (line 49)"Example" should be lowercase per sentence case rule for H3+ headings. Line 49: 6. aws-import-ids.md - Steps should use ordered list (lines 49-76)The example uses bold headings for steps instead of an ordered list. Per style guide, use ordered lists for steps. Lines 49-76: Restructure as: Finding IDs exampleLet's walk through an example of finding the import IDs for a couple of resources.
7. aws-import-ids.md - Line 97: "Import doc" excerpt unclearThe import doc line appears to be raw tool output that should be formatted more clearly or removed. Line 97: import {
to = aws_apigatewayv2_stage.example
id = "aabbccddee/example-stage"
}8. aws-import-ids.md - Typo (line 113)"PhyscialResourceId" should be "PhysicalResourceId" Line 113: 9. migrating-existing-cdk-app.md - Trailing text issue (line 28)"The safest migration approach" appears to be cut off mid-sentence at the end of the diff excerpt. Verify the content is complete. 10. from-cdk.md - Inconsistent punctuation (lines 18-19)Per style guide, list items should have consistent punctuation. Either all items end with periods or none do. Lines 18-19: Style Observations
Missing VerificationAs noted in AGENTS.md, when moving files, you should verify aliases using SummaryThe restructuring significantly improves the CDK migration documentation by clearly separating the two main approaches. The main issues are:
@claude Feel free to mention me if you'd like me to review fixes or if you have questions about any of these suggestions. |
|
Your site preview for commit cb9d2d3 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-16740-cb9d2d37.s3-website.us-west-2.amazonaws.com. |
jkodroff
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Filing my feedback so far. Not sure I'm gonna get to the end of the PR today.
|
|
||
| Every import requires a resource ID. Whether you are running `pulumi import` for a single resource or using a bulk `import.json` file (for example, generated with `pulumi preview --import-file import.json`), you need to supply an ID value that uniquely identifies the existing AWS resource. Sometimes this is a single value like a resource `ARN`, but other times it is a composite id made up of a combination of property values. For example, to import a Lambda Permission resource you need the `functionName` and the Permission `id` and it needs to be in the format `functionName|id`. | ||
|
|
||
| The first place you should start is the ids from the CloudFormation stack. Most of the time the values for the import ids can be extracted from the `PhysicalResourceId` in the CloudFormation stack. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| The first place you should start is the ids from the CloudFormation stack. Most of the time the values for the import ids can be extracted from the `PhysicalResourceId` in the CloudFormation stack. | |
| The first place you should look for resource ids for Pulumi import is by querying the CloudFormation stack. Import ids for most Pulumi resource types can be extracted from the `PhysicalResourceId` property in CloudFormation: |
|
|
||
| ## Finding Resource IDs | ||
|
|
||
| Every import requires a resource ID. Whether you are running `pulumi import` for a single resource or using a bulk `import.json` file (for example, generated with `pulumi preview --import-file import.json`), you need to supply an ID value that uniquely identifies the existing AWS resource. Sometimes this is a single value like a resource `ARN`, but other times it is a composite id made up of a combination of property values. For example, to import a Lambda Permission resource you need the `functionName` and the Permission `id` and it needs to be in the format `functionName|id`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| Every import requires a resource ID. Whether you are running `pulumi import` for a single resource or using a bulk `import.json` file (for example, generated with `pulumi preview --import-file import.json`), you need to supply an ID value that uniquely identifies the existing AWS resource. Sometimes this is a single value like a resource `ARN`, but other times it is a composite id made up of a combination of property values. For example, to import a Lambda Permission resource you need the `functionName` and the Permission `id` and it needs to be in the format `functionName|id`. | |
| ## About Pulumi import | |
| The [`pulumi import`](/docs/iac/cli/commands/pulumi_import/) command allows you to bring a resource created outside of Pulumi under Pulumi management. This includes resources created by clicking in the AWS Console, or by other infrastructure as code tools such as Terraform, CloudFormation, and AWS CDK. Each resource to be imported requires a resource ID, along with a name for the resource, and its type. | |
| ## Finding resource ids | |
| Whether you are running `pulumi import` for a single resource or using a bulk `import.json` file (for example, generated with `pulumi preview --import-file import.json`), you need to supply an ID that uniquely identifies the existing AWS resource. Sometimes this ID is a single value like a resource `ARN`, but other times it is a composite value made up of a combination of property values. For example, to import a [Lambda Permission](https://www.pulumi.com/registry/packages/aws/api-docs/lambda/permission/) resource you need both the `functionName` and the Permission `id` and the id suppled to `pulumi import` must be in the format `functionName|id`. |
| --query 'StackResourceSummaries[].{Type:ResourceType,LogicalResourceId:LogicalResourceId,Physical:PhysicalResourceId}' | ||
| ``` | ||
|
|
||
| Optionally, you can use the `cdk2pulumi` tool to lookup information on the import ids. It has an `ids` subcommand that returns information on the expected import id format. For example: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| Optionally, you can use the `cdk2pulumi` tool to lookup information on the import ids. It has an `ids` subcommand that returns information on the expected import id format. For example: | |
| Optionally, you can use the `cdk2pulumi` tool to lookup information on the import ids. `cdk2pulumi` has an `ids` subcommand that returns information on the expected import id format: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If there's no other docs page, we need to explain how to install cdk2pulumi. If there is another docs page, we need to link to it here.
| meta_image: /images/docs/meta-images/docs-meta.png | ||
| aliases: | ||
| - /docs/iac/guides/migration/migrating-to-pulumi/aws-import-ids/ | ||
| menu: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For nav, I think we probably want this under a unified CDK/CFN section. Defer to @CamSoper.
|
|
||
| Lets walk through an example of finding the import ids for a couple of resources. | ||
|
|
||
| **1. List the stack resources** |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These should just be standard ordered lists, e.g.:
1. List the stack resources:
```bash
do stuff
```
1. (do the next thing)Indent code fences 4 spaces and keep a blank line in between and they will render correctly.
| ## Choose a CDK migration path | ||
|
|
||
| It is possible to reference existing AWS CDK stacks from your program. It doesn't matter how these stacks were created. This lets you read properties of that CloudFormation stack for use within your Pulumi program. This includes output values computed from resources provisioned by that stack. | ||
| To keep using AWS CDK constructs while adopting Pulumi as the engine, see [Using Pulumi with AWS CDK](/docs/iac/guides/migration/migrating-to-pulumi/migrating-from-cdk/using-pulumi-cdk/). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This needs some intro text about your choices, or if CDK constructs are a sidenote, this should go within notes (type info).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also explain why I might want to choose each one, what the user experience is like, etc.
|
|
||
| ## The golden path: incremental migration | ||
|
|
||
| The safest migration approach is **incremental**: migrate one logical group of resources at a time, verify each group before proceeding, and maintain the ability to roll back. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| The safest migration approach is **incremental**: migrate one logical group of resources at a time, verify each group before proceeding, and maintain the ability to roll back. | |
| Pulumi recommends an incremental path in migrating CDK resources to Pulumi, importing one logical group of resources at a time, and verifying each group of resources before proceeding to the next while maintaining the ability to roll back. |
|
|
||
| The safest migration approach is **incremental**: migrate one logical group of resources at a time, verify each group before proceeding, and maintain the ability to roll back. | ||
|
|
||
| ### Recommended workflow |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This section could use some reformatting:
- Put the process into discrete steps
- Consider bolding the title of each step, e.g.
**Migrate each environment in sequence:** Import into dev
|
|
||
| ### Choose your convert/import approach | ||
|
|
||
| Pulumi offers multiple ways to convert and import resources. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Give an overview of each approaches (one sentence each) with links to each section. This will make the content easier to scan.
|
|
||
| ### Using the CDK importer tool (automated import files) | ||
|
|
||
| For larger stacks, manually building an `import.json` and chasing resource IDs can be tedious. The [Pulumi CDK importer tool](https://github.com/pulumi/pulumi-tool-cdk-importer) can generate a bulk import file for you by inspecting your Pulumi program and the underlying AWS resources. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Link to source code is probably not that helpful. Installation is the first thing a user will want to know.
This PR restructures the AWS CDK → Pulumi migration docs to separate the two major flows (“keep using CDK with Pulumi CDK adapter” vs “migrate to a Pulumi program and import existing resources”) and introduces a shared AWS import-ID guide that both CDK and CloudFormation content can reference.
Key changes
This is the new directory structure i'm proposing in this PR