Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 36 ยท Testing and Policy

Policy as Code with Pulumi CrossGuard

Enforce rules on Pulumi deployments with CrossGuard policy packs: resource and stack policies, enforcement levels, running locally, publishing to an organization and testing policies.

Tests check your own code. Policy as code checks every deployment against organization rules, whoever wrote the program: no public buckets, only approved regions, mandatory tags, no instances larger than a limit. Pulumi's policy engine is called CrossGuard. Policies are written in TypeScript or Python (or other supported ways), grouped into policy packs and evaluated during pulumi preview and pulumi up.

CrossGuard needs the Pulumi CLI, so the policy code here is read-only. The runnable stand-in implements the same idea (rules, enforcement levels, a verdict) in JavaScript, which is also a good way to test policy logic itself.

Where policies run

When a policy pack is attached, Pulumi evaluates it for every resource as it would be created or updated and once for the whole stack:

  • A resource policy inspects one resource's type and inputs.
  • A stack policy inspects all resources together (for example "at least one resource must be tagged cost-center", or "no two buckets share a name prefix").

Each policy has an enforcement level:

Level Effect
advisory Prints a warning; the update continues
mandatory Fails the preview or update with an error
disabled Skips the policy
remediate Lets a policy fix an input (for example add a tag) before the resource is created

A policy pack

Create one with pulumi policy new aws-typescript, which scaffolds a folder containing PulumiPolicy.yaml (runtime) and index.ts:

TypeScript
import * as aws from "@pulumi/aws";
import { PolicyPack, validateResourceOfType } from "@pulumi/policy";

new PolicyPack("acme-baseline", {
  policies: [
    {
      name: "s3-no-public-read",
      description: "S3 buckets must not use a public-read ACL.",
      enforcementLevel: "mandatory",
      validateResource: validateResourceOfType(aws.s3.Bucket, (bucket, args, reportViolation) => {
        if (bucket.acl === "public-read" || bucket.acl === "public-read-write") {
          reportViolation("Buckets must not be public. Use CloudFront with an origin access control instead.");
        }
      }),
    },
    {
      name: "required-tags",
      description: "Taggable resources need owner and environment tags.",
      enforcementLevel: "advisory",
      validateResource: (args, reportViolation) => {
        const tags = args.props.tags;
        if (tags !== undefined && (!tags.owner || !tags.environment)) {
          reportViolation(`Resource ${args.name} is missing the owner or environment tag.`);
        }
      },
    },
    {
      name: "ec2-small-instances-only",
      description: "Only approved instance sizes in non-prod.",
      enforcementLevel: "mandatory",
      validateResource: validateResourceOfType(aws.ec2.Instance, (instance, args, reportViolation) => {
        const allowed = ["t3.nano", "t3.micro", "t3.small"];
        if (!allowed.includes(instance.instanceType)) {
          reportViolation(`Instance type ${instance.instanceType} is not allowed. Use one of: ${allowed.join(", ")}.`);
        }
      }),
    },
  ],
});

Things to notice:

  • validateResourceOfType gives you a typed view of the resource's inputs.
  • Values can be unknown at preview (outputs of other resources). A good policy checks args.props.x !== undefined and skips what it cannot know yet; CrossGuard evaluates again during up when more is known.
  • reportViolation(message) is the only way to fail; keep messages specific, so developers know the fix.

Running a pack

Locally, point the CLI at the folder:

Terminal
pulumi preview --policy-pack ./policy
pulumi up --policy-pack ./policy
pulumi up --policy-pack ./policy --policy-pack-config ./policy-config.json

For a team, publish the pack to your Pulumi Cloud organization and attach it to policy groups (sets of stacks):

Terminal
cd policy
pulumi policy publish acme       # organization name
pulumi policy enable acme/acme-baseline latest --policy-group production

Then every update of those stacks is checked automatically, with no change to the developers' programs or CI. Packs can also be configured per policy group, for example an allow-list of regions that differs between prod and dev (config in the policy definition with a JSON schema).

Pulumi also ships premade packs (for example for compliance frameworks) that you can enable without writing code, and the policy engine can scan existing resources (audit policy groups) without deploying anything.

Stand-in: a policy engine

The stand-in evaluates resource and stack policies with enforcement levels and decides if an update may proceed. Policies are the same shape as above (name, level, validate function).

Node.js Stand-in: resource and stack policies with enforcement levels

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Warnings do not block, errors do. That is the practical meaning of advisory versus mandatory: roll out a new rule as advisory, give teams time to fix, then flip it to mandatory.

Testing policies

A policy is code, so test it. The @pulumi/policy package has no mocking harness of its own, but you can call the validation function directly with fake resource arguments and assert that reportViolation was called:

TypeScript
import { strict as assert } from "node:assert";

function collect(policy: any, args: any): string[] {
  const out: string[] = [];
  policy.validateResource(args, (m: string) => out.push(m));
  return out;
}

it("flags public buckets", () => {
  const msgs = collect(publicBucketPolicy, {
    type: "aws:s3/bucket:Bucket",
    props: { acl: "public-read" },
    name: "x",
  });
  assert.equal(msgs.length, 1);
});

Also add a "violating program" and a "compliant program" in a test stack and run pulumi preview --policy-pack against both in CI; the first must fail and the second must pass.

Practical guidance

  • Start advisory. Adoption fails when the first thing teams see is a wall of errors.
  • Write messages that say how to fix it, with a link to your internal docs.
  • Version your pack and roll out changes through a test policy group first.
  • Do not duplicate cloud-native guardrails. Cloud organization policies (AWS SCP, Azure Policy) stop actions at the API. CrossGuard stops them earlier, at preview, with a better error. Use both for defense in depth.
  • Remember what CrossGuard cannot see. It only checks deployments done with Pulumi. Console changes need your cloud's own controls or audit scans.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the difference between advisory and mandatory enforcement?

    Advisory prints a warning; mandatory violations stop the preview or update.
  2. 2. Why should a policy skip properties whose value is undefined during preview?

    Unknown values are not available at preview time, so the policy should not fail on them; it runs again when they are known.
  3. 3. How can a team apply a policy pack to all production stacks without changing their programs?

    Policy groups in Pulumi Cloud enforce published packs on a set of stacks automatically.
  4. 4. Which is the best way to introduce a brand new rule?

    Advisory first gives teams time to comply, then mandatory enforces the rule once it is realistic.

Summary

  • CrossGuard evaluates policy packs during preview and update with resource and stack policies.
  • Enforcement levels are advisory, mandatory, disabled and remediate.
  • Run packs locally with --policy-pack or publish them to an organization and attach them to policy groups.
  • Handle unknown values, write specific messages and test policies like any other code.
  • Introduce rules as advisory first and keep cloud-native guardrails as a second layer.

Next: Pulumi in CI/CD Pipelines