Migrate from Terraform to Pulumi

By Pulumi Team
Published
Updated
Terraform Migration

The Challenge

You have infrastructure managed by Terraform and want to migrate to Pulumi. You need a clear understanding of the migration path, available tooling, how to handle state and live resources, and best practices for making the transition without disrupting running infrastructure.

What You'll Build

  • → Pulumi program converted from your Terraform HCL
  • → Existing cloud resources imported into Pulumi state
  • → Project structure following Pulumi best practices
  • → No disruption to running infrastructure during migration

Neo Try This Prompt in Pulumi Neo

Run this prompt in Neo to deploy your infrastructure, or edit it to customize.

Best For

Use this prompt when you’re planning a migration from Terraform to Pulumi or evaluating whether to migrate. Useful for platform teams considering Pulumi, architects planning infrastructure modernization, or engineers who want to move from HCL to general-purpose programming languages.

Architecture Overview

Migrating from Terraform to Pulumi is not a single operation but a process with several stages. The typical path starts with converting HCL configuration to a Pulumi program, importing existing cloud resources into Pulumi state, validating that Pulumi’s view matches reality, and then iterating on the code to take advantage of Pulumi’s programming language features.

The conversion itself can be automated. Pulumi provides pulumi convert --from terraform, which translates HCL files into Pulumi programs in your chosen language (TypeScript, Python, Go, C#, or Java). The output is a working Pulumi program that provisions the same resources. From there, you refactor the generated code into idiomatic patterns, extract reusable components, add type safety, and integrate with your existing development workflows.

The critical concern during migration is handling live resources. You do not want to destroy and recreate infrastructure that is already running. Pulumi’s pulumi import command adopts existing cloud resources into Pulumi state without modifying them. Once imported, Pulumi manages the resource going forward. This lets you migrate incrementally, moving resources one stack at a time rather than doing a risky all-at-once cutover.

Code Conversion

The pulumi convert command reads your .tf files and generates equivalent Pulumi code. It handles resources, data sources, variables, outputs, and most built-in functions. Complex modules may need manual adjustment, but the converter handles the mechanical translation so you can focus on the structural improvements that motivated the migration.

State and Resource Import

Terraform state maps resource names to cloud resource IDs. Pulumi maintains an equivalent state file. During migration, you use pulumi import to bring existing resources under Pulumi management. This creates the state entries without modifying the actual cloud resources, so there is no downtime or disruption.

Incremental Migration

Most teams migrate incrementally rather than converting everything at once. You can run Terraform and Pulumi side by side, migrating one project or environment at a time. This reduces risk and lets the team build familiarity with Pulumi before tackling more complex infrastructure.

Common Customizations

  • Target a specific language: Specify your preferred language in the prompt (e.g., “convert to TypeScript” or “convert to Python”) to get migration guidance tailored to that ecosystem.
  • Focus on a specific provider: If your Terraform code uses a particular provider heavily (AWS, Azure, GCP), ask for provider-specific migration tips and gotchas.
  • Ask about module conversion: If you have custom Terraform modules, ask how to convert them into Pulumi component resources for better reuse and encapsulation.
  • Request CI/CD integration guidance: Ask how to set up Pulumi in your existing CI/CD pipeline to replace Terraform’s plan/apply workflow with Pulumi’s preview/up workflow.