updates audit and deny properties

Author: davidsmatlak

articles/governance/policy/concepts/effects.md

@@ -2,10 +2,11 @@
 title: Understand how effects work
 description: Azure Policy definitions have various effects that determine how compliance is managed and reported.
 author: davidsmatlak
-ms.date: 02/22/2023
+ms.date: 06/15/2023
 ms.topic: conceptual
 ms.author: davidsmatlak
 ---
+
 # Understand Azure Policy effects
 
 Each policy definition in Azure Policy has a single effect. That effect determines what happens when
@@ -26,9 +27,9 @@ These effects are currently supported in a policy definition:
 
 ## Interchanging effects
 
-Sometimes multiple effects can be valid for a given policy definition. Parameters are often used to specify allowed effect values so that a single definition can be more versatile. However, it's important to note that not all effects are interchangeable. Resource properties and logic in the policy rule can determine whether a certain effect is considered valid to the policy definition. For example, policy definitions with effect **AuditIfNotExists** require additional details in the policy rule that aren't required for policies with effect **Audit**. The effects also behave differently. **Audit** policies will assess a resource's compliance based on its own properties, while **AuditIfNotExists** policies will assess a resource's compliance based on a child or extension resource's properties.
+Sometimes multiple effects can be valid for a given policy definition. Parameters are often used to specify allowed effect values so that a single definition can be more versatile. However, it's important to note that not all effects are interchangeable. Resource properties and logic in the policy rule can determine whether a certain effect is considered valid to the policy definition. For example, policy definitions with effect **AuditIfNotExists** require other details in the policy rule that aren't required for policies with effect **Audit**. The effects also behave differently. **Audit** policies will assess a resource's compliance based on its own properties, while **AuditIfNotExists** policies will assess a resource's compliance based on a child or extension resource's properties.
 
-Below is some general guidance around interchangeable effects:
+The following list is some general guidance around interchangeable effects:
 - **Audit**, **Deny**, and either **Modify** or **Append** are often interchangeable.
 - **AuditIfNotExists** and **DeployIfNotExists** are often interchangeable.
 - **Manual** isn't interchangeable.
@@ -57,15 +58,15 @@ manages the evaluation and outcome and reports the results back to Azure Policy.
 - **denyAction** is evaluated last.
 
 After the Resource Provider returns a success code on a Resource Manager mode request,
-**AuditIfNotExists** and **DeployIfNotExists** evaluate to determine whether additional compliance
+**AuditIfNotExists** and **DeployIfNotExists** evaluate to determine whether more compliance
 logging or action is required.
 
-Additionally, `PATCH` requests that only modify `tags` related fields restricts policy evaluation to
+`PATCH` requests that only modify `tags` related fields restricts policy evaluation to
 policies containing conditions that inspect `tags` related fields.
 
 ## Append
 
-Append is used to add additional fields to the requested resource during creation or update. A
+Append is used to add more fields to the requested resource during creation or update. A
 common example is specifying allowed IPs for a storage resource.
 
 > [!IMPORTANT]
@@ -78,7 +79,7 @@ Append evaluates before the request gets processed by a Resource Provider during
 updating of a resource. Append adds fields to the resource when the **if** condition of the policy
 rule is met. If the append effect would override a value in the original request with a different
 value, then it acts as a deny effect and rejects the request. To append a new value to an existing
-array, use the **\[\*\]** version of the alias.
+array, use the `[*]` version of the alias.
 
 When a policy definition using the append 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**
@@ -92,9 +93,9 @@ take either a single **field/value** pair or multiples. Refer to
 
 ### Append examples
 
-Example 1: Single **field/value** pair using a non-**\[\*\]**
+Example 1: Single **field/value** pair using a non-`[*]`
 [alias](definition-structure.md#aliases) with an array **value** to set IP rules on a storage
-account. When the non-**\[\*\]** alias is an array, the effect appends the **value** as the entire
+account. When the non-`[*]` alias is an array, the effect appends the **value** as the entire
 array. If the array already exists, a deny event occurs from the conflict.
 
 ```json
@@ -110,8 +111,8 @@ array. If the array already exists, a deny event occurs from the conflict.
 }
 ```
 
-Example 2: Single **field/value** pair using an **\[\*\]** [alias](definition-structure.md#aliases)
-with an array **value** to set IP rules on a storage account. By using the **\[\*\]** alias, the
+Example 2: Single **field/value** pair using an `[*]` [alias](definition-structure.md#aliases)
+with an array **value** to set IP rules on a storage account. When you use the `[*]` alias, the
 effect appends the **value** to a potentially pre-existing array. If the array doesn't exist yet,
 it's created.
 
@@ -144,11 +145,11 @@ resource is updated.
 
 ### Audit properties
 
-For a Resource Manager mode, the audit effect doesn't have any additional properties for use in the
+For a Resource Manager mode, the audit effect doesn't have any other properties for use in the
 **then** condition of the policy definition.
 
 For a Resource Provider mode of `Microsoft.Kubernetes.Data`, the audit effect has the following
-additional subproperties of **details**. Use of `templateInfo` is required for new or updated policy
+subproperties of **details**. Use of `templateInfo` is required for new or updated policy
 definitions as `constraintTemplate` is deprecated.
 
 - **templateInfo** (required)
@@ -173,6 +174,21 @@ definitions as `constraintTemplate` is deprecated.
   - The CRD implementation of the Constraint template. Uses parameters passed via **values** as
     `{{ .Values.<valuename> }}`. In example 2 below, these values are
     `{{ .Values.excludedNamespaces }}` and `{{ .Values.allowedContainerImagesRegex }}`.
+- **constraintTemplate** (deprecated)
+  - Can't be used with `templateInfo`.
+  - Must be replaced with `templateInfo` when creating or updating a policy definition.
+  - The Constraint template CustomResourceDefinition (CRD) that defines new Constraints. The
+    template defines the Rego logic, the Constraint schema, and the Constraint parameters that are
+    passed via **values** from Azure Policy. For more information, go to [Gatekeeper constraints](https://open-policy-agent.github.io/gatekeeper/website/docs/howto/#constraints).
+- **constraintInfo** (optional)
+  - Can't be used with `constraint`, `constraintTemplate`, `apiGroups`, or `kinds`.
+  - If `constraintInfo` isn't provided, the constraint can be generated from `templateInfo` and policy.
+  - **sourceType** (required)
+    - Defines the type of source for the constraint. Allowed values: _PublicURL_ or _Base64Encoded_.
+    - If _PublicURL_, paired with property `url` to provide location of the constraint. The location must be publicly accessible.
+
+      > [!WARNING]
+      > Don't use SAS URIs or tokens in `url` or anything else that could expose a secret.
 - **namespaces** (optional)
   - An _array_ of
     [Kubernetes namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)
@@ -203,12 +219,6 @@ definitions as `constraintTemplate` is deprecated.
 - **values** (optional)
   - Defines any parameters and values to pass to the Constraint. Each value must exist in the
     Constraint template CRD.
-- **constraintTemplate** (deprecated)
-  - Can't be used with `templateInfo`.
-  - Must be replaced with `templateInfo` when creating or updating a policy definition.
-  - The Constraint template CustomResourceDefinition (CRD) that defines new Constraints. The
-    template defines the Rego logic, the Constraint schema, and the Constraint parameters that are
-    passed via **values** from Azure Policy.
 
 ### Audit example
 
@@ -355,11 +365,11 @@ non-compliant.
 
 ### Deny properties
 
-For a Resource Manager mode, the deny effect doesn't have any additional properties for use in the
+For a Resource Manager mode, the deny effect doesn't have any more properties for use in the
 **then** condition of the policy definition.
 
 For a Resource Provider mode of `Microsoft.Kubernetes.Data`, the deny effect has the following
-additional subproperties of **details**. Use of `templateInfo` is required for new or updated policy
+subproperties of **details**. Use of `templateInfo` is required for new or updated policy
 definitions as `constraintTemplate` is deprecated.
 
 - **templateInfo** (required)
@@ -384,6 +394,21 @@ definitions as `constraintTemplate` is deprecated.
   - The CRD implementation of the Constraint template. Uses parameters passed via **values** as
     `{{ .Values.<valuename> }}`. In example 2 below, these values are
     `{{ .Values.excludedNamespaces }}` and `{{ .Values.allowedContainerImagesRegex }}`.
+- **constraintTemplate** (deprecated)
+  - Can't be used with `templateInfo`.
+  - Must be replaced with `templateInfo` when creating or updating a policy definition.
+  - The Constraint template CustomResourceDefinition (CRD) that defines new Constraints. The
+    template defines the Rego logic, the Constraint schema, and the Constraint parameters that are
+    passed via **values** from Azure Policy. For more information, go to [Gatekeeper constraints](https://open-policy-agent.github.io/gatekeeper/website/docs/howto/#constraints).
+- **constraintInfo** (optional)
+  - Can't be used with `constraint`, `constraintTemplate`, `apiGroups`, or `kinds`.
+  - If `constraintInfo` isn't provided, the constraint can be generated from `templateInfo` and policy.
+  - **sourceType** (required)
+    - Defines the type of source for the constraint. Allowed values: _PublicURL_ or _Base64Encoded_.
+    - If _PublicURL_, paired with property `url` to provide location of the constraint. The location must be publicly accessible.
+
+      > [!WARNING]
+      > Don't use SAS URIs or tokens in `url` or anything else that could expose a secret.
 - **namespaces** (optional)
   - An _array_ of
     [Kubernetes namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)
@@ -414,13 +439,6 @@ definitions as `constraintTemplate` is deprecated.
 - **values** (optional)
   - Defines any parameters and values to pass to the Constraint. Each value must exist in the
     Constraint template CRD.
-- **constraintTemplate** (deprecated)
-  - Can't be used with `templateInfo`.
-  - Must be replaced with `templateInfo` when creating or updating a policy definition.
-  - The Constraint template CustomResourceDefinition (CRD) that defines new Constraints. The
-    template defines the Rego logic, the Constraint schema, and the Constraint parameters that are
-    passed via **values** from Azure Policy. It's recommended to use the newer `templateInfo` to
-    replace `constraintTemplate`.
 
 ### Deny example
 
@@ -452,9 +470,10 @@ location of the Constraint template to use in Kubernetes to limit the allowed co
     }
 }
 ```
+
 ## DenyAction (preview)
 
-`DenyAction` is used to block requests on intended action to resources. The only supported action today is `DELETE`. This effect will help prevent any accidental deletion of critical resources.
+`DenyAction` is used to block requests on intended action to resources. The only supported action today is `DELETE`. This effect helps prevent any accidental deletion of critical resources.
 
 ### DenyAction evaluation
 
@@ -467,12 +486,15 @@ assignment.
 > Under preview, assignments with `denyAction` effect will show a `Not Started` compliance state.
 
 #### Subscription deletion
+
 Policy won't block removal of resources that happens during a subscription deletion.
 
 #### Resource group deletion
+
 Policy will evaluate resources that support location and tags against `DenyAction` policies during a resource group deletion. Only policies that have the `cascadeBehaviors` set to `deny` in the policy rule will block a resource group deletion. Policy won't block removal of resources that don't support location and tags nor any policy with `mode:all`.
 
 #### Cascade deletion
+
 Cascade deletion occurs when deleting of a parent resource is implicitly deletes all its child resources. Policy won't block removal of child resources when a delete action targets the parent resources. For example, `Microsoft.Insights/diagnosticSettings` is a child resource of `Microsoft.Storage/storageaccounts`. If a `denyAction` policy targets `Microsoft.Insights/diagnosticSettings`, a delete call to the diagnostic setting (child) will fail, but a delete to the storage account (parent) will implicitly delete the diagnostic setting (child).
 
 [!INCLUDE [policy-denyAction](../../../../includes/azure-policy-deny-action.md)]
@@ -491,7 +513,8 @@ The **details** property of the DenyAction effect has all the subproperties that
   - Default value is `deny`.
 
 ### DenyAction example
-Example: Deny any delete calls targeting database accounts that have a tag environment that equals prod. Since cascade behavior is set to deny, block any DELETE call that targets a resource group with an applicable database account.
+
+Example: Deny any delete calls targeting database accounts that have a tag environment that equals prod. Since cascade behavior is set to deny, block any `DELETE` call that targets a resource group with an applicable database account.
 
 ```json
 {
@@ -619,7 +642,7 @@ related resources to match and the template deployment to execute.
 
 ### DeployIfNotExists example
 
-Example: Evaluates SQL Server databases to determine whether transparentDataEncryption is enabled.
+Example: Evaluates SQL Server databases to determine whether `transparentDataEncryption` is enabled.
 If not, then a deployment to enable is executed.
 
 ```json
@@ -766,7 +789,7 @@ The following operations are supported by Modify:
 
 > [!IMPORTANT]
 > 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
+> 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.
 
@@ -848,7 +871,7 @@ properties. Operation determines what the remediation task does to the tags, fie
 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.
+- 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.
 
@@ -931,7 +954,7 @@ 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':
+is applied only when evaluating requests with API version greater or equals to `2019-04-01`:
 
 ```json
 "then": {
@@ -960,29 +983,29 @@ different scopes. Each of these assignments is also likely to have a different e
 condition and effect for each policy is independently evaluated. For example:
 
 - Policy 1
-  - Restricts resource location to 'westus'
+  - Restricts resource location to `westus`
   - Assigned to subscription A
   - Deny effect
 - Policy 2
-  - Restricts resource location to 'eastus'
+  - Restricts resource location to `eastus`
   - Assigned to resource group B in subscription A
   - Audit effect
 
 This setup would result in the following outcome:
 
-- Any resource already in resource group B in 'eastus' is compliant to policy 2 and non-compliant to
+- Any resource already in resource group B in `eastus` is compliant to policy 2 and non-compliant to
   policy 1
-- Any resource already in resource group B not in 'eastus' is non-compliant to policy 2 and
-  non-compliant to policy 1 if not in 'westus'
-- Any new resource in subscription A not in 'westus' is denied by policy 1
-- Any new resource in subscription A and resource group B in 'westus' is created and non-compliant
+- Any resource already in resource group B not in `eastus` is non-compliant to policy 2 and
+  non-compliant to policy 1 if not in `westus`
+- Any new resource in subscription A not in `westus` is denied by policy 1
+- Any new resource in subscription A and resource group B in `westus` is created and non-compliant
   on policy 2
 
 If both policy 1 and policy 2 had effect of deny, the situation changes to:
 
-- Any resource already in resource group B not in 'eastus' is non-compliant to policy 2
-- Any resource already in resource group B not in 'westus' is non-compliant to policy 1
-- Any new resource in subscription A not in 'westus' is denied by policy 1
+- Any resource already in resource group B not in `eastus` is non-compliant to policy 2
+- Any resource already in resource group B not in `westus` is non-compliant to policy 1
+- Any new resource in subscription A not in `westus` is denied by policy 1
 - Any new resource in resource group B of subscription A is denied
 
 Each assignment is individually evaluated. As such, there isn't an opportunity for a resource to