home / skills / pulumi / agent-skills / pulumi-terraform-to-pulumi

pulumi-terraform-to-pulumi skill

safe

/migration/skills/pulumi-terraform-to-pulumi

This skill helps migrate Terraform projects to Pulumi by translating HCL to Pulumi code and configuring stacks across languages.

npx playbooks add skill pulumi/agent-skills --skill pulumi-terraform-to-pulumi

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

3.1 KB

---
name: pulumi-terraform-to-pulumi
description: Migrate Terraform projects to Pulumi. Use when users need to move infrastructure from Terraform to Pulumi, translate HCL configurations, or convert Terraform modules to Pulumi components.
---

# Migrating from Terraform to Pulumi

First establish scope and plan the migration by working out with the user:

- where the Terraform sources are (`${terraform_dir}`)
- where the migrated Pulumi project lives (`${pulumi_dir}`)
- what is the target Pulumi language (such as TypeScript, Python, YAML)
- whether migration aims to setup Pulumi stack states, or only translate source code

Confirm the plan with the user before proceeding.

Create a new Pulumi project in `${pulumi_dir}` in the chosen language. Edit sources to be empty and not declare any
resources. Ensure a Pulumi stack exists.

You must run `pulumi_up` tool before proceeding to ensure initial stack state is written.

Now produce a draft Pulumi state translation:

    pulumi plugin run terraform-migrate -- stack \
        --from ${terraform_dir} \
        --to ${pulumi_dir} \
        --out /tmp/pulumi-state.json \
        --plugins /tmp/required-providers.json

Do NOT install the plugin as it will auto-install as needed.

Sometimes terraform-migrate plugin fails because `tofu refresh` is not authorized. DO NOT skip this step. Work with the
user to find or build a Pulumi ESC environment to run the command in to make it succeed.

Read the generated `/tmp/required-providers.json` and install all these Pulumi providers into the new project,
respecting the suggested versions even if they downgrade an already installed provider. The file will contain records
such as `[{"name":"aws","version":"7.12.0"}]`.

Install providers as project dependencies using the language-specific package manager (NOT `pulumi plugin install`,
which only downloads plugins without adding dependencies):

    # TypeScript/JavaScript
    npm install @pulumi/[email protected]

    # Python
    pip install pulumi_aws==7.12.0

    # Go
    go get github.com/pulumi/pulumi-aws/sdk/[email protected]

    # C#
    dotnet add package Pulumi.Aws --version 7.12.0

Import the translated state draft (`/tmp/pulumi-state.json`) into the Pulumi stack:

    pulumi stack import --file /tmp/pulumi-state.json

Translate source code to match both the Terraform source and the translated state. Aim for exact match. You can consult
the state draft `/tmp/pulumi-state.json` for Pulumi resource types and names to use.

Iterate on fixing the source code until `pulumi_preview` tool confirms that there are no changes to make and the diff
is empty or almost empty. Provider diffs or diffs on tags may be OK.

Offer the user to link an ESC environment to the stack so that each Pulumi stack can seamlessly have access to the
provider credentials it needs.

When all looks good, create a Pull Request with the migrated source code.

IMPORTANT:

- when creating a Pulumi project, do NOT use /workspace, create one under the checked out project
- do NOT run `pulumi convert`, instead use the terraform-migrate plugin
- do NOT run `pulumi package add terraform-module`

Overview

This skill migrates Terraform projects into Pulumi projects, translating HCL configurations and Terraform modules into Pulumi language code and state. It guides the end-to-end process: planning scope, producing a Pulumi state draft, installing matching providers, importing state, and iterating code until the Pulumi preview matches the original Terraform deployment. The goal is a reproducible Pulumi project and a clean pull request-ready codebase.

How this skill works

I inspect your Terraform directory and work with you to define the target Pulumi directory and language. I run the terraform-migrate plugin to produce a Pulumi state draft, install provider packages at the versions suggested by the plugin, import the generated state into a Pulumi stack, and then translate and adjust source code until pulumi preview shows no unexpected changes. I also help set up a Pulumi ESC environment if authorization or provider credentials are required for refresh operations.

When to use it

You want to move infrastructure from Terraform to Pulumi while preserving state.
You need a code translation from HCL (Terraform) to TypeScript, Python, Go, or C# Pulumi code.
You must convert Terraform modules into Pulumi components for reuse.
You need a reproducible imported Pulumi stack that matches existing Terraform-managed resources.
You want guidance on provider version alignment and project dependency installation.

Best practices

Plan scope up front: identify terraform_dir, pulumi_dir, target language, and whether to migrate state or only code.
Create a fresh Pulumi project inside the checked-out repository (not /workspace) and ensure an empty project file and stack exist before importing state.
Always run pulumi_up (or equivalent) to ensure initial stack metadata exists before running migration steps.
Use the terraform-migrate plugin (terraform-migrate) to produce /tmp/pulumi-state.json and required-providers output; do not use pulumi convert.
Install providers via the language package manager at the exact versions recommended (npm, pip, go get, dotnet) before importing state.
Iterate on code until pulumi preview shows no diffs; accept minor provider/tag diffs only after validating they are safe.

Example use cases

Migrate a multi-environment AWS Terraform setup to Pulumi TypeScript while preserving remote state.
Translate a collection of Terraform modules into Pulumi components for internal reuse.
Convert an existing Terraform-managed GCP project to Pulumi Python and import current resources into a new Pulumi stack.
Upgrade a team from Terraform to Pulumi while keeping provider versions aligned to avoid drift.
Set up an ESC environment to allow terraform-migrate refresh operations that require provider credentials.

FAQ

Do I need to install the terraform-migrate plugin manually?

No. The plugin auto-installs when invoked; do not preinstall it. Run the migration command and let it manage installation.

What if terraform-migrate fails due to authorization during refresh?

Do not skip refresh. Work to provide credentials by linking or building a Pulumi ESC environment with required provider access so the refresh can succeed.

Should I use pulumi convert or pulumi package add terraform-module?

No. Use the terraform-migrate plugin as described. Avoid pulumi convert and pulumi package add terraform-module for this migration.