Install & Compatibility
Where this runs
tested against v1.21.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 1.494s · 86.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.4s · import 0.864s · 72MB
81MB installed
● package 81MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PolicyPack
✓ from pulumi_policy import PolicyPack
Used to register a collection of policies.
ResourceValidationPolicy
✓ from pulumi_policy import ResourceValidationPolicy
Used to define a policy that validates individual resources.
StackValidationPolicy
✓ from pulumi_policy import StackValidationPolicy
Used to define a policy that validates an entire stack's configuration.
EnforcementLevel
✓ from pulumi_policy import EnforcementLevel
Specifies whether a policy violation is 'advisory', 'mandatory', or 'remediate'.
validateResourceOfType
✓ from pulumi_policy import validateResourceOfType
A helper function to easily create resource validation policies for specific resource types.
This example defines a Pulumi Policy Pack in Python that includes a single policy. The `s3-no-public-read` policy ensures that no AWS S3 bucket can be created or updated with a `public-read` or `public-read-write` ACL. If such a bucket is detected during `pulumi preview` or `pulumi up`, the deployment will be halted due to the `MANDATORY` enforcement level. This code would typically reside in `__main__.py` within a policy pack directory created by `pulumi policy new aws-python`.
import pulumi
from pulumi_policy import PolicyPack, ResourceValidationPolicy, EnforcementLevel, validateResourceOfType
import pulumi_aws as aws
def s3_bucket_no_public_read_policy(args: aws.s3.Bucket, report_violation):
if args.acl == 'public-read' or args.acl == 'public-read-write':
report_violation(f"S3 Bucket '{args.id}' should not be publicly readable.")
PolicyPack(
name="aws-s3-security",
policies=[
ResourceValidationPolicy(
name="s3-no-public-read",
description="Prohibits setting the publicRead or publicReadWrite permission on AWS S3 buckets.",
enforcement_level=EnforcementLevel.MANDATORY,
validate=validateResourceOfType(aws.s3.Bucket, s3_bucket_no_public_read_policy)
)
]
)
pulumi-policy --version
Debug
Known issues
breakingSome Pulumi-authored policy packs (e.g., `pulumi-awsguard`) were released as 'Preview' and explicitly stated they were subject to breaking changes. While the core `pulumi-policy` SDK is more stable, be cautious with specific policy libraries and always check their release notes.fixRefer to the documentation and changelogs of the specific policy pack you are using. Upgrade to the latest stable versions when possible.
affects: Early versions of specific policy packs (e.g., pulumi-awsguard v0.x)
gotchaPolicies with `EnforcementLevel.MANDATORY` will halt `pulumi up` operations if a violation is detected. This prevents non-compliant resources from being provisioned or updated.fixUse `EnforcementLevel.ADVISORY` for warnings that don't block deployment, or `EnforcementLevel.REMEDIATE` to automatically fix certain violations. Carefully test mandatory policies in non-production environments first.
affects: All versions
gotchaPolicy Packs are only evaluated locally when the `--policy-pack <path-to-policy-pack-directory>` flag is explicitly passed to `pulumi preview` or `pulumi up`. For central enforcement across an organization, policy packs must be published to Pulumi Cloud and associated with a Policy Group.fixFor local testing, always include `--policy-pack` flag. For organizational enforcement, publish your policy pack using `pulumi policy publish` and configure it in the Pulumi Cloud console.
affects: All versions
gotchaDuring policy evaluation, any secrets defined in your Pulumi stack configuration or resources are decrypted and accessible in plaintext to the policy code. Treat your policy code with the same security considerations as your infrastructure code.fixEnsure that only trusted policy packs are run against your stacks and that your policy code itself does not log or expose sensitive information unnecessarily.
affects: All versions
gotcha`pulumi stack import` and `pulumi refresh` commands do not trigger policy evaluations. Policies are primarily designed to run during `pulumi preview` and `pulumi up` to validate changes before or during deployment.fixBe aware that resources imported or refreshed might temporarily be out of compliance without immediate policy notification. Subsequent `pulumi up` operations will then apply policies.
affects: All versions
Errors
Common errors & fixes
409 conflict: Another update is currently in progress
Another Pulumi update is already running on the stack, or a previous update crashed, leaving a stale lease.
fixConfirm no other users are running updates. If not, use `pulumi cancel` in the stack directory to clear the stale lease.
Policy violations not being reported during pulumi preview/up
The policy pack is not correctly referenced (locally) or enabled (in Pulumi Cloud).
fixIf testing locally, ensure you are running `pulumi preview --policy-pack <path-to-your-policy-pack-directory>`. If expecting cloud enforcement, verify the policy pack is published and associated with a Policy Group in your Pulumi Cloud organization.
Error: after mutation of snapshot
This error message indicates an internal bug within the Pulumi engine related to its data structure self-check.
fixThis is a rare error and usually points to a Pulumi bug. It is recommended to open a GitHub issue with Pulumi, providing detailed steps to reproduce the issue and diagnostic logs.
Upgrade
Version history
1.21.0latest on PyPI · released May 20, 2026
Audit
Dependencies
pulumirequiredCore Pulumi SDK required for any Pulumi program, including policy packs.