Pulumi & HCL

Pulumi supports writing your infrastructure as code using Pulumi HCL, a language plugin that lets you author Pulumi programs in Terraform-like HCL syntax. You get familiar HCL blocks, expressions, and built-in functions while using Pulumi’s state management, secrets handling, and deployment engine.

Pulumi HCL is developed in the pulumi-labs/pulumi-hcl repository.

Prerequisites

All you need to use Pulumi HCL is the Pulumi CLI, version 3.235.0 or later. The HCL language and converter plugins ship with the CLI.

Example

A Pulumi HCL project consists of a Pulumi.yaml with runtime: hcl and one or more .hcl files in the project directory.

Pulumi.yaml:

name: simple-hcl
runtime: hcl
description: A simple Pulumi HCL project

main.hcl:

pulumi {
  required_providers {
    random = {
      source  = "pulumi/random"
      version = ">= 4.0.0"
    }
  }
}

variable "prefix" {
  type    = string
  default = "test"
}

resource "random_pet" "my_pet" {
  prefix = var.prefix
  length = 2
}

output "pet_name" {
  value = random_pet.my_pet.id
}

Further examples are available in the Pulumi HCL GitHub repository. The specification for Pulumi HCL programs is in the Pulumi HCL reference.

Pulumi programming model

The Pulumi programming model defines the core concepts you will use when creating infrastructure as code programs using Pulumi. Concepts describes these concepts with examples available in all supported languages.

To learn how the Pulumi programming model is implemented for Pulumi HCL, refer to the Pulumi HCL reference.

Terraform compatibility

Pulumi HCL is broadly compatible with Terraform-like HCL syntax. Resources, data sources, variables, locals, outputs, modules, expressions, and most built-in functions work as documented by HashiCorp, with two notable behavioral differences:

• Provider sources must use the pulumi/ namespace, not hashicorp/.
• Resource replacement creates the new resource before deleting the old one (the opposite of Terraform). Set create_before_destroy = false in a lifecycle block to opt into delete-first behavior.

For the full list of differences and unsupported features, see the Terraform compatibility section of the reference.

HCL packages

The Pulumi Registry houses 100+ packages that can be consumed from Pulumi HCL programs by declaring them in a pulumi required_providers block.

For Terraform or OpenTofu providers that aren’t published in the Pulumi Registry, use Any Terraform Provider to generate a local package on the fly. This is especially relevant for Pulumi HCL users who are bringing existing programs from a Terraform codebase that depends on community or internal providers without bridged Pulumi equivalents.