The Pulumi Converter is a tool that lets you translate existing Terraform code into Pulumi code, allowing you to migrate your infrastructure management to Pulumi without rewriting everything from scratch.
Let’s see it in action. Imagine you have a simple Terraform configuration that creates an AWS S3 bucket:
# main.tf
resource "aws_s3_bucket" "example" {
bucket = "my-unique-pulumi-bucket-12345"
tags = {
Environment = "Dev"
ManagedBy = "Terraform"
}
}
To convert this to Pulumi, you’d first install the Pulumi CLI and the converter tool. Then, you’d navigate to the directory containing your Terraform code and run the converter:
pulumi convert --from terraform --to python
This command tells Pulumi to take input from Terraform and output Python code. After running, you’ll find a new main.py file (or similar, depending on your chosen output language) in your directory:
# main.py
import pulumi
import pulumi_aws as aws
example = aws.s3.Bucket("example",
bucket="my-unique-pulumi-bucket-12345",
tags={
"Environment": "Dev",
"ManagedBy": "Terraform",
})
You can also specify other languages like TypeScript, Go, or C#. For example, to convert to TypeScript:
pulumi convert --from terraform --to typescript
This would produce:
// index.ts
import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";
const example = new aws.s3.Bucket("example", {
bucket: "my-unique-pulumi-bucket-12345",
tags: {
Environment: "Dev",
ManagedBy: "Terraform",
},
});
The Pulumi Converter works by parsing your Terraform HCL (HashiCorp Configuration Language) files and mapping Terraform resources, data sources, and variables to their equivalent Pulumi resources and constructs. It understands the relationships between resources and attempts to preserve the intended infrastructure state. For instance, it knows that a aws_s3_bucket resource in Terraform corresponds to the aws.s3.Bucket class in the Pulumi AWS provider. It also handles attributes and arguments, translating them directly.
The primary problem the converter solves is the steep learning curve and the effort involved in a manual rewrite when adopting Pulumi. Instead of learning Pulumi’s SDKs and re-implementing all your infrastructure logic, you can get a significant head start. This is particularly valuable for organizations with large, complex Terraform codebases. It allows for a gradual migration, where you can convert modules or components incrementally, test them, and then move on to others.
The converter isn’t just a simple text-replacement tool; it performs a semantic translation. It understands the concepts of resource dependencies and outputs. For example, if your Terraform code references an output from one resource to configure another, the converter will attempt to replicate this using Pulumi’s output and dependency management. It also handles basic variable interpolation and conditional logic found in Terraform.
When you run pulumi convert, it first analyzes your Terraform project, identifying all .tf files. It then builds an Abstract Syntax Tree (AST) of your configuration. This AST is traversed, and for each Terraform resource or construct, a corresponding Pulumi resource is instantiated in your target language. The attributes are mapped based on the Pulumi provider schemas. If a direct mapping isn’t immediately obvious, the converter might flag it for manual review, often in comments within the generated code, indicating potential areas that require attention.
A common point of confusion is how Pulumi handles state. While the converter translates your code, it doesn’t migrate your state. After conversion, you’ll typically run pulumi up against your new Pulumi code. Pulumi will then compare the desired state (from your new code) with the actual state of your infrastructure (which is still managed by Terraform’s state file initially). You might need to run terraform state pull and then pulumi import for each resource to bring Pulumi’s state file in sync with your existing infrastructure. The converter facilitates the code transition, but state management is a separate, albeit related, step.
The tool also supports converting Terraform modules into Pulumi components, which are Pulumi’s way of abstracting and composing infrastructure. This allows you to maintain a similar level of modularity and reusability in your Pulumi code as you had in your Terraform modules.
After converting your code, the next logical step is to understand how Pulumi’s deployment engine, the pulumi engine, reconciles the desired state defined in your code with the actual state of your cloud resources.