Edit

Azure Policy definitions modify effect

  • Article

The modify effect is used to add, update, or remove properties or tags on a subscription or resource during creation or update. A common example is updating tags on resources such as costCenter. Existing non-compliant resources can be remediated with a remediation task. A single Modify rule can have any number of operations. Policy assignments with effect set as Modify require a managed identity to do remediation.

The modify effect supports the following operations:

  • Add, replace, or remove resource tags. For tags, a Modify policy should have mode set to indexed unless the target resource is a resource group.
  • Add or replace the value of managed identity type (identity.type) of virtual machines and Virtual Machine Scale Sets. You can only modify the identity.type for virtual machines or Virtual Machine Scale Sets.
  • Add or replace the values of certain aliases.
    • Use Get-AzPolicyAlias | Select-Object -ExpandProperty 'Aliases' | Where-Object { $_.DefaultMetadata.Attributes -eq 'Modifiable' } in Azure PowerShell 4.6.0 or higher to get a list of aliases that can be used with modify.

Important

If you're managing tags, it's recommended to use Modify instead of Append as Modify provides more operation types and the ability to remediate existing resources. However, Append is recommended if you aren't able to create a managed identity or Modify doesn't yet support the alias for the resource property.

Modify evaluation

Modify evaluates before the request gets processed by a Resource Provider during the creation or updating of a resource. The modify operations are applied to the request content when the if condition of the policy rule is met. Each modify operation can specify a condition that determines when it's applied. Operations with false condition evaluations are skipped.

When an alias is specified, the more checks are performed to ensure that the modify operation doesn't change the request content in a way that causes the resource provider to reject it:

  • The property the alias maps to is marked as Modifiable in the request's API version.
  • The token type in the modify operation matches the expected token type for the property in the request's API version.

If either of these checks fail, the policy evaluation falls back to the specified conflictEffect.

Important

It's recommended that Modify definitions that include aliases use the audit conflict effect to avoid failing requests using API versions where the mapped property isn't 'Modifiable'. If the same alias behaves differently between API versions, conditional modify operations can be used to determine the modify operation used for each API version.

When a policy definition using the modify effect is run as part of an evaluation cycle, it doesn't make changes to resources that already exist. Instead, it marks any resource that meets the if condition as non-compliant.

Modify properties

The details property of the modify effect has all the subproperties that define the permissions needed for remediation and the operations used to add, update, or remove tag values.

  • roleDefinitionIds (required)
  • conflictEffect (optional)
    • Determines which policy definition "wins" if more than one policy definition modifies the same property or when the modify operation doesn't work on the specified alias.
      • For new or updated resources, the policy definition with deny takes precedence. Policy definitions with audit skip all operations. If more than one policy definition has the effect deny, the request is denied as a conflict. If all policy definitions have audit, then none of the operations of the conflicting policy definitions are processed.
      • For existing resources, if more than one policy definition has the effect deny, the compliance status is Conflict. If one or fewer policy definitions have the effect deny, each assignment returns a compliance status of Non-compliant.
    • Available values: audit, deny, disabled.
    • Default value is deny.
  • operations (required)
    • An array of all tag operations to be completed on matching resources.
    • Properties:
      • operation (required)
        • Defines what action to take on a matching resource. Options are: addOrReplace, Add, Remove. Add behaves similar to the append effect.
      • field (required)
        • The tag to add, replace, or remove. Tag names must adhere to the same naming convention for other fields.
      • value (optional)
        • The value to set the tag to.
        • This property is required if operation is addOrReplace or Add.
      • condition (optional)
        • A string containing an Azure Policy language expression with Policy functions that evaluates to true or false.
        • Doesn't support the following Policy functions: field(), resourceGroup(), subscription().

Modify operations

The operations property array makes it possible to alter several tags in different ways from a single policy definition. Each operation is made up of operation, field, and value properties. The operation determines what the remediation task does to the tags, field determines which tag is altered, and value defines the new setting for that tag. The following example makes the following tag changes:

  • Sets the environment tag to "Test" even if it already exists with a different value.
  • Removes the tag TempResource.
  • Sets the Dept tag to the policy parameter DeptName configured on the policy assignment.
"details": {
  ...
  "operations": [
    {
      "operation": "addOrReplace",
      "field": "tags['environment']",
      "value": "Test"
    },
    {
      "operation": "Remove",
      "field": "tags['TempResource']",
    },
    {
      "operation": "addOrReplace",
      "field": "tags['Dept']",
      "value": "[parameters('DeptName')]"
    }
  ]
}

The operation property has the following options:

Operation Description
addOrReplace Adds the defined property or tag and value to the resource, even if the property or tag already exists with a different value.
add Adds the defined property or tag and value to the resource.
remove Removes the defined property or tag from the resource.

Modify examples

Example 1: Add the environment tag and replace existing environment tags with "Test":

"then": {
  "effect": "modify",
  "details": {
    "roleDefinitionIds": [
      "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c"
    ],
    "operations": [
      {
        "operation": "addOrReplace",
        "field": "tags['environment']",
        "value": "Test"
      }
    ]
  }
}

Example 2: Remove the env tag and add the environment tag or replace existing environment tags with a parameterized value:

"then": {
  "effect": "modify",
  "details": {
    "roleDefinitionIds": [
      "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c"
    ],
    "conflictEffect": "deny",
    "operations": [
      {
        "operation": "Remove",
        "field": "tags['env']"
      },
      {
        "operation": "addOrReplace",
        "field": "tags['environment']",
        "value": "[parameters('tagValue')]"
      }
    ]
  }
}

Example 3: Ensure that a storage account doesn't allow blob public access, the modify operation is applied only when evaluating requests with API version greater or equals to 2019-04-01:

"then": {
  "effect": "modify",
  "details": {
    "roleDefinitionIds": [
      "/providers/microsoft.authorization/roleDefinitions/17d1049b-9a84-46fb-8f53-869881c3d3ab"
    ],
    "conflictEffect": "audit",
    "operations": [
      {
        "condition": "[greaterOrEquals(requestContext().apiVersion, '2019-04-01')]",
        "operation": "addOrReplace",
        "field": "Microsoft.Storage/storageAccounts/allowBlobPublicAccess",
        "value": false
      }
    ]
  }
}

Next steps