Skip to content

Conversation

@corymhall
Copy link
Contributor

@corymhall corymhall commented Dec 4, 2025

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”
  • CloudFormation guide now references the shared AWS import-ID guide

This is the new directory structure i'm proposing in this PR

Screenshot 2025-12-05 at 2 12 41 PM

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
Copy link
Contributor Author

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.

@claude
Copy link
Contributor

claude bot commented Dec 4, 2025

Documentation Review

I have reviewed PR #16740 and found several issues that need to be addressed before merging.

Critical Issues

1. 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 Issues

4. 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 Issues

6. 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 Items

Must fix before merge:

  • Add trailing newlines to all three new files
  • Complete or remove empty sections in aws-import-ids-and-special-cases.md
  • Fix malformed code block on line 212
  • Fix ordered lists to use all 1.

Should fix:

  • Standardize shell command formatting
  • Use consistent Pulumi program terminology
  • Verify links

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.

@pulumi-bot
Copy link
Collaborator

@pulumi-bot
Copy link
Collaborator

@pulumi-bot
Copy link
Collaborator

@pulumi-bot
Copy link
Collaborator

@pulumi-bot
Copy link
Collaborator

@pulumi-bot
Copy link
Collaborator

@pulumi-bot
Copy link
Collaborator

@pulumi-bot
Copy link
Collaborator

@corymhall corymhall marked this pull request as ready for review December 5, 2025 19:34
@claude
Copy link
Contributor

claude bot commented Dec 5, 2025

Documentation Review

I'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 Found

1. aws-import-ids.md - Inconsistent code fence language (lines throughout)

The file mixes console and bash fence types inconsistently. According to the style guide, use bash for commands and output for console output.

Lines 24, 28, 50, 80, 144, 158, 177, 194, 200: Change console to bash:


2. aws-import-ids.md - Missing H1 title (line 5)

The h1 front matter field should match Hugo conventions. Based on the title structure, this appears correct, but verify the H1 isn't duplicated in the body.

3. aws-import-ids.md - Ordered list formatting (lines 20-21)

Per AGENTS.md, ordered lists should use 1. for every item to minimize diff noise.

Line 20-21:

1. The name or ARN of the Lambda function, version, or alias.
  **Name formats**
1. *Function name* – ``my-function`` (name-only), ``my-function:v1`` (with alias).
1. *Function ARN* – ``arn:aws:lambda:us-west-2:123456789012:function:my-function``.
1. *Partial ARN* – ``123456789012:function:my-function``.

4. aws-import-ids.md - Inconsistent formatting (lines 37-42)

The indented list under "functionName" uses + bullets which appears to be copied from CDK documentation. Should use consistent Markdown - or numbered lists.

Lines 37-42:

  - functionName (Input): The name or ARN of the Lambda function, version, or alias.
  **Name formats**
  - *Function name* – ``my-function`` (name-only), ``my-function:v1`` (with alias).
  - *Function ARN* – ``arn:aws:lambda:us-west-2:123456789012:function:my-function``.
  - *Partial ARN* – ``123456789012:function:my-function``.

5. aws-import-ids.md - Heading capitalization (line 49)

"Example" should be lowercase per sentence case rule for H3+ headings.

Line 49:

### Finding IDs example

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:
suggestion

Finding IDs example

Let's walk through an example of finding the import IDs for a couple of resources.

  1. List the stack resources

    aws cloudformation list-stack-resources --stack-name test-app-dev \
        --query 'StackResourceSummaries[].{ResourceType:ResourceType,LogicalResourceId:LogicalResourceId,PhysicalResourceId:PhysicalResourceId}'
    [output here]
    
  2. Find the import id format for each

    pulumi plugin run cdk2pulumi -- ids AWS::ApiGatewayV2::Api

7. aws-import-ids.md - Line 97: "Import doc" excerpt unclear

The import doc line appears to be raw tool output that should be formatted more clearly or removed.

Line 97:
suggestion
Import doc: To import aws_apigatewayv2_stage using the API identifier and stage name, use:

import {
  to = aws_apigatewayv2_stage.example
  id = "aabbccddee/example-stage"
}

8. aws-import-ids.md - Typo (line 113)

"PhyscialResourceId" should be "PhysicalResourceId"

Line 113:

then this will also typically be the `PhysicalResourceId`.

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:

1. Coexist with resources provisioned by CDK by referencing stack outputs
1. Convert your CDK application to Pulumi, either by using the Pulumi CDK adapter or by migrating to a Pulumi program that imports existing resources

Style Observations

  1. aws-import-ids.md: The guide is well-structured and provides valuable examples. The use of real CLI commands and outputs is helpful.

  2. Structure improvement: The separation of "using Pulumi CDK" vs "migrating to Pulumi" is much clearer than the previous combined approach.

  3. Alias preservation: Good job adding proper aliases to maintain SEO and prevent broken links.

Missing Verification

As noted in AGENTS.md, when moving files, you should verify aliases using /scripts/alias-verification/. Since this is a restructuring with new files and modified navigation, please run those verification scripts.

Summary

The restructuring significantly improves the CDK migration documentation by clearly separating the two main approaches. The main issues are:

  • Code fence language inconsistencies (console vs bash)
  • Ordered list formatting not following the 1. convention
  • Steps presented as bold headings instead of ordered lists
  • Minor typos and formatting issues

@claude Feel free to mention me if you'd like me to review fixes or if you have questions about any of these suggestions.

@pulumi-bot
Copy link
Collaborator

Copy link
Member

@jkodroff jkodroff left a 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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:

Copy link
Member

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:
Copy link
Member

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**
Copy link
Member

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/).
Copy link
Member

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).

Copy link
Member

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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
Copy link
Member

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.
Copy link
Member

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.
Copy link
Member

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants