From 53745efbb953aa263c0a2b9ab05d8118f9cbba43 Mon Sep 17 00:00:00 2001 From: Josh Kodroff Date: Thu, 23 Oct 2025 16:25:24 -0400 Subject: [PATCH 1/2] Document how to use components with local packages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes #16173 Added documentation explaining how to properly configure components that contain local packages (such as Terraform providers via terraform-provider or nested components). This ensures users understand the requirement to commit generated SDK code to version control for Pulumi 3.200.0+. Changes: - Added new section "Using components with local packages" to local-packages.md explaining requirements and workflow - Added warning note to build-a-component.md linking to detailed documentation - Fixed command syntax for pulumi package add (removed --version flag) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../components/build-a-component.md | 4 +++ .../packages/local-packages.md | 33 ++++++++++++++++++- 2 files changed, 36 insertions(+), 1 deletion(-) diff --git a/content/docs/iac/guides/building-extending/components/build-a-component.md b/content/docs/iac/guides/building-extending/components/build-a-component.md index e9cc4d8fc47a..6137b0f89839 100644 --- a/content/docs/iac/guides/building-extending/components/build-a-component.md +++ b/content/docs/iac/guides/building-extending/components/build-a-component.md @@ -41,6 +41,10 @@ Pulumi Components are implemented as custom classes in any Pulumi-supported lang Pulumi Components inherently support multi-language use. Regardless of the language a component was written in, it is a fast one-step process to generate a SDK, allowing you to use it in all Pulumi-supported languages. +{{< notes type="warning" >}} +If your component uses a local package (such as any Terraform provider via `terraform-provider`, or another component that contains a local package), you must commit the generated SDK code to version control. See [Using components with local packages](/docs/iac/guides/building-extending/packages/local-packages/#components-with-local-packages) for details. +{{< /notes >}} + ## Structure of a Component A Pulumi Component consists of three main parts: diff --git a/content/docs/iac/guides/building-extending/packages/local-packages.md b/content/docs/iac/guides/building-extending/packages/local-packages.md index 2760fb318d46..2c74ce85c3b5 100644 --- a/content/docs/iac/guides/building-extending/packages/local-packages.md +++ b/content/docs/iac/guides/building-extending/packages/local-packages.md @@ -206,11 +206,42 @@ When working with local packages, it's important to understand how breaking chan To ensure stability, you should specify the version of both: ```bash - pulumi package add terraform-provider hashicorp/random --version=3.5.1 + pulumi package add terraform-provider hashicorp/random 3.5.1 ``` This pins the Terraform provider version, protecting you from unexpected breaking changes when the underlying provider is updated. +## Using components with local packages {#components-with-local-packages} + +When creating a component that contains a local package, you must ensure the generated SDK is available to consumers of your component. This applies when your component uses: + +- Any Terraform provider via [`terraform-provider`](/registry/packages/terraform-provider/) +- Another component that itself contains a local package +- Any other dynamically generated SDK + +### Requirements + +1. You must be using Pulumi 3.200.0 or later. +1. In your component code, run `pulumi package add` to generate the upstream SDK. +1. Ensure the generated code in the `sdk` folder is committed to version control. + +### Why this is necessary + +When someone consumes your component, they need access to all the SDKs your component depends on. For published packages from the Pulumi Registry, these dependencies are automatically resolved. However, for local packages generated within your component, the generated SDK code must be available in your repository so that consumers can use it. + +### Example workflow + +If you're building a component that uses a Terraform provider: + +```bash +cd my-component +pulumi package add terraform-provider hashicorp/random 3.5.1 +git add sdk/ +git commit -m "Add generated SDK for terraform-provider random" +``` + +Consumers of your component will then be able to use it without needing to regenerate the SDK themselves. + ## See also For more information about developing and publishing your own packages, see the [Publishing Packages](/docs/iac/build-with-pulumi/publishing-packages/) guide. From e762b99d1f1af36a6c69b97bbc504787b8a6175f Mon Sep 17 00:00:00 2001 From: Josh Kodroff Date: Fri, 24 Oct 2025 11:22:53 -0400 Subject: [PATCH 2/2] Address Claude's comments --- .../guides/building-extending/packages/local-packages.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/iac/guides/building-extending/packages/local-packages.md b/content/docs/iac/guides/building-extending/packages/local-packages.md index 2c74ce85c3b5..f86d0fa64972 100644 --- a/content/docs/iac/guides/building-extending/packages/local-packages.md +++ b/content/docs/iac/guides/building-extending/packages/local-packages.md @@ -66,10 +66,10 @@ This clones the repo and executes the source, enabling you to use packages from #### Using `terraform-provider` ```bash -pulumi package add terraform-provider hashicorp/random +pulumi package add terraform-provider hashicorp/random 3.5.1 ``` -Refer to the [Terraform Provider documentation](/docs/iac/using-pulumi/pulumi-packages/terraform-provider/) for more details. +Refer to the [Any Terraform Provider documentation](/docs/iac/using-pulumi/pulumi-packages/terraform-provider/) for more details. ## Using generated SDKs @@ -217,7 +217,7 @@ When creating a component that contains a local package, you must ensure the gen - Any Terraform provider via [`terraform-provider`](/registry/packages/terraform-provider/) - Another component that itself contains a local package -- Any other dynamically generated SDK +- Any other Pulumi plugin that generates code in the `sdk` folder ### Requirements