Merge pull request #205217 from timwarner-msft/timwarner-policyMG

liljack17 · web-flow · commit 3e5789a7e31e · 2022-07-19T11:02:39.000-07:00
Add support for management groups
diff --git a/articles/event-grid/event-schema-policy.md b/articles/event-grid/event-schema-policy.md
@@ -1,10 +1,10 @@
 ---
 title: Azure Policy as an Event Grid source
 description: This article describes how to use Azure Policy as an Event Grid event source. It provides the schema and links to tutorial and how-to articles.
-ms.topic: conceptual
 author: timwarner-msft
+ms.topic: conceptual
 ms.author: timwarner
-ms.date: 07/12/2022
+ms.date: 07/19/2022
 ---
 
 # Azure Policy as an Event Grid source
diff --git a/articles/governance/policy/tutorials/route-state-change-events.md b/articles/governance/policy/tutorials/route-state-change-events.md
@@ -1,11 +1,11 @@
 ---
 title: "Tutorial: Route policy state change events to Event Grid with Azure CLI"
 description: In this tutorial, you configure Event Grid to listen for policy state change events and call a webhook.
-ms.date: 06/29/2022
+author: timwarner-msft
+ms.date: 07/19/2022
 ms.topic: tutorial
 ms.custom: devx-track-azurecli
 ms.author: timwarner
-author: timwarner-msft
 ---
 # Tutorial: Route policy state change events to Event Grid with Azure CLI
 
@@ -27,19 +27,6 @@ send the events to a web app that collects and displays the messages.
   `az --version`. If you need to install or upgrade, see
   [Install Azure CLI](/cli/azure/install-azure-cli).
 
-- Even if you've previously used Azure Policy or Event Grid, re-register their respective resource
-  providers:
-
-  ```azurecli-interactive
-  # Log in first with az login if you're not using Cloud Shell
-
-  # Provider register: Register the Azure Policy provider
-  az provider register --namespace Microsoft.PolicyInsights
-
-  # Provider register: Register the Azure Event Grid provider
-  az provider register --namespace Microsoft.EventGrid
-  ```
-
 [!INCLUDE [cloud-shell-try-it.md](../../../../includes/cloud-shell-try-it.md)]
 
 ## Create a resource group
@@ -63,14 +50,27 @@ az group create --name <resource_group_name> --location westus
 Now that we have a resource group, we create a
 [system topic](../../../event-grid/system-topics.md). A system topic in Event Grid represents one or
 more events published by Azure services such as Azure Policy and Azure Event Hubs. This system topic
-uses the `Microsoft.PolicyInsights.PolicyStates` topic type for Azure Policy state changes. Replace
-`<SubscriptionID>` in the **scope** parameter with the ID of your subscription and
-`<resource_group_name>` in **resource-group** parameter with the previously created resource group.
+uses the `Microsoft.PolicyInsights.PolicyStates` topic type for Azure Policy state changes.
+
+First, you'll need to register the `PolicyInsights` and `EventGrid` resource providers (RPs) at the appropriate management scope. Whereas the Azure portal auto-registers any RPs you invoke for the first time, Azure CLI does not.
 
 ```azurecli-interactive
 # Log in first with az login if you're not using Cloud Shell
 
-az eventgrid system-topic create --name PolicyStateChanges --location global --topic-type Microsoft.PolicyInsights.PolicyStates --source "/subscriptions/<subscriptionID>" --resource-group "<resource_group_name>"
+# Register the required RPs at the management group scope
+az provider register --namespace Microsoft.PolicyInsights -m <managementGroupId>
+az provider register --namespace Microsoft.EventGrid -m <managementGroupId>
+
+# Alternatively, register the required RPs at the subscription scope (defaults to current subscription context)
+az provider register --namespace Microsoft.PolicyInsights
+az provider register --namespace Microsoft.EventGrid
+```
+
+Next, replace `<subscriptionId>` in the **scope** parameter with the ID of your subscription and
+`<resource_group_name>` in **resource-group** parameter with the previously created resource group.
+
+```azurecli-interactive
+az eventgrid system-topic create --name PolicyStateChanges --location global --topic-type Microsoft.PolicyInsights.PolicyStates --source "/subscriptions/<subscriptionId>" --resource-group "<resource_group_name>"
 ```
 
 If your Event Grid system topic will be applied to the management group scope, then the Azure CLI `--source` parameter syntax is a bit different. Here's an example:
@@ -144,7 +144,7 @@ hold the Event Grid topic:
 ```azurecli-interactive
 # Log in first with az login if you're not using Cloud Shell
 
-az policy assignment create --name 'requiredtags-events' --display-name 'Require tag on RG' --scope '<ResourceGroupScope>' --policy '<policy definition ID>' --params '{ \"tagName\": { \"value\": \"EventTest\" } }'
+az policy assignment create --name 'requiredtags-events' --display-name 'Require tag on RG' --scope '<resourceGroupScope>' --policy '<policy definition ID>' --params '{ \"tagName\": { \"value\": \"EventTest\" } }'
 ```
 
 The preceding command uses the following information:
@@ -155,7 +155,7 @@ The preceding command uses the following information:
 - **Scope** - A scope determines what resources or grouping of resources the policy assignment gets
   enforced on. It could range from a subscription to resource groups. Be sure to replace
   &lt;scope&gt; with the name of your resource group. The format for a resource group scope is
-  `/subscriptions/<SubscriptionID>/resourceGroups/<ResourceGroup>`.
+  `/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>`.
 - **Policy** - The policy definition ID, based on which you're using to create the assignment. In
   this case, it's the ID of policy definition _Require a tag on resource groups_. To get the policy
   definition ID, run this command:
@@ -175,19 +175,26 @@ event notification to appear in the web app. The resource group we created show
 ## Trigger a change on the resource group
 
 To make the resource group compliant, a tag with the name **EventTest** is required. Add the tag to
-the resource group with the following command replacing `<SubscriptionID>` with your subscription ID
-and `<ResourceGroup>` with the name of the resource group:
+the resource group with the following command replacing `<subscriptionId>` with your subscription ID
+and `<resourceGroup>` with the name of the resource group:
 
 ```azurecli-interactive
 # Log in first with az login if you're not using Cloud Shell
 
-az tag create --resource-id '/subscriptions/<SubscriptionID>/resourceGroups/<ResourceGroup>' --tags EventTest=true
+az tag create --resource-id '/subscriptions/<SubscriptionID>/resourceGroups/<resourceGroup>' --tags EventTest=true
 ```
 
 After adding the required tag to the resource group, wait for a
 **Microsoft.PolicyInsights.PolicyStateChanged** event notification to appear in the web app. Expand
 the event and the `data.complianceState` value now shows _Compliant_.
 
+## Troubleshooting
+
+If you see an error similar to one of the following, please make sure that you've registered both resource providers at the scope to which you're subscribing (management group or subscription):
+
+- `Deployment has failed with the following error: {"code":"Publisher Notification Error","message":"Failed to enable publisher notifications.","details":[{"code":"Publisher Provider Error","message":"GET request for <uri> failed with status code: Forbidden, code: AuthorizationFailed and message: The client '<identifier>' with object id '<identifier>' does not have authorization to perform action 'microsoft.policyinsights/eventGridFilters/read' over scope '<scope>/providers/microsoft.policyinsights/eventGridFilters/_default' or the scope is invalid. If access was recently granted, please refresh your credentials.."}]}`
+- `Deployment has failed with the following error: {'code':'Publisher Notification Error','message':'Failed to enable publisher notifications.','details':[{'code':'ApiVersionNotSupported','message':'Event Grid notifications are currently not supported by microsoft.policyinsights in global. Try re-registering Microsoft.EventGrid provider if this is your first event subscription in this region.'}]}`
+
 ## Clean up resources
 
 If you plan to continue working with this web app and Azure Policy event subscription, don't clean
diff --git a/includes/policy/policy-events.md b/includes/policy/policy-events.md
@@ -2,7 +2,7 @@
 author: timwarner-msft
 ms.service: azure-policy
 ms.topic: include
-ms.date: 07/12/2022
+ms.date: 07/19/2022
 ms.author: timwarner
 ms.custom: generated
 ---
@@ -65,7 +65,7 @@ The data object has the following properties:
 ## Example event
 
 # [Event Grid event schema](#tab/event-grid-event-schema)
-The following example shows the schema of a policy state created event:
+The following example shows the schema of a policy state created event scoped at the subscription level:
 
 ```json
 [{
@@ -88,7 +88,7 @@ The following example shows the schema of a policy state created event:
 }]
 ```
 
-The schema for a policy state changed event is similar:
+The schema for a policy state changed event scoped at the subscription level is similar:
 
 ```json
 [{
@@ -110,9 +110,10 @@ The schema for a policy state changed event is similar:
     "metadataVersion": "1"
 }]
 ```
+
 # [Cloud event schema](#tab/cloud-event-schema)
 
-The following example shows the schema of a policy state created event:
+The following example shows the schema of a policy state created event scoped at the subscription level:
 
 ```json
 [{
@@ -134,7 +135,7 @@ The following example shows the schema of a policy state created event:
 }]
 ```
 
-The schema for a policy state changed event is similar:
+The schema for a policy state changed event scoped at the subscription level is similar:
 
 ```json
 [{
@@ -157,3 +158,98 @@ The schema for a policy state changed event is similar:
 ```
 
 ---
+
+# [Event Grid event schema](#tab/event-grid-event-schema)
+The following example shows the schema of a policy state created event scoped at the management group level:
+
+```json
+[{
+    "id": "5829794FCB5075FCF585476619577B5A5A30E52C84842CBD4E2AD73996714C4C",
+    "topic": "/tenants/<tenantId>/providers/Microsoft.Management/managementGroups/<managementGroupId>",
+    "subject": "/subscriptions/<SubscriptionID>/resourceGroups/<ResourceGroup>/providers/<ProviderNamespace>/<ResourceType>/<ResourceName>",
+    "data": {
+        "timestamp": "2021-03-27T18:37:42.4496956Z",
+        "policyAssignmentId": "<policy-assignment-scope>/providers/microsoft.authorization/policyassignments/<policy-assignment-name>",
+        "policyDefinitionId": "<policy-definition-scope>/providers/microsoft.authorization/policydefinitions/<policy-definition-name>",
+        "policyDefinitionReferenceId": "",
+        "complianceState": "NonCompliant",
+        "subscriptionId": "<subscription-id>",
+        "complianceReasonCode": ""
+    },
+    "eventType": "Microsoft.PolicyInsights.PolicyStateCreated",
+    "eventTime": "2021-03-27T18:37:42.5241536Z",
+    "dataVersion": "1",
+    "metadataVersion": "1"
+}]
+```
+
+The schema for a policy state changed event scoped at the management group level is similar:
+
+```json
+[{
+    "id": "5829794FCB5075FCF585476619577B5A5A30E52C84842CBD4E2AD73996714C4C",
+    "topic": "/tenants/<tenantId>/providers/Microsoft.Management/managementGroups/<managementGroupId>",
+    "subject": "/subscriptions/<SubscriptionID>/resourceGroups/<ResourceGroup>/providers/<ProviderNamespace>/<ResourceType>/<ResourceName>",
+    "data": {
+        "timestamp": "2021-03-27T18:37:42.4496956Z",
+        "policyAssignmentId": "<policy-assignment-scope>/providers/microsoft.authorization/policyassignments/<policy-assignment-name>",
+        "policyDefinitionId": "<policy-definition-scope>/providers/microsoft.authorization/policydefinitions/<policy-definition-name>",
+        "policyDefinitionReferenceId": "",
+        "complianceState": "NonCompliant",
+        "subscriptionId": "<subscription-id>",
+        "complianceReasonCode": ""
+    },
+    "eventType": "Microsoft.PolicyInsights.PolicyStateChanged",
+    "eventTime": "2021-03-27T18:37:42.5241536Z",
+    "dataVersion": "1",
+    "metadataVersion": "1"
+}]
+```
+
+# [Cloud event schema](#tab/cloud-event-schema)
+
+The following example shows the schema of a policy state created event scoped at the management group level:
+
+```json
+[{
+    "id": "5829794FCB5075FCF585476619577B5A5A30E52C84842CBD4E2AD73996714C4C",
+    "source": "/tenants/<tenantId>/providers/Microsoft.Management/managementGroups/<managementGroupId>",
+    "subject": "/subscriptions/<SubscriptionID>/resourceGroups/<ResourceGroup>/providers/<ProviderNamespace>/<ResourceType>/<ResourceName>",
+    "data": {
+        "timestamp": "2021-03-27T18:37:42.4496956Z",
+        "policyAssignmentId": "<policy-assignment-scope>/providers/microsoft.authorization/policyassignments/<policy-assignment-name>",
+        "policyDefinitionId": "<policy-definition-scope>/providers/microsoft.authorization/policydefinitions/<policy-definition-name>",
+        "policyDefinitionReferenceId": "",
+        "complianceState": "NonCompliant",
+        "subscriptionId": "<subscription-id>",
+        "complianceReasonCode": ""
+    },
+    "type": "Microsoft.PolicyInsights.PolicyStateCreated",
+    "time": "2021-03-27T18:37:42.5241536Z",
+    "specversion": "1.0"
+}]
+```
+
+The schema for a policy state changed event scoped at the management group level is similar:
+
+```json
+[{
+    "id": "5829794FCB5075FCF585476619577B5A5A30E52C84842CBD4E2AD73996714C4C",
+    "source": "/tenants/<tenantId>/providers/Microsoft.Management/managementGroups/<managementGroupId>",
+    "subject": "/subscriptions/<SubscriptionID>/resourceGroups/<ResourceGroup>/providers/<ProviderNamespace>/<ResourceType>/<ResourceName>",
+    "data": {
+        "timestamp": "2021-03-27T18:37:42.4496956Z",
+        "policyAssignmentId": "<policy-assignment-scope>/providers/microsoft.authorization/policyassignments/<policy-assignment-name>",
+        "policyDefinitionId": "<policy-definition-scope>/providers/microsoft.authorization/policydefinitions/<policy-definition-name>",
+        "policyDefinitionReferenceId": "",
+        "complianceState": "NonCompliant",
+        "subscriptionId": "<subscription-id>",
+        "complianceReasonCode": ""
+    },
+    "type": "Microsoft.PolicyInsights.PolicyStateChanged",
+    "time": "2021-03-27T18:37:42.5241536Z",
+    "specversion": "1.0"
+}]
+```
+
+---
