Update modify effect

Author: DCtheGeek

articles/governance/policy/concepts/definition-structure.md

@@ -1,7 +1,7 @@
 ---
 title: Details of the policy definition structure
 description: Describes how policy definitions are used to establish conventions for Azure resources in your organization.
-ms.date: 08/17/2020
+ms.date: 08/27/2020
 ms.topic: conceptual
 ---
 # Azure Policy definition structure
@@ -805,6 +805,14 @@ Policy, use one of the following methods:
   (Get-AzPolicyAlias -NamespaceMatch 'compute').Aliases
   ```
 
+  > [!NOTE]
+  > To find aliases that can be used with the [modify](./effects.md#modify) effect, use the
+  > following command:
+  >
+  > ```azurepowershell-interactive
+  > Get-AzPolicyAlias | Select-Object -ExpandProperty 'Aliases' | Where-Object { $_.DefaultMetadata.Attributes -eq 'Modifiable' }
+  > ```
+
 - Azure CLI
 
   ```azurecli-interactive

articles/governance/policy/concepts/effects.md

@@ -1,7 +1,7 @@
 ---
 title: Understand how effects work
 description: Azure Policy definitions have various effects that determine how compliance is managed and reported.
-ms.date: 08/17/2020
+ms.date: 08/27/2020
 ms.topic: conceptual
 ---
 # Understand Azure Policy effects
@@ -605,23 +605,51 @@ Example: Gatekeeper v2 admission control rule to allow only the specified contai
 
 ## Modify
 
-Modify is used to add, update, or remove tags on a resource during creation or update. A common
-example is updating tags on resources such as costCenter. A Modify policy should always have `mode`
-set to _Indexed_ unless the target resource is a resource group. Existing non-compliant resources
+Modify is used to add, update, or remove properties or tags on a 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](../how-to/remediate-resources.md). A single Modify rule
 can have any number of operations.
 
+The following operations are supported by Modify:
+
+- 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.
+- Add or replace the values of certain aliases (preview).
+  - Use
+    `Get-AzPolicyAlias | Select-Object -ExpandProperty 'Aliases' | Where-Object { $_.DefaultMetadata.Attributes -eq 'Modifiable' }`
+    in Azure PowerShell to get a list of aliases that can be used with Modify.
+
 > [!IMPORTANT]
-> Modify is currently only for use with tags. If you are managing tags, it's recommended to use
-> Modify instead of Append as Modify provides additional operation types and the ability to
-> remediate existing resources. However, Append is recommended if you aren't able to create a
-> managed identity.
+> If you're managing tags, it's recommended to use Modify instead of Append as Modify provides
+> additional 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. Modify adds or updates tags on a resource when the **if** condition of the
-policy rule is met.
+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 conditions that are evaluated to _false_ are skipped.
+
+When an alias is specified, the following additional 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 recommeneded 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**
@@ -636,11 +664,11 @@ needed for remediation and the **operations** used to add, update, or remove tag
   - This property must include an array of strings that match role-based access control role ID
     accessible by the subscription. For more information, see
     [remediation - configure policy definition](../how-to/remediate-resources.md#configure-policy-definition).
-  - The role defined must include all operations granted to the [Contributor](../../../role-based-access-control/built-in-roles.md#contributor)
-    role.
+  - The role defined must include all operations granted to the
+    [Contributor](../../../role-based-access-control/built-in-roles.md#contributor) role.
 - **conflictEffect** (optional)
   - Determines which policy definition "wins" in the event that more than one policy definition
-    modifies the same property.
+    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
       _deny_, the request is denied as a conflict. If all policy definitions have _audit_, then none
@@ -662,6 +690,12 @@ needed for remediation and the **operations** used to add, update, or remove tag
     - **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](./definition-structure.md#policy-functions) that evaluates to _true_ or
+        _false_.
+      - Doesn't support the following Policy functions: `field()`, `resourceGroup()`,
+        `subscription()`.
 
 ### Modify operations
 
@@ -701,9 +735,9 @@ The **operation** property has the following options:
 
 |Operation |Description |
 |-|-|
-|addOrReplace |Adds the defined tag and value to the resource, even if the tag already exists with a different value. |
-|Add |Adds the defined tag and value to the resource. |
-|Remove |Removes the defined tag from the resource. |
+|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
 
@@ -753,6 +787,29 @@ with a parameterized value:
 }
 ```
 
+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':
+
+```json
+"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
+            }
+        ]
+    }
+}
+```
+
 ## Layering policy definitions
 
 A resource may be impacted by several assignments. These assignments may be at the same scope or at
@@ -799,4 +856,4 @@ to validate the right policy assignments are affecting the right scopes.
 - Understand how to [programmatically create policies](../how-to/programmatically-create.md).
 - Learn how to [get compliance data](../how-to/get-compliance-data.md).
 - Learn how to [remediate non-compliant resources](../how-to/remediate-resources.md).
-- Review what a management group is with [Organize your resources with Azure management groups](../../management-groups/overview.md).
+- Review what a management group is with [Organize your resources with Azure management groups](../../management-groups/overview.md).

articles/governance/policy/how-to/remediate-resources.md

@@ -1,14 +1,14 @@
 ---
 title: Remediate non-compliant resources
 description: This guide walks you through the remediation of resources that are non-compliant to policies in Azure Policy.
-ms.date: 06/09/2020
+ms.date: 08/27/2020
 ms.topic: how-to
 ---
 # Remediate non-compliant resources with Azure Policy
 
 Resources that are non-compliant to a **deployIfNotExists** or **modify** policy can be put into a
 compliant state through **Remediation**. Remediation is accomplished by instructing Azure Policy to
-run the **deployIfNotExists** effect or the tag **operations** of the assigned policy on your
+run the **deployIfNotExists** effect or the **modify operations** of the assigned policy on your
 existing resources, whether that assignment is to a management group, a subscription, a resource
 group, or an individual resource. This article shows the steps needed to understand and accomplish
 remediation with Azure Policy.