Policies

A policy is a single rule that your infrastructure must follow, such as “S3 buckets must not be public” or “every stack may declare at most three databases.” You write policies in TypeScript, JavaScript, Python, or OPA (Rego), and group related policies into a policy pack. Policy groups then decide which stacks and cloud accounts each pack applies to.

Resource and stack validation policies

Every policy validates either one resource at a time or a whole stack at once.

• Resource validation policies run once for each resource. The policy receives the resource’s type, name, and properties, and reports a violation if the resource breaks the rule. Most policies are resource validation policies: checks on encryption, public access, instance types, or required tags all look at one resource.
• Stack validation policies run once for each stack, and receive every resource in the stack together. Use them for rules that depend on more than one resource, such as limits on how many resources of a type a stack declares, or requirements about how resources relate to each other.

When a policy finds a problem, it reports a violation with a message that explains what’s wrong. A policy that reports nothing has found the resource or stack compliant.

In a preventative evaluation, during pulumi preview or pulumi up, a policy sees the properties your program declares, before any resource is created. Properties that the cloud provider computes, such as IDs and other outputs, aren’t known yet. In an audit evaluation, a policy sees the current state of resources that already exist. For when each kind of evaluation happens, see Policy as code.

Enforcement levels

Each policy has an enforcement level that decides what happens when it reports a violation:

A policy pack sets a default level for its policies, and each policy can override it. The people who apply a pack can also override the level for any policy through configuration, without changing the pack’s code. Audit evaluations report violations but never block anything, whatever the level.

The mandatory and remediate levels require particular editions of Pulumi Cloud when policies are managed centrally. See pricing.

Remediation

A remediation policy doesn’t just report a problem: it returns corrected properties for the resource, and Pulumi deploys the corrected resource instead of the one the program declared. For example, a remediation policy could turn on storage encryption for a database that the program left unencrypted.

Only resource validation policies written in TypeScript, JavaScript, or Python can remediate. A stack validation policy set to remediate is treated as mandatory, and OPA policies report violations without fixing them. To write one, see Remediating policy violations.

Configuration

A policy can declare configuration parameters, so one policy pack can serve teams with different requirements. For example, a policy that limits instance sizes can take the maximum size as a parameter instead of hard-coding it. The people who apply the pack set the values, and can also override each policy’s enforcement level. See Configuring policy packs.

Metadata

Besides its validation logic, a policy carries fields that describe it: a unique name and a description, and optionally a display name, a severity, remediation steps, a link to more information, tags, and the compliance framework control it implements. Pulumi Cloud uses these fields when it shows policies and their violations, for example to sort findings by severity. For every field and how to set it in each language, see the policy fields reference.

Next steps

• Use pre-built policy packs to apply policies that Pulumi maintains, with no code to write.
• Write a policy pack in TypeScript, JavaScript, Python, or OPA.