Document practices for writing Pulumi Policies for Dynamic Providers

[jkodroff]

Add comprehensive documentation on how to write policies for dynamic providers, addressing the challenge that all dynamic resources share the same resource type. Include examples in TypeScript and Python that demonstrate property-based filtering to identify specific dynamic providers, along with best practices for authoring such policies.

Changes:

• Add new section in policy authoring docs with complete examples
• Add informational note in dynamic providers docs linking to guidance
• Provide best practices for writing robust dynamic provider policies

Fixes #14437

🤖 Generated with Claude Code

[claude]

Documentation Review

I've reviewed the changes in this PR and they look good overall. The documentation provides clear, helpful guidance for writing policies for dynamic providers, which addresses a real gap in the documentation.

Positive aspects

• Clear explanation of the core challenge (all dynamic resources share the same type)
• Well-structured examples in both TypeScript and Python
• Good use of code comments to explain the logic
• Practical best practices section
• Appropriate use of the info note in the dynamic providers doc
• Both files end with newlines as required
• Internal links are correctly formatted and targets exist

Issues found

content/docs/iac/concepts/resources/dynamic-providers.md:27

Minor style issue: The note uses the phrase "However, since..." which creates a longer, more complex sentence. Consider breaking this into two sentences for better readability:

**Note:** [Pulumi Policy Packs](/docs/insights/policy/) can be used to validate dynamic provider resources. Since all dynamic resources share the same resource type (`pulumi-nodejs:dynamic:Resource` for TypeScript/JavaScript or `pulumi-python:dynamic:Resource` for Python), policies must identify specific dynamic providers by checking for unique properties. See [Writing policies for dynamic providers](/docs/insights/policy/policy-packs/authoring/#writing-policies-for-dynamic-providers) for examples and best practices.

content/docs/insights/policy/policy-packs/authoring.md:335

In the best practices list items, the formatting uses bold for the key concept followed by a colon. This is good, but consider whether "Identify unique properties" should use "identifying" for consistency with the instructional tone of items 2-4. However, this is a minor stylistic preference and the current version is acceptable.

Summary

The documentation accurately addresses issue #14437 and provides users with the information they need to write effective policies for dynamic providers. The examples are realistic and follow Pulumi coding conventions. The changes adhere to the style guide requirements.

Mention me (@claude) if you'd like me to review any revisions or have questions about the feedback.

[pulumi-bot]

Your site preview for commit d03ce7b is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16522-d03ce7ba.s3-website.us-west-2.amazonaws.com.

[CamSoper]

Looks fine to me, one minor suggestion.

[CamSoper]

Suggested change

	Since you cannot rely on the resource type alone to identify which dynamic provider a resource uses, you must inspect the resource's properties to differentiate between different dynamic provider implementations.
	Since you can't rely on the resource type alone to identify which dynamic provider a resource uses, you must inspect the resource's properties to differentiate between different dynamic provider implementations.