Pulumi vs Terraform

By Michael Samuel Naeem · November 9, 2024 · 5 min read

The platform team spent six weeks building a custom HCL generator because their provisioning logic needed conditionals, loops, and unit tests that Terraform's language fought at every turn. Meanwhile, the product infrastructure group next door shipped the same AWS topology in TypeScript with Pulumi in nine days, importing shared VPC helpers from an internal npm package. Neither tool is universally better — but pretending the choice is only "declarative YAML vs declarative YAML" misses why teams switch.

Language model: HCL vs general-purpose code

Terraform's HashiCorp Configuration Language is purpose-built for infrastructure. It handles graphs, dependencies, and providers well, but complex abstractions — dynamic nested blocks, conditional module instantiation, string manipulation beyond basics — push teams toward code generation or ugly workarounds.

Pulumi lets you write infrastructure in TypeScript, Python, Go, Java, C#, or YAML. Real code means real IDE support: go-to-definition, refactoring, type checking, and standard test frameworks.

// Pulumi — conditional RDS with typed config
import * as aws from "@pulumi/aws";
import * as pulumi from "@pulumi/pulumi";

const config = new pulumi.Config();
const env = config.require("environment");

const instance = env === "prod"
  ? new aws.rds.Instance("db", {
      engine: "postgres",
      instanceClass: "db.r6g.large",
      multiAz: true,
    })
  : new aws.rds.Instance("db", {
      engine: "postgres",
      instanceClass: "db.t4g.micro",
      multiAz: false,
    });

# Terraform — equivalent conditional
variable "environment" { type = string }

resource "aws_db_instance" "db" {
  engine          = "postgres"
  instance_class  = var.environment == "prod" ? "db.r6g.large" : "db.t4g.micro"
  multi_az        = var.environment == "prod"
}

For simple conditionals, HCL is fine. When infrastructure code shares business logic with application code — feature flags, tenancy rules, cost allocation tags computed from a billing database — Pulumi's general-purpose languages reduce duplication.

Ecosystem and provider coverage

Terraform's provider ecosystem is larger and matures faster for niche SaaS integrations. The Terraform Registry hosts thousands of verified modules; terraform init pulls providers with a workflow every hiring manager recognizes.

Pulumi packages mirror most major cloud providers and increasingly wrap Terraform providers through bridged resources. Coverage gaps still appear for obscure providers — always verify your required resources exist in Pulumi's registry before committing. For AWS, GCP, Azure, and Kubernetes, both tools are production-ready.

State, secrets, and drift

Both tools need remote state with locking for team use. Terraform defaults to local terraform.tfstate until you configure a backend; Pulumi defaults to Pulumi Cloud but supports self-managed S3-compatible backends.

Secrets deserve attention in both: neither tool should store plaintext secrets in state if avoidable. Use your cloud's secret manager, reference values at deploy time, and mark sensitive outputs accordingly. pulumi stack export and terraform state pull both reveal what is stored — treat state buckets as highly privileged resources.

Drift detection works similarly: terraform plan and pulumi preview compare desired state against actual APIs. Scheduled drift runs in CI catch manual console changes regardless of tool.

Testing and CI integration

Pulumi's language choice enables standard unit tests — mock providers, assert resource properties, run in Jest or pytest without standing up cloud resources. Terraform testing historically relied on terraform plan in CI, Terratest in Go, or commercial tools like Spacelift and env0.

// Pulumi unit test with @pulumi/testing
import * as pulumi from "@pulumi/pulumi";
pulumi.runtime.setMocks({
  newResource: (args) => ({ id: args.name + "_id", state: args.inputs }),
});

// Assert instance class in test runner

Terraform 1.6+ added native terraform test with mock providers, closing some of the gap. If testing is a primary requirement, evaluate both tools' current testing story against your language preferences rather than assuming Pulumi still leads.

Team operations and hiring

Terraform skills transfer across employers because HCL and workflow are industry-standard keywords on job postings. Pulumi skills correlate with whichever language your stack uses — valuable internally, less portable on a resume dominated by Terraform listings.

Policy-as-code differs: Terraform has Sentinel (Terraform Cloud enterprise) and Open Policy Agent integrations; Pulumi has CrossGuard policies written in the same language as your infrastructure code. Pick based on whether your compliance team already runs OPA.

When to choose which

Choose Terraform when provider coverage for your stack is non-negotiable, your team already knows HCL, you rely on the public module ecosystem, and your infrastructure logic stays declarative without heavy computation.

Choose Pulumi when your team is fluent in TypeScript or Python, you want infrastructure in the same monorepo with shared libraries, complex provisioning logic mirrors application code, or IDE-driven development matters more than the largest module registry.

Many organizations run Terraform for core cloud foundations and Pulumi for application-specific resources provisioned by product teams. That split works if boundaries are clear; it fails if two tools manage the same resources without coordination.

Common production mistakes

Teams get pulumi vs terraform wrong in predictable ways:

• Skipping failure-mode rehearsal — run a game day or fault injection exercise before peak traffic, not after the first outage.
• Missing correlation context — every error path should carry request, trace, or tenant identifiers so incidents are debuggable.
• Optimizing for demo, not steady state — load tests, cache warm-up, and cold-start paths matter more than local dev latency.
• Undocumented trade-offs — if you chose speed over strict correctness (or vice versa), write that down for the next engineer.

Production implementations of pulumi vs terraform fail when staging mirrors production topology poorly, rollback is untested, and on-call runbooks describe the happy path only.

Debugging and triage workflow

When pulumi vs terraform misbehaves in production, work top-down instead of guessing:

1. Confirm scope — one tenant, region, or deployment stage? Narrow blast radius before deep diving.
2. Check recent changes — deploys, flag flips, config pushes, and schema migrations in the last 24 hours.
3. Compare golden signals — latency, error rate, saturation, and traffic for the affected surface vs. baseline.
4. Reproduce minimally — smallest input or scenario that triggers the failure; capture traces/logs with correlation IDs.
5. Fix forward or rollback — if rollback is faster than root-cause during incident, rollback first, postmortem second.
6. Add a guard — alert, integration test, or circuit breaker so the same class of failure is caught earlier next time.

Document the timeline during triage. Future you (and on-call) will need timestamps, not just conclusions.

Resources

• Pulumi documentation
• Terraform documentation
• Pulumi vs Terraform — official comparison
• Terraform AWS provider registry
• Pulumi AWS classic provider