Almost every rule a governance team sets out to write already exists, maintained by somebody else, versioned, and free. The skill worth having is not authoring. It is reading the catalogue well enough to know which of those rules you can take, which you have to change, and what taking one commits you to.
Start from the assumption that it exists
The instinct of a competent engineer handed Azure Policy is to write a definition. It is the wrong first move almost every time. Microsoft ships thousands of built-in definitions and several hundred initiatives, covering the things organisations actually ask for: allowed locations, allowed resource types, required tags, encryption at rest, private endpoints, TLS versions, diagnostic settings, public network access, managed disks, and most of the security posture your auditor will name. They are maintained, versioned, documented, and they cost nothing.
The custom definitions I am asked to review divide fairly cleanly. Some exist because the built-in genuinely did not fit, which is a legitimate and later subject in this series. Rather more exist because nobody looked. The cost of that is not the afternoon spent writing it. It is that a custom definition is yours forever: your bug, your update when the resource provider changes, your problem when the person who wrote it leaves and the rule keeps running.
A built-in is somebody else’s maintenance commitment. A custom definition is yours, for as long as the rule is assigned, which is usually longer than anyone’s tenure.
Four kinds of definition, and the one nobody expects
Every definition carries a policyType, which you cannot set and which the portal and the SDKs both surface. BuiltIn means Microsoft provides and maintains it. Custom means somebody in your organisation created it. NotSpecified you will rarely meet.
Static is the one worth understanding, because it behaves unlike anything else in the product. A static definition belongs to a regulatory compliance initiative and represents a control that Microsoft owns rather than you. Its compliance result does not come from evaluating your estate at all. It comes from third-party audits of Microsoft’s own infrastructure, and the portal sometimes labels it Microsoft managed. You cannot make it pass and you cannot make it fail.
The consequence is that a compliance figure drawn from a regulatory initiative is a blend of your work and Microsoft’s, and a share of it was never yours to influence. That is not a flaw, it is shared responsibility expressed as data, but anyone reporting that number upward should know which part of it they earned. This series returns to that properly in the regulatory article, because the split between customer, Microsoft and shared ownership is the most misread thing in Azure governance.
Where the catalogue actually lives
The portal groups built-ins by the category property in their metadata, which is how you get the familiar list of General, Compute, Storage, Key Vault, Monitoring, Guest Configuration and the rest. It is a serviceable way to browse and a poor way to decide, because the portal shows you a display name and a description written to be short.
The real source is the Azure Policy GitHub repository, which holds every built-in as JSON, and Microsoft’s own index links each definition to its file there. Read the rule before you assign it. It takes two minutes and it answers the questions the description cannot: precisely which resource types are matched, which aliases are inspected, which effects the definition offers, what the parameters default to, and whether the logic handles a property that is absent rather than merely wrong. That last one decides whether a control means anything, and it is invisible from a display name.
The repository has a second use that matters more over time. It carries commit history, so when a built-in behaves differently than it did last quarter, the diff is there. The community tooling the Cloud Adoption Framework names, AzAdvertizer in particular, exists to watch that history for you, and it is worth having in the workflow before you need it rather than after.
What the version number is telling you
Built-ins are versioned as major, minor and patch, and Microsoft documents what it puts in each. The definitions are worth knowing precisely, because they describe what can change underneath an assignment you are not watching.
| Increment | What Microsoft puts in it | What that means for you |
|---|---|---|
| Major | Breaking changes: major rule logic changes, removing parameters, and adding an enforcement effect by default | The last item is the one to sit with. A major version can turn a rule that audited into a rule that denies. Assignments do not take major versions automatically, which is the entire reason that boundary exists. |
| Minor | Minor rule logic changes, new allowed values for a parameter, changes to roleDefinitionIds, and adding or removing definitions inside an initiative | Taken automatically by default. Note what is in here: the roles a remediating assignment’s identity needs can change in a minor version, and adding or removing member definitions changes what an initiative covers. |
| Patch | String and metadata changes, and break-glass security scenarios, which Microsoft describes as rare | Always taken, by design. You cannot pin an exact patch. |
An initiative member definition that specifies no version refers to the latest major version at assignment time and takes minor updates as they arrive. So the default posture across most estates is: hold the major, accept everything below it. That is a reasonable default and it is a choice, and the rollout article covers meeting a major version on your own terms.
Two flags travel alongside. A preview definition appends a suffix to its version, treated as a boolean. A deprecated one is marked in metadata. Assigning either is defensible; assigning either without recording that you did is how an estate ends up depending on something Microsoft has already announced it is retiring.
Judging a built-in before you assign it
Five questions, in order, and they take about ten minutes for a definition you are going to run for years.
Which effects does it offer, and is a reporting effect among them, because a definition offering only Deny cannot be introduced gradually. What does the rule actually match, read from the JSON rather than the description, with particular attention to whether an absent property is treated as compliant. What is the definition’s mode, since Indexed silently excludes resource groups and subscriptions and that is right for most rules and wrong for a few. What does each parameter default to, because the defaults are what you get when somebody assigns it in a hurry. And if it is a remediating definition, which roles does it declare, because assigning it is the act that grants them.
A sixth question applies only to initiatives and it is the one people skip: how many definitions are in it. The regulatory initiatives run into the hundreds, and assigning one is not assigning a rule, it is assigning a programme of work. Knowing the number before rather than after changes the conversation you have about it.
Where a built-in stops being enough
Three situations, and they are the whole reason the later half of this series exists. The rule is right but the threshold is wrong for your organisation. The rule is right but its mode or scope excludes something you need covered, and Microsoft’s own description sometimes tells you so directly. Or nothing in the catalogue addresses the thing at all, usually because it is specific to your naming, your tagging, or an internal standard nobody outside your organisation shares.
The first two are a customisation problem and the third is an authoring problem, and they carry different costs. Both come later. The order matters: implement what fits first, and let the gaps declare themselves, because a gap you have measured is a much better specification than a gap you predicted in a workshop.
From here
The build sheet that follows assigns the security baseline Microsoft maintains, in audit, on the Northfork estate, and then reads the result the way it should be read: by control rather than by resource, with the Microsoft-owned controls separated out from the ones that are actually yours to fix.
Azure Policy
‹ Previous: [AP 2] The Object Model: Definitions, Initiatives, and the Explicit Deny
Next: [AP 3.1] Build Sheet: Assign the Baseline and Read What It Did ›
