Skip to content

Commit a87096a

Browse files
American-DipperAmerican-Dipper
authored
Merge pull request #270147 from davidsmatlak/ds-update-policy-rest-20240325
Updates Azure Policy REST API quickstart
2 parents 87160ad + 6d7e226 commit a87096a

File tree

1 file changed

+152
-90
lines changed

1 file changed

+152
-90
lines changed

‎articles/governance/policy/assign-policy-rest-api.md

Lines changed: 152 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -1,136 +1,198 @@
11
---
2-
title: "Quickstart: New policy assignment with REST API"
2+
title: "Quickstart: Create policy assignment with REST API"
33
description: In this quickstart, you use REST API to create an Azure Policy assignment to identify non-compliant resources.
4-
ms.date: 08/17/2021
4+
ms.date: 03/26/2024
55
ms.topic: quickstart
66
---
7-
# Quickstart: Create a policy assignment to identify non-compliant resources with REST API
87

9-
The first step in understanding compliance in Azure is to identify the status of your resources.
10-
This quickstart steps you through the process of creating a policy assignment to identify virtual
11-
machines that aren't using managed disks.
8+
# Quickstart: Create a policy assignment to identify non-compliant resources with REST API
129

13-
At the end of this process, you identify virtual machines that aren't using managed
14-
disks. They're _non-compliant_ with the policy assignment.
10+
The first step in understanding compliance in Azure is to identify the status of your resources. In this quickstart, you create a policy assignment to identify non-compliant resources using REST API. The policy is assigned to a resource group and audits virtual machines that don't use managed disks. After you create the policy assignment, you identify non-compliant virtual machines.
1511

16-
REST API is used to create and manage Azure resources. This guide uses REST API to create a policy
17-
assignment and to identify non-compliant resources in your Azure environment.
12+
This guide uses REST API to create a policy assignment and to identify non-compliant resources in your Azure environment. The examples in this article use PowerShell and the Azure CLI `az rest` commands. You can also run the `az rest` commands from a Bash shell like Git Bash.
1813

1914
## Prerequisites
2015

21-
- If you don't have an Azure subscription, create a [free](https://azure.microsoft.com/free/)
22-
account before you begin.
23-
24-
- If you haven't already, install [ARMClient](https://github.com/projectkudu/ARMClient). It's a tool
25-
that sends HTTP requests to Azure Resource Manager-based REST APIs. You can also use tooling like PowerShell's
26-
[Invoke-RestMethod](/powershell/module/microsoft.powershell.utility/invoke-restmethod).
27-
28-
## Create a policy assignment
29-
30-
In this quickstart, you create a policy assignment and assign the **Audit VMs that do not use
31-
managed disks** (`06a78e20-9358-41c9-923c-fb736d382a4d`) definition. This policy definition
32-
identifies resources that aren't compliant to the conditions set in the policy definition.
33-
34-
Run the following command to create a policy assignment:
16+
- If you don't have an Azure account, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
17+
- Latest version of [PowerShell](/powershell/scripting/install/installing-powershell) or a Bash shell like Git Bash.
18+
- Latest version of [Azure CLI](/cli/azure/install-azure-cli).
19+
- [Visual Studio Code](https://code.visualstudio.com/).
20+
- A resource group with at least one virtual machine that doesn't use managed disks.
3521

36-
- REST API URI
22+
## Review the REST API syntax
3723

38-
```http
39-
PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/policyAssignments/audit-vm-manageddisks?api-version=2021-09-01
40-
```
24+
There are two elements to run REST API commands: the REST API URI and the request body. For information, go to [Policy Assignments - Create](/rest/api/policy/policy-assignments/create).
4125

42-
- Request Body
26+
The following example shows the REST API URI syntax to create a policy definition.
4327

44-
```json
45-
{
46-
"properties": {
47-
"displayName": "Audit VMs without managed disks Assignment",
48-
"description": "Shows all virtual machines not using managed disks",
49-
"policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/06a78e20-9358-41c9-923c-fb736d382a4d",
50-
"nonComplianceMessages": [
51-
{
52-
"message": "Virtual machines should use a managed disk"
53-
}
54-
]
55-
}
56-
}
57-
```
58-
59-
The preceding endpoint and request body uses the following information:
28+
```http
29+
PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/policyAssignments/{policyAssignmentName}?api-version=2023-04-01
30+
```
6031

61-
REST API URI:
62-
- **Scope** - A scope determines which resources or group of resources the policy assignment gets
63-
enforced on. It could range from a management group to an individual resource. Be sure to replace
32+
- `scope`: A scope determines which resources or group of resources the policy assignment gets
33+
enforced on. It could range from a management group to an individual resource. Replace
6434
`{scope}` with one of the following patterns:
6535
- Management group: `/providers/Microsoft.Management/managementGroups/{managementGroup}`
6636
- Subscription: `/subscriptions/{subscriptionId}`
6737
- Resource group: `/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}`
6838
- Resource: `/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/[{parentResourcePath}/]{resourceType}/{resourceName}`
69-
- **Name** - The name of the assignment. For this example, _audit-vm-manageddisks_ was used.
70-
71-
Request Body:
72-
- **DisplayName** - Display name for the policy assignment. In this case, you're using _Audit VMs
73-
without managed disks Assignment_.
74-
- **Description** - A deeper explanation of what the policy does or why it's assigned to this scope.
75-
- **policyDefinitionId** - The policy definition ID, based on which you're using to create the
76-
assignment. In this case, it's the ID of policy definition _Audit VMs that don't use managed
77-
disks_.
78-
- **nonComplianceMessages** - Set the message seen when a resource is denied due to non-compliance
79-
or evaluated to be non-compliant. For more information, see
80-
[assignment non-compliance messages](./concepts/assignment-structure.md#non-compliance-messages).
39+
- `policyAssignmentName`: Creates the policy assignment name for your assignment. The name is included in the policy assignment's `policyAssignmentId` property.
40+
41+
The following example is the JSON to create a request body file.
42+
43+
```json
44+
{
45+
"properties": {
46+
"displayName": "",
47+
"description": "",
48+
"policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/11111111-1111-1111-1111-111111111111",
49+
"nonComplianceMessages": [
50+
{
51+
"message": ""
52+
}
53+
]
54+
}
55+
}
56+
```
57+
58+
- `displayName`: Display name for the policy assignment.
59+
- `description`: Can be used to add context about the policy assignment.
60+
- `policyDefinitionId`: The policy definition ID that to create the assignment.
61+
- `nonComplianceMessages`: Set the message to use when a resource is evaluated as non-compliant. For more information, see [assignment non-compliance messages](./concepts/assignment-structure.md#non-compliance-messages).
62+
63+
## Connect to Azure
64+
65+
From a Visual Studio Code terminal session, connect to Azure. If you have more than one subscription, run the commands to set context to your subscription. Replace `<subscriptionID>` with your Azure subscription ID.
66+
67+
```azurecli
68+
az login
69+
70+
# Run these commands if you have multiple subscriptions
71+
az account list --output table
72+
az account set --subscription <subscriptionID>
73+
```
74+
75+
Use `az login` even if you're using PowerShell because the examples use Azure CLI [az rest](/cli/azure/reference-index#az-rest) commands.
76+
77+
## Create a policy assignment
78+
79+
In this example, you create a policy assignment and assign the [Audit VMs that do not use managed disks](https://github.com/Azure/azure-policy/blob/master/built-in-policies/policyDefinitions/Compute/VMRequireManagedDisk_Audit.json) definition.
80+
81+
A request body is needed to create the assignment. Save the following JSON in a file named _request-body.json_.
82+
83+
```json
84+
{
85+
"properties": {
86+
"displayName": "Audit VM managed disks",
87+
"description": "Policy assignment to resource group scope created with REST API",
88+
"policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/06a78e20-9358-41c9-923c-fb736d382a4d",
89+
"nonComplianceMessages": [
90+
{
91+
"message": "Virtual machines should use managed disks"
92+
}
93+
]
94+
}
95+
}
96+
```
97+
98+
To create your policy assignment in an existing resource group scope, use the following REST API URI with a file for the request body. Replace `{subscriptionId}` and `{resourceGroupName}` with your values. The command displays JSON output in your shell.
99+
100+
```azurepowershell
101+
az rest --method put --uri https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Authorization/policyAssignments/audit-vm-managed-disks?api-version=2023-04-01 --body `@request-body.json
102+
```
103+
104+
In PowerShell, the backtick (``` ` ```) is needed to escape the `at sign` (`@`) to specify a filename. In a Bash shell like Git Bash, omit the backtick.
105+
106+
For information, go to [Policy Assignments - Create](/rest/api/policy/policy-assignments/create).
81107

82108
## Identify non-compliant resources
83109

84-
To view the non-compliant resources that aren't compliant under this new assignment, run the following command to
85-
get the resource IDs of the non-compliant resources that are output into a JSON file:
110+
The compliance state for a new policy assignment takes a few minutes to become active and provide results about the policy's state. You use REST API to display the non-compliant resources for this policy assignment and the output is in JSON.
86111

87-
```http
88-
POST https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/policyDefinitions/06a78e20-9358-41c9-923c-fb736d382a4d/providers/Microsoft.PolicyInsights/policyStates/latest/queryResults?api-version=2019-10-01&$filter=IsCompliant eq false and PolicyAssignmentId eq 'audit-vm-manageddisks'&$apply=groupby((ResourceId))"
112+
To identify non-compliant resources, run the following command. Replace `{subscriptionId}` and `{resourceGroupName}` with your values used when you created the policy assignment.
113+
114+
```azurepowershell
115+
az rest --method post --uri https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.PolicyInsights/policyStates/latest/queryResults?api-version=2019-10-01 --uri-parameters `$filter="complianceState eq 'NonCompliant' and PolicyAssignmentName eq 'audit-vm-managed-disks'"
89116
```
90117

118+
The `filter` queries for resources that are evaluated as non-compliant with the policy definition named _audit-vm-managed-disks_ that you created with the policy assignment. Again, notice the backtick is used to escape the dollar sign (`$`) in the filter. For a Bash client, a backslash (`\`) is a common escape character.
119+
91120
Your results resemble the following example:
92121

93122
```json
94123
{
95-
"@odata.context": "https://management.azure.com/subscriptions/<subscriptionId>/providers/Microsoft.PolicyInsights/policyStates/$metadata#latest",
96-
"@odata.count": 3,
97-
"value": [{
98-
"@odata.id": null,
99-
"@odata.context": "https://management.azure.com/subscriptions/<subscriptionId>/providers/Microsoft.PolicyInsights/policyStates/$metadata#latest/$entity",
100-
"ResourceId": "/subscriptions/<subscriptionId>/resourcegroups/<rgname>/providers/microsoft.compute/virtualmachines/<virtualmachineId>"
101-
},
102-
{
103-
"@odata.id": null,
104-
"@odata.context": "https://management.azure.com/subscriptions/<subscriptionId>/providers/Microsoft.PolicyInsights/policyStates/$metadata#latest/$entity",
105-
"ResourceId": "/subscriptions/<subscriptionId>/resourcegroups/<rgname>/providers/microsoft.compute/virtualmachines/<virtualmachine2Id>"
106-
},
107-
{
108-
"@odata.id": null,
109-
"@odata.context": "https://management.azure.com/subscriptions/<subscriptionId>/providers/Microsoft.PolicyInsights/policyStates/$metadata#latest/$entity",
110-
"ResourceId": "/subscriptions/<subscriptionName>/resourcegroups/<rgname>/providers/microsoft.compute/virtualmachines/<virtualmachine3Id>"
111-
}
112-
113-
]
124+
"@odata.context": "https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.PolicyInsights/policyStates/$metadata#latest",
125+
"@odata.count": 1,
126+
"@odata.nextLink": null,
127+
"value": [
128+
{
129+
"@odata.context": "https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.PolicyInsights/policyStates/$metadata#latest/$entity",
130+
"@odata.id": null,
131+
"complianceReasonCode": "",
132+
"complianceState": "NonCompliant",
133+
"effectiveParameters": "",
134+
"isCompliant": false,
135+
"managementGroupIds": "",
136+
"policyAssignmentId": "/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/microsoft.authorization/policyassignments/audit-vm-managed-disks",
137+
"policyAssignmentName": "audit-vm-managed-disks",
138+
"policyAssignmentOwner": "tbd",
139+
"policyAssignmentParameters": "",
140+
"policyAssignmentScope": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}",
141+
"policyAssignmentVersion": "",
142+
"policyDefinitionAction": "audit",
143+
"policyDefinitionCategory": "tbd",
144+
"policyDefinitionGroupNames": [
145+
""
146+
],
147+
"policyDefinitionId": "/providers/microsoft.authorization/policydefinitions/06a78e20-9358-41c9-923c-fb736d382a4d",
148+
"policyDefinitionName": "06a78e20-9358-41c9-923c-fb736d382a4d",
149+
"policyDefinitionReferenceId": "",
150+
"policyDefinitionVersion": "1.0.0",
151+
"policySetDefinitionCategory": "",
152+
"policySetDefinitionId": "",
153+
"policySetDefinitionName": "",
154+
"policySetDefinitionOwner": "",
155+
"policySetDefinitionParameters": "",
156+
"policySetDefinitionVersion": "",
157+
"resourceGroup": "{resourceGroupName}",
158+
"resourceId": "/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/microsoft.compute/virtualmachines/{vmName}>",
159+
"resourceLocation": "westus3",
160+
"resourceTags": "tbd",
161+
"resourceType": "Microsoft.Compute/virtualMachines",
162+
"subscriptionId": "{subscriptionId}",
163+
"timestamp": "2024-03-26T02:19:28.3720191Z"
164+
}
165+
]
114166
}
115167
```
116168

117-
The results are comparable to what you'd typically see listed under **Non-compliant resources** in the Azure portal view.
169+
For more information, go to [Policy States - List Query Results For Resource Group](/rest/api/policy/policy-states/list-query-results-for-resource-group).
118170

119171
## Clean up resources
120172

121-
To remove the assignment created, use the following command:
173+
To remove the policy assignment, use the following command. Replace `{subscriptionId}` and `{resourceGroupName}` with your values used when you created the policy assignment. The command displays JSON output in your shell.
122174

123-
```http
124-
DELETE https://management.azure.com/{scope}/providers/Microsoft.Authorization/policyAssignments/audit-vm-manageddisks?api-version=2021-09-01
175+
```azurepowershell
176+
az rest --method delete --uri https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Authorization/policyAssignments/audit-vm-managed-disks?api-version=2023-04-01
177+
```
178+
179+
You can verify the policy assignment was deleted with the following command. A message is displayed in your shell.
180+
181+
```azurepowershell
182+
az rest --method get --uri https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Authorization/policyAssignments/audit-vm-managed-disks?api-version=2023-04-01
183+
```
184+
185+
```output
186+
The policy assignment 'audit-vm-managed-disks' is not found.
125187
```
126188

127-
Replace `{scope}` with the scope you used when you first created the policy assignment.
189+
For more information, go to [Policy Assignments - Delete](/rest/api/policy/policy-assignments/delete) and [Policy Assignments - Get](/rest/api/policy/policy-assignments/get).
128190

129191
## Next steps
130192

131193
In this quickstart, you assigned a policy definition to identify non-compliant resources in your Azure environment.
132194

133-
To learn more about assigning policies to validate that new resources are compliant, continue to the tutorial for:
195+
To learn more about how to assign policies that validate resource compliance, continue to the tutorial.
134196

135197
> [!div class="nextstepaction"]
136-
> [Creating and managing policies](./tutorials/create-and-manage.md)
198+
> [Tutorial: Create and manage policies to enforce compliance](./tutorials/create-and-manage.md)

0 commit comments

Comments
 (0)