How Do I Convert HCL Into Pulumi?

Introduction

If you’re looking to migrate from HCL-based infrastructure to Pulumi, you’re in luck! Pulumi provides robust tools to automate the conversion of HCL code into Pulumi programs. This allows you to maintain your existing infrastructure while transitioning to Pulumi’s more flexible programming model. In this guide, we’ll explore how to convert HCL-based infrastructure code to Pulumi using the pulumi convert command.

Explanation

Basic Conversion Process

Converting HCL to Pulumi is straightforward with the pulumi convert command. Here’s how to use it:

pulumi convert --from hcl --language typescript

You can specify any of Pulumi’s supported languages:

pulumi convert --from hcl --language typescript
pulumi convert --from hcl --language python
pulumi convert --from hcl --language go
pulumi convert --from hcl --language csharp
pulumi convert --from hcl --language java
pulumi convert --from hcl --language yaml

By default, the conversion outputs to the current directory. You can specify an output directory:

pulumi convert --from hcl --language typescript --out pulumi-ts-program

Note: In the actual command, use the name of the HCL-based tool you’re converting from instead of hcl. We use hcl in this document as a placeholder for the specific tool name.

Support for Any HCL-based Provider

A major advantage of Pulumi’s conversion tool is its ability to handle ANY HCL-based provider, even those without native Pulumi equivalents. The converter:

1. Automatically bridges existing providers
2. Generates necessary SDK code for providers not in the Pulumi registry
3. Creates a complete, ready-to-deploy Pulumi project

Project Structure After Conversion

After running the conversion, your new Pulumi project will include:

• Pulumi.yaml: The Pulumi project configuration file
• Main program file (e.g., index.ts for TypeScript, __main__.py for Python)
• An sdks directory containing generated code for providers not in the Pulumi registry
• Language-specific project files (e.g., package.json for TypeScript, requirements.txt for Python)

Configuration After Conversion

While the code is converted automatically, you’ll need to set up your configuration values. The converter creates placeholders in the Pulumi.yaml file for variables from your original HCL code:

name: hcl-convert-example
runtime: nodejs
config:
  aws:region:
    value: 'TODO: var.aws_region' # fill in here

You’ll need to replace these placeholders with actual values before deploying.

Importing Existing Resources

After converting your code, you may want to import your existing infrastructure. Pulumi supports importing resources from any provider, including those bridged from other tools:

1. Find the Pulumi type for the resource:

   pulumi package get-schema provider-reference hashicorp/aws
   

2. Import the resource using its provider ID:

   pulumi import "aws:s3/bucket:Bucket" my-bucket "my-bucket-id"
   

Pulumi will generate code you can add to your project to manage the imported resource.

Real-World Example

Let’s look at a simple example converting an HCL file with multiple providers:

Original HCL (main.tf):

required_providers {
  aws = {
    source  = "hashicorp/aws"
    version = "~> 4.0"
  }
  planetscale = {
    source  = "planetscale/planetscale"
    version = "~> 0.1.0"
  }
}

provider "aws" {
  region = var.aws_region
}

provider "planetscale" {
  service_token = var.planetscale_token
}

resource "aws_s3_bucket" "data_bucket" {
  bucket = "my-data-bucket"
}

resource "planetscale_database" "db" {
  name         = "my-app-db"
  organization = var.planetscale_org
}

Converted TypeScript (index.ts):

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";
import * as planetscale from "./sdks/planetscale";

// Create an AWS S3 bucket
const dataBucket = new aws.s3.Bucket("dataBucket", {
    bucket: "my-data-bucket",
});

// Create a PlanetScale database
const db = new planetscale.database.Database("db", {
    name: "my-app-db",
    organization: "my-org",
});

// Export the bucket name and database URL
export const bucketName = dataBucket.bucket;
export const databaseUrl = db.url;

Considerations and Limitations

While Pulumi’s conversion tool is powerful, there are some considerations to keep in mind:

1. Modules: If your HCL modules are defined in parent directories of your deployment code, you may need to restructure before conversion.

2. Dynamic Types: HCL is dynamically typed, so when converting to statically typed languages like TypeScript or Go, the converter may use catch-all types like any.

3. Configuration: The variable files aren’t automatically converted to Pulumi stack configurations and will need manual adjustment.

4. HCL Functions: While Pulumi supports most HCL functions, some dynamic functions (like try) may require manual intervention.

Summary

Converting HCL to Pulumi is simpler than ever with the pulumi convert command. This tool handles any HCL-based provider, generates appropriate code for your chosen language, and sets up a complete Pulumi project structure.

After conversion, you’ll need to:

1. Set up your configuration values in Pulumi.yaml
2. Import existing resources if needed
3. Make any necessary adjustments to handle dynamic features

The resulting Pulumi code gives you all the benefits of your preferred programming language, including better abstractions, error checking, and reusability, while maintaining compatibility with your existing infrastructure.