Merge pull request #96759 from DCtheGeek/dmc-policy-newarrays

Add count expression language details

Author: American-Dipper

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: 11/04/2019
+ms.date: 11/26/2019
 ms.topic: conceptual
 ---
 # Azure Policy definition structure
@@ -63,8 +63,8 @@ All Azure Policy samples are at [Azure Policy samples](../samples/index.md).
 
 ## Mode
 
-**Mode** is configured depending on if the policy is targeting an Azure Resource Manager property or a
-Resource Provider property.
+**Mode** is configured depending on if the policy is targeting an Azure Resource Manager property or
+a Resource Provider property.
 
 ### Resource Manager modes
 
@@ -85,7 +85,8 @@ it prevents resources that don't support tags and locations from showing up as n
 compliance results. The exception is **resource groups**. Policies that enforce location or tags on
 a resource group should set **mode** to `all` and specifically target the
 `Microsoft.Resources/subscriptions/resourceGroups` type. For an example, see [Enforce resource group
-tags](../samples/enforce-tag-rg.md). For a list of resources that support tags, see [Tag support for Azure resources](../../../azure-resource-manager/tag-support.md).
+tags](../samples/enforce-tag-rg.md). For a list of resources that support tags, see
+[Tag support for Azure resources](../../../azure-resource-manager/tag-support.md).
 
 ### <a name="resource-provider-modes" />Resource Provider modes (preview)
 
@@ -123,7 +124,8 @@ A parameter has the following properties that are used in the 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](#using-a-parameter-value).
-- `type`: Determines if the parameter is a **string**, **array**, **object**, **boolean**, **integer**, **float**, or **datetime**.
+- `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
@@ -467,6 +469,160 @@ starting with abc" is returned instead and compared to **abc**. A resource with
 doesn't begin with **abc** still fails the policy rule, but no longer causes an error during
 evaluation.
 
+### Count
+
+Conditions that count how many members of an array in the resource payload satisfy a condition
+expression can be formed using **count** expression. Common scenarios are checking whether 'at least
+one of', 'exactly one of', 'all of', or 'none of' the array members satisfy the condition. **count**
+evaluates each array member for a condition expression and sums the _true_ results, which is then
+compared to the expression operator.
+
+The structure of the **count** expression is:
+
+```json
+{
+    "count": {
+        "field": "<[*] alias>",
+        "where": {
+            /* condition expression */
+        }
+    },
+    "<condition>": "<compare the count of true condition expression array members to this value>"
+}
+```
+
+The following properties are used with **count**:
+
+- **count.field** (required): Contains the path to the array and must be an array alias. If the
+  array is missing, the expression is evaluated to _false_ without considering the condition
+  expression.
+- **count.where** (optional): The condition expression to individually evaluate each [\[\*\]
+  alias](#understanding-the--alias) array member of **count.field**. If this property is not
+  provided, all array members with the path of 'field' are evaluated to _true_. Any
+  [condition](../concepts/definition-structure.md#conditions) can be used inside this property.
+  [Logical operators](#logical-operators) can be used inside this property to create complex
+  evaluation requirements.
+- **\<condition\>** (required): The value is compared to the number of items that met the
+  **count.where** condition expression. A numeric
+  [condition](../concepts/definition-structure.md#conditions) should be used.
+
+#### Count examples
+
+Example 1: Check if an array is empty
+
+```json
+{
+    "count": {
+        "field": "Microsoft.Network/networkSecurityGroups/securityRules[*]"
+    },
+    "equals": 0
+}
+```
+
+Example 2: Check for only one array member to meet the condition expression
+
+```json
+{
+    "count": {
+        "field": "Microsoft.Network/networkSecurityGroups/securityRules[*]",
+        "where": {
+            "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].description",
+            "equals": "My unique description"
+        }
+    },
+    "equals": 1
+}
+```
+
+Example 3: Check for at least one array member to meet the condition expression
+
+```json
+{
+    "count": {
+        "field": "Microsoft.Network/networkSecurityGroups/securityRules[*]",
+        "where": {
+            "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].description",
+            "equals": "My common description"
+        }
+    },
+    "greaterOrEquals": 1
+}
+```
+
+Example 4: Check that all object array members meet the condition expression
+
+```json
+{
+    "count": {
+        "field": "Microsoft.Network/networkSecurityGroups/securityRules[*]",
+        "where": {
+            "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].description",
+            "equals": "description"
+        }
+    },
+    "equals": "[length(field(Microsoft.Network/networkSecurityGroups/securityRules[*]))]"
+}
+```
+
+Example 5: Check that all string array members meet the condition expression
+
+```json
+{
+    "count": {
+        "field": "Microsoft.Sql/servers/securityAlertPolicies/emailAddresses[*]",
+        "where": {
+            "field": "Microsoft.Sql/servers/securityAlertPolicies/emailAddresses[*]",
+            "like": "*@contoso.com"
+        }
+    },
+    "equals": "[length(field('Microsoft.Sql/servers/securityAlertPolicies/emailAddresses[*]'))]"
+}
+```
+
+Example 6: Use **field** inside **value** to check that all array members meet the condition
+expression
+
+```json
+{
+    "count": {
+        "field": "Microsoft.Sql/servers/securityAlertPolicies/emailAddresses[*]",
+        "where": {
+            "value": "[last(split(first(field('Microsoft.Sql/servers/securityAlertPolicies/emailAddresses[*]')), '@'))]",
+            "equals": "contoso.com"
+        }
+    },
+    "equals": "[length(field('Microsoft.Sql/servers/securityAlertPolicies/emailAddresses[*]'))]"
+}
+```
+
+Example 7: Check that at least one array member matches multiple properties in the condition
+expression
+
+```json
+{
+    "count": {
+        "field": "Microsoft.Network/networkSecurityGroups/securityRules[*]",
+        "where": {
+            "allOf": [
+                {
+                    "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].direction",
+                    "equals": "Inbound"
+                },
+                {
+                    "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].access",
+                    "equals": "Allow"
+                },
+                {
+                    "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].destinationPortRange",
+                    "equals": "3389"
+                }
+            ]
+        }
+    },
+    "greater": 0
+}
+```
+
 ### Effect
 
 Azure Policy supports the following types of effect:
@@ -581,21 +737,22 @@ Policy, use one of the following methods:
 
 ### Understanding the [*] alias
 
-Several of the aliases that are available have a version that appears as a 'normal' name and
-another that has **[\*]** attached to it. For example:
+Several of the aliases that are available have a version that appears as a 'normal' name and another
+that has **\[\*\]** attached to it. For example:
 
 - `Microsoft.Storage/storageAccounts/networkAcls.ipRules`
 - `Microsoft.Storage/storageAccounts/networkAcls.ipRules[*]`
 
 The 'normal' alias represents the field as a single value. This field is for exact match comparison
 scenarios when the entire set of values must be exactly as defined, no more and no less.
 
-The **[\*]** alias makes it possible to compare against the value of each element in the array and
+The **\[\*\]** alias makes it possible to compare against the value of each element in the array and
 specific properties of each element. This approach makes it possible to compare element properties
-for 'if none of', 'if any of', or 'if all of' scenarios. Using **ipRules[\*]**, an example would be
-validating that every _action_ is _Deny_, but not worrying about how many rules exist or what the
-IP _value_ is. This sample rule checks for any matches of **ipRules[\*].value** to **10.0.4.1** and
-applies the **effectType** only if it doesn't find at least one match:
+for 'if none of', 'if any of', or 'if all of' scenarios. For more complex scenarios, use the
+[count](#count) condition expression. Using **ipRules\[\*\]**, an example would be validating that
+every _action_ is _Deny_, but not worrying about how many rules exist or what the IP _value_ is.
+This sample rule checks for any matches of **ipRules\[\*\].value** to **10.0.4.1** and applies the
+**effectType** only if it doesn't find at least one match:
 
 ```json
 "policyRule": {
@@ -617,14 +774,17 @@ applies the **effectType** only if it doesn't find at least one match:
 }
 ```
 
-For more information, see [evaluating the [\*] alias](../how-to/author-policies-for-arrays.md#evaluating-the--alias).
+
+
+For more information, see [evaluating the [\*]
+alias](../how-to/author-policies-for-arrays.md#evaluating-the--alias).
 
 ## Initiatives
 
 Initiatives enable you to group several related policy definitions to simplify assignments and
 management because you work with a group as a single item. For example, you can group related
-tagging policy definitions into a single initiative. Rather than assigning each policy
-individually, you apply the initiative.
+tagging policy definitions into a single initiative. Rather than assigning each policy individually,
+you apply the initiative.
 
 The following example illustrates how to create an initiative for handling two tags: `costCenter`
 and `productName`. It uses two built-in policies to apply the default tag value.
@@ -708,4 +868,4 @@ and `productName`. It uses two built-in policies to apply the default tag value.
 - 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/author-policies-for-arrays.md

@@ -1,7 +1,7 @@
 ---
 title: Author policies for array properties on resources
 description: Learn to work with array parameters and array language expressions, evaluate the [*] alias, and to append elements with Azure Policy definition rules.
-ms.date: 03/06/2019
+ms.date: 11/26/2019
 ms.topic: conceptual
 ---
 # Author policies for array properties on Azure resources
@@ -15,8 +15,9 @@ used in several different ways:
 - Part of a [policy rule](../concepts/definition-structure.md#policy-rule) using the conditions
   **in** or **notIn**
 - Part of a policy rule that evaluates the [\[\*\]
-  alias](../concepts/definition-structure.md#understanding-the--alias) to evaluate specific
-  scenarios such as **None**, **Any**, or **All**
+  alias](../concepts/definition-structure.md#understanding-the--alias) to evaluate:
+  - Scenarios such as **None**, **Any**, or **All**
+  - Complex scenarios with **count**
 - In the [append effect](../concepts/effects.md#append) to replace or add to an existing array
 
 This article covers each use by Azure Policy and provides several example definitions.
@@ -160,12 +161,13 @@ expression. To resolve this error message, change `equals` to either `in` or `no
 
 ### Evaluating the [*] alias
 
-Aliases that have **[\*]** attached to their name indicate the **type** is an _array_. Instead of
-evaluating the value of the entire array, **[\*]** makes it possible to evaluate each element of the
-array. There are three scenarios this per item evaluation is useful in: None, Any, and All.
+Aliases that have **\[\*\]** attached to their name indicate the **type** is an _array_. Instead of
+evaluating the value of the entire array, **\[\*\]** makes it possible to evaluate each element of
+the array. There are three standard scenarios this per item evaluation is useful in: None, Any, and
+All. For complex scenarios, use [count](../concepts/definition-structure.md#count).
 
 The policy engine triggers the **effect** in **then** only when the **if** rule evaluates as true.
-This fact is important to understand in context of the way **[\*]** evaluates each individual
+This fact is important to understand in context of the way **\[\*\]** evaluates each individual
 element of the array.
 
 The example policy rule for the scenario table below:
@@ -221,11 +223,11 @@ rule and array of existing values above:
 ## The append effect and arrays
 
 The [append effect](../concepts/effects.md#append) behaves differently depending on if the
-**details.field** is a **[\*]** alias or not.
+**details.field** is a **\[\*\]** alias or not.
 
-- When not a **[\*]** alias, append replaces the entire array with the **value** property
-- When a **[\*]** alias, append adds the **value** property to the existing array or creates the new
-  array
+- When not a **\[\*\]** alias, append replaces the entire array with the **value** property
+- When a **\[\*\]** alias, append adds the **value** property to the existing array or creates the
+  new array
 
 For more information, see the [append examples](../concepts/effects.md#append-examples).