Document practices for writing Pulumi Policies for Dynamic Providers

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](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: jkodroff

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

@@ -23,6 +23,10 @@ The dynamic resource provider construct can be used to build a local provider fo
 **Note:** The Pulumi registry includes the [Command Provider](https://www.pulumi.com/registry/packages/command/) as an even lighter weight solution and can be used in place of a dynamic resource provider in some cases.
 {{% /notes %}}
 
+{{% notes type="info" %}}
+**Note:** [Pulumi Policy Packs](/docs/insights/policy/) can be used to validate dynamic provider resources. However, 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.
+{{% /notes %}}
+
 There are several reasons why you might want to write a dynamic resource provider. Here are some of them:
 
 - You want to create some new custom resource types.

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

@@ -248,6 +248,98 @@ Use stack validation policies when you need to:
 
 Most policies are resource validation policies. Stack validation policies are useful for more complex scenarios that require understanding the full context of your infrastructure.
 
+## Writing policies for dynamic providers
+
+[Dynamic providers](/docs/iac/concepts/resources/dynamic-providers/) allow you to create custom resource types directly in your Pulumi programs. When writing policies for dynamic providers, you need to account for a key constraint: **all dynamic resources share the same resource type** (`pulumi-nodejs:dynamic:Resource` for TypeScript/JavaScript or `pulumi-python:dynamic:Resource` for Python).
+
+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.
+
+### Example: Validating a specific dynamic provider
+
+This example shows how to write a policy that validates resources from a specific dynamic provider by checking for a unique property:
+
+{{< chooser language "typescript,python" >}}
+
+{{% choosable language typescript %}}
+
+```typescript
+import * as pulumi from "@pulumi/pulumi";
+import { PolicyPack, ResourceValidationPolicy } from "@pulumi/policy";
+
+new PolicyPack("dynamic-provider-policies", {
+    policies: [{
+        name: "environment-name-validation",
+        description: "Validates that environment dynamic resources use the correct name.",
+        enforcementLevel: "mandatory",
+        validateResource: (args, reportViolation) => {
+            // All dynamic resources in TypeScript/JavaScript have the type "pulumi-nodejs:dynamic:Resource".
+            // To identify a specific dynamic provider, check for unique properties.
+            if (args.type === "pulumi-nodejs:dynamic:Resource" && args.props.environmentName !== undefined) {
+                const envName = args.props.environmentName;
+                if (envName !== "myTestEnv") {
+                    reportViolation(
+                        `Environment name must be 'myTestEnv'. Current value: '${envName}'`);
+                }
+            }
+        },
+    }],
+});
+```
+
+{{% /choosable %}}
+
+{{% choosable language python %}}
+
+```python
+from pulumi_policy import (
+    EnforcementLevel,
+    PolicyPack,
+    ReportViolation,
+    ResourceValidationArgs,
+    ResourceValidationPolicy,
+)
+
+def env_dynprov_check(args: ResourceValidationArgs, report_violation: ReportViolation):
+    # All dynamic resources in Python have the type "pulumi-python:dynamic:Resource"
+    # To identify a specific dynamic provider, check for unique properties
+    # In this case, we look for resources with an "environment_name" property
+    if args.resource_type == "pulumi-python:dynamic:Resource" and "environment_name" in args.props:
+        environment_name = args.props["environment_name"]
+        if environment_name != "myTestEnv":
+            report_violation(
+                f"Environment name must be 'myTestEnv'. Current value: '{environment_name}'")
+
+dyn_prov_policy = ResourceValidationPolicy(
+    name="environment-name-validation",
+    description="Validates that environment dynamic resources use the correct name.",
+    enforcement_level=EnforcementLevel.MANDATORY,
+    validate=env_dynprov_check,
+)
+
+PolicyPack(
+    name="dynamic-provider-policies",
+    policies=[
+        dyn_prov_policy,
+    ],
+)
+```
+
+{{% /choosable %}}
+
+{{< /chooser >}}
+
+### Best practices for dynamic provider policies
+
+When writing policies for dynamic providers:
+
+1. **Identify unique properties**: Determine which properties uniquely identify the dynamic provider you want to validate. In the example above, the `environment_name` (or `environmentName`) property indicates this is an environment resource.
+
+1. **Be specific with property checks**: Since all dynamic resources share the same type, check for specific property names or combinations that distinguish your dynamic provider from others.
+
+1. **Handle missing properties gracefully**: Use property existence checks (like `"environment_name" in args.props`) before accessing property values to avoid errors when the policy runs against other dynamic providers.
+
+1. **Document your assumptions**: Clearly document which properties your policy uses to identify dynamic providers so that changes to the dynamic provider implementation don't inadvertently break policy enforcement.
+
 ## Running policies locally
 
 Test your policy pack locally before publishing.