Pulumi Policy Python SDK

Common errors

• 409 conflict: Another update is currently in progress

  cause Another Pulumi update is already running on the stack, or a previous update crashed, leaving a stale lease.
  fix Confirm 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

  cause The policy pack is not correctly referenced (locally) or enabled (in Pulumi Cloud).
  fix If 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

  cause This error message indicates an internal bug within the Pulumi engine related to its data structure self-check.
  fix This 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.

Warnings

• breaking Some 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.
  Fix: Refer to the documentation and changelogs of the specific policy pack you are using. Upgrade to the latest stable versions when possible.
• gotcha Policies with `EnforcementLevel.MANDATORY` will halt `pulumi up` operations if a violation is detected. This prevents non-compliant resources from being provisioned or updated.
  Fix: Use `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.
• gotcha Policy 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.
  Fix: For 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.
• gotcha During 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.
  Fix: Ensure that only trusted policy packs are run against your stacks and that your policy code itself does not log or expose sensitive information unnecessarily.
• 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.
  Fix: Be aware that resources imported or refreshed might temporarily be out of compliance without immediate policy notification. Subsequent `pulumi up` operations will then apply policies.

Install

• pip install pulumi-policy Install Pulumi Policy SDK
• pulumi policy new aws-python Create a new Python Policy Pack

Imports

• 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.

Quickstart

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)
        )
    ]
)