When to Choose Terraform Over Pulumi

Introduction: Terraform vs Pulumi

Infrastructure as Code (IaC) has become a cornerstone of modern cloud engineering. Two of the most prominent tools in this space are Terraform, developed by HashiCorp, and Pulumi, a newer entrant that leverages general-purpose programming languages. While both tools aim to declaratively provision and manage cloud resources, they take fundamentally different approaches. This tutorial explores when you should choose Terraform over Pulumi, with practical examples and best practices.

What Is Terraform?

Terraform is an open-source IaC tool that uses HashiCorp Configuration Language (HCL), a declarative domain-specific language (DSL), to define infrastructure. It follows a declarative model where you describe the desired end state, and Terraform figures out how to reach it. Terraform uses a directed acyclic graph (DAG) to determine resource dependencies and orchestrate creation and destruction in the correct order.

What Is Pulumi?

Pulumi is an IaC tool that allows developers to define infrastructure using familiar programming languages such as TypeScript, Python, Go, C#, and Java. Instead of a DSL, Pulumi uses a real programming language, enabling loops, conditionals, functions, and object-oriented patterns directly in infrastructure code.

Why the Choice Matters

Selecting the right IaC tool is not just a matter of preference. It affects team productivity, onboarding time, maintainability, ecosystem integration, and long-term operational costs. A poor choice can lead to fragmented infrastructure code, difficult audits, and vendor lock-in. Understanding the strengths of each tool helps you make an informed decision that aligns with your team's skills and organizational goals.

When to Choose Terraform Over Pulumi

1. Your Team Already Knows HCL

If your operations or DevOps team has invested years in HCL, switching to Pulumi means retraining everyone in a programming language. Terraform's learning curve is relatively gentle for infrastructure-focused engineers who may not have deep software development backgrounds.

2. You Need a Mature Ecosystem

Terraform has been around since 2014 and boasts the largest provider ecosystem in the IaC world. The Terraform Registry hosts thousands of providers covering AWS, Azure, Google Cloud, Kubernetes, and hundreds of SaaS platforms. Pulumi's ecosystem is growing but still lags behind in breadth and community-contributed modules.

3. Compliance and Audit Requirements

Terraform's declarative HCL is easier to audit than imperative programming code. Security and compliance teams can review a Terraform plan and predict exactly what will change. With Pulumi, the logic embedded in loops and conditionals can make it harder to predict the final state without actually running the code.

4. You Want Predictable State Management

Terraform's state file is a straightforward JSON document that maps resources to their real-world counterparts. While state management has its challenges, the model is well understood. Pulumi's state management is also robust, but the abstraction layer over programming languages can introduce subtle state drift issues when logic changes between runs.

5. Broad Community and Hiring Pool

Terraform skills are more widely available in the job market. If you anticipate scaling your team or hiring contractors, Terraform knowledge is easier to find. Job postings consistently list Terraform more frequently than Pulumi.

6. You Rely on Terraform Modules and Patterns

The Terraform community has produced a wealth of battle-tested modules, such as the AWS modules from the terraform-aws-modules organization. These modules implement best practices for VPCs, EKS clusters, security groups, and more. Reusing them saves significant time and reduces errors.

How to Use Terraform: A Practical Example

Let's walk through a practical example that provisions an AWS S3 bucket and a DynamoDB table. This example demonstrates Terraform's declarative approach and highlights why it excels in simplicity and readability.

Project Structure

terraform-project/
├── main.tf
├── variables.tf
├── outputs.tf
└── providers.tf

Defining the Provider

Create a providers.tf file to configure the AWS provider:

terraform {
  required_version = ">= 1.5.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = var.aws_region
}

Defining Variables

Create a variables.tf file to parameterize your configuration:

variable "aws_region" {
  description = "The AWS region to deploy resources in"
  type        = string
  default     = "us-east-1"
}

variable "project_name" {
  description = "Name of the project, used for resource naming"
  type        = string
  default     = "my-app"
}

variable "environment" {
  description = "Deployment environment (dev, staging, prod)"
  type        = string
  default     = "dev"
}

Defining Resources

Create a main.tf file with the actual infrastructure resources:

resource "aws_s3_bucket" "app_data" {
  bucket = "${var.project_name}-${var.environment}-data"

  tags = {
    Name        = "${var.project_name}-data"
    Environment = var.environment
    ManagedBy   = "terraform"
  }
}

resource "aws_s3_bucket_versioning" "app_data" {
  bucket = aws_s3_bucket.app_data.id

  versioning_configuration {
    status = "Enabled"
  }
}

resource "aws_s3_bucket_server_side_encryption_configuration" "app_data" {
  bucket = aws_s3_bucket.app_data.id

  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm = "AES256"
    }
  }
}

resource "aws_dynamodb_table" "app_sessions" {
  name         = "${var.project_name}-${var.environment}-sessions"
  billing_mode = "PAY_PER_REQUEST"
  hash_key     = "SessionId"

  attribute {
    name = "SessionId"
    type = "S"
  }

  tags = {
    Name        = "${var.project_name}-sessions"
    Environment = var.environment
    ManagedBy   = "terraform"
  }
}

Defining Outputs

Create an outputs.tf file to expose important values:

output "s3_bucket_name" {
  description = "Name of the S3 bucket"
  value       = aws_s3_bucket.app_data.id
}

output "s3_bucket_arn" {
  description = "ARN of the S3 bucket"
  value       = aws_s3_bucket.app_data.arn
}

output "dynamodb_table_name" {
  description = "Name of the DynamoDB table"
  value       = aws_dynamodb_table.app_sessions.name
}

output "dynamodb_table_arn" {
  description = "ARN of the DynamoDB table"
  value       = aws_dynamodb_table.app_sessions.arn
}

Running Terraform

Execute the following commands to deploy your infrastructure:

# Initialize the working directory
terraform init

# Validate the configuration
terraform validate

# Format the code
terraform fmt

# Preview the changes
terraform plan

# Apply the changes
terraform apply

# Destroy when no longer needed
terraform destroy

Comparing the Same Infrastructure in Pulumi

To illustrate the difference, here is the equivalent infrastructure written in Pulumi using TypeScript. Notice how the logic is embedded in a programming language:

import * as aws from "@pulumi/aws";
import * as pulumi from "@pulumi/pulumi";

const config = new pulumi.Config();
const projectName = pulumi.getProject();
const environment = config.get("environment") ?? "dev";

const bucket = new aws.s3.Bucket(`${projectName}-${environment}-data`, {
  tags: {
    Name: `${projectName}-data`,
    Environment: environment,
    ManagedBy: "pulumi",
  },
});

new aws.s3.BucketVersioning(`${projectName}-${environment}-data-versioning`, {
  bucket: bucket.id,
  versioningConfiguration: {
    status: "Enabled",
  },
});

new aws.s3.BucketServerSideEncryptionConfiguration(
  `${projectName}-${environment}-data-encryption`,
  {
    bucket: bucket.id,
    rules: [
      {
        applyServerSideEncryptionByDefault: {
          sseAlgorithm: "AES256",
        },
      },
    ],
  }
);

const table = new aws.dynamodb.Table(`${projectName}-${environment}-sessions`, {
  billingMode: "PAY_PER_REQUEST",
  hashKey: "SessionId",
  attributes: [
    {
      name: "SessionId",
      type: "S",
    },
  ],
  tags: {
    Name: `${projectName}-sessions`,
    Environment: environment,
    ManagedBy: "pulumi",
  },
});

export const s3BucketName = bucket.id;
export const s3BucketArn = bucket.arn;
export const dynamodbTableName = table.name;
export const dynamodbTableArn = table.arn;

While the Pulumi version is familiar to developers who know TypeScript, it introduces programming constructs that can complicate audits. A reviewer must mentally execute the code to understand the final infrastructure state. Terraform's HCL, by contrast, is purely declarative and easier to reason about at a glance.

Best Practices When Using Terraform

1. Use a Module-Based Architecture

Break your infrastructure into reusable modules. Each module should have a single responsibility, such as networking, database, or compute. This approach mirrors software engineering principles and makes your codebase maintainable.

module "vpc" {
  source = "terraform-aws-modules/vpc/aws"

  name = "${var.project_name}-vpc"
  cidr = "10.0.0.0/16"

  azs             = ["us-east-1a", "us-east-1b", "us-east-1c"]
  private_subnets = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
  public_subnets  = ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"]

  enable_nat_gateway = true
  single_nat_gateway = true
}

module "eks" {
  source = "terraform-aws-modules/eks/aws"

  cluster_name    = "${var.project_name}-cluster"
  cluster_version = "1.28"

  vpc_id     = module.vpc.vpc_id
  subnet_ids = module.vpc.private_subnets

  eks_managed_node_groups = {
    default = {
      instance_types = ["t3.medium"]
      min_size       = 1
      max_size       = 3
      desired_size   = 2
    }
  }
}

2. Manage State Remotely and Securely

Never store Terraform state locally in a shared project. Use remote backends such as AWS S3 with DynamoDB locking, Terraform Cloud, or HashiCorp Consul. This ensures team collaboration and prevents state corruption.

terraform {
  backend "s3" {
    bucket         = "my-terraform-state-bucket"
    key            = "prod/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-locks"
    encrypt        = true
  }
}

3. Pin Provider Versions

Always pin your provider versions to avoid unexpected breaking changes. Use the required_providers block with specific version constraints.

4. Use Workspaces or Separate Directories for Environments

Separate environments (dev, staging, production) using either Terraform Workspaces or separate directories. Many teams prefer separate directories because they provide stronger isolation and make it easier to manage different variable files per environment.

environments/
├── dev/
│   ├── main.tf
│   ├── variables.tf
│   └── terraform.tfvars
├── staging/
│   ├── main.tf
│   ├── variables.tf
│   └── terraform.tfvars
└── prod/
    ├── main.tf
    ├── variables.tf
    └── terraform.tfvars

5. Run terraform fmt and terraform validate in CI

Integrate terraform fmt -check and terraform validate into your CI pipeline. This ensures that all code merged into your repository is properly formatted and syntactically correct before it reaches production.

6. Use terraform plan in Pull Requests

Configure your CI system to run terraform plan on every pull request and post the output as a comment. This gives reviewers visibility into exactly what infrastructure changes a PR will make.

7. Tag Everything Consistently

Use a consistent tagging strategy across all resources. Tags are critical for cost allocation, access control, and resource discovery. Consider using a default_tags block in your provider configuration:

provider "aws" {
  region = var.aws_region

  default_tags {
    tags = {
      Project     = var.project_name
      Environment = var.environment
      ManagedBy   = "terraform"
      Owner       = "platform-team"
    }
  }
}

When Pulumi Might Actually Be Better

For balance, it is worth acknowledging scenarios where Pulumi shines. If your team is composed primarily of software engineers who are already proficient in TypeScript or Python, Pulumi's learning curve will be lower. Pulumi also excels when you need complex conditional logic that would be awkward in HCL, such as generating resources based on dynamic data structures fetched from an API at runtime. Additionally, Pulumi's ability to share types and logic between application code and infrastructure code can reduce duplication in certain architectures.

Conclusion

Choosing between Terraform and Pulumi ultimately depends on your team's composition, existing tooling, and organizational requirements. Terraform remains the stronger choice when you value a mature ecosystem, a large hiring pool, declarative simplicity for audits, and a vast library of community modules. Its HCL-based approach makes infrastructure code predictable and accessible to operations-focused engineers. Pulumi is an excellent tool in its own right, particularly for developer-heavy teams who want to leverage their existing programming skills. By understanding the trade-offs outlined in this tutorial, you can make an informed decision that serves your infrastructure needs both today and as your organization scales.