GCP Architecture Series #20 — Boolean, List and Custom Constraints

Business Challenge

Every one of these comes from writing a constraint that looked obviously correct and behaved otherwise.

Architecture

A constraint is a definition; #19 covered how the policy that configures it reaches a resource. What follows is what the definition itself can express.

The three kinds, and what each is for

Boolean rules: the whole vocabulary is one word

A legacy managed constraint with a boolean rule is either enforced or not enforced. The policy that configures it says so directly:

rules:
- enforce: true

There is nothing else to express. That is a virtue rather than a limitation — a boolean constraint is unambiguous, cheap to audit, and impossible to get subtly wrong. When a boolean constraint fits the requirement, it is always the right choice.

List rules: values, and the prefixes that give them meaning

List rules allow or disallow a list of values defined in the organization policy, using allowedValues and deniedValues. The values are hierarchy strings, and the prefix decides what the comparison means:

Custom constraints: a YAML file and a CEL expression

A custom constraint is defined in a YAML file specifying the resources, methods, conditions and actions subject to it. Google's own example is compact enough to read in full:

name: organizations/1234567890123/customConstraints/custom.disableGkeAutoUpgrade
resourceTypes: container.googleapis.com/NodePool
methodTypes:
  - CREATE
  - UPDATE
condition: "resource.management.autoUpgrade == false"
actionType: ALLOW
displayName: Disable GKE auto upgrade
description: Only allow GKE NodePool resource to be created or updated if AutoUpgrade is not enabled.

Each field has a job and a limit worth knowing before you hit it:

• resourceTypes — the fully qualified name of the Google Cloud resource containing the object and field you want to restrict. Each service defines the set of custom constraint fields available on its resources, so the field you want has to be one that service exposes.
• methodTypes — the REST methods enforced on. CREATE is universal; UPDATE depends on the resource, and a constraint that only fires on CREATE will not stop somebody editing a compliant resource into a non-compliant one.
• condition — a CEL expression, up to 1000 characters, combined with && and ||. Organization Policy Service uses Common Expression Language to evaluate these.
• actionType — ALLOW or DENY, and the source of the inversion below.
• displayName up to 200 characters, description up to 2000. The description is where the reason lives, and it is the only part a colleague reads at three in the morning.

Why This Architecture Holds Up

actionType reads backwards

This is the single thing most worth internalising about custom constraints. ALLOW does not mean "permit this when the condition matches". It means permit the operation only if the condition evaluates to true — and therefore deny it in every other case.

Google's own example makes the trap visible once you look for it. The constraint is called disableGkeAutoUpgrade, the condition is resource.management.autoUpgrade == false, and the action is ALLOW. Read casually, it looks like a rule that allows auto-upgrade to be disabled. It is the opposite: node pools may be created or updated only with auto-upgrade off, and every node pool with it on is refused. The name says what it enforces; the YAML says how, and the two only agree once you know the inversion.

Which kind to reach for

Custom constraints are code, and should be treated as such

A custom constraint is a CEL expression evaluated on every create — and sometimes every update — of a resource type across an organization. That is a piece of production logic with a blast radius larger than most services, written in a language nobody uses daily, in a YAML file, against a resource schema that varies per service.

Three habits follow. Keep the constraints in version control alongside everything else, because 20 per resource type is a budget that needs review rather than a limit to discover. Write the description as though the reader has no context, because the 2000 characters are free and the constraint will outlive whoever wrote it. And never let one reach production without watching it run first — which is exactly what the next post is about.

Key Architecture Decisions

Closing Thought

There is a progression buried in these three kinds, and it is the usual one. A boolean constraint expresses a decision somebody already made for you and named. A list constraint expresses a decision you made, from a vocabulary Google supplied. A custom constraint expresses a decision nobody has made before, in a language that will evaluate it on every resource your organization creates.

The power increases and so does the number of ways to be quietly wrong — an empty list meaning "deny all", a missing prefix matching a folder but not its contents, an actionType that inverts a condition reading perfectly well in English. None of those produce an error. They produce a policy that is enforced exactly as written and not at all as intended, which is the most expensive kind of correct. Reach for the simplest constraint that expresses the requirement, and when you cannot, assume the custom one is wrong until you have watched it run.

Official Google Cloud Reference

• Understanding constraints
• Creating and managing custom constraints
• Create custom constraints
• Organization policy constraints
• Introduction to the Organization Policy Service
• Understanding hierarchy evaluation