[blog] Launch post: Terraform modules in the Pulumi Cloud registry - #20648
[blog] Launch post: Terraform modules in the Pulumi Cloud registry#20648fnune wants to merge 3 commits into
Conversation
github-actions
Bot
added
the
review:triaging
github-actions
Bot
added
domain:blog
github-actions
Bot
added
the
review:in-progress
Pre-merge Review — Last updated 2026-08-03T08:46:37ZTip Summary: This is a new launch blog post ( Review confidence:
Investigation log
🔍 Verification trail34 claims extracted · 22 verified · 3 unverifiable · 2 contradicted
📊 Editorial balanceSingle-subject post; balance check N/A. 🚨 Outstanding in this PRThese must be resolved or refuted before merging.
|
github-actions
Bot
added
review:outstanding-issues
|
Your site preview for commit 0e3b04a is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-20648-0e3b04ac.s3-website.us-west-2.amazonaws.com Changed pages: |
Social Media Reviewcontent/blog/terraform-modules-pulumi-cloud-registry/index.mdX — FAILReasons:
LinkedIn — PASSBluesky — missingNo copy provided. Suggested copy drafted below. Suggested copyX (217/255 chars) — minimum-change repair; split the existing sentence into two paragraphs at the colon, wording otherwise unchanged:
Bluesky (279/300 chars) — drafted from the article:
Suggestions (advisory)These are stylistic notes — they don't block the post.
Updated for commit |
* [registry] Document Terraform module hosting in the Pulumi Cloud registry Add a new concept page under IDP describing how Pulumi Cloud hosts Terraform modules: authentication via `terraform login`, the three HCP-compatible publish paths (go-tfe, hashicorp/tfe provider, tfc-workflows-github Action), the standard module layout we extract from at publish, consumption from OpenTofu / Terraform via the Module Registry Protocol, and consumption from a Pulumi program via `pulumi package add terraform-module`. Cross-link from the existing "Use a Terraform Module in Pulumi" guide so consumers landing on the IaC guide can discover the Pulumi-Cloud-hosted path. Design doc: https://app.notion.com/p/Terraform-module-hosting-in-the-Pulumi-Cloud-registry-372fdbdf1cce801ea7a3f4946c1e4154 Fixes pulumi/pulumi-service#44080 ## Test plan - Render the IDP concepts section locally and confirm the new "Terraform Modules" entry appears under the Concepts menu - Click through every internal link in the new page to confirm targets exist * [registry] Add launch blog post; correct registry host to tf.pulumi.com Add the announcement blog post for hosting Terraform modules in the Pulumi Cloud registry, and correct the registry host across the docs and blog from app.pulumi.com to the canonical tf.pulumi.com (per pulumi/pulumi-service#44889; app.pulumi.com is the console only). Move the migration guidance out of the blog and into the concept page, and document the one naming rule that differs from HCP Terraform: module names reject underscores. * [registry] Fix auth: Pulumi access token, not terraform login The TFE discovery document (cmd/service/api/tfe_discover.go) advertises tfe.v2, state.v2, and modules.v1 but no login.v1, so terraform login against tf.pulumi.com is unsupported. Document the real auth instead: a Pulumi access token is the bearer for publish (go-tfe, the tfe provider, the GitHub Action), pulumi login for pulumi package add, and TF_TOKEN_tf_pulumi_com for plain OpenTofu or Terraform. * [registry] Address review: drop GitHub Action, fix injection and layout - Remove the tfc-workflows-github Action from the publish and delete paths and from the auth list. create-run triggers a run; it does not touch the module registry. The testbed only exercised go-tfe and the tfe provider. - Consume from Pulumi: drop the rejected "CLI injects TF_TOKEN_<host>" detail. After pulumi login the provider resolves the module with your Pulumi credentials. Note that terraform-module is a parameterized provider and name its parameters. - Module layout: parse all root .tf files (any filenames); examples and README are captured at publish, not rendered (console rendering is not built yet). - Say packages, not components. * [registry] Brand: sentence-case the concept page title; link state backend Apply the Pulumi brand writing-style rules: sentence case for the concept page title_tag/title/h1 and no over-capitalized concepts, so "Terraform modules in the Pulumi Cloud registry" rather than title case. Drop the "just" minimizer from the migration line. Link "keep Terraform state in Pulumi Cloud" in the blog to the state backend guide. * [registry] Consume via the hcl package instead of terraform-module The Pulumi-program consume path now uses the forthcoming hcl package: pulumi package add hcl module <source> [version], with the version optional (omit for latest, pass to pin). Drops the terraform-module alias parameter, since the hcl module form derives the package name from the module. * [registry] Document conversion as the default Pulumi consumption path Publishing a module version converts it into a Pulumi package, and neither the concept page, the launch post, nor the Terraform module guide said so. All three taught `pulumi package add hcl module ...` as the way to consume from a Pulumi program, which is now the fallback rather than the default. The concept page gains a section on what publishing produces: the `<name>-<system>` package name, that conversion runs per version, and where to see which versions have converted. `pulumi package add <name>-<system>` becomes the documented path. The `hcl module` form stays, for versions still converting, noting that it runs the same conversion locally rather than using the published package. The guide's "Using a Module from Pulumi Cloud" section follows the same order. The pages describe what the package gives a consumer, not only that one exists: the module becomes a multi-language component, so its variables are typed inputs and its outputs typed outputs, with a generated SDK in the project's language, its resources visible individually in previews and the resource graph, an API reference generated from those variables and outputs, and a record of which stacks depend on it and which are behind the latest version. Usage tracking follows the package, so a consumer reaching the module over the Terraform protocol does not report a dependency and does not appear in the usage columns or the "Used by" tab. Both pages say so. Consuming from OpenTofu or Terraform moves below the Pulumi path on the concept page and in the post. It still documents that existing `.tf` consumers are unaffected and how to reference the module and its submodules. All three state that installing a converted package needs Pulumi CLI 3.248.0 or newer, verified by bisect: 3.247.0 fails the plugin handshake, 3.248.0 works. The Terraform module detail page is being removed from the console, so the pages describe conversion state as living on the package's page instead. Fixes #20555 ## Test plan 1. Automated checks - `./scripts/format.sh` on all three files - `vale --config=.vale.ini` on all three: 0 errors; remaining warnings are on lines this change does not touch * [registry] Retitle the launch post and set its author The title names the payoff rather than the hosting. Author set to the existing team entry. * [registry] Stop selling local conversion as a fallback, link install and console URLs Local conversion runs the same `hcl` provider the registry runs, so a module the registry could not convert fails locally for the same reason. All three pages offered it as the answer for a module using Terraform features Pulumi cannot express, which it is not. It is now described as what it is: the same conversion, run at the moment you run it, useful while a version is still converting. The concept page's section is renamed to match and says outright that it is not a way around a failed conversion. The CLI version requirement links to Download & Install Pulumi on all three pages, so a reader on an older CLI has somewhere to go. The concept page picks up aliases for the two docs URLs the console links to, both of which 404 today: - `/docs/terraform-modules/`, from the package install card - `/docs/iac/using-pulumi/pulumi-cloud/registry/terraform-modules/`, from the Terraform modules list page The concept page's deletion section is removed while we decide what deleting a converted package should do to the module it came from (pulumi/pulumi-service#47170). Documenting module deletion now would describe behavior we expect to change. The post is dated 2026-08-04. * [registry] Fix lint failures and the review's link and style findings `make lint` gates the build and was failing: - The post was missing the required `category` front matter. It announces a shipped feature, so `product` - Its `meta_desc` was 182 characters against a 160 limit. Dropped the usage tracking clause, which the post covers in the body - Removing the concept page's deletion section left a trailing blank line From the pre-merge review: - The multi-language component link 404s. `pulumi-hcl` has no `main` branch; `https://github.com/pulumi/pulumi-hcl/blob/master/docs/mlc.md` resolves. Fixed in the post and the concept page - The access token link went through an alias. The page's canonical route is `/docs/administration/access-identity/access-tokens/`; the old path is line 19 of that page's own aliases list - The closing line of "Converting a module locally" restated what the Authenticate section already establishes - Style: two `It is` openings and one `mostly` - The guide's new heading was Title Case, against AGENTS.md's sentence case rule for H2 and below The module name rule is now stated as the regex the service enforces, `[a-z0-9][a-z0-9-]*` (`pkg/apitype/registry_artifact.go`), rather than a character list that implied a leading hyphen was valid. Two review findings are not acted on. The registry host is `tf.pulumi.com`: `tfe.pulumi.com` is a dead record that CloudFront-403s since the distribution alias, ALB host rule, and service dispatch moved, so the provider test the review cites is stale. And `canonical_url` pointing at the concept page is what BLOGGING.md prescribes for a feature announcement documented in the docs. * [registry] Address review: heading context, define system, trim inside baseball * [registry] Split the blog into #20648; make local conversion a fallback, not a wait-saver * [registry] Say plainly that local conversion publishes no package --------- Co-authored-by: Christian Nunciato <chris@nunciato.org>
2 participants
Launch blog post for Terraform module hosting in the Pulumi Cloud registry, split out of #19453 so the docs can merge independently and the post can go out on launch day.
The post covers the HCP-compatible registry surface (
tf.pulumi.com), publishing with go-tfe or thehashicorp/tfeprovider, the Pulumi package every published version converts into, and consuming that package from a Pulumi program or the module itself from OpenTofu / Terraform.canonical_urlpoints at the concept page, so the docs page stays the canonical reference.Merge order: this depends on #19453. The post links to
/docs/idp/concepts/terraform-modules/(also itscanonical_url) and to the new "Using a module from Pulumi Cloud" section of the Terraform module guide, neither of which exists onmasteryet. Merge #19453 first.date: 2026-08-04, so the post does not render until launch day.Test plan
./scripts/format.shandvale --config=.vale.ini: 0 errorsnode scripts/lint/lint-markdown.js: 0 errorsmake serve, confirm the post renders at/blog/terraform-modules-pulumi-cloud-registry/with its feature image