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.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

interface:
  display_name: "AWS CDK to Pulumi Migration"
  short_description: "Convert an AWS CDK application to Pulumi"
  default_prompt: "Use $pulumi-cdk-to-pulumi to convert an AWS CDK application to Pulumi."

# Pulumi CDK Conversion Tool (`cdk2pulumi`)

This tool plugin converts AWS CDK Cloud Assemblies to Pulumi YAML programs.

## Prerequisites

- The tool must be installed: `pulumi plugin install tool cdk2pulumi`
- All commands run through the Pulumi CLI using: `pulumi plugin run cdk2pulumi -- <args>`
- A CDK Cloud Assembly (typically in `cdk.out` directory) must exist for conversion operations

## Commands

### 1. Convert CDK Assembly to Pulumi YAML

Converts a CDK Cloud Assembly to a Pulumi YAML program (`Pulumi.yaml`) with an accompanying conversion report (`Pulumi.yaml.report.json`).

**Basic conversion:**

```bash
pulumi plugin run cdk2pulumi -- --assembly path/to/cdk.out
```

**Required flags:**

- `--assembly`: Path to the synthesized CDK Cloud Assembly (typically `cdk.out` directory). By default this will convert the entire CDK application (i.e. all stacks and stages)

**Optional flags:**

- `--stacks`: Comma separated list of CDK Stacks to convert
- `--stage`: Filter conversion to a specific CDK Stage
- `--skip-custom`: Skip converting CDK custom resources

**Important Notes:**

- Cross-stack references in partially converted stacks become config placeholders: `${external.<stack>.<output>}`
- Set these with: `pulumi config set external.<stack>.<output> <value>` before deployment
- CDK custom resources are rewritten to `aws-native:cloudformation:CustomResourceEmulator`
- The generated code will use the original CDK logical IDS. DO NOT update these otherwise automated import will FAIL

## Common Workflows

### Converting a CDK Application to Pulumi

1. **Synthesize the CDK app** to generate the Cloud Assembly:

   ```bash
   cdk synth
   ```

2. **Convert the assembly** to Pulumi YAML:

   ```bash
   pulumi plugin run cdk2pulumi -- --assembly cdk.out
   ```

3. **Review the conversion report** at `Pulumi.yaml.report.json` to identify any resources that didn't convert 1:1

4. **Set any required config** for cross-stack references:

   ```bash
   pulumi config set external.<stack>.<output> <value>
   ```

5. **Convert the Pulumi YAML program** to the target language:

   ```bash
   pulumi convert --from yaml --generate-only --language typescript --out ./generated-program
   ```

   > NOTE: after converting to another language you need to remove or rename the `Pulumi.yaml` file, otherwise it will still be treated as the main application

6. **Preview** the Pulumi program:

   ```bash
   pulumi preview
   ```

## Tips for Running

- Always use `--` to separate Pulumi CLI arguments from plugin arguments
- The `--assembly` flag expects a directory path (typically `cdk.out`), not a file
- When converting specific stacks, use comma-separated names without spaces: `--stacks Stack1,Stack2`
- For multi-stage CDK apps, use `--stage <name>` to target nested assemblies
- The tool outputs to `Pulumi.yaml` by default; use `--out` to specify a different location

# Pulumi CDK Importer Tool

This tool assists migrating CDK-managed infrastructure to Pulumi. It imports existing AWS resources from CloudFormation stacks into Pulumi state.

## Installation

```shell
pulumi plugin install tool cdk-importer
```

## Credentials

Running the `cdk-importer` tool 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 using the tool.

You MUST confirm the AWS region with the user. The results may be incorrect if ran with the wrong AWS Region. The region can be set with the `AWS_REGION` environment variable

## Commands

### program import

Import into the selected Pulumi stack using an existing generated Pulumi program.

```shell
pulumi plugin run cdk-importer -- program import \
  --program-dir ./generated \
  --stack MyStack
```

**Required flags:**

- `--program-dir`: Path to an existing Pulumi program generated from a CDK app
- `--stack`: CloudFormation stack name (can be specified multiple times or comma-separated)

**Optional flags:**

- `--import-file`: Path to write a Pulumi bulk import file with failing resources (defaults to `import.json` when provided without a value)
- `--debug`: Enable line by line logging of imported resources

**Behavior:**

- Runs against the selected Pulumi stack.
- With `--import-file`, writes the bulk import file after import. The file will only contain entries for resources that failed to import with `<PLACEHOLDER>` ids.
- Can be run iteratively to progressively import resources.

**Example Output:**

```shell
[INFO] Getting stack resources component="cdk-importer" stack=NeoExample-Dev
[INFO] Starting up providers... component="cdk-importer"
[INFO] Importing stack... component="cdk-importer"
[INFO] Run complete component="cdk-importer" status="success" resourcesImported=50 resourcesFailedToImport=0 stack="NeoExample-Dev" importFile="/workspace/pulumi-example-app-neo/import.json" importFileExists=true
```

## Import File Output

The generated `import.json` includes:

- Full AWS resource metadata (type, logical name, provider reference, component bit, provider version)
- Property subsets captured during provider interception

Resources with composite identifiers may show `<PLACEHOLDER>` IDs that need manual completion before running `pulumi import --file import.json`.

## Unsupported Resources

**Resources that cannot be imported:**

- CFN Custom Resources (`aws-native:cloudformation:CustomResourceEmulator`)

## Example Workflow

1. Generate a Pulumi program from your CDK app using `cdk2pulumi`

2. Import into your real stack:

   ```shell
   pulumi plugin run cdk-importer -- program import \
     --program-dir ./pulumi-program-dir \
     --stack CdkStack
   ```

## Handling Failures

This tool may not support 100% of the CloudFormation resources in the stack. For unsupported resources it is necessary to find the import ID and import manually.

**Example output:**

```shell
[INFO] Getting stack resources component="cdk-importer" stack=NeoExample-Dev
[INFO] Starting up providers... component="cdk-importer"
[INFO] Importing stack... component="cdk-importer"
[INFO] Pulumi errors component="cdk-importer" details=urn:pulumi:dev::cdk-convert-example::aws:rds/proxyDefaultTargetGroup:ProxyDefaultTargetGroup::DatabaseDbClusterDbProxyProxyTargetGroupA552DCC1: Don't have an ID!: aws:rds/proxyDefaultTargetGroup:ProxyDefaultTargetGroup neo-example-dev-database-db-cluster-db-proxy-eede4daa urn:pulumi:dev::cdk-convert-example::aws:rds/proxyDefaultTargetGroup:ProxyDefaultTargetGroup::DatabaseDbClusterDbProxyProxyTargetGroupA552DCC1

update failed
[INFO] Run complete component="cdk-importer" status="failed" resourcesImported=69 resourcesFailedToImport=1 stack="NeoExample-Dev"
- operation failed
```

**Example Failure Workflow:**

1. Import ran with error

2. Review failures and run `pulumi preview`.
   - Any resources that fail to import should appear as creations in the preview.
   - Optionally run `program import` with the `--import-file` flag to generate a `import.json` file with the failing resources.

3. Manually import remaining resources

# Pulumi Import ID Lookup (`cdk2pulumi ids`)

This tool looks up the required Pulumi import ID format for AWS resources, helping you understand what identifier shape is needed when importing existing AWS resources into Pulumi.

## Prerequisites

- The tool must be installed: `pulumi plugin install tool cdk2pulumi`
- Run via: `pulumi plugin run cdk2pulumi -- ids <resource-type>`

## Usage

### Look Up by Pulumi Resource Token or CloudFormation type

```bash
pulumi plugin run cdk2pulumi -- ids aws-native:s3:Bucket
pulumi plugin run cdk2pulumi -- ids AWS::S3::Bucket
```

## Understanding the Output

The tool returns two key pieces of information:

### 1. Import ID Format

Shows the structure of the ID required by Pulumi's `import` command. Examples:

- **Single-part ID**: `<BucketName>` - Just the bucket name
- **Composite ID**: `<FunctionName>|<StatementId>` - Multiple parts separated by delimiters
- **Complex ID**: `<CertificateAuthorityArn>|<CertificateArn>` - ARNs or other identifiers

### 2. Finding the ID Hint

Provides guidance on how to obtain the actual ID value from AWS:

- **Single-part IDs**: "Use the CloudFormation PhysicalResourceId"
  - Find this in CloudFormation via `aws cloudformation describe-stack-resources` or `aws cloudformation list-stack-resources`
- **Composite IDs**: Shows an `aws cloudcontrol list-resources` command example
  - May include `--resource-model '{...}'` when the Cloud Control API requires input parameters
  - Example: `aws cloudcontrol list-resources --type-name AWS::Lambda::Permission --resource-model '{"FunctionName":"my-function"}'`

## Examples

### Simple Resource (S3 Bucket)

```bash
$ pulumi plugin run cdk2pulumi -- ids AWS::S3::Bucket
Import ID format: <BucketName>
Finding the ID: Use the CloudFormation PhysicalResourceId
```

### Composite ID (Lambda Permission)

```bash
$ pulumi plugin run cdk2pulumi -- ids AWS::Lambda::Permission
Import ID format: <FunctionName>|<StatementId>
Finding the ID: aws cloudcontrol list-resources --type-name AWS::Lambda::Permission --resource-model '{"FunctionName":"<function-name>"}'
```

### Complex Resource (ACM PCA Certificate)

```bash
$ pulumi plugin run cdk2pulumi -- ids AWS::ACMPCA::Certificate
Import ID format: <CertificateAuthorityArn>|<CertificateArn>
Finding the ID: aws cloudcontrol list-resources --type-name AWS::ACMPCA::Certificate --resource-model '{"CertificateAuthorityArn":"<ca-arn>"}'
```

## Tips for Running

- Always use `--` to separate Pulumi CLI arguments from plugin arguments
- For composite IDs, pay attention to the delimiter (usually `|`, `/`, or `:`)
- When the hint shows `--resource-model`, you'll need to provide known properties to list the resources
- The PhysicalResourceId from CloudFormation is often the simplest way to find single-part IDs
- Some resources may require multiple API calls to construct the full composite ID

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

1. **Complete Resource Coverage**
   - Every CloudFormation resource synthesized by CDK MUST:
     - Be represented in the Pulumi program **OR**
     - Be explicitly justified in the final report.

2. **Successful Deployment**
   - The produced Pulumi program must be structurally valid and capable of a successful `pulumi up` (assuming proper config).

3. **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:

```bash
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`:

```bash
jq '.artifacts | to_entries | map(select(.value.type == "aws:cloudformation:stack") | {displayName: .key, environment: .value.environment}) | .[]' cdk.out/manifest.json
```

Example output:

```json
{
  "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:

```bash
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:

```bash
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](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:**

1. Keep the `CustomResourceEmulator` (default behavior)
2. 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).

```bash
# Inspect asset definitions
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:**
>
> 1. **CI/CD Pipeline** (Recommended): Move the build step to your CI pipeline and reference the pre-built artifact in Pulumi
> 2. **Pulumi Command Provider**: Use `command.local.Command` to run the build command during `pulumi up`
> 3. **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()`:

```ts
// ❌ WRONG - Will cause TypeScript errors
functionName: lambdaFunction.functionName!,

// ✅ CORRECT - Handle undefined safely
functionName: lambdaFunction.functionName.apply(name => name || ""),
```

#### 2.5 Environment Logic Preservation

Carry forward all conditional behaviors:

```ts
if (currentEnv.createVpc) {
  // create resources
} 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](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:

- Follow [cloudformation-id-lookup.md](cloudformation-id-lookup.md) to look up CloudFormation import identifiers.
- Use the web-fetch tool to get content from the official Pulumi documentation.

- **Finding AWS import IDs** -> <https://www.pulumi.com/docs/iac/guides/migration/aws-import-ids/>
- **Manual migration approaches** -> <https://www.pulumi.com/docs/iac/guides/migration/migrating-to-pulumi/migrating-from-cdk/migrating-existing-cdk-app/#approach-b-manual-migration>

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

1. **Overview** (high-level description)
2. **Migration Plan Summary**
3. **Pulumi Code Outputs** (TypeScript; structured by file)
4. **Resource Mapping Table** (CDK → Pulumi)
5. **Custom Resources Summary** (if any):
   - Handlers migrated to native Pulumi resources
   - Handlers kept as `CustomResourceEmulator` with rationale
   - Any handlers requiring user attention
6. **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
7. **Final Migration Report** (PR-ready)
8. **Next Steps** (optional refactors)

Keep code syntactically valid and clearly separated by files.

# Queries that should activate the pulumi-cdk-to-pulumi skill
queries:
  # Full migration (convert + import deployed state)
  - "We're migrating from CDK to Pulumi with several deployed stacks in AWS"
  - "Convert our AWS CDK application to Pulumi and import the existing state"
  - "I have a CDK app with 3 stacks deployed, help me migrate everything to Pulumi"
  - "Migrate our CDK infrastructure to Pulumi without downtime"

  # Conversion only (no import needed)
  - "Convert this CDK TypeScript code to Pulumi"
  - "Help me translate my CDK constructs to Pulumi resources"

  # cdk.out / cdk synth workflows (uses cdk-convert supplemental tool)
  - "I have a cdk.out directory, convert it to Pulumi YAML"
  - "Run cdk synth and then convert the output to Pulumi"

  # Import-focused (uses cdk-importer supplemental tool)
  - "I already have Pulumi code from CDK, now I need to import the CloudFormation state"
  - "Import my existing CDK-deployed resources into Pulumi state"
  - "The CDK stack is deployed in AWS, I need to import those resources into Pulumi"
  - "The cdk-importer failed for AWS::ECS::Service, what's the correct import ID?"
  - "The CDK import is failing because I don't know what ID to use for AWS::Lambda::Function"

  # Real-world prompts from users
  - "Convert my CDK stack to Pulumi"
  - "Convert my CDK stack to Pulumi please"
  - "Convert my CDK code to a Pulumi Typescript program"
  - "Import existing resources from AWS that were created by CDK"
  - "Convert my CDK code to a Pulumi Typescript program and import existing resources from AWS that were created by CDK"
  - "This repo contains a CDK project written in TypeScript. I'd like you to migrate it to Pulumi python"
  - "Begin converting the CDK code. Use the Pulumi AWS Cloud Control provider"
  - "Map any CDK constructs to Pulumi components for the migration"

  # Implicit (CDK context is implied)
  - "Our CloudFormation stacks were created by CDK originally"
  - "The cdk.out folder has the synthesized CloudFormation templates"