Policy definition mode tells Azure Policy what kind of resources the policy should evaluate. The all mode evaluates resource groups, subscriptions, and resource types. The indexed mode focuses on resource types that support tags and location, which is useful for tag and location policies. Some built-in policies use resource provider modes for deeper surfaces such as Kubernetes or Key Vault data. Choosing the wrong mode can make a policy miss resources, mark the wrong resources non-compliant, or fail to behave the way authors expect.
Policy definition mode determines which resource types Azure Policy evaluates for a policy definition. Resource Manager modes include all and indexed, while resource provider modes target specific data or component surfaces. The mode must match the rule’s intended resource properties and evaluation behavior.
In Azure architecture, policy definition mode is part of the policy definition JSON under Microsoft.Authorization. It works with aliases, effects, parameters, and policy rules to decide evaluation coverage. The common Resource Manager modes are all and indexed. Resource provider modes, such as Microsoft.Kubernetes.Data or Microsoft.KeyVault.Data, evaluate specialized provider surfaces and may have different support boundaries. Mode affects compliance results, false positives, child resource behavior, and whether a custom definition can express the intended guardrail. CLI and PowerShell can set mode when creating definitions.
Why it matters
Policy definition mode matters because a policy rule can be logically correct and still evaluate the wrong resource universe. A tag policy using all may mark resources without tag support as non-compliant. A policy that should cover resource groups or subscriptions may fail if it relies on indexed behavior. A resource provider mode policy may handle components that ordinary Resource Manager mode does not cover. For learners, mode explains why two similar policies produce different compliance results. For operators, it is a common root cause behind confusing dashboards, failed deployments, and custom policies that appear assigned but do not catch the intended condition.
⌁
Where you see it
Signals, screens, and Azure surfaces where this term usually becomes operational.
Signal 01
In policy definition JSON, the mode field appears near displayName, description, metadata, parameters, and policyRule, commonly set to all or indexed during policy authoring reviews.
Signal 02
In az policy definition show output, properties.mode tells operators whether the definition evaluates broad Resource Manager resources or an indexed subset during troubleshooting reviews.
Signal 03
In compliance troubleshooting, unexpected non-compliant resources or missing findings often lead engineers back to the policy definition mode and alias combination after assignment and rollout changes.
✦
When this becomes relevant
Specific situations where this term helps solve real Azure design, operations, migration, security, reliability, cost, or governance problems.
Choose indexed for tag or location policies to avoid noisy non-compliance from resources that do not support those fields.
Use all when a policy must evaluate resource groups, subscriptions, or broad Resource Manager resource types.
Troubleshoot a custom policy that misses resources by comparing mode, aliases, API shape, and assignment scope.
Document why a resource provider mode is used for specialized built-in governance such as Kubernetes or Key Vault data surfaces.
Validate mode choices in policy-as-code tests before assigning deny or modify effects at management group scale.
◆
Real-world case studies
Different enterprise-style examples that show the term being used to hit measurable objectives.
Case study 01
Fixing noisy tag compliance for streaming workloads
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
StreamVista ran content delivery, analytics, and live-event tooling in Azure. Its required tag policy marked many resources non-compliant even when those resource types did not support tags meaningfully.
🎯Business/Technical Objectives
Reduce false positives in tag compliance reporting.
Keep cost-center tags enforced for resources that support them.
Avoid weakening production cost allocation controls.
Teach platform engineers how mode affects policy results.
✅Solution Using Policy definition mode
The governance team reviewed the custom tag policy and found it used all mode without targeting appropriate resource types. They changed the definition to indexed for tag enforcement and tested it against storage, compute, networking, and unsupported resource examples. Azure CLI showed the updated properties.mode value and exported compliance results before and after the change. The policy-as-code pull request documented why indexed was chosen and listed sample resources used for validation. Production assignments were updated after a test subscription showed that real tag gaps still appeared while noisy unsupported resources disappeared. Reviewers approved the update after confirming sample findings.
📈Results & Business Impact
False tag non-compliance dropped by 67 percent.
Cost-center tag coverage for supported production resources stayed above 95 percent.
Monthly FinOps review time decreased by three days.
Policy authors added a mode review checklist to every custom definition change.
💡Key Takeaway for Glossary Readers
Policy definition mode can decide whether compliance reporting is useful evidence or distracting noise.
Case study 02
Catching subscription-level location gaps in biotech research
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
GeneWave Labs needed strict location governance for regulated research data. A custom policy was catching many resources but failed to evaluate subscription and resource group scenarios used by shared research platforms.
🎯Business/Technical Objectives
Evaluate location controls at resource, resource group, and subscription boundaries.
Remove uncertainty about why some scopes were missing from compliance data.
Prevent regulated research workloads from landing in unapproved regions.
Validate policy behavior before assigning a deny effect.
✅Solution Using Policy definition mode
Architects compared the policy rule with exported resource group and subscription JSON. They found the definition used indexed mode, which was not appropriate for the required scope coverage. The team rewrote the definition with all mode and explicit type conditions for resource groups and subscriptions. Azure CLI confirmed properties.mode and policy state output after assignment in a test management group. The deny effect remained disabled during validation, then moved to a controlled production scope after compliance results matched expected pass and fail examples. Documentation explained why all mode was necessary for this control.
📈Results & Business Impact
Previously missed resource group findings appeared in the next compliance scan.
Unapproved region deployments in regulated subscriptions fell to zero after enforcement.
Policy troubleshooting time decreased because mode behavior was documented.
The lab avoided a planned blanket exemption that would have weakened location controls.
💡Key Takeaway for Glossary Readers
The right definition mode ensures Azure Policy evaluates the scope where the real governance requirement lives.
Case study 03
Understanding provider mode for connected device governance
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
CircuitVale Devices operated AKS clusters that hosted device telemetry processors. Security wanted Azure Policy to evaluate Kubernetes components, but application teams expected ordinary Resource Manager policy behavior.
🎯Business/Technical Objectives
Explain why Kubernetes component policies behaved differently from ARM policies.
Validate which built-in definitions used provider mode.
Avoid copying unsupported provider mode patterns into custom definitions.
Improve remediation planning for cluster-level policy findings.
✅Solution Using Policy definition mode
The platform team inspected built-in policy definitions with Azure CLI and focused on the mode field. Kubernetes-related built-ins used a provider mode that evaluated cluster components rather than only the parent Azure resource. The team compared those results with ordinary all mode Resource Manager policies for AKS cluster configuration. Training material showed how mode, assignment scope, and component compliance states worked together. Custom policy work stayed with supported Resource Manager modes, while specialized Kubernetes governance used the built-ins and documented limitations. Compliance reports separated cluster resource findings from component-level findings. The architecture board approved the guidance.
📈Results & Business Impact
Policy-related AKS support tickets dropped by 41 percent.
No unsupported provider-mode custom policies were introduced into production.
Security reporting separated parent resource compliance from component findings.
Cluster remediation planning became clearer for platform and application teams.
💡Key Takeaway for Glossary Readers
Provider modes are powerful, but architects must understand their support boundaries before depending on them for governance.
Why use Azure CLI for this?
As an Azure engineer with ten years of policy authoring experience, I use Azure CLI for definition mode because it exposes the raw definition without portal simplification. CLI can show the properties.mode value, create definitions with a chosen mode, list provider aliases, and query states after assignment. That combination helps me prove whether a compliance surprise is caused by mode, alias, scope, or effect. The portal is fine for browsing, but CLI output belongs in pull requests and troubleshooting notes. It also makes it easy to compare built-in and custom definitions before copying a pattern incorrectly. during incident triage.
CLI use cases
Show a policy definition and confirm whether properties.mode is all, indexed, or a provider mode.
Create a custom definition with --mode Indexed for a tested tag or location requirement.
List provider aliases before deciding whether the mode and field expressions can evaluate the target property.
Query policy states after assignment to verify the chosen mode produced expected compliance results.
Before you run CLI
Confirm tenant, subscription, management group, and definition location before creating or updating custom policy definitions.
Check the intended resource types, aliases, effects, and whether the policy should include resource groups or subscriptions.
Use read-only show and list commands before updating definitions that may affect existing assignments across many scopes.
Prefer JSON output because mode, policyRule, parameters, and aliases are nested and easy to misread in table form.
What output tells you
properties.mode shows the evaluation mode that controls which resource types the policy definition considers.
policyRule fields and aliases show whether the rule is targeting properties supported by the chosen mode.
metadata, policyType, version, and parameters help distinguish built-in patterns from custom definitions copied into policy-as-code.
Policy state output confirms whether the mode produced expected compliant and non-compliant resources after assignment.
Mapped Azure CLI commands
Policy definition mode CLI commands
direct
az policy definition show --name <definition-name> --query "{name:name,mode:properties.mode,policyType:properties.policyType}" --output json
az policy definitiondiscoverManagement and Governance
az policy definitionsecureManagement and Governance
az policy definition list --query "[].{name:name,mode:properties.mode,policyType:properties.policyType}" --output table
az policy definitiondiscoverManagement and Governance
az provider show --namespace <namespace> --expand "resourceTypes/aliases" --output json
az providerdiscoverManagement and Governance
az policy state list --policy-definition <definition-name> --top 50 --output json
az policy statediscoverManagement and Governance
Architecture context
A seasoned Azure architect treats policy definition mode as a design choice, not a default to ignore. Most governance definitions start with all unless there is a clear reason to use indexed for tag or location enforcement. Resource group and subscription policies usually require all with explicit type targeting. Provider modes belong in specialized scenarios, often built-in definitions, where the provider exposes component-level policy behavior. The architecture review should verify the resource types, aliases, arrays, effects, and sample resources before assignment. Mode should be documented in policy-as-code because future maintainers need to understand why the definition evaluated that boundary.
Security
Security impact is direct when mode determines whether protective rules evaluate the intended resources. A policy that misses a resource type can leave public access, weak TLS, missing diagnostics, or unsupported regions undetected. A policy with overly broad mode can produce false non-compliance and encourage teams to request exemptions instead of fixing real risk. Access to create and update definitions should be restricted, and custom definition changes should be reviewed for mode, aliases, effect, and target types. Security teams should test mode choices with known compliant and non-compliant resources before relying on the policy for enforcement evidence. Evidence should prove coverage.
Cost
Cost impact is indirect. Mode can determine whether cost controls such as allowed SKUs, required tags, allowed regions, or diagnostic requirements evaluate the right resources. If mode misses resources, spending can drift outside approved patterns. If mode creates false positives, teams spend time chasing policy noise or requesting exemptions. Some provider mode policies may enforce settings that add cost, such as diagnostics or security features, and that tradeoff should be deliberate. FinOps reviews should check that tag and location policies use a mode that produces useful compliance evidence without flooding reports with resources that cannot support the requirement. Owners need evidence.
Reliability
Reliability impact is indirect but meaningful. Mode can enforce reliability controls only when the relevant resource types are evaluated correctly. Backup, zone redundancy, diagnostics, SKU, and region guardrails all depend on the policy definition reaching the right resources. Wrong mode can block valid deployments, miss critical resources, or inflate non-compliance reports with resources that cannot satisfy the rule. Reliable rollout includes testing definitions in non-production, reviewing compliance states, and checking provider mode limitations. When a policy failure appears during deployment, mode should be part of the triage path along with alias, effect, scope, and parameters. Teams should document tested examples.
Performance
Runtime performance impact is usually indirect. Mode does not change application request latency, but it affects policy evaluation scope, deployment feedback, and troubleshooting speed. A well-chosen mode narrows evaluation to the right surface and makes compliance findings easier to interpret. A poor mode creates noise, missed findings, or unexpected deployment failures that slow teams down. Resource provider modes may expose component-level results that require more careful querying. Operators improve diagnostic performance by filtering policy states, checking mode early, and validating definitions against representative resource JSON before broad assignment. Clear mode choices shorten policy design and incident reviews. Reviews become faster.
Operations
Operators encounter policy definition mode when creating custom definitions, troubleshooting compliance surprises, and reviewing policy-as-code pull requests. They inspect the mode field, compare it with the rule’s aliases and target resource types, and test against exported resource JSON. Azure CLI helps show definitions, create definitions with a mode value, list provider aliases, and query policy states after assignment. Operational runbooks should explain when indexed is appropriate, why all is safer for broad Resource Manager coverage, and when provider modes are limited to supported built-ins. Documentation should capture sample resources used to validate the mode choice. Operators should preserve samples.
Common mistakes
Using indexed for a policy that must evaluate resource groups, subscriptions, or resource types outside tag and location support.
Leaving mode null in older CLI-created definitions and forgetting that it behaves like indexed for backward compatibility.
Copying a built-in provider mode pattern into a custom policy without checking support boundaries.
Debugging only assignment scope when the real issue is the definition mode and alias combination.