Merge pull request #189134 from pilor/policyBestPractices

Clarify policy best practices

Author: PRMerger15

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

@@ -133,8 +133,10 @@ after creation of the initial assignment.
 ## Policy definition ID
 
 This field must be the full path name of either a policy definition or an initiative definition.
-`policyDefinitionId` is a string and not an array. It's recommended that if multiple policies are
-often assigned together, to use an [initiative](./initiative-definition-structure.md) instead.
+`policyDefinitionId` is a string and not an array. The latest content of the assigned policy
+definition or initiative will be retrieved each time the policy assignment is evaluated. It's
+recommended that if multiple policies are often assigned together, to use an
+[initiative](./initiative-definition-structure.md) instead.
 
 ## Non-compliance messages
 
@@ -222,3 +224,4 @@ For policy assignments with effect set to **deployIfNotExisit** or **modify**, i
 - 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).
+  

articles/governance/policy/concepts/policy-as-code.md

@@ -120,6 +120,12 @@ Like policy definitions, when adding or updating an existing initiative, the wor
 automatically update the initiative definition in Azure. Testing of the new or updated initiative
 definition comes in a later step.
 
+> [!NOTE]
+> It's recommended to use a centralized deployment mechanism like GitHub workflows or Azure
+> Pipelines to deploy policies. This helps to ensure only reviewed policy resources are deployed
+> to your environment and that a central deployment mechanism is used. _Write_ permissions
+> to policy resources can be restricted to the identity used in the deployment.
+
 ### Test and validate the updated definition
 
 Once automation has taken your newly created or updated policy or initiative definitions and made
@@ -213,3 +219,4 @@ GitHub, see
 - 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).
+  

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

@@ -63,6 +63,12 @@ following code:
 az role definition list --name 'Contributor'
 ```
 
+> [!IMPORTANT]
+> Permissions should be restricted to the smallest possible set when defining **roleDefinitionIds**
+> within a policy definition or assigning permissions to a managed identity manually. See
+> [managed identity best practice recommendations](../../../active-directory/managed-identities-azure-resources/managed-identity-best-practice-recommendations.md)
+> for more best practices.
+
 ## Manually configure the managed identity
 
 When creating an assignment using the portal, Azure Policy can both generate a managed identity and
@@ -228,7 +234,7 @@ To create a **remediation task**, follow these steps:
 
 1. On the **New remediation task** page, optional remediation settings are shown: 
 
-    - **Failure Threshold percentage** - Used to specify whether the remediation task should fail if the percentage of failures exceeds the given threshold. Provided as a number between 0 to 100. By default, the failure threshold is 100%. 
+    - **Failure Threshold percentage** - Used to specify whether the remediation task should fail if the percentage of failures exceeds the given threshold. Provided as a number between 0 to 100. By default, the failure threshold is 100%. 
     - **Resource Count** - Determines how many non-compliant resources to remediate in a given remediation task. The default value is 500 (the previous limit). The maximum number of is 50,000 resources.
     - **Parallel Deployments** - Determines how many resources to remediate at the same time. The allowed values are 1 to 30 resources at a time. The default value is 10.
 

articles/governance/policy/overview.md

@@ -116,13 +116,17 @@ Azure Policy has several permissions, known as operations, in two Resource Provi
 Many Built-in roles grant permission to Azure Policy resources. The **Resource Policy Contributor**
 role includes most Azure Policy operations. **Owner** has full rights. Both **Contributor** and
 **Reader** have access to all _read_ Azure Policy operations. **Contributor** may trigger resource
-remediation, but can't _create_ definitions or assignments. **User Access Administrator** is
+remediation, but can't _create_ or _update_ definitions and assignments. **User Access Administrator** is
 necessary to grant the managed identity on **deployIfNotExists** or **modify** assignments necessary
 permissions. All policy objects will be readable to all roles over the scope.
 
 If none of the Built-in roles have the permissions required, create a
 [custom role](../../role-based-access-control/custom-roles.md).
 
+Azure Policy operations can have a significant impact on your Azure environment. Only the minimum set of 
+permissions necessary to perform a task should be assigned and these permissions should not be granted
+to users who do not need them.
+
 > [!NOTE]
 > The managed identity of a **deployIfNotExists** or **modify** policy assignment needs enough
 > permissions to create or update targetted resources. For more information, see
@@ -157,12 +161,16 @@ Here are a few pointers and tips to keep in mind:
   _initiativeDefC_. If you create another policy definition later for _policyDefB_ with goals
   similar to _policyDefA_, you can add it under _initiativeDefC_ and track them together.
 
-- Once you've created an initiative assignment, policy definitions added to the initiative also
+    - Once you've created an initiative assignment, policy definitions added to the initiative also
   become part of that initiative's assignments.
-
-- When an initiative assignment is evaluated, all policies within the initiative are also evaluated.
+  
+  - When an initiative assignment is evaluated, all policies within the initiative are also evaluated.
   If you need to evaluate a policy individually, it's better to not include it in an initiative.
 
+- Manage Azure Policy resources as code with manual reviews on changes to policy definitions,
+  initiatives, and assignments. To learn more about suggested patterns and tooling, see
+  [Design Azure Policy as Code Workflows](./concepts/policy-as-code.md).
+
 ## Azure Policy objects
 
 ### Policy definition
@@ -264,7 +272,7 @@ To learn more about the structures of initiative definitions, review
 
 ### Assignments
 
-An assignment is a policy definition or initiative that has been assigned to take place within a
+An assignment is a policy definition or initiative that has been assigned to a
 specific scope. This scope could range from a [management group](../management-groups/overview.md)
 to an individual resource. The term _scope_ refers to all the resources, resource groups,
 subscriptions, or management groups that the definition is assigned to. Assignments are inherited by
@@ -284,6 +292,10 @@ subscription from the management group-level assignment. Then, assign the more p
 on the child management group or subscription level. If any assignment results in a resource getting
 denied, then the only way to allow the resource is to modify the denying assignment.
 
+Policy assignments always use the latest state of their assigned definition or initiative when
+evaluating resources. If a policy definition that is already assigned is changed all existing
+assignments of that definition will use the updated logic when evaluating.
+
 For more information on setting assignments through the portal, see [Create a policy assignment to
 identify non-compliant resources in your Azure environment](./assign-policy-portal.md). Steps for
 [PowerShell](./assign-policy-powershell.md) and [Azure CLI](./assign-policy-azurecli.md) are also