Quickstart: Create a policy assignment to identify non-compliant resources using Azure PowerShell

Article
03/08/2023

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 virtual machines that aren't using managed disks. When complete, you'll identify virtual machines that are non-compliant.

The Azure PowerShell module is used to manage Azure resources from the command line or in scripts. This guide explains how to use Az module to create a policy assignment.

Prerequisites

If you don't have an Azure subscription, create a free account before you begin.
Before you start, make sure that the latest version of Azure PowerShell is installed. See Install Azure PowerShell module for detailed information.
Register the Azure Policy Insights resource provider using Azure PowerShell. Registering the resource provider makes sure that your subscription works with it. To register a resource provider, you must have permission to the register resource provider operation. This operation is included in the Contributor and Owner roles. Run the following command to register the resource provider:
```
# Register the resource provider if it's not already registered
Register-AzResourceProvider -ProviderNamespace 'Microsoft.PolicyInsights'
```
For more information about registering and viewing resource providers, see Resource Providers and Types.

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 or command block. Selecting Try It doesn't automatically copy the code or command to Cloud Shell.
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser.
Select the Cloud Shell button on the menu bar at the upper right in the Azure portal.

To use Azure Cloud Shell:

Start Cloud Shell.
Select the Copy button on a code block (or command block) to copy the code or command.
Paste the code or command into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux, or by selecting Cmd+Shift+V on macOS.
Select Enter to run the code or command.

Create a policy assignment

In this quickstart, you create a policy assignment for the Audit VMs without managed disks definition. This policy definition identifies virtual machines not using managed disks.

Run the following commands to create a new policy assignment:

# Get a reference to the resource group that is the scope of the assignment
$rg = Get-AzResourceGroup -Name '<resourceGroupName>'

# Get a reference to the built-in policy definition to assign
$definition = Get-AzPolicyDefinition | Where-Object { $_.Properties.DisplayName -eq 'Audit VMs that do not use managed disks' }

# Create the policy assignment with the built-in definition against your resource group
New-AzPolicyAssignment -Name 'audit-vm-manageddisks' -DisplayName 'Audit VMs without managed disks Assignment' -Scope $rg.ResourceId -PolicyDefinition $definition

The preceding commands use the following information:

Name - The actual name of the assignment. For this example, audit-vm-manageddisks was used.
DisplayName - Display name for the policy assignment. In this case, you're using Audit VMs without managed disks Assignment.
Definition - The policy definition, 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.
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 <scope> with the name of your resource group.

You're now ready to identify non-compliant resources to understand the compliance state of your environment.

Identify non-compliant resources

Use the following information to identify resources that aren't compliant with the policy assignment you created. Run the following commands:

# Get the resources in your resource group that are non-compliant to the policy assignment
Get-AzPolicyState -ResourceGroupName $rg.ResourceGroupName -PolicyAssignmentName 'audit-vm-manageddisks' -Filter 'IsCompliant eq false'

For more information about getting policy state, see Get-AzPolicyState.

Your results resemble the following example:

Timestamp                   : 3/9/19 9:21:29 PM
ResourceId                  : /subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmId}
PolicyAssignmentId          : /subscriptions/{subscriptionId}/providers/microsoft.authorization/policyassignments/audit-vm-manageddisks
PolicyDefinitionId          : /providers/Microsoft.Authorization/policyDefinitions/06a78e20-9358-41c9-923c-fb736d382a4d
IsCompliant                 : False
SubscriptionId              : {subscriptionId}
ResourceType                : /Microsoft.Compute/virtualMachines
ResourceTags                : tbd
PolicyAssignmentName        : audit-vm-manageddisks
PolicyAssignmentOwner       : tbd
PolicyAssignmentScope       : /subscriptions/{subscriptionId}
PolicyDefinitionName        : 06a78e20-9358-41c9-923c-fb736d382a4d
PolicyDefinitionAction      : audit
PolicyDefinitionCategory    : Compute
ManagementGroupIds          : {managementGroupId}

The results match what you see in the Resource compliance tab of a policy assignment in the Azure portal view.

Clean up resources

To remove the assignment created, use the following command:

# Removes the policy assignment
Remove-AzPolicyAssignment -Name 'audit-vm-manageddisks' -Scope '/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>'

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