migrating toBrowse playbooks
← All playbooks
Infrastructure as code migration

Terraform → Pulumi

Move configuration source and language, state, resource addresses, and provider ids, providers, resources, and schema versions, modules, components, and reusable libraries, backends, locking, encryption, and history, secrets, variables, configuration, and environments, imports, moves, aliases, and replacements, plans, previews, policy, and approvals from Terraform to Pulumi with a reversible cutover, explicit exception ledger, and evidence-backed verification.

Typical timeline15–45 business days70–180 hours active work
Statusneeds review
Source profileTerraform documentation reviewed 2026-07-20
Destination profilePulumi documentation reviewed 2026-07-20
Documentation date
Review window
Evidence2 sources
This route needs review.Use it as a planning baseline, then verify the dated sources and test with representative data before production.
Before you migrate

Should you make this move?

Both platforms have a case. Compare what you gain with what you give up before scheduling the cutover.

Current platform

Terraform

Reasons to stay
  • A vast provider and module ecosystem makes declarative multi-cloud infrastructure broadly understood
  • Declarative infrastructure makes environments reviewable, repeatable, and automatable
Reasons to leave
  • State safety, provider upgrades, licensing changes, and complex HCL systems demand careful governance
  • State identity, provider behavior, secrets, and plans must remain aligned to avoid destructive changes
New platform

Pulumi

What gets better
  • General-purpose languages, component abstractions, testing, and managed state make infrastructure familiar to developers
  • Declarative infrastructure makes environments reviewable, repeatable, and automatable
What gets worse
  • Language runtimes, generated state, provider bridges, and Pulumi-specific URNs add migration complexity
  • State identity, provider behavior, secrets, and plans must remain aligned to avoid destructive changes
Best of the move

Pulumi: General-purpose languages, component abstractions, testing, and managed state make infrastructure familiar to developers. This removes a major source-side concern: State safety, provider upgrades, licensing changes, and complex HCL systems demand careful governance.

Worst of the move

What you lose: A vast provider and module ecosystem makes declarative multi-cloud infrastructure broadly understood. What you inherit: Language runtimes, generated state, provider bridges, and Pulumi-specific URNs add migration complexity.

Connected catalog

2 destinations are documented from Terraform. Compare nearby routes before committing.

Also from Terraform
Also moving to Pulumi
Jump to a section
01At a glance

Know the shape of the move.

Transfer outcome10 features audited
Transfer outcome distributionClean transfer: 0, Partial transfer: 4, Manual rebuild: 5, Not transferred: 1.
Clean0
Partial4
Manual5
Lost1
Mapping route9 of 9 fields have a destination path

This timeline assumes

  • Up to 200 stacks, 20,000 managed resources, 500 modules, and 100 deployment pipelines
  • Administrators control both Terraform and Pulumi, including billing, identity, APIs, integrations, and export permissions.
  • Terraform remains intact and recoverable until Pulumi completes one representative operating cycle.
  • A production-shaped pilot includes every object type, access class, edge case, and failure path.
  • The migration team preserves stable source identifiers and records durable evidence for every blocking check.
02What transfers

What survives the move.

“Partial” and “manual” are not footnotes. They are work that must be scheduled and verified.

ItemOutcomeImpactWhat happensMitigation
Configuration source and languagepartialcriticalHCL compatibility, general-purpose language semantics, generated code, and project layout require review. A successful bulk job therefore does not prove semantic parity between Terraform and Pulumi.Map configuration source and language explicitly, pilot every feature class, and reconcile accepted, changed, rejected, and excluded items.
State, resource addresses, and provider IDspartialcriticalState formats, addresses, lineage, serials, URNs, aliases, and provider identifiers must remain aligned. A successful bulk job therefore does not prove semantic parity between Terraform and Pulumi.Map state, resource addresses, and provider ids explicitly, pilot every feature class, and reconcile accepted, changed, rejected, and excluded items.
Providers, resources, and schema versionspartialcriticalProvider packages, forks, versions, defaults, unsupported resources, and upgrade behavior differ. A successful bulk job therefore does not prove semantic parity between Terraform and Pulumi.Map providers, resources, and schema versions explicitly, pilot every feature class, and reconcile accepted, changed, rejected, and excluded items.
Modules, components, and reusable librariespartialhighModule sources, component abstractions, inputs, outputs, and version constraints require conversion. A successful bulk job therefore does not prove semantic parity between Terraform and Pulumi.Map modules, components, and reusable libraries explicitly, pilot every feature class, and reconcile accepted, changed, rejected, and excluded items.
Backends, locking, encryption, and historymanualcriticalRemote state services, locks, encryption, retention, and recovery use different controls. A successful bulk job therefore does not prove semantic parity between Terraform and Pulumi.Inventory and rebuild backends, locking, encryption, and history, then test normal, edge, failure, and rollback behavior.
Secrets, variables, configuration, and environmentsmanualcriticalSecret stores, sensitivity, environment inheritance, stacks, and variable precedence differ. A successful bulk job therefore does not prove semantic parity between Terraform and Pulumi.Inventory and rebuild secrets, variables, configuration, and environments, then test normal, edge, failure, and rollback behavior.
Imports, moves, aliases, and replacementsmanualcriticalResource adoption and refactoring operations can silently schedule destructive replacement. A successful bulk job therefore does not prove semantic parity between Terraform and Pulumi.Inventory and rebuild imports, moves, aliases, and replacements, then test normal, edge, failure, and rollback behavior.
Plans, previews, policy, and approvalsmanualcriticalDiff rendering, saved plans, policy engines, approvals, and drift controls need reconstruction. A successful bulk job therefore does not prove semantic parity between Terraform and Pulumi.Inventory and rebuild plans, previews, policy, and approvals, then test normal, edge, failure, and rollback behavior.
CI/CD, runners, identities, and cloud accessmanualcriticalWorkflow commands, plugins, credentials, OIDC, caches, and concurrent applies change. A successful bulk job therefore does not prove semantic parity between Terraform and Pulumi.Inventory and rebuild ci/cd, runners, identities, and cloud access, then test normal, edge, failure, and rollback behavior.
Run history, drift evidence, and rollbacklosthighHistorical plans, logs, policy results, and state versions do not all transfer as native history. A successful bulk job therefore does not prove semantic parity between Terraform and Pulumi.Archive run history, drift evidence, and rollback as dated source evidence and define the new destination baseline.
03Field and feature mapping

Where each thing goes.

SourceDestinationMethodNotes
Terraform: Configuration source and languagePulumi: approved configuration source and language representationtransformPreserve source IDs, ownership, timestamps, access intent, and an explicit exception status for configuration source and language.
Terraform: State, resource addresses, and provider IDsPulumi: approved state, resource addresses, and provider ids representationtransformPreserve source IDs, ownership, timestamps, access intent, and an explicit exception status for state, resource addresses, and provider ids.
Terraform: Providers, resources, and schema versionsPulumi: approved providers, resources, and schema versions representationtransformPreserve source IDs, ownership, timestamps, access intent, and an explicit exception status for providers, resources, and schema versions.
Terraform: Modules, components, and reusable librariesPulumi: approved modules, components, and reusable libraries representationtransformPreserve source IDs, ownership, timestamps, access intent, and an explicit exception status for modules, components, and reusable libraries.
Terraform: Backends, locking, encryption, and historyPulumi: approved backends, locking, encryption, and history representationmanualPreserve source IDs, ownership, timestamps, access intent, and an explicit exception status for backends, locking, encryption, and history.
Terraform: Secrets, variables, configuration, and environmentsPulumi: approved secrets, variables, configuration, and environments representationmanualPreserve source IDs, ownership, timestamps, access intent, and an explicit exception status for secrets, variables, configuration, and environments.
Terraform: Imports, moves, aliases, and replacementsPulumi: approved imports, moves, aliases, and replacements representationmanualPreserve source IDs, ownership, timestamps, access intent, and an explicit exception status for imports, moves, aliases, and replacements.
Terraform: Plans, previews, policy, and approvalsPulumi: approved plans, previews, policy, and approvals representationmanualPreserve source IDs, ownership, timestamps, access intent, and an explicit exception status for plans, previews, policy, and approvals.
Terraform: CI/CD, runners, identities, and cloud accessPulumi: approved ci/cd, runners, identities, and cloud access representationmanualPreserve source IDs, ownership, timestamps, access intent, and an explicit exception status for ci/cd, runners, identities, and cloud access.
04Before you begin

Make the move recoverable.

Backup procedure

Create the source-of-truth backup

Preserve Terraform data, configuration, access, and operating evidence before any destination write.

  1. Export every available Terraform object and binary in scope, including configuration source and language, state, resource addresses, and provider ids, providers, resources, and schema versions, modules, components, and reusable libraries.
  2. Capture configuration and runtime dependencies for backends, locking, encryption, and history, secrets, variables, configuration, and environments, imports, moves, aliases, and replacements, plans, previews, policy, and approvals.
  3. Record counts, sizes, owners, timestamps, access classes, financial totals where applicable, and known exceptions.
  4. Hash immutable exports, record tool versions and commands, and transform working copies only.

Proof to capture: A signed manifest accounts for every scoped record class, configuration object, binary, count, total, exception, and hash.

Transformation · Version-controlled migration workbook, SQL, or typed transformation code

Identity, schema, and disposition registry

Preserve stable identity and make every mapping or exclusion reviewable.

  1. Inventory source types, identifiers, owners, states, and access.
  2. Define one approved destination representation or explicit archive decision.
  3. Reject unmapped critical items and produce an exception ledger.

Proof to capture: Save the input, output, command or tool settings, warnings, and final item counts.

Transformation · Official APIs, provider importers, checksums, and reconciliation scripts

Dependency-ordered migration package

Load prerequisite identities and configuration before dependent records and runtime actions.

  1. Normalize encoding, timestamps, identifiers, nulls, and destination limits.
  2. Run a representative pilot and retain request, response, and rejection evidence.
  3. Reconcile the final delta before enabling destination production writers.

Proof to capture: Save the input, output, command or tool settings, warnings, and final item counts.

05Handle with care

The things most likely to hurt.

These are operating limits. Treat every “Stop if” condition as a blocked migration, not a suggestion.

Import

A completed migration hides missing or altered configuration source and language

criticalpossible likelihood

Headline counts look plausible while semantic, access, or relationship checks fail.

Consequence
The destination becomes authoritative with incomplete or misleading business data.
Mitigation
Reconcile by type, state, owner, access class, and representative record rather than total count alone.

Stop if: Any critical item lacks a verified destination, approved transformation, explicit exclusion, or recoverable archive.

Cutover

Terraform and Pulumi both perform production actions

criticalpossible likelihood

Users, schedules, webhooks, integrations, or traffic continue changing both systems.

Consequence
State diverges or customers receive duplicate, contradictory, or unsafe actions.
Mitigation
Freeze source writers and transfer one production owner at a time with an approved rollback.

Stop if: An unapproved source writer or destination duplicate action appears after the freeze.

Verification

Destination access or security is broader than approved

criticalpossible likelihood

A representative restricted user can read, change, export, or trigger an unauthorized item.

Consequence
Confidential, regulated, financial, or security-sensitive data is exposed or changed.
Mitigation
Apply least privilege before bulk loading and test every access class using ordinary identities.

Stop if: Any unauthorized read, write, export, administrative action, or secret access succeeds.

06Precise timeline

Do the work in this order.

Estimate forUp to 200 stacks, 20,000 managed resources, 500 modules, and 100 deployment pipelines
Total elapsed15–45 business days
Active work70–180 hours
BufferAdd time for large Terraform exports, destination rate limits, unsupported features, identity exceptions, regulated data, or a strict downtime objective.
01
Days 1–4Inventory and decisions2–4 days
02
Days 3–8Backup and reconcile2–5 days
03
Days 6–20Map, transform, and pilot5–12 days
04
Days 18–35Bulk load, final delta, and switch2–8 days
05
Days 25–45Observe and close7–14 days
  1. Days 1–4 · inventory

    Inventory and decisions

    8–16 hours active2–4 days elapsedOwner, legal, security, and finance review waiting
    • Inventory Terraform data, configuration, identities, integrations, limits, and billing.
    • Approve scope, owners, mappings, exclusions, acceptance thresholds, and rollback authority.

    Depends on: Terraform and Pulumi administrator access

    Stop / go checkpoint

    Export?

    Go when: Every critical item and production action has an owner and disposition.

    Stop when: Authority, retention, billing, access, or system ownership is unclear.

  2. Days 3–8 · backup

    Backup and reconcile

    8–20 hours active2–5 days elapsedProvider export processing waiting
    • Create immutable data, configuration, binary, and audit exports.
    • Reconcile source counts, totals, sizes, access classes, and hashes.

    Depends on: Approved inventory and retention location

    Stop / go checkpoint

    Transform?

    Go when: The signed source manifest and exports agree.

    Stop when: Any critical dataset, binary, configuration, or recovery path is absent.

  3. Days 6–20 · pilot

    Map, transform, and pilot

    25–70 hours active5–12 days elapsedDestination processing and owner review waiting
    • Configure Pulumi and transform a production-shaped pilot.
    • Test normal records, every feature class, edge cases, permissions, failures, and rollback.

    Depends on: Verified source backup and approved mapping registry

    Stop / go checkpoint

    Scale?

    Go when: Every pilot mapping and blocking verification check passes.

    Stop when: Any critical invariant, access boundary, or production action lacks a safe destination.

  4. Days 18–35 · cutover

    Bulk load, final delta, and switch

    20–55 hours active2–8 days elapsedImports, propagation, indexing, or synchronization waiting
    • Freeze production writes and automated actions in Terraform.
    • Apply and reconcile the final delta, switch ownership to Pulumi, and run all blocking checks.

    Depends on: Passed pilot, stakeholder go decision, and rehearsed rollback

    Stop / go checkpoint

    Open production?

    Go when: Pulumi is the sole production owner and every critical exception is resolved.

    Stop when: A source writer remains active, a blocking check fails, or rollback is unavailable.

  5. Days 25–45 · observe

    Observe and close

    9–19 hours active7–14 days elapsedRepresentative operating-cycle evidence waiting
    • Monitor correctness, access, failures, latency, delivery, cost, and user outcomes.
    • Sign the verification report and close rollback only after stable evidence.

    Depends on: Verified cutover

    Stop / go checkpoint

    Close rollback?

    Go when: No trigger occurs during the approved observation period.

    Stop when: Data, access, delivery, routing, cost, or business results regress.

07The point of change

Cut over with a way back.

Go live

Cutover

Make Pulumi the only production system without losing the final Terraform delta.

Recommended window: A low-volume weekday morning with platform, data, security, networking, finance, and business owners available.

  1. Freeze user, integration, schedule, and API writes in Terraform.
  2. Capture and reconcile the final source delta against the last verified checkpoint.
  3. Apply the approved delta and configuration changes to Pulumi.
  4. Switch traffic, domains, integrations, credentials, automation, and user entry points in dependency order.
  5. Run every blocking verification check and keep the source intact.

Proof to capture: Pulumi alone owns production, totals reconcile, exceptions are signed, and every blocking check has durable evidence.

Return to safety

Rollback

Return production ownership to Terraform without losing destination-era changes.

Deadline: Within seven days and before source data, plans, credentials, domains, keys, or retention settings are changed.

  1. Stop new user, integration, schedule, and API writes in Pulumi.
  2. Restore prior Terraform traffic, domains, credentials, automation, and integration ownership.
  3. Export and classify the Pulumi post-cutover delta.
  4. Apply safe destination-era changes back to Terraform without duplicating actions.
  5. Run the same blocking checks against the restored source.

Proof to capture: Terraform again owns production with current data and no duplicate destination action.

Rollback immediately when
  • Unexplained critical count, value, relationship, or checksum variance
  • Missing, corrupted, or exposed critical data
  • Duplicate production action or unresolved split-brain state
  • Failed access, security, delivery, routing, performance, or integration check
  • A critical feature has no safe destination replacement or rollback path
08Verification report

Prove the migration worked.

Every blocking check must pass. Capture the evidence before cleanup begins.

0%
Interactive report preview0 / 8 checks passed
PassIDCheckMethodExpected resultEvidence
V-01BlockingConfiguration source and language reconciliationCompare source inventory, transformed output, destination results, and a stratified sample for configuration source and language.Every in-scope item is present, intentionally transformed, explicitly excluded, or retained in the signed source archive.Configuration source and language ledger with counts, exceptions, sample IDs, and owner sign-off.
V-02BlockingState, resource addresses, and provider IDs reconciliationCompare source inventory, transformed output, destination results, and a stratified sample for state, resource addresses, and provider ids.Every in-scope item is present, intentionally transformed, explicitly excluded, or retained in the signed source archive.State, resource addresses, and provider IDs ledger with counts, exceptions, sample IDs, and owner sign-off.
V-03BlockingProviders, resources, and schema versions reconciliationCompare source inventory, transformed output, destination results, and a stratified sample for providers, resources, and schema versions.Every in-scope item is present, intentionally transformed, explicitly excluded, or retained in the signed source archive.Providers, resources, and schema versions ledger with counts, exceptions, sample IDs, and owner sign-off.
V-04BlockingModules, components, and reusable libraries reconciliationCompare source inventory, transformed output, destination results, and a stratified sample for modules, components, and reusable libraries.Every in-scope item is present, intentionally transformed, explicitly excluded, or retained in the signed source archive.Modules, components, and reusable libraries ledger with counts, exceptions, sample IDs, and owner sign-off.
V-05BlockingBackends, locking, encryption, and history reconciliationCompare source inventory, transformed output, destination results, and a stratified sample for backends, locking, encryption, and history.Every in-scope item is present, intentionally transformed, explicitly excluded, or retained in the signed source archive.Backends, locking, encryption, and history ledger with counts, exceptions, sample IDs, and owner sign-off.
V-06BlockingSecrets, variables, configuration, and environments reconciliationCompare source inventory, transformed output, destination results, and a stratified sample for secrets, variables, configuration, and environments.Every in-scope item is present, intentionally transformed, explicitly excluded, or retained in the signed source archive.Secrets, variables, configuration, and environments ledger with counts, exceptions, sample IDs, and owner sign-off.
V-07BlockingImports, moves, aliases, and replacements reconciliationCompare source inventory, transformed output, destination results, and a stratified sample for imports, moves, aliases, and replacements.Every in-scope item is present, intentionally transformed, explicitly excluded, or retained in the signed source archive.Imports, moves, aliases, and replacements ledger with counts, exceptions, sample IDs, and owner sign-off.
V-08BlockingPlans, previews, policy, and approvals reconciliationCompare source inventory, transformed output, destination results, and a stratified sample for plans, previews, policy, and approvals.Every in-scope item is present, intentionally transformed, explicitly excluded, or retained in the signed source archive.Plans, previews, policy, and approvals ledger with counts, exceptions, sample IDs, and owner sign-off.
09Post-migration cleanup

Remove the scaffolding safely.

Safe after: One complete operating cycle, at least seven stable days, and owner sign-off on every blocking check and exception.

  1. Create final Terraform exports and archive verification, access, financial, and rollback evidence.
  2. Revoke temporary credentials, API keys, webhooks, elevated roles, and migration network access.
  3. Remove obsolete jobs, embeds, domains, integrations, collectors, routes, and DNS records.
  4. Keep the source intact and read-only through the approved legal and operational retention window.
  5. Cancel paid plans only after billing, legal, security, evidence, and recovery review.
  6. Schedule the next Pulumi backup, restore test, access review, and migration-playbook review.
10Experiences from the field

When the plan met reality.

First-hand accounts are preferred. Vendor case studies are labeled, and every note below is an editorial paraphrase—follow the link for the full context.

First-person accountOlivier Pichon · dzangolab

Pulumi 1 year later2024

Olivier Pichon evaluates Pulumi more than a year after dzangolab moved from Terraform. For a team of occasional DevOps practitioners, TypeScript improved infrastructure-as-code adoption, component resources simplified lifecycle grouping, and Pulumi Cloud removed the need to bootstrap separate state storage. The author remained frustrated by Input and Output semantics, project and stack naming, and global name collisions, yet concluded the migration met the team's requirements.

What they recommend
  • Judge programming-language IaC against the team's actual DevOps frequency and skills rather than assuming it benefits every organization equally.
  • Prototype asynchronous outputs, stack boundaries, state handling, and naming conventions before translating the full Terraform estate.
Worth noticing
  • Familiar TypeScript made infrastructure work more approachable for product developers who only handled DevOps occasionally.
  • The move reduced state-management setup while introducing conceptual friction around outputs and organization-wide naming.
Sources and evidence

Verify against the primary material.

Platform behavior changes. Check these sources and the review dates above before executing a production migration.

  1. Terraform: official portability and migration documentationAccessed 2026-07-20
  2. Pulumi: official portability and migration documentationAccessed 2026-07-20