policy assignment scope

This browser is no longer supported.

Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.

Azure Policy assignment structure

• 9 contributors

Policy assignments are used by Azure Policy to define which resources are assigned which policies or initiatives. The policy assignment can determine the values of parameters for that group of resources at assignment time, making it possible to reuse policy definitions that address the same resource properties with different needs for compliance.

For more information on Azure Policy scope, see Understand scope in Azure Policy .

You use JavaScript Object Notation (JSON) to create a policy assignment. The policy assignment contains elements for:

• display name
• description
• resource selectors
• enforcement mode
• excluded scopes
• policy definition
• non-compliance messages

For example, the following JSON shows a policy assignment in DoNotEnforce mode with dynamic parameters:

All Azure Policy samples are at Azure Policy samples .

Display name and description

You use displayName and description to identify the policy assignment and provide context for its use with the specific set of resources. displayName has a maximum length of 128 characters and description a maximum length of 512 characters.

The optional metadata property stores information about the policy assignment. Customers can define any properties and values useful to their organization in metadata . However, there are some common properties used by Azure Policy. Each metadata property has a limit of 1,024 characters.

Common metadata properties

assignedBy (string): The friendly name of the security principal that created the assignment.

createdBy (string): The GUID of the security principal that created the assignment.

createdOn (string): The Universal ISO 8601 DateTime format of the assignment creation time.

parameterScopes (object): A collection of key-value pairs where the key matches a strongType configured parameter name and the value defines the resource scope used in Portal to provide the list of available resources by matching strongType . Portal sets this value if the scope is different than the assignment scope. If set, an edit of the policy assignment in Portal automatically sets the scope for the parameter to this value. However, the scope isn't locked to the value and it can be changed to another scope.

The following example of parameterScopes is for a strongType parameter named backupPolicyId that sets a scope for resource selection when the assignment is edited in the Portal.

updatedBy (string): The friendly name of the security principal that updated the assignment, if any.

updatedOn (string): The Universal ISO 8601 DateTime format of the assignment update time, if any.

evidenceStorages (object): The recommended default storage account that should be used to hold evidence for attestations to policy assignments with a manual effect. The displayName property is the name of the storage account. The evidenceStorageAccountID property is the resource ID of the storage account. The evidenceBlobContainer property is the blob container name in which you plan to store the evidence.

Resource selectors

The optional resourceSelectors property facilitates safe deployment practices (SDP) by enabling you to gradually roll out policy assignments based on factors like resource location, resource type, or whether a resource has a location. When resource selectors are used, Azure Policy will only evaluate resources that are applicable to the specifications made in the resource selectors. Resource selectors can also be used to narrow down the scope of exemptions in the same way.

In the following example scenario, the new policy assignment is evaluated only if the resource's location is either East US or West US .

When you're ready to expand the evaluation scope for your policy, you just have to modify the assignment. The following example shows our policy assignment with two more Azure regions added to the SDPRegions selector. Note, in this example, SDP means to Safe Deployment Practice :

Resource selectors have the following properties:

name : The name of the resource selector.

selectors : (Optional) The property used to determine which subset of resources applicable to the policy assignment should be evaluated for compliance.

kind : The property of a selector that describes which characteristic narrows down the set of evaluated resources. Each kind can only be used once in a single resource selector. Allowed values are:

resourceLocation : This property is used to select resources based on their type. Can't be used in the same resource selector as resourceWithoutLocation .

resourceType : This property is used to select resources based on their type.

resourceWithoutLocation : This property is used to select resources at the subscription level that don't have a location. Currently only supports subscriptionLevelResources . Can't be used in the same resource selector as resourceLocation .

in : The list of allowed values for the specified kind . Can't be used with notIn . Can contain up to 50 values.

notIn : The list of not-allowed values for the specified kind . Can't be used with in . Can contain up to 50 values.

A resource selector can contain multiple selectors . To be applicable to a resource selector, a resource must meet requirements specified by all its selectors. Further, up to 10 resource selectors can be specified in a single assignment. In-scope resources are evaluated when they satisfy any one of these resource selectors.

The optional overrides property allows you to change the effect of a policy definition without modifying the underlying policy definition or using a parameterized effect in the policy definition.

The most common use case for overrides is policy initiatives with a large number of associated policy definitions. In this situation, managing multiple policy effects can consume significant administrative effort, especially when the effect needs to be updated from time to time. Overrides can be used to simultaneously update the effects of multiple policy definitions within an initiative.

Let's take a look at an example. Imagine you have a policy initiative named CostManagement that includes a custom policy definition with policyDefinitionReferenceId corpVMSizePolicy and a single effect of audit . Suppose you want to assign the CostManagement initiative, but don't yet want to see compliance reported for this policy. This policy's 'audit' effect can be replaced by 'disabled' through an override on the initiative assignment, as shown in the following sample:

Overrides have the following properties:

kind : The property the assignment will override. The supported kind is policyEffect .

value : The new value that overrides the existing value. The supported values are effects .

selectors : (Optional) The property used to determine what scope of the policy assignment should take on the override.

kind : The property of a selector that describes what characteristic will narrow down the scope of the override. Allowed value for kind: policyEffect is:

• policyDefinitionReferenceId : This specifies which policy definitions within an initiative assignment should take on the effect override.

Note that one override can be used to replace the effect of many policies by specifying multiple values in the policyDefinitionReferenceId array. A single override can be used for up to 50 policyDefinitionReferenceIds, and a single policy assignment can contain up to 10 overrides, evaluated in the order in which they're specified. Before the assignment is created, the effect chosen in the override is validated against the policy rule and parameter allowed value list (in cases where the effect is parameterized ).

Enforcement mode

The enforcementMode property provides customers the ability to test the outcome of a policy on existing resources without initiating the policy effect or triggering entries in the Azure Activity log .

This scenario is commonly referred to as "What If" and aligns to safe deployment practices. enforcementMode is different from the Disabled effect, as that effect prevents resource evaluation from happening at all.

This property has the following values:

If enforcementMode isn't specified in a policy or initiative definition, the value Default is used. Remediation tasks can be started for deployIfNotExists policies, even when enforcementMode is set to DoNotEnforce .

Excluded scopes

The scope of the assignment includes all child resource containers and child resources. If a child resource container or child resource shouldn't have the definition applied, each can be excluded from evaluation by setting notScopes . This property is an array to enable excluding one or more resource containers or resources from evaluation. notScopes can be added or updated after creation of the initial assignment.

An excluded resource is different from an exempted resource. For more information, see Understand scope in Azure Policy .

Policy definition ID

This field must be the full path name of either a policy definition or an initiative definition. policyDefinitionId is a string and not an array. The latest content of the assigned policy definition or initiative is retrieved each time the policy assignment is evaluated. It's recommended that if multiple policies are often assigned together, to use an initiative instead.

Non-compliance messages

To set a custom message that describes why a resource is non-compliant with the policy or initiative definition, set nonComplianceMessages in the assignment definition. This node is an array of message entries. This custom message is in addition to the default error message for non-compliance and is optional.

Custom messages for non-compliance are only supported on definitions or initiatives with Resource Manager modes definitions.

If the assignment is for an initiative, different messages can be configured for each policy definition in the initiative. The messages use the policyDefinitionReferenceId value configured in the initiative definition. For details, see policy definitions properties .

This segment of the policy assignment provides the values for the parameters defined in the policy definition or initiative definition . This design makes it possible to reuse a policy or initiative definition with different resources, but check for different business values or outcomes.

In this example, the parameters previously defined in the policy definition are prefix and suffix . This particular policy assignment sets prefix to DeptA and suffix to -LC . The same policy definition is reusable with a different set of parameters for a different department, reducing the duplication and complexity of policy definitions while providing flexibility.

For policy assignments with effect set to deployIfNotExist or modify , it's required to have an identity property to do remediation on non-compliant resources. When using identity, the user must also specify a location for the assignment.

A single policy assignment can be associated with only one system- or user-assigned managed identity. However, that identity can be assigned more than one role if necessary.

• Learn about the policy definition structure .
• Understand how to programmatically create policies .
• Learn how to get compliance data .
• Learn how to remediate non-compliant resources .
• Review what a management group is with Organize your resources with Azure management groups .

Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback .

Submit and view feedback for

Additional resources

DEV Community

Posted on Oct 31, 2022

Bicep and Azure Policy: Manage Policy and Initiative Assignment

This is the third post about Azure Policy. This time, the post will focus on policy assignments with Azure Bicep and PowerShell. Policy assignment enforces a policy and a policy set at a given scope, management group, or subscription. This is where policies are applied to target resources.

A policy Assignment object has several properties:

• A name (limited to 24 characters at the management group scope, 64 characters for other scopes)
• A location, the Azure to store the operation metadata
• A display name, limited to 128 characters
• An identity object
• A description
• The enforcement mode, either default (enforced) or DonotEnforce
• A non-compliance object. The message will be displayed when resources are not compliant with the policy.
• A not scope array, to not apply the assignment at some management group or subscriptions
• A parameters object, to apply parameters for the policy for the assignment
• The Policy definition ID, resource ID of the policy definition, or the policy set

In Bicep language

The deployment of this bicep file could be done by the New-AzManagementGroupDeployment cmdlet. But like custom policy definitions and policy sets, you will certainly be asked to not assign only one policy. How can you manage several policy assignments in one place? This is the same problem we had with deploying policies. But even if a policy assignment can be seen as a JSON document, the amount of information needed to assign a policy is limited. Instead of using one JSON file per assignment, we can create a single JSON document with all assignments, but we need to take care of the scope.

the bicep file:

This Bicep file will deploy a policy assignment. As the deployment will be made via PowerShell, we need to convert the value of the parameters and the nonComplianceMessage properties from string to JSON with the JSON function in Bicep.

All the parameters needed for the deployment are stored in a JSON document.

There is one policy to assign but two assignments in the JSON document. It’s to illustrate the power of parameters in the assignment process. You can assign the same policy, multiple times, even at the same scope, as long as the name changes and the parameters are different.

Each object in the JSON document will serve to deploy the assignment via a PowerShell script.

The script read the content of the JSON document and for each object, it extracts the variable needed to deploy the bicep file. But there is a difficulty, the bicep nonComplianceMessages require a JSON array, but most of the time there will be only one message or no message at all (multiple messages are only used for policy set). And if there is only one message (or none) you will not end up with a JSON array, but a simple JSON object, so a modification is needed.

To deploy, simply run the deployAssignment.ps1 from its folder. You can add the "location" parameter to adjust the azure region for your needs.

You can find the related PwSh/Bicep code here

Top comments (0)

Templates let you quickly answer FAQs or store snippets for re-use.

Are you sure you want to hide this comment? It will become hidden in your post, but will still be visible via the comment's permalink .

Hide child comments as well

For further actions, you may consider blocking this person and/or reporting abuse

Streamlining Azure Cloud Infrastructure with AKS and Hub & Spoke Model

Mike Tyson of the Cloud - Jan 12

Jumpstart Your AI Skilling Journey in 2024 with the Microsoft AI Tour!

Nitya Narasimhan, Ph.D - Jan 10

Using MongoDB Atlas with Azure Kubernetes Service - Coded with Pulumi

Paul Reichelt-Ritter - Jan 10

Microsoft Sentinel : Using KQL to detect failed login on Linux

Aniket Rajendra Trimbake - Jan 7

We're a place where coders share, stay up-to-date and grow their careers.

Assignment Naming Element

Assigning policy sets or policies, assignment scopes and excluded scopes, defining parameters with json, defining overrides with json, defining noncompliancemessages with json.

• Defining parameters, overrides and nonComplianceMessages with a CSV file

Defining resourceSelectors

Defining metadata, defining enforcementmode.

• Policy Exemptions

Policy Assignments

This chapter describes how Policy Assignments are handled by EPAC. To learn about how custom Policy and Policy Set definitions are managed, see the Policies and Policy Set Definitions .

Assignment JSON structure

Assignment JSON is hierarchical for efficient definitions, avoiding duplication (copy/paste) of JSON. Each branch of the tree is cumulative. Each tree node must include a nodeName - an arbitrary string exclusively used by EPAC to display an error location. EPAC concatenates a leading / and the nodeName entries encountered in the tree to create a "breadcrumbs" trail; therefore, we recommend that you use / to help separate the concatenated nodeName . The following (partial and invalid) assignment tree would create this error message.

JSON Schema

The GitHub repo contains a JSON schema which can be used in tools such as VS Code to provide code completion.

To utilize the schema add a $schema tag to the JSON file.

This schema is new in v7.4.x and may not be complete. Please let us know if we missed anything.

• Every tree branch must accumulate a definitionEntry (or definitionEntryList ), Assignment naming ( name and displayName ) and scope element.
• The elements parameters , overrides , resourceSelectors , notScope , enforcementMode , metadata , userAssignedIdentity , managedIdentityLocations , additionalRoleAssignments and nonComplianceMessages are optional.
• For Policy Sets with large numbers of included Policies you should use a spreadsheet (CSV file) to manage effects (parameterized or effect overrides ), parameters and optional nonComplianceMessages . We recommend the CSV approach for Policy Sets with more than 10 included Policies.
• EPAC continues to support deprecated elements initiativeId , initiativeName and ignoreBranch , Consider using their replacements policySetId , policySetName and enforcementMode instead.

The tree is not required to be balanced. The number of levels is not restricted; however, anything beyond 3 levels is unnecessary in real scenarios and would be difficult to read and manage as the depth increases.

Tree Structure

Each Assignment is required to have a name which is used in it's resource id. EPAC also requires a displayName . The description is optional. For the allowed location assignment you specify the component with:

Multiple assignment naming components in a tree branch are string concatenated for each of the three fields.

Azure has a limit of 24 characters for the concatenated name string. EPAC displays an error if this limit is exceeded.

Each assignment assigns either a Policy or Policy Set. In EPAC this is done with a definitionEntry or a definitionEntryList . Exactly one occurrence must exist in any collated tree branch. For each entry, you need to specify one of the following:

• policyName - custom Policy managed by EPAC. Specifying just the name allows EPAC to inject the correct definition scope.
• policySetName - custom Policy Set managed by EPAC.
• policyId - resource id for builtin Policy.
• policySetId - resource id for builtin Policy Set.

displayName is an optional field to document the entry if the Policy name is a GUID. Builtin Policies and Policy Sets use a GUID.

Using definitionEntryList allows you to save on copy/paste tree branches. Without it, the number of branches would need to be duplicated as many times as the list has entries.

Each entry in the list creates an Assignment at each leaf of the tree. Since assignments must have unique names at a specific scope, the Assignment naming component must be amended for each list entry. In this sub-component you can decide if you want to concatenate the string by appending or prepending them by specifying append boolean value.

In the above example one of the children (leaf node) has the following Assignment name.

This example generates two assignments at the "prod" leaf per scope:

• /providers/Microsoft.Management/managementGroups/ Contoso-Prod /providers/Microsoft.Authorization/policyAssignments/ pr-asb
• displayName = "Prod Azure Security Benchmark"
• description = "Prod Environment controls enforcement with Azure Security Benchmark Initiative."
• /providers/Microsoft.Management/managementGroups/ Contoso-Prod /providers/Microsoft.Authorization/policyAssignments/ pr-nist-800-53-r5
• displayName = "Prod NIST SP 800-53 Rev. 5"
• description = "Prod Environment controls enforcement with NIST SP 800-53 Rev. 5 Initiative."

scope is required exactly once in each tree branch. Excluded scopes ( notScope ) are cumulative from global-settings.json and the entire tree branch; however, once a scope is defined notScope may not be defined at any child node.

Both scope and notScope are specific to an EPAC Environment using the pacSelector name , e.g., epac-dev and tenant .

notScope works the same. In addition "*" means all EPAC Environments which is most often used for resourceGroupPatterns .

Managed Identities and role assignments

Policies with a DeployIfNotExists or Modify effect need a Managed Identity (MI) and role assignments to execute remediation task. EPAC calculates the necessary role assignments based on the roleDefinitionIds in the Policy definition. By default EPAC uses a system-assigned Manged Identity. The team maintaining EPAC recommend system-assigned identities; however, your organization may have role assignment reasons to use user-assigned Managed Identities.

Defining managedIdentityLocations

Policy assignments requiring a Managed Identity (system-assigned or user-assigned) require a location managedIdentityLocations . You must specify the location based on EPAC Environment or use "*" to use the same location for all of the EPAC Environments. You can specify them in global-settings.jsonc or at any node in the tree. The last (closest to the leaf node) is the one chosen if multiple managedIdentityLocations entries are encountered in a tree branch.

Defining optional additionalRoleAssignments

In some scenarios you will need additionalRoleAssignments ; e.g., for diagnostics settings to Event Hubs, the target resource might be in a different Management Group and therefore the Managed Identity requires additional role assignments. You must specify the additionalRoleAssignments based on EPAC Environment or use "*" to use the same additionalRoleAssignments for all of the EPAC Environments.

User-assigned Managed Identities

Azure Policy can use a user-defined Managed Identity and EPAC allows you to use this functionality (new in version 7.0). You must specify the user-defined Managed Identity based on EPAC Environment or use "*" to use the same identity for all of the EPAC Environments (only possible in single tenant scenarios). Within each EPAC Environment entry, you can specify just the URI string indicating to use the same identity even if we are using a definitionEntryList , or in the case of a definitionEntryList can assign a different identity based on the definitionEntryList by specifying a matching policyName , policyId , policySetName or policySetId .

The rest (below) of the node components are optional.

parameters have a simple JSON structure. You do not need the additional value indirection Azure requests (EPAC will inject that indirection).

Too enable definitionEntryList , parameters not present in the Policy or Policy Set definition are quietly ignored.

overrides are in the same format as documented by Azure . They are cumulative in each tree branch. The selectors element is only used for Assignments of Policy Sets. They are not valid for Assignments of a single Policy.

If using definitionEntryList , you must add the policyName , policyId , policySetName or policySetId as used in the definitionEntryList item.

Assign a non-compliance message to the assignment, or individual non-compliance messages if the assignment is for an Policy Set. This value is an array of objects - each containing a message, and in the case of an initiative a policyDefinitionReferenceId. See this link for details.

If you use single definitionEntry , place them normally. If you use a definitionEntryList place them in the respective list entry.

Defining parameters , overrides and nonComplianceMessages with a CSV file

Assigning single or multiple security and compliance focused Policy Sets (Initiatives), such as Azure Security Benchmark, NIST 800-53 r5, PCI, NIST 800-171, etc, with just JSON parameters becomes very complex fast. Add to this the complexity of overriding the effect if it is not surfaced as a parameter in the Policy Set using overrides . Finally, adding the optional nonComplianceMessages further increases the complexity.

To address the problem of reading and maintaining hundreds or thousands of JSON lines, EPAC can use the content of a spreadsheet (CSV) to create parameters , overrides and optionally nonComplianceMessages for a single Policy assignment definitionEntry or multiple Policy definitions ( definitionEntryList ).

This approach is best for very large Policy Sets such as Azure Security Benchmark, NIST 800-53, etc. Smaller Policy Sets should still be handled with JSON parameters , overrides and nonComplianceMessages .

Start by generating documentation for one or more of those Policy Sets , then modify the effect and parameter columns for each type of environment types you will use. In the example header below the infrastructure environments prod, test, dev, and sandbox are used as prefixes to the columns for Effect and Parameters respectively. Optionally you can add a column for nonComplianceMessages . If you want to switch from JSON to CSV, you can generate this CSV file frm your already deployed Assignment(s) .

The CSV file generated contains the following headers/columns:

name,referencePath,policyType,category,displayName,description,groupNames,policySets,allowedEffects,allowedOverrides,prodEffect,testEffect,devEffect,sandboxEffect,prodParameters,testParameters,devParameters,sandboxParameters,nonComplianceMessages

Column explanations:

• name is the name of the policyDefinition referenced by the Policy Sets being assigned.
• referencePath is only used if the Policy is used more than once in at least one of the Policy Sets to disambiguate them. The format is <policySetName>//<policyDefinitionReferenceId> .
• policyType , category , displayName , description , groupNames , policySets , allowedEffects are optional and not used for deployment planning. They assist you in filling out the <env>Effect columns.
• <env>Effect columns must contain one of the allowedValues or allowedOverrides values. You define which scopes define each type of environment and what short name you give the environment type to use as a column prefix.
• <env>Parameters can contain additional parameters. You can also specify such parameters in JSON. EPAC will use the union of all parameters.
• nonComplianceMessages column is optional. The documentation script does not generate this columns.

EPAC will find the effect parameter name for each Policy in each Policy Set and use them. If no effect parameter is defined by the Policy Set, EPAC will use overrides to set the effect. EPAC will generate the policyDefinitionReferenceId for nonComplianceMessages .

After building the spreadsheet, you must reference the CSV file and the column prefix in each tree branch. parameterFile can be overridden in a child node; however, it is often used once per tree branch and defined adjacent to the 'definitionEntry or definitionEntryList .

In the child nodes specifying the scope(s) specify which column prefix to use for selecting the CSV columns with parameterSelector . The actual prefix names have no meaning; they only need to match between the JSON below and the CSV file.

The element nonComplianceMessageColumn may appear anywhere in the tree. Definitions at a child override the previous setting. If no nonComplianceMessageColumn is specified, the spreadsheet is not used for the (optional) nonComplianceMessages .

resourceSelectors may appear anywhere in the tree and are cumulative in any branch. They follow the standard Azure Format .

metadata is sometimes used to track tickets for changes. Do NOT specify EPAC-reserved elements roles and pacOwnerId . For the final metadata EPAC creates the union of instances in the entire tree branch.

enforcementMode is similar to the deprecated ignoreBranch ; it deploys the assignment and sets the assignment to Default or DoNotEnforce . DoNotEnforce allows a what-if analysis. enforcementMode may appear anywhere in the tree. Definitions at a child override the previous setting.

Example assignment files

Simple policy assignment (allowed locations).

In the simple case an assignment is a single assignment or with no difference in assignment , parameters , and definitionEntry across multiple scopes. In many scenarios "Allowed Locations" is such a simple Assignment. Such Assignments do not have child nodes, just the root node.

• nodeName is required for error messages; it's value is immaterial. EPAC concatenates them in the current tree branch.
• definitionEntry specifies that the custom Policy Set general-allowed-locations-policy-set from our starter kit. displayName has no meaning - it is for readability and in this instance is superfluous.
• assignment fields name , displayName and description are used when creating the assignment.
• This assignment has no metadata . You don't need an empty collection. EPAC will add pacOwnerId and roles metadata . Do not add them manually.
• enforcementMode is set to default - it is superfluous.
• parameters are obvious. Note: you don't add the value layer Azure inserts - EPAC takes care of that.
• During Policy resource development (called epac-dev ) the Assignment is deployed to an EPAC development Management Group Epac-Mg-1 .
• During Policy prod deployments ( tenant -wide), it is deployed to the tenant Management Group Epac-Mg-1 .
• No notScope entries are specified.

If we remove the empty and superfluous entries, we arrive at:

Security-Focused Policy Assignment with JSON parameters

• In the following example we named our root node ( nodeName ) /security/ . Since it is only used in case of error messages produced by EPAC during planning it's actual value doesn't matter as long as it's unique.
• We use a definitionEntryList to create two assignments at every leaf (six assignments total).
• For assignment string concatenation we append the strings in the definitionEntryList to the strings in the child nodes. You can see this best when you look at the description string in the child nodes. It will form a sentence when concatenated by append ing the definitionEntryList assignment field description .
• The parameters specified in the children are specific to the IaC environment types and their scope . Note: a real assignment would define many more parameters. The set here is abbreviated since the actual set could easily exceed a hundred entries for each of the IaC environments. We'll see in the next example how to simplify large Policy Set parameters with a CSV file.

Security-Focused Policy Assignment with CSV file parameters

This example is the same as the previous, except we replaced inline JSON parameters with a CSV file and use the column prefixes in the CSV file to select which parameter values we use by:

• Setting the file name at the root node with

json "parameterFile": "security-baseline-parameters.csv",

• Setting the column prefix with parameterSelector to prod , nonprod and sandbox . For example:

The CSV file is explained above . The entire file is:

Inverted Policy Assignment (Tag Inheritance and Required Tags)

As mentioned above sometimes it is advantageous (to reduce the number of repetitions) to turn a definition on its head:

• Common parameters , scope , definitionEntryList (with two Policies) at the root ( nodeName is /Tags/ ).
• Start of the assignment strings ( append is defaulted to false ). Again look at description which will be a concatenated sentence.
• The children define the tagName parameter and the second part of the strings for assignment . The set of parameters is the union of the root node and the child node.
• This creates six Assignments (number of Policies assigned times number of children).

Non-Compliance Messages in a Policy Definition Assignment

An example of a policy assignment for a single policy definition with a default non-compliance message.

Non-Compliance Messages in a Policy Set Definition Assignment

An example of a policy assignment for a policy set definition with a default non-compliance message and a policy specific non-compliance message.

Non-Compliance Messages in a Policy Set Definition Assignment with a definitionEntryList

An example of how to use a non-compliance message when using a definitionEntryList list in the assignment.

How to deploy Azure Policy with Bicep

It has been a while since I wrote about Azure Policy last time, plus recently there was a lot of hype around Bicep , so I decided to give it a try and shed some light on creating and deploying custom Azure policies with that new language.

Prerequisites

I assume that you are already familiar with what Azure Policy is and how it works. If you are new to that really helpful and often underrated technology, I suggest checking out my Azure Policy Starter Guide .

Also, I recommend that you read through official Bicep documentation to get some notion about this new domain-specific language, which Microsoft promotes as an abstraction over ARM templates and Azure Resource Manager.

Bicep basics for Azure Policy

Like JSON-based ARM templates, Bicep is a declarative language that allows you to define desired Azure resource configuration and let Azure Resource Manager do its job of provisioning it. Initially, you had to compile a Bicep file into a regular ARM template to deploy your configuration. However, it is not the case anymore as both Azure CLI and Azure PowerShell now support deploying Bicep definitions . Note that input parameters for Bicep definitions are still come in the same format as for old-school ARM templates .

Apart from that, as we work with the same Azure service, you should expect that all Azure Policy specifics are applicable regardless of the language you use to define your configurations. So, all the tips and tricks you learned about creating, deploying and evaluating Azure Policy are still relevant.

Speaking of Bicep, you can define a single policy as well as a policy initiative, aka policy set, along with their assignment to a specific scope using the Bicep resource primitive . For example, to create a custom Azure Policy, you can define the following resource in your Bicep file:

As you might notice from that sample, in order for some policy-specific syntax to be valid, you should use backslash as an escape character for single quotation marks. Also, you shouldn’t use an additional forward square bracket in the expressions as it will be automatically added to the JSON during the Bicep build.

In the same manner, you can define your custom policy initiative:

As policy initiatives don’t define any rules, they use the ‘ policyDefinitions’ keyword to reference existing policy definitions.

Policy and policy initiative assignments are also pretty straightforward and defined as yet another resource:

For complete definitions, look into bicep samples in my Azure Policy repository on GitHub . Besides, the Bicep product team and the community regularly update and create new sample Bicep definitions for various Azure services, including Azure Policy, so I suggest checking them for additional cases.

Advanced technics

Now, when the basics are clear, let’s look into more advanced topics.

First of all, remember that you can deploy your custom Azure policy definitions at the subscription and management group levels only . At the same time, Azure Policy assignments can be created at the management group, subscription, and resource group levels. Also, keep in mind that the deployment scope of a policy, in turn, effectively limits its assignment scope .

The Bicep VS Code extension will warn you about the resources that cannot be deployed to the target scope, and the Bicep compiler will produce the compilation error.

In terms of Bicep definitions, you can scope your deployments by using the ‘ targetScope ’ keyword. Depending on that scope, a bicep file will be compiled into an ARM template using the corresponding deployment schema.

Using different deployment scopes will also impact the way you reference other resources in your configuration. If it is a new resource defined in the same Bicep file, then using standard syntax like ‘ resourceSymbolicName.Id ’ should be enough. However, when you need to reference an existing resource , e.g., a policy definition in policy initiative, first you should correctly define that resource in your Bicep file, and second, you should use the correct reference function:

• for Azure Policy definitions deployed at the subscription level use the ‘ subscriptionResourceId ’ function;
• for Azure Policy definitions deployed at the management group level use the ‘ extensionResourceId ’ function as custom policy definitions are implemented as resource extensions .

If you want to assign your policy at the tenant level, you should use the Tenant Root Group for that.

For example, to reference your existing policy definition deployed at the subscription level in a policy initiative, you can define it as the following:

Same referencing but at the management group level can be accomplished with the following syntax:

I don’t cover the Azure Policy exemptions feature here as it’s currently in preview and might change in the future.

Current drawbacks

Unfortunately, authoring Azure Policies with Bicep is still far from ideal. So, here are a few things that are not specifically related to Azure Policy, but rather Bicep language-generic features or their absence that annoyed me.

As I already mentioned, referencing policies from policy initiatives is a bit complicated and non-intuitive as you must be explicit about your reference scopes and always keep that nuance in mind. On a larger scale, when you have dozens of definitions that are defined in separate files and need to be deployed and assigned at different scopes, the new authoring experience is quite painful.

The next thing, which adds up to the negative authoring and debugging experience, is the lack of IntelliSense support for Azure Policy internal logic defined in Bicep files . What is more, the syntax highlighting for Bicep-defined Azure Policy rules in VS Code is also very limited. Apart from that, I was also unpleasantly surprised that, in contrast to the ARM template authoring experience, Bicep will not warn you about unused parameters or variables you have in your files.

Lastly, the way you currently define human-readable names and descriptions for policy parameters using the Bicep parameter decorators looks a bit awkward for me:

Why not provide the same simplified syntax for the ‘name’ metadata tag for the ‘description’ ?

Fortunately, the Bicep product team makes good progress in implementing new Bicep features and providing the community with simpler and better options for defining Azure infrastructure as code, and I’m impatiently looking forward to new Bicep releases .

If you were writing lots of ARM templates and haven’t tried Bicep yet, I certainly recommend you check it out and post your impressions in the comments below!

Written by:

Andrew Matveychuk

Member discussion:.

Manage Azure Policy with Terraform

I am going to reverse the order I would normally explain a concept, in this blog we will look at the call to the module first and then dive into each of the components.

The Module Call

The initiative definition.

Let's step into the initiative definition next.

There are four top-level keys that we have to set:

• name — unique name for the initiative.
• display_name — the name displayed with the initiative.
• description — a description of what the policy is for and does.
• policies — objects containing the value definitions of BuiltIn and Custom policies.

With these properties we will be able to pass in all of the relevant values into our policies for a range of environments, further, we can also set a default if we don't have values specific to an environment. Let's take a look at the two types of policy definitions.

First, let's take a look at the policy properties:

• type — the type of policy that we are referencing; Custom or BuiltIn .
• file — if the policy is Custom we require the name of the file to import. This will be forced into the ${path.root}/policies/ directory by the Terraform code.
• id — the GUID id of an existing Azure policy provided by Microsoft, this is required when type is set to BuiltIn .
• default — the default parameter and effect values.
• dev/uat/prd/... — the key is the environment and the keys must be the same as default , this provides an optional setting of policy parameters by the environment.

Inside the default or environment block we have the following few properties:

• effect — the effect this policy will have, deny as an example. This property cannot be set on BuiltIn policies.

Custom Policy Definition

The key at the beginning AllowedLocations is how we will reference our policy and retrieve its components in the Terraform code. By allowing us to pass in the file to a json file it allows us to easily create custom policies alongside the fantastic baseline policies that Microsoft already give us. In the above example if we were running our Terraform code in the uat environment our code would use the properties we have defined in default as there are no environment-specific overrides. Allowing this makes our Terraform more powerful as perhaps when we start with Azure policy we don't necessarily understand what each environment requires, or they all explicitly require the same types of enforcement.

Built-in Policy Definition

The above is how we would set our parameters for a Built-in Azure policy. Remembering that we cannot set the effect of this policy as that is set by Microsoft, if you did need to alter that effect then it would be best to use a custom policy.

The Custom Policy Definition

We won't go into the mud on how to write an Azure Policy Definition if you're interested in that then check out the Azure Policy definition structure article by Microsoft.

The main point here is that you have a json definition of the Azure Policy either that you have written from scratch or perhaps you're pulling from the Azure portal so that you're now able to change the effect. As you can see on the high-lighted line below the value for the effect key is using string interpolation which will be set by templatefile in our Terraform code later. This is how we are going to be setting the effect on a per-environment basis.

Now we get into the fun stuff 🎉! Whilst going through the module I am going to split it up into some sub-sections to make it easier for us to talk through. Further, the module supports three scopes; Management Group ( mg ), Subscription ( sub ), and Resource Group ( rg ) I will just be referencing the resource group code below as it is almost identical to the other scopes.

The Module Interface .css-1a60e3e{transition-property:var(--chakra-transition-property-common);transition-duration:var(--chakra-transition-duration-fast);transition-timing-function:var(--chakra-transition-easing-ease-out);cursor:pointer;-webkit-text-decoration:none;text-decoration:none;outline:2px solid transparent;outline-offset:2px;color:inherit;font-weight:var(--chakra-fontWeights-normal);opacity:0;margin-left:var(--chakra-space-2);}.css-1a60e3e:hover,.css-1a60e3e[data-hover]{opacity:1;color:var(--chakra-colors-accent-500);-webkit-text-decoration:underline;text-decoration:underline;}.css-1a60e3e:focus,.css-1a60e3e[data-focus]{opacity:1;color:var(--chakra-colors-accent-500);-webkit-text-decoration:underline;text-decoration:underline;} #

If you've worked with me or read my articles before you would know that I treat the variables.tf as our documented API interface, think of it like an OpenAPI definition for a REST API. We will go through each variable one by one.

Our first variable is initiative_definition this is where we pass the full path to our definition yaml file like we discussed in The Initiative Definition .

Secondly, we need to pass in an environment , this must be in whatever format you've used in the initiative definition otherwise our Terraform code won't be able to retrieve the properties for an environment.

The most important input variable for us is the assignment variable, this is where we pass in a single or list of resource IDs we are going to be assigning the policy initiative. Allowing a list of assignments means that we can deal with assignments on a larger scale than a single resource. This is especially powerful when operating in an enterprise environment.

The name property of the assignments object we will use as part of our exemptions process, this ensures there is an easy and intentional lookup for us when we are trying to exempt a resource from a given initiative.

We also have some validation ensuring that the scope passed in is valid for our scenario.

When Azure Policy is concerned there is always going to be a requirement to be able to exempt some resources from having that policy applied/enforced on them. We manage that here through the use of the exemptions variable. This variable allows us to pass in a list of our exemptions object. We have the assignment_reference which as we mentioned above is a reference to name in the assignments object. This allows us to cleanly look up which assignment we are looking to exempt a given resource for.

In this variable, we need to validate that our exemption scope is valid, not only valid for Azure but for our given scenario. For instance, you can exempt a single resource from a policy but our module only supports down to the resource group is the most granular level. The second thing we are validating is that the category on the exemption is one of the two valid strings as expected by Microsoft.

Local Variables and Setup #

The first few pieces of setup that we are going to do is get some random_uuid 's setup that we can use for unique names of our policies, assignments and exemptions. Some properties in the azurerm the provider will auto-generate names for us, and others won't. In this instance, we are going to be dealing with the generation of the names.

Next, we need to decode our initiative_definition yaml into a Terraform object that we can use throughout our module. The policies local variable is a convenience variable for us so that we can quickly access the property. Also, if the way we access the policies object/key from our yaml file changes the code that consumes the policies doesn't need to know about that change.

Policy definitions #

We use an azurerm_policy_definition resource for a Custom policy and the azurerm_policy_definition data source for our BuiltIn policies. Doing so allows us to support both in our module.

When we are creating a Custom policy we have an object that is the filename of a policy json file before creating these policy instances we need to complete the templatefile on each policy. We will loop through our local.policies object and decodes each file to json once the templatefile action has been performed and we have applied the effect either via a default key from our initiative definition or an environment-specific one. This will only occur when the type property is Custom . Then we simply take the properties from our json and plug them into the resource. Some properties such as; metadata , policy_rule , and parameters require to have jsonencode on the object we are retrieving from the policy json as when we do our for_each those are converted into objects that Terraform can deal with.

For the data source, we simply need to loop through our local.policies object and filter to only use objects where the type property is BuiltIn . We do this by using a for expression within the for_each block. You can read more about that in my post Terraform For Expressions .

Policy Initiative #

Now that we have all of our policies in the state we require them its time to create our initiative and pass in the parameter values to each policy.

First off we will merge all our policies, both the resource and the data source. This will give us a single object to operate on. Using the new all_policies object we will get the parameter values, this will be environment specific if available otherwise it will return default . Having a pre-populated property for this allows for easy access within the azurerm_policy_set_definition resource.

Now we have two objects; all_policies and parameters these two combined are what allow us to set up all the policies within the initiative. Using a dynamic block -which you can read more about here - we will iterate over each policy in local.all_policies and assign the parameter_values from the local.parameters variable based on the key from our for_each . This is easily possible as when we created the local.parameters variable we did so by doing a for_each over the local.all_policies variable, this means that both the dynamic block and our parameters variable will use the same value as a key.

Policy Assignment #

The actual policy assignment portion of the module is most likely the simplest part. In this, we simply for through the var.assignment.assignments list and return a map where the key is the name property and the value is the id property of our assignments object.

We do however do a check on scope to ensure that we are operating on the right scope for the right resource type. In this instance the resource group. If we were doing this on azurerm_management_group_policy_assignment the resource then our check would be if var.assignment.scope == "mg" . You can see that in the full module code the terraform-azurerm-policy-initiative repository on my GitHub.

Policy Exemption #

The exemptions are where things get a little funkier, as we need to be able to match zero or more exemptions to the correct assignment.

Our first problem to solve is how we reference the correct Terraform resource block given each assignment type ( mg , sub , rg ) has its own Terraform resource. We do this by using the local variables' ability to reference a resource rather than a string. The try is important as Terraform will try to evaluate each of these even if they're not called which would be fine except that they will never all exist at the same time given assignment can only be done on a single scope.

With the above we can now access the right Terraform resource with the following:

To be honest, the ability to reference other resources with locals is INCREDIBLY powerful!!

Now that we can get the right policy assignment it's time to deal with the exemption side of things. For this, we are going to for through our assignments and our exemptions variables to create a new data structure containing all the relevant pieces of data. The assignment_id key will only ever return one value due to the use of the one function, this behavior is 💯 what we want if there was an instance where there were more than one assignment ID for a specific assignment_reference we would know someone has made a mistake. At this stage, we also validate that the assignment.scope is correct.

You can read more about the for expressions in my Terraform For Expressions post.

The name property is something that we construct out of the random_uuid for the exemptions as well as the last component of the resource ID. In the instance of a resource group that will be the name of the resource group. We also use this same logic to generate the id or key field on our for_each it is because of this that the resource we are referencing must exist before this code is run. If the resource does not exist then Terraform will error out saying that it is unable to determine the value of something that is part of the ID of a map. Whilst this behavior is not ideal I also don't think that it is that bad. The reason being is that should we ever try and exempt a policy on a resource that doesn't exist Terraform/Azure is going to wig out, therefore the behavior is more or less the same just at a different place in the run.

Closing Out #

Today we have gone through a module I've created to deal with creating Azure Policy initiatives. We went through the initiative definition, the custom policy definition and the module itself. By using this module we are now easily able to deploy and manage Azure Policies and exemptions on our cloud platform at scale. We also ensured that we can have the right level of flexibility when it comes to setting the parameter values and the effects on an Azure Policy.

For me, this was not what I would call an easy module to write, as it required me to think about how I could get the most amount of configuration information into the module without making it overly complex to consume. However, going back to My Development Workflow helped me through the process. This module had four iterations before it got to what we have here today.

You can find this module at BrendanThompson/terraform-azurerm-policy-initiative

I would love to hear from you on if you think this module is useful and what you have done to manage something as complex as Azure Policy in your cloud environment!

Azure Policy Subscription Policy Assignment

This page shows how to write Terraform and Azure Resource Manager for Policy Subscription Policy Assignment and write them securely.

Review your .tf file for Azure best practices

Shisho Cloud, our free checker to make sure your Terraform configuration follows best practices, is available (beta).

azurerm_subscription_policy_assignment (Terraform)

The Subscription Policy Assignment in Policy can be configured in Terraform with the resource name azurerm_subscription_policy_assignment . The following sections describe 6 examples of how to use the resource and its parameters.

• Example Usage from GitHub

Review your Terraform file for Azure best practices

The following arguments are supported:

name - (Required) The name which should be used for this Policy Assignment. Changing this forces a new Policy Assignment to be created.

policy_definition_id - (Required) The ID of the Policy Definition or Policy Definition Set. Changing this forces a new Policy Assignment to be created.

subscription_id - (Required) The ID of the Subscription where this Policy Assignment should be created. Changing this forces a new Policy Assignment to be created.

description - (Optional) A description which should be used for this Policy Assignment.

display_name - (Optional) The Display Name for this Policy Assignment.

enforce - (Optional) Specifies if this Policy should be enforced or not?

identity - (Optional) An identity block as defined below.

- > Note: The location field must also be specified when identity is specified.

location - (Optional) The Azure Region where the Policy Assignment should exist. Changing this forces a new Policy Assignment to be created.

metadata - (Optional) A JSON mapping of any Metadata for this Policy.

not_scopes - (Optional) Specifies a list of Resource Scopes (for example a Subscription, or a Resource Group) within this Management Group which are excluded from this Policy.

parameters - (Optional) A JSON mapping of any Parameters for this Policy. Changing this forces a new Management Group Policy Assignment to be created.

A identity block supports the following:

• type - (Optional) The Type of Managed Identity which should be added to this Policy Definition. The only possible value is SystemAssigned .

In addition to the Arguments listed above - the following Attributes are exported:

• id - The ID of the Subscription Policy Assignment.

The identity block exports the following:

principal_id - The Principal ID of the Policy Assignment for this Subscription.

tenant_id - The Tenant ID of the Policy Assignment for this Subscription.

>> from Terraform Registry

• Explanation in Terraform Registry

Manages a Subscription Policy Assignment.

Microsoft.Authorization/policyAssignments (Azure Resource Manager)

The policyAssignments in Microsoft.Authorization can be configured in Azure Resource Manager with the resource name Microsoft.Authorization/policyAssignments . The following sections describe how to use the resource and its parameters.

The Other Related Azure Policy Resources

Azure Policy Assignment

Azure Policy Configuration Policy Assignment

Azure Policy Definition

Azure Policy Policy Assignment

Azure Policy Remediation

Azure Policy Resource Group Policy Assignment

Azure Policy Set Definition

Azure Policy Virtual Machine Configuration Assignment

• Frequently asked questions

What is Azure Policy Subscription Policy Assignment?

Azure Policy Subscription Policy Assignment is a resource for Policy of Microsoft Azure. Settings can be wrote in Terraform.

Where can I find the example code for the Azure Policy Subscription Policy Assignment?

For Terraform, the globalbao/azure-policy-as-code , quintindk/azurebootcamp21 and acend/terraform-training-env source code examples are useful. See the Terraform Example section for further details.

For Azure Resource Manager, the lolittle/azure , microsoft/azure_arc and karlochacon/my-arc-repo source code examples are useful. See the Azure Resource Manager Example section for further details.

Automate config file reviews on your commits

Fix issues in your infrastructure as code with auto-generated patches.

Table of Contents