Azure Policy definition structure parameters

  • Article

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 but their values change based on the individual filling out the form. Parameters work the same way when building policies. By including parameters in a policy definition, you can reuse that policy for different scenarios by using different values.

Adding or removing parameters

Parameters might be added to an existing and assigned definition. The new parameter must include the defaultValue property. This property prevents existing assignments of the policy or initiative from indirectly being made invalid.

Parameters can't be removed from a policy definition because there might be an assignment that sets the parameter value, and that reference would become broken. Some built-in policy definitions deprecate parameters using metadata "deprecated": true, which hides the parameter when assigning the definition in Azure portal. While this method isn't supported for custom policy definitions, another option is to duplicate and create a new custom policy definition without the parameter.

Parameter properties

A parameter uses the following properties in a policy 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: 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.
    • assignPermissions: (Optional) Set as true to have Azure portal create role assignments during policy assignment. This property is useful in case you wish to assign permissions outside the assignment scope. There's one role assignment per role definition in the policy (or per role definition in all of the initiative's policies). The parameter value must be a valid resource or scope.
    • deprecated: A boolean flag to indicate whether a parameter is deprecated in a built-in definition.
  • defaultValue: (Optional) Sets the value of the parameter in an assignment if no value is given. Required when updating an existing policy definition that is assigned. For oject-type parameters, the value must match the appropriate schema.
  • allowedValues: (Optional) Provides an array of values that the parameter accepts during assignment.
    • Case sensitivity: Allowed value comparisons are case-sensitive when assigning a policy, meaning that the selected parameter values in the assignment must match the casing of values in the allowedValues array in the definition. However, once values are selected for the assignment, evaluation of string comparisons might be case insensitive depending on the condition used. For example, if the parameter specifies Dev as an allowed tag value in an assignment, and this value is compared to an input string using the equals condition, then Azure Policy would later evaluate a tag value of dev as a match even though it's lowercase because notEquals is case insensitive.
    • For object-type parameters, the values must match the appropriate schema.
  • schema: (Optional) Provides validation of parameter inputs during assignment using a self-defined JSON schema. This property is only supported for object-type parameters and follows the Json.NET Schema 2019-09 implementation. You can learn more about using schemas at https://json-schema.org/ and test draft schemas at https://www.jsonschemavalidator.net/.

Sample parameters

Example 1

As an example, you could define a policy definition to limit the locations where resources can be deployed. A parameter for that policy definition could be allowedLocations and used by each assignment of the policy definition to limit the accepted values. The use of strongType provides an enhanced experience when completing the assignment through the portal:

"parameters": {
  "allowedLocations": {
    "type": "array",
    "metadata": {
      "description": "The list of allowed locations for resources.",
      "displayName": "Allowed locations",
      "strongType": "location"
    },
    "defaultValue": [
      "westus2"
    ],
    "allowedValues": [
      "eastus2",
      "westus2",
      "westus"
    ]
  }
}

A sample input for this array-type parameter (without strongType) at assignment time might be ["westus", "eastus2"].

Example 2

In a more advanced scenario, you could define a policy that requires Kubernetes cluster pods to use specified labels. A parameter for that policy definition could be labelSelector and used by each assignment of the policy definition to specify Kubernetes resources in question based on label keys and values:

"parameters": {
  "labelSelector": {
    "type": "Object",
    "metadata": {
      "displayName": "Kubernetes label selector",
      "description": "Label query to select Kubernetes resources for policy evaluation. An empty label selector matches all Kubernetes resources."
    },
    "defaultValue": {},
    "schema": {
      "description": "A label selector is a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. An empty label selector matches all resources.",
      "type": "object",
      "properties": {
        "matchLabels": {
          "description": "matchLabels is a map of {key,value} pairs.",
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "minProperties": 1
        },
        "matchExpressions": {
          "description": "matchExpressions is a list of values, a key, and an operator.",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "key": {
                "description": "key is the label key that the selector applies to.",
                "type": "string"
              },
              "operator": {
                "description": "operator represents a key's relationship to a set of values.",
                "type": "string",
                "enum": [
                  "In",
                  "NotIn",
                  "Exists",
                  "DoesNotExist"
                ]
              },
              "values": {
                "description": "values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty.",
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "key",
              "operator"
            ],
            "additionalProperties": false
          },
          "minItems": 1
        }
      },
      "additionalProperties": false
    }
  },
}

A sample input for this object-type parameter at assignment time would be in JSON format, validated by the specified schema, and might be:

{
  "matchLabels": {
    "poolID": "abc123",
    "nodeGroup": "Group1",
    "region": "southcentralus"
  },
  "matchExpressions": [
    {
      "key": "name",
      "operator": "In",
      "values": [
        "payroll",
        "web"
      ]
    },
    {
      "key": "environment",
      "operator": "NotIn",
      "values": [
        "dev"
      ]
    }
  ]
}

Using a parameter value

In the policy rule, you reference parameters with the following parameters function syntax:

{
  "field": "location",
  "in": "[parameters('allowedLocations')]"
}

This sample references the 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. The format for a resource type strongType is <Resource Provider>/<Resource Type>. For example, Microsoft.Network/virtualNetworks/subnets.

Some resource types not returned by Get-AzResourceProvider are supported. Those types are:

  • Microsoft.RecoveryServices/vaults/backupPolicies

The non resource type allowed values for strongType are:

  • location
  • resourceTypes
  • storageSkus
  • vmSKUs
  • existingResourceGroups

Next steps