Consuming pulumi-terraform-module from an SST app

[MarianBeuther]

I want to consume an existing internal Terraform module from an SST app but can't find a way to wire it in.

I tried using the pulumi-terraform-module provider to no avail

pnpm sst add terraform-module
✕  Could not find provider terraform-module

Is there a supported way today?
Any pointers to make this work would be highly appreciated

[vimtor]

the current workaround is to submit a PR in the following repo:
https://github.com/anomalyco/provider

we will then publish it as an npm package.

[MarianBe]

@vimtor Thanks but that doesn't really fit our use-case since we need to consume a private terraform module from a private repo.
Are you open to a PR adding support for external terraform modules?

[jsve]

AFAIK There's no sst add path for this today. terraform-module isn't a registered Pulumi provider, so that command will always fail. What does work is generating a Pulumi SDK from the TF module yourself and consuming it as a normal package. I've been doing this in a monorepo and it's held up fine. Sharing the approach in case it helps.

The idea is to use the pulumi-terraform-module bridge to generate an SDK from the module, commit it into your repo (e.g. under packages/pulumi-/), and import it like any other provider package from your SST app.

One important gotcha: use SST's bundled Pulumi for codegen, not the one on your PATH.

Don't use the pulumi binary from PATH (whether from nix or get.pulumi.com). Use the one SST ships, e.g. on macOS at ~/Library/Application Support/sst/bin/pulumi.

The reason: newer Pulumi binaries emit codegen that calls runtime.registerPackage and pin the SDK to @pulumi/pulumi >= 3.238.0. SST bundles @pulumi/pulumi 3.215.0 in .sst/platform/, where that wrapper doesn't exist — so the deploy crashes at runtime with runtime.registerPackage is not a function. SST's bundled Pulumi instead emits the legacy monitor.registerPackage pattern pinned to ^3.142.0, which matches what it actually runs.

Generating the SDK

Roughly, pulumi package add (run with SST's bundled binary) against the module, then a bit of cleanup so it commits cleanly: flatten the generated sdks//* up a level, patch package.json (name, types, drop the scripts), run tsc, and copy package.json into bin/ since utilities.js reads it at runtime. I wrap all of that in a regen script so the only time it runs is on a module version bump. Then add a workspace dep wherever you use it:
json"@your-scope/pulumi-": "workspace:*"

The runtime plugin

The generated SDK is just a thin TS wrapper. The actual gRPC binary pulumi-resource-terraform-module is what Pulumi shells out to at deploy time, so it has to be present in ~/.pulumi/plugins/resource-terraform-module-v/. Pin that version to the pulumi.version field in the generated SDK's package.json. I vendor it via a nix derivation and symlink it in through the shellHook, but you can also just pulumi plugin install it — the key thing is the version matches.

On install scripts: I deliberately keep the tsc build and cp package.json bin/ out of package postinstalls and commit the build output instead, to avoid opting into trustedDependencies. Since the regen script does the build, it only needs to run on a version bump anyway.

For completeness, here's the nix piece that vendors the runtime plugin and makes it discoverable to Pulumi without hitting get.pulumi.com. Pin pluginVersion to the pulumi.version field in your generated SDK's package.json and bump them in lockstep.

# pulumi-terraform-module runtime plugin (the gRPC binary Pulumi shells
# out to when applying a `terraform-module` parameterized resource).
# Not in nixpkgs; vendor the GitHub release tarball.
pulumi-terraform-module-plugin = let
  pluginVersion = "0.2.0";
  sources = {
    "aarch64-darwin" = {
      url = "https://github.com/pulumi/pulumi-terraform-module/releases/download/v${pluginVersion}/pulumi-resource-terraform-module-v${pluginVersion}-darwin-arm64.tar.gz";
      hash = "sha256-..."; # fill in
    };
    "x86_64-linux" = {
      url = "https://github.com/pulumi/pulumi-terraform-module/releases/download/v${pluginVersion}/pulumi-resource-terraform-module-v${pluginVersion}-linux-amd64.tar.gz";
      hash = "sha256-..."; # fill in
    };
  };
  source = sources.${pkgs.stdenv.system} or (throw "pulumi-terraform-module: no source pinned for ${pkgs.stdenv.system}");
in pkgs.stdenv.mkDerivation {
  pname = "pulumi-resource-terraform-module";
  version = pluginVersion;
  src = pkgs.fetchurl source;
  dontUnpack = true;
  installPhase = ''
    runHook preInstall
    mkdir -p $out/bin
    tar -xzf "$src" -C $out/bin
    chmod +x $out/bin/pulumi-resource-terraform-module
    runHook postInstall
  '';
};

Then in the shellHook, symlink it into the plugin dir Pulumi looks in, so it never tries to download it itself:

# Pulumi looks for plugins under
# $PULUMI_HOME/plugins/resource-<name>-v<version>/
PLUGIN_DIR="$HOME/.pulumi/plugins/resource-terraform-module-v${pulumi-terraform-module-plugin.version}"
if [ ! -L "$PLUGIN_DIR/pulumi-resource-terraform-module" ]; then
  mkdir -p "$PLUGIN_DIR"
  ln -sf "${pulumi-terraform-module-plugin}/bin/pulumi-resource-terraform-module" \
    "$PLUGIN_DIR/pulumi-resource-terraform-module"
fi

# pulumi-terraform-module needs a Terraform executor; OpenTofu works
# (MPL-licensed fork). Terraform itself is fine too.
export PULUMI_TERRAFORM_MODULE_EXECUTOR=opentofu