Azure Policy initiative definition structure

  • Article

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
  • 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",
        "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.

Note

The Azure Policy service uses version, preview, and deprecated properties to convey level of change to a built-in policy definition or initiative and state. The format of version is: {Major}.{Minor}.{Patch}. Specific states, such as deprecated or preview, are appended to the version property or in another property as a boolean. For more information about the way Azure Policy versions built-ins, see Built-in versioning.

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 the parameters 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