Publishing Packages: Explain how the resource provider plugin and SDKs are generated

[trondhindenes]

File: content/docs/iac/guides/building-extending/packages/publishing-packages.md

In the file above, it is very briefly mentioned "The binary Pulumi resource provider plugin" however, the page doesn't contain any information about how to generate this plugin. Neither does it mention how to generate the sdk's but that's kindof given by looking at the options in pulumi package (gen-sdk). But how to generate the binary? I could not figure it out.

[jkodroff]

@trondhindenes Thanks for submitting this issue.

The page you're referencing is specifically for publishing packages to the Pulumi Registry, which we need to make more clear. I've added #16367 to ensure that we're clearer about this.

The newly-rewritten Packages concepts page should make this more clear: https://www.pulumi.com/docs/iac/guides/building-extending/packages/packages/#how-packages-work

The "provider binary" may or may not be a binary - it depends on what language you're writing in and whether you're using local packages or not. (For context, we've developed capabilities since the docs were last updated that allow easier consumption of e.g. components in Python.)

If you're writing a component in Python and want to share it as a local package, the component code is the "provider binary" in this case.

Let me know if the rewritten page answers your original issue.

[trondhindenes]

Thanks! I think the whole workflow of "write + consume org-internal packages" need more coverage. "package add" is one thing, but how to perform day-2 management ("am I up to date?" "is there a new version of the package I consume?") - the whole concept / how it's thought to be used is still very unclear to me.

A few comments on the update page:
"Pulumi packages consist of two parts that allow them to be consumed in any Pulumi language":
maybe instead
"Depending on how its written, a pulumi package consists of one or two parts that allow them to be consumed in any Pulumi language" This ties better together with the "consumption depends on whoe the package is written" in the next section

"If you are authoring a Pulumi component to be shared within your team or organization" <-- kudos for proper guidance here, this was sorely missed before. I think it would be very benefical to link to a full example of authoring a component, consuming it from another project, then show the lifecycle around bumping version, how to discover the version update from the consumer side etc. Reading thu this for the n'th time I think I now understand that running "pulumi package add" writes something to the pulumi.yaml file but that needs to be very explicitly mentioned imho - users need to understand how the workflow works, not just that individual commands work. Think of not the first person to consume a package, but their colleage who run "git clone" and then do.... what? Something as simple as

"Running 'pulumi package add' registers the package in pulumi.yaml, you should commit this to source control. at anytime you can run "pulumi install" to (re) install the packages defined in pulumi.yaml " <-- that sentence would have saved me hours of running in circles in pulumi docs I think. I hope it's correct.

[jkodroff]

@trondhindenes RE you previous feedback:

Depending on how its written...

That's now covered in https://www.pulumi.com/docs/iac/guides/building-extending/packages/local-packages/

I think it would be very benefical to link to a full example of authoring a component, consuming it from another project, then show the lifecycle around bumping version, how to discover the version update from the consumer side etc.

We have a tutorial for authoring and publishing a component: https://www.pulumi.com/docs/iac/guides/building-extending/components/build-a-component/

#16404 will cover the part about ensuring we have guidance on updating. However, for OSS users (as I believe you are), there is no functionality to address this. Consumers of a component will have to check the upstream git repo for a more recent semver tag.

Running 'pulumi package add' registers the package in pulumi.yaml...

This should be addressed in #16699.

Since this issue has strayed from the original description, and I believe the remaining feedback is covered in the linked issues in this comment, I'm going to close this issue as fixed.