A guided tour of Terraform state, hosted modules, and HCL in Pulumi | Pulumi BlogSkip to main content<br>Latest release: Full support for Terraform state, cross-language modules, and HCL as a first-class language.<br>See the release
25.6K<br>Contact us<br>Sign in<br>Dashboard<br>Get started<br>25.6K<br>Contact us<br>Sign in<br>Dashboard<br>Get started
Navigation
25.6K<br>Contact us<br>Sign in<br>Dashboard<br>Get started
Copy logo SVG<br>Download mark<br>Get other variants<br>Read brand guide
Blog
In this post<br>Start with a Terraform project<br>Migrate the state to Pulumi Cloud<br>Publish a Terraform module<br>Consume the module from a Pulumi program<br>Write and run HCL, natively<br>Where to go next
Today’s big release contains a whole new set of features designed for seamless interoperability with the Terraform and OpenTofu ecosystems, and there’s a lot there — so much that it can be tough to get your head around all of it. But it generally falls into three major categories:<br>Support for Pulumi Cloud as a Terraform state backend , including remote execution with human approvals<br>A Terraform module registry in Pulumi Cloud that lets you publish, document, and share your modules even across language boundaries<br>First-class support for HCL as an authoring language in the Pulumi engine<br>To make this release a little easier to appreciate holistically, I’ve put together a quick end-to-end walkthrough that doesn’t quite cover everything, but does cover the big stuff, and should give you a sense of how it all comes together. We’ll start with a simple Terraform project that you’ll deploy to AWS, and then one step at a time, bring it into Pulumi Cloud and kick the tires on each of these new features as we go. It’ll take a bit, but all you’ll need are a free Pulumi account and the ability to deploy an S3 bucket to AWS.<br>We’ve got a bunch to cover, so let’s jump right in.<br>Start with a Terraform project<br>Our tour begins with a tiny Terraform project that provisions a single Amazon S3 bucket using a locally defined module that we’ll publish later. The project is available on GitHub as a template, and the easiest way to use it is with the GitHub CLI:<br>$ gh repo create my-tf-project \<br>--template cnunciato/simple-tf-template \<br>--public \<br>--clone && cd my-tf-project
We’ll use the local Terraform backend to start. Set your AWS credentials (preferably with environment variables), then deploy the project with Terraform or OpenTofu. (This walkthrough uses the terraform CLI, but you can swap in tofu if that’s your preference.)<br>$ terraform init && terraform apply<br>...
Apply complete! Resources: 2 added, 0 changed, 0 destroyed.
Outputs:
bucket_arn = "arn:aws:s3:::my-tf-project-bucket-14d19ece"<br>bucket_name = "my-tf-project-bucket-14d19ece"
Now let’s see how to move this project into Pulumi Cloud.<br>Migrate the state to Pulumi Cloud<br>First, create a Pulumi Cloud account if you don’t already have one (it’s free for individuals) and sign in to the Pulumi console. Then, add a backend block to main.tf, swapping for your own Pulumi Cloud account or organization name:<br>terraform {<br># ...
backend "remote" {<br>hostname = "tf.pulumi.com"<br>organization = ""
workspaces {<br>name = "my-tf-project_dev"
The workspace name is an underscore-delimited string that expresses the name of the project you’d like to use (here, my-tf-project) and the stack (dev). A single Pulumi project can have as many stacks as you like.<br>Next, sign in to Pulumi Cloud with the Terraform CLI:<br>$ terraform login tf.pulumi.com
Choose yes when prompted, and you’ll be taken to Pulumi Cloud to create a personal access token, which you can paste into the prompt to authenticate:
Success! Logged in to Terraform Enterprise (tf.pulumi.com)<br>With the backend block in place and your terraform CLI signed in to Pulumi Cloud, you’re ready to complete the migration:<br>$ terraform init -migrate-state
Terraform should detect the backend change and offer to copy your existing state:<br>Do you want to copy existing state to the new backend?<br>Pre-existing state was found while migrating the previous "local" backend<br>to the newly configured "remote" backend. [...] Enter "yes" to copy and<br>"no" to start with an empty state.
Enter a value: yes<br>Choose yes, and you’re done:<br>Successfully configured the backend "remote"! Terraform will automatically<br>use this backend unless the backend configuration changes.<br>Note that nothing about your deployed infrastructure has changed here; all we did was migrate your local state to Pulumi Cloud, and the process is identical whether you’re moving from S3, Azure, Google Cloud, or HCP Terraform or Terraform Enterprise. See Store Terraform state in Pulumi Cloud for details.<br>Now hop over to the Pulumi Cloud console, choose Stacks , and you’ll see your new stack in the list, along with its first update:
Runs happen remotely by default<br>Another thing to note is that Terraform stacks backed by Pulumi Cloud run remotely...