Skip to article
Management and Governance Azure Policy

Policy definition

The rule template that tells Azure Policy what to evaluate and which effect to apply when resources match.

Source: Microsoft Learn - Details of Azure Policy definition structure basics Reviewed 2026-05-30

Exam trap
Editing a definition without checking how many assignments already depend on it.
Production check
Run az policy definition show and inspect mode, parameters, and policyRule before assignment.
Practice this topic Microsoft Learn
Article details and learning context
Aliases
None listed
Difficulty
fundamentals
CLI mappings
5
Last verified
2026-05-30
Article depth
field-manual-complete
Learning paths Learn Policy, Compliance, and Remediation Policy definition
Compare related concepts Search related resources Browse the glossary

Understand the concept

In plain English

A policy definition is the rule itself in Azure Policy. It describes what Azure should look for and what should happen when a resource matches the rule. The definition can audit, deny, modify, append, or deploy supporting settings depending on its effect. For example, one definition might audit storage accounts without secure transfer, while another denies public IP creation. The definition is not active everywhere by itself; it becomes operational when assigned to a scope with parameters and enforcement choices.

Why it matters

Policy definition matters because it is where governance intent becomes machine-readable. A vague standard such as use approved regions or require diagnostics is not enough for automated enforcement. The definition encodes the condition, supported resource types, parameters, effect, and evaluation mode. If it is too broad, it blocks legitimate deployments. If it is too narrow, risky resources pass as compliant. If the aliases are wrong, the policy may never evaluate the property teams care about. Good definitions let organizations scale security, compliance, tagging, cost controls, and reliability standards without relying on manual review for every deployment. That precision is what makes automation trustworthy.

Official wording and source

An Azure Policy definition describes a governance rule for Azure resources. Microsoft Learn explains that a definition contains metadata, parameters, mode, and a policy rule whose conditions evaluate resources and whose effect determines what Azure Policy does when conditions match.

Open Microsoft Learn

Technical context

Technically, a policy definition is a JSON resource that belongs to the Azure governance control plane. It includes display metadata, mode, parameters, and a policyRule with if and then blocks. The if block evaluates resource properties, aliases, values, or logical operators. The then block declares the effect, such as audit, deny, append, modify, disabled, deployIfNotExists, or auditIfNotExists. Definitions can be built-in or custom, grouped in initiatives, assigned at scopes, and reported through policy state compliance records.

Exam context

What to know

operator-ready

Compare with

Policy assignment Initiative definition Policy exemption Template spec

Where it is used

Where you see it

  1. In the Azure Policy Definitions blade, users see built-in and custom definitions with display name, category, policy type, mode, parameters, and effect summary. during governance review
  2. In JSON files stored with platform code, policy definitions appear as policyRule if and then blocks that reviewers can diff before publishing. before production assignment
  3. In deployment-denied errors, the policy definition ID and rule details help operators identify which condition matched the attempted resource configuration. during troubleshooting and audit reviews

Common situations

  • Create a custom rule that denies public network access for a service not covered by built-in policies.
  • Parameterize allowed regions or required tags so one definition can support multiple business units.
  • Group related definitions into an initiative for security, reliability, or cost-management baselines.
  • Audit existing resources before enforcing a deny effect in production subscriptions.
  • Use modify or deployIfNotExists definitions to standardize settings that teams repeatedly forget.

Illustrative Azure scenarios

These examples show how the concept can affect design and operations. They are illustrative scenarios, not customer claims.

Scenario 01 Port authority writes a precise private endpoint rule A port authority created a custom definition after built-in controls missed a service-specific exposure risk.
Scenario

A port authority used Azure for vessel scheduling, customs document exchange, and camera metadata. A security review found that one niche data service could still be deployed with public network access because no built-in policy covered the exact property.

Goals
  • Create a custom policy definition for the uncovered service setting.
  • Avoid blocking unrelated resources that shared the same provider namespace.
  • Test the rule in audit mode before enabling deny.
  • Reuse the definition across harbor operations and logistics subscriptions.
Approach using Policy definition

Platform engineers wrote a custom policy definition with a narrowly scoped if condition that matched the service resource type and public network property. The then block used audit during testing, and parameters controlled whether the desired state was Disabled or a specific approved value. They validated the alias against sample ARM exports and tested known compliant and noncompliant resources in a sandbox subscription. After two clean compliance cycles, the definition was assigned through an initiative and moved to deny for new deployments.

Potential outcomes
  • The custom rule found 11 exposed resources that generic policies missed.
  • False positives stayed under 2 percent during the audit pilot.
  • New public deployments for the service were blocked before the next security audit.
  • The same definition supported three subscription groups through parameters instead of cloned JSON.
What to learn

A good policy definition turns a specific risk into repeatable governance logic without punishing unrelated resources.

Scenario 02 Fashion marketplace standardizes chargeback tags A marketplace used parameterized policy definitions to make cost allocation enforceable across short-lived teams.
Scenario

A fashion marketplace had dozens of campaign teams creating Azure resources for photo processing, search experiments, and recommendation services. Finance could not allocate costs because tag names and values varied by team.

Goals
  • Define a reusable required-tag rule for campaign and product-line ownership.
  • Keep allowed values parameterized by subscription group.
  • Start with audit results before denying new resource creation.
  • Reduce manual month-end cost cleanup.
Approach using Policy definition

The FinOps and platform teams built a custom policy definition that checked for required tags and accepted values using assignment parameters. Rather than hard-code campaign names, they used metadata and parameter files per management group. The rule first ran with an audit effect so product owners could fix existing resources. After 30 days, the same definition was assigned with a deny effect for new resources. CLI exports of the definition JSON and assignment parameters were stored with the finance controls repository. The workflow also linked every denied deployment to a remediation example for campaign engineers and reviewers.

Potential outcomes
  • Resources missing chargeback tags dropped from 42 percent to 6 percent in two billing cycles.
  • Month-end allocation cleanup decreased from three days to four hours.
  • No campaign team needed a custom cloned definition.
  • Deny-related support tickets fell after example templates were added to developer docs.
What to learn

Parameterized policy definitions let governance teams enforce cost standards while still adapting to different operating groups.

Scenario 03 Satellite analytics team audits diagnostic coverage A space analytics firm wrote definitions that audited missing telemetry before moving to automatic remediation.
Scenario

A satellite imagery analytics firm ran storage, event ingestion, GPU processing, and search services across research subscriptions. Incident reviews showed that missing diagnostic settings made it hard to trace failed image-processing runs.

Goals
  • Build definitions that identify resources lacking required diagnostics.
  • Separate audit logic from later remediation rollout.
  • Cover only resource types with approved log categories.
  • Give engineers clear noncompliance reasons tied to service properties.
Approach using Policy definition

The cloud reliability team created a set of custom policy definitions for resource types used in the imagery pipeline. Each definition checked whether diagnostic settings existed and whether required categories were enabled. They avoided a single broad rule because log categories differed by service. Definitions were grouped into an initiative and assigned in audit mode first. After engineers fixed the largest gaps, selected definitions were converted into deployIfNotExists variants with managed identity remediation. The definition repository included example compliant resources and test cases for service upgrades. The added tests made future service changes safer to review.

Potential outcomes
  • Diagnostic coverage for critical pipeline services rose from 61 percent to 94 percent.
  • Image-processing incident reconstruction time dropped from 90 minutes to 28 minutes.
  • The team avoided noisy false positives by using service-specific definitions.
  • Remediation work was prioritized from accurate audit findings instead of manual inventories.
What to learn

Policy definitions work best when they are precise enough to generate trustworthy compliance signals that operators can act on.

Azure CLI

As an Azure engineer, I use Azure CLI for policy definitions because I need to inspect the actual JSON, not just the friendly name. CLI lets me list built-in and custom definitions, show rule logic, compare modes, export parameters, create or update definitions from version-controlled files, and find assignments that use a definition. That is critical when a deployment denial says a policy blocked the resource but the portal summary hides the exact if condition. CLI also fits governance pipelines where definitions move from development to test to production with reviewable diffs and repeatable validation. without relying on portal memory.

Useful for

  • List definitions by category or policy type when selecting a built-in control.
  • Show a definition's rule, mode, aliases, parameters, and effect before assignment.
  • Create or update a custom definition from JSON stored in a repository.
  • Find assignments that reference a definition before changing or retiring it.
  • Export definition JSON for review during a deployment-denial investigation.

Before you run a command

  • Confirm whether you are inspecting built-in or custom definitions and which scope owns custom definitions.
  • Check permissions for policy definition read or write operations at subscription or management-group scope.
  • Validate JSON syntax, policy mode, parameters, and aliases before creating or updating a definition.
  • Treat definition updates as high impact because existing assignments may immediately evaluate new logic.
  • Use source-controlled files and JSON output so reviewers can see the exact rule being published.

What the output tells you

  • The mode tells you which resource evaluation behavior the definition uses, such as All, Indexed, or provider-specific modes.
  • The policyRule shows the if conditions and then effect that drive compliance or denial behavior.
  • Parameters reveal which values must be supplied during assignment and which defaults may apply.
  • Policy type and ID show whether the definition is built-in, custom, and safe to reference in automation.

Mapped commands

Azure Policy definition commands

direct 
az policy definition list --query "[].{name:name,displayName:displayName,policyType:policyType,mode:mode}" --output table
az policy definitiondiscoverManagement and Governance
read-only Microsoft Learn 
az policy definition show --name <definition-name>
az policy definitiondiscoverManagement and Governance
read-only Microsoft Learn 
az policy definition create --name <definition-name> --rules rules.json --params parameters.json --mode All
az policy definitionsecureManagement and Governance
mutating Microsoft Learn 
az policy definition update --name <definition-name> --rules rules.json --params parameters.json
az policy definitionsecureManagement and Governance
mutating Microsoft Learn 
az policy assignment list --policy <definition-id> --output table
az policy assignmentdiscoverManagement and Governance
read-only Microsoft Learn

Architecture context

Architecturally, policy definitions are the reusable building blocks of Azure governance. I design them like code: versioned, reviewed, tested, parameterized, and assigned through a controlled rollout path. Built-in definitions cover common controls, while custom definitions fill gaps unique to naming, regions, data boundaries, diagnostic standards, or service-specific requirements. Definitions should avoid hard-coding business-unit values when parameters can keep one rule reusable. They should also have documented effect strategy: audit first, deny when safe, modify or deployIfNotExists only with clear remediation identity and rollback. A weak definition becomes organizational folklore; a strong one becomes dependable platform guardrail. That discipline keeps custom governance maintainable.

Security
Security impact is direct because policy definitions encode controls that can stop or report unsafe configuration. Definitions can deny public exposure, audit missing encryption, require private endpoints, enforce managed identity patterns, or deploy diagnostic settings. They can also create false confidence if written with the wrong mode, incomplete aliases, or effects that do not apply to the target resource type. Custom definitions should be code-reviewed by security and platform teams, tested against known compliant and noncompliant examples, and documented with expected bypass or exemption paths. The definition is the security control logic; assignment only decides where it runs. That review prevents dangerous blind spots.
Cost
Policy definitions influence cost by preventing or flagging expensive patterns before they spread. Definitions can restrict premium SKUs, enforce required tags, require budgets or diagnostics standards, and block resource types that a subscription is not approved to run. They can also add cost indirectly when deployIfNotExists definitions create monitoring, backup, security, or networking resources. Poorly written definitions may force teams into expensive compliant alternatives or trigger excessive remediation. FinOps teams should review custom definitions that affect SKU, region, retention, redundancy, or resource type choices. A policy definition is not billed directly, but it can steer millions in deployment decisions. before spend grows silently.
Reliability
Reliability impact is usually indirect but powerful. Definitions can require backup, zone redundancy, diagnostic settings, approved SKUs, or deployment patterns that improve resilience. They can also cause reliability problems if deny effects block urgent fixes or if deployIfNotExists changes resources unexpectedly. Teams should test definitions in audit mode, measure noncompliance volume, and communicate effect changes before enforcement. For reliability-sensitive controls, definitions should be precise enough to avoid blocking unrelated resources. A policy rule that treats every resource type the same often creates noise instead of resilience, which causes operators to ignore compliance results. This keeps resilience controls helpful instead of disruptive.
Performance
Application runtime performance is usually not directly changed by a policy definition, but delivery and operational performance are. Clear definitions catch bad configurations early and reduce manual architecture review. Confusing definitions slow deployments, create denial loops, and force engineers to decode JSON during release windows. Definitions can also influence performance indirectly by enforcing SKUs, regions, diagnostics, or network settings. For example, a rule that blocks unapproved regions may prevent latency-heavy deployments, while a badly scoped rule may block a required performance tier. Governance teams should test definitions against realistic templates before assigning them broadly. That clarity improves release throughput measurably.
Operations
Operators use policy definitions to understand why resources are compliant, denied, modified, or remediated. Work includes reading policyRule logic, checking parameters, mapping aliases to resource properties, finding assignments that reference the definition, and testing changes in a controlled scope. When troubleshooting, operators should not stop at the assignment name; they need the definition ID, effect, condition, and evaluated field. Platform teams should keep custom definitions in source control, include examples, document expected effects, and run periodic reviews for deprecated aliases or service behavior changes. Good definitions reduce support tickets; unclear definitions create them. This turns governance logic into supportable platform code.

Common mistakes

  • Editing a definition without checking how many assignments already depend on it.
  • Hard-coding business values instead of using parameters for allowed locations, tags, or SKUs.
  • Using the wrong policy mode and wondering why expected resources never evaluate.
  • Skipping audit-mode testing before deploying a broad deny definition.
  • Writing a rule against an alias that does not match the service property being governed.