Azure Policy initiative definition structure
Initiatives enable you to group several related policy definitions to simplify assignments and management because you work with a group as a single item. For example, you can group related tagging policy definitions into a single initiative. Rather than assigning each policy individually, you apply the initiative.
You use JSON to create a policy initiative definition. The policy initiative definition contains elements for:
- display name
- description
- metadata
- version
- parameters
- policy definitions
The following example illustrates how to create an initiative for handling two tags: costCenter
and productName
. It uses two built-in policies to apply the default tag value.
{
"properties": {
"displayName": "Billing Tags Policy",
"policyType": "Custom",
"description": "Specify cost Center tag and product name tag",
"version" : "1.0.0",
"metadata": {
"version": "1.0.0",
"category": "Tags"
},
"parameters": {
"costCenterValue": {
"type": "String",
"metadata": {
"description": "required value for Cost Center tag"
},
"defaultValue": "DefaultCostCenter"
},
"productNameValue": {
"type": "String",
"metadata": {
"description": "required value for product Name tag"
},
"defaultValue": "DefaultProduct"
}
},
"policyDefinitions": [{
"policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/1e30110a-5ceb-460c-a204-c1c3969c6d62",
"parameters": {
"tagName": {
"value": "costCenter"
},
"tagValue": {
"value": "[parameters('costCenterValue')]"
}
}
},
{
"policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/2a0e14a6-b0a6-4fab-991a-187a4f81c498",
"parameters": {
"tagName": {
"value": "costCenter"
},
"tagValue": {
"value": "[parameters('costCenterValue')]"
}
}
},
{
"policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/1e30110a-5ceb-460c-a204-c1c3969c6d62",
"parameters": {
"tagName": {
"value": "productName"
},
"tagValue": {
"value": "[parameters('productNameValue')]"
}
}
},
{
"policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/2a0e14a6-b0a6-4fab-991a-187a4f81c498",
"parameters": {
"tagName": {
"value": "productName"
},
"tagValue": {
"value": "[parameters('productNameValue')]"
}
}
}
]
}
}
Azure Policy built-ins and patterns are at Azure Policy samples.
Metadata
The optional metadata
property stores information about the policy initiative definition.
Customers can define any properties and values useful to their organization in metadata
. However,
there are some common properties used by Azure Policy and in built-ins.
Common metadata properties
version
(string): Tracks details about the version of the contents of a policy initiative definition.category
(string): Determines under which category in the Azure portal the policy definition is displayed.preview
(boolean): True or false flag for if the policy initiative definition is preview.deprecated
(boolean): True or false flag for if the policy initiative definition has been marked as deprecated.
Parameters
Parameters help simplify your policy management by reducing the number of policy definitions. Think
of parameters like the fields on a form - name
, address
, city
, state
. These parameters
always stay the same, however their values change based on the individual filling out the form.
Parameters work the same way when building policy initiatives. By including parameters in a policy
initiative definition, you can reuse that parameter in the included policies.
Note
Once an initiative is assigned, initiative level parameters can't be altered. Due to this, the recommendation is to set a defaultValue when defining the parameter.
Parameter properties
A parameter has the following properties that are used in the policy initiative definition:
name
: The name of your parameter. Used by theparameters
deployment function within the policy rule. For more information, see using a parameter value.type
: Determines if the parameter is a string, array, object, boolean, integer, float, or datetime.metadata
: Defines subproperties primarily used by the Azure portal to display user-friendly information:description
: (Optional) The explanation of what the parameter is used for. Can be used to provide examples of acceptable values.displayName
: The friendly name shown in the portal for the parameter.strongType
: (Optional) Used when assigning the policy definition through the portal. Provides a context aware list. For more information, see strongType.
defaultValue
: (Optional) Sets the value of the parameter in an assignment if no value is given.allowedValues
: (Optional) Provides an array of values that the parameter accepts during assignment.
As an example, you could define a policy initiative definition to limit the locations of resources in the various included policy definitions. A parameter for that policy initiative definition could be allowedLocations. The parameter is then available to each included policy definition and defined during assignment of the policy initiative.
"parameters": {
"init_allowedLocations": {
"type": "array",
"metadata": {
"description": "The list of allowed locations for resources.",
"displayName": "Allowed locations",
"strongType": "location"
},
"defaultValue": [ "chinanorth2" ],
"allowedValues": [
"chinaeast2",
"chinanorth2",
"chinanorth"
]
}
}
Passing a parameter value to a policy definition
You declare which initiative parameters you pass to which included policy definitions in the policyDefinitions array of the initiative definition. While the parameter name can be the same, using different names in the initiatives than in the policy definitions simplifies code readability.
For example, the init_allowedLocations initiative parameter defined previously can be passed to several included policy definitions and their parameters, sql_locations and vm_locations, like this:
"policyDefinitions": [
{
"policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/0ec8fc28-d5b7-4603-8fec-39044f00a92b",
"policyDefinitionReferenceId": "allowedLocationsSQL",
"parameters": {
"sql_locations": {
"value": "[parameters('init_allowedLocations')]"
}
}
},
{
"policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/aa09bd0f-aa5f-4343-b6ab-a33a6a6304f3",
"policyDefinitionReferenceId": "allowedLocationsVMs",
"parameters": {
"vm_locations": {
"value": "[parameters('init_allowedLocations')]"
}
}
}
]
This sample references the init_allowedLocations parameter that was demonstrated in parameter properties.
strongType
Within the metadata
property, you can use strongType to provide a multiselect list of options
within the Azure portal. strongType can be a supported resource type or an allowed value. To
determine whether a resource type is valid for strongType, use
Get-AzResourceProvider.
Some resource types not returned by Get-AzResourceProvider are supported. Those resource types are:
Microsoft.RecoveryServices/vaults/backupPolicies
The non-resource type allowed values for strongType are:
location
resourceTypes
storageSkus
vmSKUs
existingResourceGroups
Policy definitions
The policyDefinitions
portion of the initiative definition is an array of which existing policy
definitions are included in the initiative. As mentioned in
Passing a parameter value to a policy definition,
this property is where initiative parameters are passed to the policy definition.
Policy definition properties
Each array element that represents a policy definition has the following properties:
policyDefinitionId
(string): The ID of the custom or built-in policy definition to include.policyDefinitionReferenceId
(string): A short name for the included policy definition.parameters
: (Optional) The name/value pairs for passing an initiative parameter to the included policy definition as a property in that policy definition. For more information, see Parameters.
Here's an example of policyDefinitions
that has two included policy definitions that are each
passed the same initiative parameter:
"policyDefinitions": [
{
"policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/0ec8fc28-d5b7-4603-8fec-39044f00a92b",
"policyDefinitionReferenceId": "allowedLocationsSQL",
"parameters": {
"sql_locations": {
"value": "[parameters('init_allowedLocations')]"
}
}
},
{
"policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/aa09bd0f-aa5f-4343-b6ab-a33a6a6304f3",
"policyDefinitionReferenceId": "allowedLocationsVMs",
"parameters": {
"vm_locations": {
"value": "[parameters('init_allowedLocations')]"
}
}
}
]
Next steps
- See the definition structure
- Review examples at Azure Policy samples.
- Review Understanding policy effects.
- 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.