§ Reference · Policies

Writing policies

The four rules for writing a plan policy, each with a captured run, plan-wide rules, and the typos that forbid nothing.

On this page

A policy is a CUE value that the plan document must unify with. The usual shape is a list template over changes: a struct that every element of the list must unify with.

changes: [...{
	addr:   string
	mode:   string
	action: string
	// guards and constraints that read these fields
}]

CUE resolves a name by lexical scope. A guard reads only what the template declares: mode: string is what makes mode visible to the if below it. Without the declaration the file does not compile, and the run is refused at load.

Rule	Use	Failure it avoids
Prohibit with a guard	An `if` on identity fields and `error()`.	A rule that cannot say what is wrong.
Require with a constraint	A constraint on `after`.	A value that is absent, null or unknown passes.
Do not prohibit a value with an equality guard	Write the allowed set as a constraint.	An unknown value passes.
Read an absent field only after a presence test	Declare the field optional and test it.	A refusal for the wrong reason.

Work in an empty directory. The root is infra, and the policies are in policy. The commands print the plan before the verdict. This page shows the verdict.

infra/main.cue

package infra

import (
	"pravo.dev/pravo"
	rnd "pravo.dev/providers/hashicorp/random"
)

$random: rnd.#Provider & {$version: "~> 3.6"}

seed: $random.#Resource.random_id & {byte_length: 4}

pet: $random.#Resource.random_pet & {
	length: 2
	keepers: owner: "platform"
}

ticket: $random.#Resource.random_integer & {
	min: 1
	max: 99
	keepers: source: pet.id
}

name: pravo.#Output & {value: pet.id}

terminal

$cp infra/main.cue base.cue

$pravo -C infra init > /dev/null

$pravo -C infra apply --auto-approve | grep '^Apply complete'

Apply complete! Resources: 3 added, 0 changed, 0 destroyed. [txn <id>]

Prohibit with a guard

The identity fields (addr, mode, type, name, action) are always present, so a guard on them is reliable. Declare each field the guard reads, and name the change in the message.

policy/no-destroy.cue

// A managed resource is neither deleted nor replaced.
changes: [...{
	addr:   string
	mode:   string
	action: string
	if mode == "managed" && (action == "delete" || action == "replace") {
		error("\(addr): \(action) is not allowed")
	}
}]

Change length of the pet from 2 to 3 and byte_length of the seed from 4 to 5. The plan holds a replacement of all three resources, because ticket reads the pet:

terminal

$sed -e 's/length: 2/length: 3/' -e 's/byte_length: 4/byte_length: 5/' base.cue > infra/main.cue

$pravo -C infra plan --policy ../policy/no-destroy.cue 2>&1 | sed -n '/^Plan:/,$p'

Plan: 3 to add, 0 to change, 3 to destroy.
Graph: planned 3 of 3, 3 refreshed.

Outputs:
  name: (known after apply)

Error: the plan violates the policy ../policy/no-destroy.cue (sha256:0c23a31e78bd):
changes.0: seed: replace is not allowed:
    ../policy/no-destroy.cue:7:3
changes.1: pet: replace is not allowed:
    ../policy/no-destroy.cue:7:3
changes.2: ticket: replace is not allowed:
    ../policy/no-destroy.cue:7:3

Each message is the one the policy gave to error(), with the address of the change. The path before it, changes.1, is the index of the change in the document's list. The plan is printed above these lines in full, so what is judged is what the reader saw.

Under --json the document is printed on standard output, and then the error object, so that a program can read both:

terminal

$pravo -C infra plan --json --policy ../policy/no-destroy.cue 2>/dev/null | tail -n 1

{"code":5,"kind":"error","message":"the plan violates the policy ../policy/no-destroy.cue (sha256:0c23a31e78bd):\nchanges.0: seed: replace is not allowed:\n    ../policy/no-destroy.cue:7:3\nchanges.1: pet: replace is not allowed:\n    ../policy/no-destroy.cue:7:3\nchanges.2: ticket: replace is not allowed:\n    ../policy/no-destroy.cue:7:3\n"}

With --out, a refused plan writes no plan file:

terminal

$pravo -C infra plan --policy ../policy/no-destroy.cue --out refused.plan > /dev/null 2>&1

$test -e refused.plan || echo "refused.plan does not exist"

refused.plan does not exist

Require with a constraint

A requirement is a constraint on a value the plan must have. A value that is absent, null or unknown until apply does not satisfy it. This policy requires an owner key on every pet that is created:

policy/owner.cue

// Every random_pet that is created carries an owner.
changes: [...{
	type:   string
	action: string
	if type == "random_pet" && action == "create" {
		after: keepers: owner: string & !=""
	}
}]

The guard (if type == "random_pet" && action == "create") says which changes the requirement governs. The constraint (string & !="") says what they must have. Five plans follow, each with a different keepers line in the pet block. The state is empty first, so the plans create the pet.

terminal

$pravo -C infra destroy --auto-approve | grep '^Destroy complete'

Destroy complete! Resources: 0 added, 0 changed, 3 destroyed. [txn <id>]

Case	In `main.cue`	Verdict
present	`keepers: owner: "platform"`	satisfied
absent	`keepers: team: "storage"`	refused: the key `owner` is not there
null	no `keepers` line	refused: `keepers` is `null`
unknown	`keepers: owner: seed.hex`	refused: the value is `{"$unknown": true}`
empty string	`keepers: owner: ""`	refused: `!=""` excludes it

Present:

terminal