Quickstart: Create a policy assignment to identify non-compliant resources with REST API

  • บทความ
  • 3 นาทีในการอ่าน

The first step in understanding compliance in Azure is to identify the status of your resources. This quickstart steps you through the process of creating a policy assignment to identify virtual machines that aren't using managed disks.

At the end of this process, you'll successfully identify virtual machines that aren't using managed disks. They're non-compliant with the policy assignment.

REST API is used to create and manage Azure resources. This guide uses REST API to create a policy assignment and to identify non-compliant resources in your Azure environment.

Prerequisites

  • If you don't have an Azure subscription, create a free account before you begin.

  • If you haven't already, install ARMClient. It's a tool that sends HTTP requests to Azure Resource Manager-based REST APIs. You can also use the "Try It" feature in REST documentation or tooling like PowerShell's Invoke-RestMethod or Postman.

Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article without having to install anything on your local environment.

To start Azure Cloud Shell:

Option Example/Link
Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell. Example of Try It for Azure Cloud Shell
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. Launch Cloud Shell in a new window
Select the Cloud Shell button on the menu bar at the upper right in the Azure portal. Cloud Shell button in the Azure portal

To run the code in this article in Azure Cloud Shell:

  1. Start Cloud Shell.

  2. Select the Copy button on a code block to copy the code.

  3. Paste the code into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux or by selecting Cmd+Shift+V on macOS.

  4. Select Enter to run the code.

Create a policy assignment

In this quickstart, you create a policy assignment and assign the Audit VMs that do not use managed disks (06a78e20-9358-41c9-923c-fb736d382a4d) definition. This policy definition identifies resources that aren't compliant to the conditions set in the policy definition.

Run the following command to create a policy assignment:

  • REST API URI

    PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/policyAssignments/audit-vm-manageddisks?api-version=2021-09-01

  • Request Body

    {
  "properties": {
    "displayName": "Audit VMs without managed disks Assignment",
    "description": "Shows all virtual machines not using managed disks",
    "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/06a78e20-9358-41c9-923c-fb736d382a4d",
    "nonComplianceMessages": [
        {
            "message": "Virtual machines should use a managed disk"
        }
    ]
  }
}

The preceding endpoint and request body uses the following information:

REST API URI:

  • Scope - A scope determines what resources or grouping of resources the policy assignment gets enforced on. It could range from a management group to an individual resource. Be sure to replace {scope} with one of the following patterns:
    • Management group: /providers/Microsoft.Management/managementGroups/{managementGroup}
    • Subscription: /subscriptions/{subscriptionId}
    • Resource group: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}
    • Resource: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/[{parentResourcePath}/]{resourceType}/{resourceName}
  • Name - The actual name of the assignment. For this example, audit-vm-manageddisks was used.

Request Body:

  • DisplayName - Display name for the policy assignment. In this case, you're using Audit VMs without managed disks Assignment.
  • Description - A deeper explanation of what the policy does or why it's assigned to this scope.
  • policyDefinitionId - The policy definition ID, based on which you're using to create the assignment. In this case, it's the ID of policy definition Audit VMs that do not use managed disks.
  • nonComplianceMessages - Set the message seen when a resource is denied due to non-compliance or evaluated to be non-compliant. For more information, see assignment non-compliance messages.

Identify non-compliant resources

To view the resources that aren't compliant under this new assignment, run the following command to get the resource IDs of the non-compliant resources that are output into a JSON file:

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))"

Your results resemble the following example:

{
    "@odata.context": "https://management.azure.com/subscriptions/<subscriptionId>/providers/Microsoft.PolicyInsights/policyStates/$metadata#latest",
    "@odata.count": 3,
    "value": [{
            "@odata.id": null,
            "@odata.context": "https://management.azure.com/subscriptions/<subscriptionId>/providers/Microsoft.PolicyInsights/policyStates/$metadata#latest/$entity",
            "ResourceId": "/subscriptions/<subscriptionId>/resourcegroups/<rgname>/providers/microsoft.compute/virtualmachines/<virtualmachineId>"
        },
        {
            "@odata.id": null,
            "@odata.context": "https://management.azure.com/subscriptions/<subscriptionId>/providers/Microsoft.PolicyInsights/policyStates/$metadata#latest/$entity",
            "ResourceId": "/subscriptions/<subscriptionId>/resourcegroups/<rgname>/providers/microsoft.compute/virtualmachines/<virtualmachine2Id>"
        },
        {
            "@odata.id": null,
            "@odata.context": "https://management.azure.com/subscriptions/<subscriptionId>/providers/Microsoft.PolicyInsights/policyStates/$metadata#latest/$entity",
            "ResourceId": "/subscriptions/<subscriptionName>/resourcegroups/<rgname>/providers/microsoft.compute/virtualmachines/<virtualmachine3Id>"
        }

    ]
}

The results are comparable to what you'd typically see listed under Non-compliant resources in the Azure portal view.

Clean up resources

To remove the assignment created, use the following command:

DELETE https://management.azure.com/{scope}/providers/Microsoft.Authorization/policyAssignments/audit-vm-manageddisks?api-version=2021-09-01

Replace {scope} with the scope you used when you first created the policy assignment.

Next steps

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

To learn more about assigning policies to validate that new resources are compliant, continue to the tutorial for:

Creating and managing policies