Quickstart: Create a policy assignment to identify non-compliant resources with REST API
Grein
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.
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.
When assigning a built-in policy or initiative definition, it's optional to reference a version. Policy assignments of built-in definitions default to the latest version and automatically inherit minor version changes unless otherwise specified.
Prerequisites
If you don't have an Azure account, create a free account before you begin.
Latest version of PowerShell or a Bash shell like Git Bash.
A resource group with at least one virtual machine that doesn't use managed disks.
Review the REST API syntax
There are two elements to run REST API commands: the REST API URI and the request body. For information, go to Policy Assignments - Create.
The following example shows the REST API URI syntax to create a policy definition.
HTTP
PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/policyAssignments/{policyAssignmentName}?api-version=2023-04-01
scope: A scope determines which resources or group of resources the policy assignment gets
enforced on. It could range from a management group to an individual resource. Replace
{scope} with one of the following patterns:
policyAssignmentName: Creates the policy assignment name for your assignment. The name is included in the policy assignment's policyAssignmentId property.
The following example is the JSON to create a request body file.
displayName: Display name for the policy assignment.
description: Can be used to add context about the policy assignment.
policyDefinitionId: The policy definition ID that to create the assignment.
nonComplianceMessages: Set the message to use when a resource is evaluated as non-compliant. For more information, see assignment non-compliance messages.
Connect to Azure
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.
Azure CLI
az login# Run these commands if you have multiple subscriptionsaz account list --output table
az account set --subscription<subscriptionID>
Use az login even if you're using PowerShell because the examples use Azure CLI az rest commands.
A request body is needed to create the assignment. Save the following JSON in a file named request-body.json.
JSON
{
"properties": {
"displayName": "Audit VM managed disks",
"description": "Policy assignment to resource group scope created with REST API",
"policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/06a78e20-9358-41c9-923c-fb736d382a4d",
"nonComplianceMessages": [
{
"message": "Virtual machines should use managed disks"
}
]
}
}
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.
Azure PowerShell
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
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.
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.
To identify non-compliant resources, run the following command. Replace {subscriptionId} and {resourceGroupName} with your values used when you created the policy assignment.
Azure PowerShell
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'"
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.
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.
Azure PowerShell
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
You can verify the policy assignment was deleted with the following command. A message is displayed in your shell.
Azure PowerShell
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
Output
The policy assignment 'audit-vm-managed-disks' is not found.