Edit

Azure Policy pattern: group policy definitions

  • Article

An initiative is a group of policy definitions. By grouping related policy definitions into a single object, you can create a single assignment that would have been multiple assignments.

Sample initiative definition

This initiative deploys two policy definitions, each of which takes the tagName and tagValue parameters. The initiative itself has two parameters: costCenterValue and productNameValue. These initiative parameters are each provided to each of the grouped policy definitions. This design maximizes reuse of the existing policy definitions while limiting the number of assignments created to implement them as needed.

{
    "properties": {
        "displayName": "Billing Tags Policy Initiative",
        "description": "Specify cost Center tag and product name tag",
        "parameters": {
            "costCenterValue": {
                "type": "String",
                "metadata": {
                    "displayName": "required value for Cost Center tag"
                }
            },
            "productNameValue": {
                "type": "String",
                "metadata": {
                    "displayName": "required value for product Name tag"
                }
            }
        },
        "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')]"
                    }
                }
            }
        ]
    }
}

Explanation

Initiative parameters

An initiative can define it's own parameters that are then passed to the grouped policy definitions. In this example, both costCenterValue and productNameValue are defined as initiative parameters. The values are provided when the initiative is assigned.

"parameters": {
    "costCenterValue": {
        "type": "String",
        "metadata": {
            "displayName": "required value for Cost Center tag"
        }
    },
    "productNameValue": {
        "type": "String",
        "metadata": {
            "displayName": "required value for product Name tag"
        }
    }
},

Includes policy definitions

Each included policy definition must provide the policyDefinitionId and a parameters array if the policy definition accepts parameters. In the following snippet, the included policy definition takes two parameters: tagName and tagValue. tagName is defined with a literal, but tagValue uses the parameter costCenterValue defined by the initiative. This passthrough of values improves reuse.

{
    "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/2a0e14a6-b0a6-4fab-991a-187a4f81c498",
    "parameters": {
        "tagName": {
            "value": "costCenter"
        },
        "tagValue": {
            "value": "[parameters('costCenterValue')]"
        }
    }
},

Next steps