Write your own policy packs

1. Create a directory for your policy pack and navigate to it.

   $ mkdir policypack && cd policypack
   

2. Create a new TypeScript project:

   $ pulumi policy new aws-typescript
   

3. Replace the generated policy in index.ts with this example, which demonstrates a clearer pattern for organizational policy enforcement:

   Each policy must have:

   • A unique name, description, and validation function
   • A validation function (this example uses validateResourceOfType to run only for AWS S3 bucket resources)
   • An enforcement level set at the policy pack level (applies to all policies) or per policy (overrides the pack level)

   For more information on all available fields, see policy metadata.

   import * as aws from "@pulumi/aws";
   import { PolicyPack, validateResourceOfType } from "@pulumi/policy";
   
   // Create a new policy pack.
   new PolicyPack("policy-pack-typescript", {
       // Specify the policies in the policy pack.
       policies: [{
           // The name for the policy must be unique within the pack.
           name: "s3-bucket-prefix",
   
           // The description should document what the policy does and why it exists.
           description: "Ensures S3 buckets use the required naming prefix.",
   
           // The enforcement level can be "advisory", "mandatory", or "disabled". An "advisory" enforcement level
           // simply prints a warning for users, while a "mandatory" policy will block an update from proceeding, and
           // "disabled" disables the policy from running.
           enforcementLevel: "mandatory",
   
           // The validateResourceOfType function allows you to filter resources. In this case, the rule only
           // applies to S3 buckets and reports a violation if the bucket prefix doesn't match the required prefix.
           validateResource: validateResourceOfType(aws.s3.Bucket, (bucket, args, reportViolation) => {
               const requiredPrefix = "mycompany-";
               const bucketPrefix = bucket.bucketPrefix || "";
               if (!bucketPrefix.startsWith(requiredPrefix)) {
                   reportViolation(
                       `S3 bucket must use '${requiredPrefix}' prefix. Current prefix: '${bucketPrefix}'`);
               }
           }),
       }],
   });
   

1. Create a directory for your policy pack and navigate to it.

   $ mkdir policypack && cd policypack
   

2. Create a new Python project:

   $ pulumi policy new aws-python
   

   Virtual environment configuration: Python policy packs use a virtual environment specified in PulumiPolicy.yaml. The default name is venv. If you use a different name (like .venv), update PulumiPolicy.yaml:

   runtime:
   name: python
   options:
       virtualenv: .venv
   

3. Replace the generated policy in __main__.py with this example, which demonstrates a clearer pattern for organizational policy enforcement:

   Each policy must have:

   • A unique name, description, and validation function
   • An enforcement level set at the policy pack level (applies to all policies) or per policy (overrides the pack level)

   from pulumi_policy import (
       EnforcementLevel,
       PolicyPack,
       ReportViolation,
       ResourceValidationArgs,
       ResourceValidationPolicy,
   )
   
   # The validation function is called before each resource is created or updated.
   # In this case, the rule only applies to S3 buckets and reports a violation if the
   # bucket prefix doesn't match the required prefix.
   REQUIRED_S3_PREFIX = "mycompany-"
   
   def s3_bucket_prefix_validator(args: ResourceValidationArgs, report_violation: ReportViolation):
       if args.resource_type == "aws:s3/bucket:Bucket" and "bucketPrefix" in args.props:
           actual_prefix = args.props["bucketPrefix"]
           if not actual_prefix.startswith(REQUIRED_S3_PREFIX):
               report_violation(
                   f"S3 bucket must use '{REQUIRED_S3_PREFIX}' prefix. Current prefix: '{actual_prefix}'")
   
   s3_bucket_prefix = ResourceValidationPolicy(
       # The name for the policy must be unique within the pack.
       name="s3-bucket-prefix",
   
       # The description should document what the policy does and why it exists.
       description="Ensures S3 buckets use the required naming prefix.",
   
       # The enforcement level can be ADVISORY, MANDATORY, or DISABLED. An ADVISORY enforcement level
       # simply prints a warning for users, while a MANDATORY policy will block an update from proceeding, and
       # DISABLED disables the policy from running.
       enforcement_level=EnforcementLevel.MANDATORY,
   
       # The validation function, defined above.
       validate=s3_bucket_prefix_validator,
   )
   
   # Create a new policy pack.
   PolicyPack(
       name="policy-pack-python",
       # Specify the policies in the policy pack.
       policies=[
           s3_bucket_prefix,
       ],
   )
   

Here’s a simple test example using Mocha and assert:

describe("s3-bucket-prefix-policy", () => {
    it("should pass when bucket has correct prefix", () => {
        const args = getEmptyArgs();
        args.type = "aws.s3.Bucket";
        args.props.bucketPrefix = "mycompany-data";
        assert.doesNotThrow(() => {
            runResourcePolicy(s3BucketPrefixPolicy, args);
        });
    });

For a complete example including test helpers and setup, see the unit test policy example on GitHub.

Here’s a simple test example using pytest:

def test_bucket_with_correct_prefix():
    """Test that policy passes when bucket has correct prefix."""
    args = ResourceValidationArgs(
        resource_type="aws:s3/bucket:Bucket",
        props={"bucketPrefix": "mycompany-data"},
        urn="urn:pulumi:dev::test::aws:s3/bucket:Bucket::my-bucket",
        name="my-bucket",
        opts={},
        provider="",
    )

    # Should not raise any violations
    violations = []
    def report_violation(message: str):
        violations.append(message)

    s3_bucket_prefix_validator(args, report_violation)
    assert len(violations) == 0

For a complete example including additional test cases, see the unit test policy example on GitHub.

1. Use the --policy-pack flag to specify your policy pack directory:

   If you need a test program, create one with pulumi new aws-typescript. This creates an S3 bucket to test the policy.

   $ mkdir test-program && cd test-program
   $ pulumi new aws-typescript
   

   For AWS examples, ensure you have AWS credentials configured and set your region with pulumi config set aws:region <region>.

2. In the Pulumi program’s directory, run:

   $ pulumi preview --policy-pack <path-to-policy-pack-directory>
   

   If the stack is compliant, the output shows which policy packs ran.

   Previewing update (dev):
           Type                 Name          Plan
       +   pulumi:pulumi:Stack  test-dev      create
       +   └─ aws:s3:Bucket     my-bucket     create
   
   Resources:
       + 2 to create
   
   Policy Packs run:
       Name                                                 Version
       aws-typescript (/Users/user/path/to/policy-pack)     (local)
   

3. Edit the stack code to specify a non-matching prefix:

   const bucket = new aws.s3.Bucket("my-bucket", {
       bucketPrefix: "wrongprefix-",
   });
   

4. Run pulumi preview again. This time, the policy violation blocks the preview:

   Previewing update (dev):
           Type                 Name          Plan       Info
       +   pulumi:pulumi:Stack  test-dev      create     1 error
       +   └─ aws:s3:Bucket     my-bucket     create
   
   Diagnostics:
       pulumi:pulumi:Stack (test-dev):
       error: preview failed
   
   Policy Violations:
       [mandatory]  aws-typescript v0.0.1  s3-bucket-prefix (my-bucket: aws:s3/bucket:Bucket)
       Ensures S3 buckets use the required naming prefix.
       S3 bucket must use 'mycompany-' prefix. Current prefix: 'wrongprefix-'
   

1. Use the --policy-pack flag to specify your policy pack directory:

   If you need a test program, create one with pulumi new aws-python. This creates an S3 bucket to test the policy.

   $ mkdir test-program && cd test-program
   $ pulumi new aws-python
   

   For AWS examples, ensure you have AWS credentials configured and set your region with pulumi config set aws:region <region>.

2. In the Pulumi program’s directory, run:

   $ pulumi preview --policy-pack <path-to-policy-pack-directory>
   

   If the stack is compliant, the output shows which policy packs ran.

   Previewing update (dev):
           Type                 Name          Plan
       +   pulumi:pulumi:Stack  test-dev      create
       +   └─ aws:s3:Bucket     my-bucket     create
   
       Resources:
           + 2 to create
   
       Policy Packs run:
           Name                                             Version
           aws-python (/Users/user/path/to/policy-pack)     (local)
   

3. Edit the stack code to specify a non-matching prefix:

   bucket = s3.Bucket('my-bucket', bucket_prefix="wrongprefix-")
   

4. Run pulumi preview again. This time, the policy violation blocks the preview:

    Previewing update (dev):
         Type                 Name          Plan       Info
     +   pulumi:pulumi:Stack  test-dev      create     1 error
     +   └─ aws:s3:Bucket     my-bucket     create
   
    Diagnostics:
      pulumi:pulumi:Stack (test-dev):
        error: preview failed
   
    Policy Violations:
        [mandatory]  aws-python v0.0.1  s3-bucket-prefix (my-bucket: aws:s3/bucket:Bucket)
        Ensures S3 buckets use the required naming prefix.
        S3 bucket must use 'mycompany-' prefix. Current prefix: 'wrongprefix-'