Skip to content
Terraform to Pulumi Migration

Terraform to Pulumi Migration Skill

Pulumi's official migration skill for moving Terraform or OpenTofu projects to Pulumi — translating HCL and importing tfstate without recreating live infrastructure.

GitHub Docs

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from pulumi/agent-skills.

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

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

Copy the whole skill folder — SKILL.md and any scripts or references beside it — into ~/.claude/skills/pulumi-terraform-to-pulumi/, where Claude Code picks it up in every project. Only git is needed.

tmp=$(mktemp -d) && \
  git clone --depth 1 --branch main https://github.com/pulumi/agent-skills.git "$tmp" && \
  mkdir -p ~/.claude/skills && \
  cp -R "$tmp"/migration/skills/pulumi-terraform-to-pulumi ~/.claude/skills/pulumi-terraform-to-pulumi

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/pulumi-terraform-to-pulumi/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/

About

  • Translates HCL sources into TypeScript, Python or YAML Pulumi programs
  • Imports existing Terraform state into a Pulumi stack instead of recreating resources
  • Uses the terraform-migrate plugin, explicitly forbidding `pulumi convert`
  • Pulls state from remote backends (S3, Pulumi Cloud, Terraform Cloud) when no local .tfstate exists
  • Requires scope and target language to be agreed with the user before any change

Migrating infrastructure-as-code between tools is dangerous in a specific way: translate the source but lose the state mapping, and the next up destroys and recreates production. pulumi-terraform-to-pulumi is Pulumi's official agent skill for doing the migration the safe way.

The workflow it enforces starts with agreement, not action. Before touching anything the agent must establish where the Terraform sources live, where the Pulumi project should go, which target language to emit (TypeScript, Python, YAML), and — the important question — whether the goal is to carry the stack state across or merely translate the source code. Only then does it create an empty Pulumi project, declare no resources, and run pulumi_up so an initial stack state exists to import into.

It is equally explicit about what not to do, which is where most hand-rolled migrations go wrong:

  • Do not run pulumi convert — the skill routes through the terraform-migrate plugin instead, because that is what preserves the state mapping.
  • Do not run pulumi package add terraform-module; that is a different workflow entirely.
  • Do not create the Pulumi project outside the checked-out repository.

When no local .tfstate is present, the skill assumes a remote backend — S3, Pulumi Cloud, Terraform Cloud — and pulls it with terraform state pull > terraform.tfstate before continuing.

It ships as part of Pulumi's migration plugin group alongside skills for AWS CDK, CloudFormation and Azure ARM/Bicep migrations, and a Pulumi Cloud Discovery-based path for stacks you no longer have templates for. Install with /plugin install pulumi-migration, or /plugin install pulumi for the full end-user set. Apache-2.0.

Best for teams with a real Terraform estate they need to move, not for evaluating Pulumi against Terraform — the skill explicitly declines to trigger on comparison questions.

Try it

Once installed, ask your agent something like:

Migrate the Terraform project in ./infra to a Pulumi TypeScript program and import the existing state from our S3 backend.

SKILL.md

The instructions your agent loads, as published by Pulumi.

SKILL.md
name
pulumi-terraform-to-pulumi
description
Migrate Terraform/OpenTofu projects to Pulumi, including translating HCL source code and/or importing Terraform state into a Pulumi stack. Use when a user wants to convert Terraform to Pulumi, migrate from HCL, or import tfstate into Pulumi. Do NOT trigger for general Terraform-vs-Pulumi comparisons or questions about using both tools side-by-side.

Migrating from Terraform to Pulumi

Critical constraints — read before acting:
- Do NOT run pulumi convert — use the terraform-migrate plugin instead, which preserves state mapping.
- Do NOT run pulumi package add terraform-module — this is for a different workflow.
- Do NOT create the Pulumi project under /workspace — create it inside the checked-out repo.
- Replace ${terraform_dir} and ${pulumi_dir} below with the actual paths confirmed with the user.

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.

If no local .tfstate file exists in ${terraform_dir}, the state may be in a remote backend (S3, Pulumi Cloud, Terraform Cloud, etc.). Pull it before proceeding:

cd ${terraform_dir} && terraform state pull > terraform.tfstate

This works for all backends, including Pulumi Cloud. If terraform is not available, try tofu state pull instead.

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 that provides the necessary credentials so the command can succeed. If setting up an ESC environment is not feasible, inform the user that the migration cannot proceed automatically.

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/aws@7.12.0

# Python
pip install pulumi_aws==7.12.0

# Go
go get github.com/pulumi/pulumi-aws/sdk/v7@v7.12.0

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

Install
New

Microsoft's official skill for preparing apps for Azure with the Azure Developer CLI: writes a deployment plan first, then generates azure.yaml, Bicep or Terraform infrastructure and Dockerfiles before handing off to validation.

Skill: Azure Deploy

by Microsoft

New

Microsoft's official skill for executing Azure deployments of already-prepared apps: it checks for a validated deployment plan, runs azd up, azd deploy, terraform apply or az deployment with error recovery, then verifies endpoints and RBAC roles.

Browse all skills →