Skip to content

Commit 469a991

Browse files
Stacyrch140Stacyrch140
authored
Merge pull request #266307 from davidsmatlak/ds-update-policy-powershell-qs-20240213
Update Azure Policy PowerShell quickstart
2 parents 3b9e166 + b94252c commit 469a991

File tree

1 file changed

+117
-78
lines changed

1 file changed

+117
-78
lines changed

‎articles/governance/policy/assign-policy-powershell.md

Lines changed: 117 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,127 +1,166 @@
11
---
2-
title: "Quickstart: New policy assignment with PowerShell"
3-
description: In this quickstart, you use Azure PowerShell to create an Azure Policy assignment to identify non-compliant resources.
4-
ms.date: 08/17/2021
2+
title: "Quickstart: Create policy assignment using Azure PowerShell"
3+
description: In this quickstart, you create an Azure Policy assignment to identify non-compliant resources using Azure PowerShell.
4+
ms.date: 02/15/2024
55
ms.topic: quickstart
66
ms.custom: devx-track-azurepowershell
77
---
8+
89
# Quickstart: Create a policy assignment to identify non-compliant resources using Azure PowerShell
910

10-
The first step in understanding compliance in Azure is to identify the status of your resources. In
11-
this quickstart, you create a policy assignment to identify virtual machines that aren't using
12-
managed disks. When complete, you'll identify virtual machines that are _non-compliant_.
11+
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 Azure PowerShell. This example evaluates virtual machines that don't use managed disks. After you create the policy assignment, you identify non-compliant virtual machines.
1312

14-
The Azure PowerShell module is used to manage Azure resources from the command line or in scripts.
15-
This guide explains how to use Az module to create a policy assignment.
13+
The Azure PowerShell modules can be used to manage Azure resources from the command line or in scripts. This article explains how to use Azure PowerShell to create a policy assignment.
1614

1715
## Prerequisites
1816

19-
- If you don't have an Azure subscription, create a [free](https://azure.microsoft.com/free/)
20-
account before you begin.
17+
- If you don't have an Azure account, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
18+
- [Azure PowerShell](/powershell/azure/install-az-ps).
19+
- [Visual Studio Code](https://code.visualstudio.com/).
20+
- `Microsoft.PolicyInsights` must be [registered](../../azure-resource-manager/management/resource-providers-and-types.md) in your Azure subscription. To register a resource provider, you must have permission to register resource providers. That permission is included in the Contributor and Owner roles.
21+
- A resource group with at least one virtual machine that doesn't use managed disks.
22+
23+
## Connect to Azure
24+
25+
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.
26+
27+
```azurepowershell
28+
Connect-AzAccount
29+
30+
# Run these commands if you have multiple subscriptions
31+
Get-AzSubScription
32+
Set-AzContext -Subscription <subscriptionID>
33+
```
2134

22-
- Before you start, make sure that the latest version of Azure PowerShell is installed. See
23-
[Install Azure PowerShell module](/powershell/azure/install-azure-powershell) for detailed information.
35+
## Register resource provider
2436

25-
- Register the Azure Policy Insights resource provider using Azure PowerShell. Registering the
26-
resource provider makes sure that your subscription works with it. To register a resource
27-
provider, you must have permission to the register resource provider operation. This operation is
28-
included in the Contributor and Owner roles. Run the following command to register the resource
29-
provider:
37+
When a resource provider is registered, it's available to use in your Azure subscription.
3038

31-
```azurepowershell-interactive
32-
# Register the resource provider if it's not already registered
33-
Register-AzResourceProvider -ProviderNamespace 'Microsoft.PolicyInsights'
34-
```
39+
To verify if `Microsoft.PolicyInsights` is registered, run `Get-AzResourceProvider`. The resource provider contains several resource types. If the result is `NotRegistered` run `Register-AzResourceProvider`:
3540

36-
For more information about registering and viewing resource providers, see
37-
[Resource Providers and Types](../../azure-resource-manager/management/resource-providers-and-types.md).
41+
```azurepowershell
42+
Get-AzResourceProvider -ProviderNamespace 'Microsoft.PolicyInsights' |
43+
Select-Object -Property ResourceTypes, RegistrationState
3844
39-
[!INCLUDE [cloud-shell-try-it.md](../../../includes/cloud-shell-try-it.md)]
45+
Register-AzResourceProvider -ProviderNamespace 'Microsoft.PolicyInsights'
46+
```
4047

41-
## Create a policy assignment
48+
## Create policy assignment
4249

43-
In this quickstart, you create a policy assignment for the _Audit VMs without managed disks_
44-
definition. This policy definition identifies virtual machines not using managed disks.
50+
Use the following commands to create a new policy assignment for your resource group. This example uses an existing resource group that contains a virtual machine _without_ managed disks. The resource group is the scope for the policy assignment.
4551

46-
Run the following commands to create a new policy assignment:
52+
Run the following commands and replace `<resourceGroupName>` with your resource group name:
4753

48-
```azurepowershell-interactive
49-
# Get a reference to the resource group that is the scope of the assignment
54+
```azurepowershell
5055
$rg = Get-AzResourceGroup -Name '<resourceGroupName>'
5156
52-
# Get a reference to the built-in policy definition to assign
53-
$definition = Get-AzPolicyDefinition | Where-Object { $_.Properties.DisplayName -eq 'Audit VMs that do not use managed disks' }
57+
$definition = Get-AzPolicyDefinition |
58+
Where-Object { $_.Properties.DisplayName -eq 'Audit VMs that do not use managed disks' }
59+
```
60+
61+
The `$rg` variable stores properties for the resource group and the `$definition` variable stores the policy definition's properties. The properties are used in subsequent commands.
62+
63+
Run the following command to create the policy assignment:
5464

55-
# Create the policy assignment with the built-in definition against your resource group
56-
New-AzPolicyAssignment -Name 'audit-vm-manageddisks' -DisplayName 'Audit VMs without managed disks Assignment' -Scope $rg.ResourceId -PolicyDefinition $definition
65+
```azurepowershell
66+
$policyparms = @{
67+
Name = 'audit-vm-managed-disks'
68+
DisplayName = 'Audit VMs without managed disks Assignment'
69+
Scope = $rg.ResourceId
70+
PolicyDefinition = $definition
71+
Description = 'Az PowerShell policy assignment to resource group'
72+
}
73+
74+
New-AzPolicyAssignment @policyparms
5775
```
5876

59-
The preceding commands use the following information:
77+
The `$policyparms` variable uses [splatting](/powershell/module/microsoft.powershell.core/about/about_splatting) to create parameter values and improve readability. The `New-AzPolicyAssignment` command uses the parameter values defined in the `$policyparms` variable.
78+
79+
- `Name` creates the policy assignment name used in the assignment's `ResourceId`.
80+
- `DisplayName` is the name for the policy assignment and is visible in Azure portal.
81+
- `Scope` uses the `$rg.ResourceId` property to assign the policy to the resource group.
82+
- `PolicyDefinition` assigns the policy definition stored in the `$definition` variable.
83+
- `Description` can be used to add context about the policy assignment.
84+
85+
The results of the policy assignment resemble the following example:
6086

61-
- **Name** - The actual name of the assignment. For this example, _audit-vm-manageddisks_ was used.
62-
- **DisplayName** - Display name for the policy assignment. In this case, you're using _Audit VMs
63-
without managed disks Assignment_.
64-
- **Definition** - The policy definition, based on which you're using to create the assignment. In
65-
this case, it's the ID of policy definition _Audit VMs that do not use managed disks_.
66-
- **Scope** - A scope determines what resources or grouping of resources the policy assignment gets
67-
enforced on. It could range from a subscription to resource groups. Be sure to replace
68-
&lt;scope&gt; with the name of your resource group.
87+
```output
88+
Name : audit-vm-managed-disks
89+
ResourceId : /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Authorization/policyAssignments/audit-vm-managed-disks
90+
ResourceName : audit-vm-managed-disks
91+
ResourceGroupName : {resourceGroupName}
92+
ResourceType : Microsoft.Authorization/policyAssignments
93+
SubscriptionId : {subscriptionId}
94+
PolicyAssignmentId : /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Authorization/policyAssignments/audit-vm-managed-disks
95+
Properties : Microsoft.Azure.Commands.ResourceManager.Cmdlets.Implementation.Policy.PsPolicyAssignmentProperties
96+
```
6997

70-
You're now ready to identify non-compliant resources to understand the compliance state of your
71-
environment.
98+
For more information, go to [New-AzPolicyAssignment](/powershell/module/az.resources/new-azpolicyassignment).
7299

73100
## Identify non-compliant resources
74101

75-
Use the following information to identify resources that aren't compliant with the policy assignment
76-
you created. Run the following commands:
102+
The compliance state for a new policy assignment takes a few minutes to become active and provide results about the policy's state.
77103

78-
```azurepowershell-interactive
79-
# Get the resources in your resource group that are non-compliant to the policy assignment
80-
Get-AzPolicyState -ResourceGroupName $rg.ResourceGroupName -PolicyAssignmentName 'audit-vm-manageddisks' -Filter 'IsCompliant eq false'
104+
Use the following command to identify resources that aren't compliant with the policy assignment
105+
you created:
106+
107+
```azurepowershell
108+
$complianceparms = @{
109+
ResourceGroupName = $rg.ResourceGroupName
110+
PolicyAssignmentName = 'audit-vm-managed-disks'
111+
Filter = 'IsCompliant eq false'
112+
}
113+
114+
Get-AzPolicyState @complianceparms
81115
```
82116

83-
For more information about getting policy state, see
84-
[Get-AzPolicyState](/powershell/module/az.policyinsights/Get-AzPolicyState).
117+
The `$complianceparms` variable uses splatting to create parameter values used in the `Get-AzPolicyState` command.
118+
119+
- `ResourceGroupName` gets the resource group name from the `$rg.ResourceGroupName` property.
120+
- `PolicyAssignmentName` specifies the name used when the policy assignment was created.
121+
- `Filter` uses an expression to find resources that aren't compliant with the policy assignment.
85122

86-
Your results resemble the following example:
123+
For more information, go to [Get-AzPolicyState](/powershell/module/az.policyinsights/Get-AzPolicyState).
124+
125+
Your results resemble the following example and `ComplianceState` shows `NonCompliant`:
87126

88127
```output
89-
Timestamp : 3/9/19 9:21:29 PM
90-
ResourceId : /subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmId}
91-
PolicyAssignmentId : /subscriptions/{subscriptionId}/providers/microsoft.authorization/policyassignments/audit-vm-manageddisks
92-
PolicyDefinitionId : /providers/Microsoft.Authorization/policyDefinitions/06a78e20-9358-41c9-923c-fb736d382a4d
93-
IsCompliant : False
94-
SubscriptionId : {subscriptionId}
95-
ResourceType : /Microsoft.Compute/virtualMachines
96-
ResourceTags : tbd
97-
PolicyAssignmentName : audit-vm-manageddisks
98-
PolicyAssignmentOwner : tbd
99-
PolicyAssignmentScope : /subscriptions/{subscriptionId}
100-
PolicyDefinitionName : 06a78e20-9358-41c9-923c-fb736d382a4d
101-
PolicyDefinitionAction : audit
102-
PolicyDefinitionCategory : Compute
103-
ManagementGroupIds : {managementGroupId}
128+
Timestamp : 2/14/2024 18:25:37
129+
ResourceId : /subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/microsoft.compute/virtualmachines/{vmId}
130+
PolicyAssignmentId : /subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/microsoft.authorization/policyassignments/audit-vm-managed-disks
131+
PolicyDefinitionId : /providers/microsoft.authorization/policydefinitions/06a78e20-9358-41c9-923c-fb736d382a4d
132+
IsCompliant : False
133+
SubscriptionId : {subscriptionId}
134+
ResourceType : Microsoft.Compute/virtualMachines
135+
ResourceLocation : {location}
136+
ResourceGroup : {resourceGroupName}
137+
ResourceTags : tbd
138+
PolicyAssignmentName : audit-vm-managed-disks
139+
PolicyAssignmentOwner : tbd
140+
PolicyAssignmentScope : /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}
141+
PolicyDefinitionName : 06a78e20-9358-41c9-923c-fb736d382a4d
142+
PolicyDefinitionAction : audit
143+
PolicyDefinitionCategory : tbd
144+
ManagementGroupIds : {managementGroupId}
145+
ComplianceState : NonCompliant
146+
AdditionalProperties : {[complianceReasonCode, ]}
104147
```
105148

106-
The results match what you see in the **Resource compliance** tab of a policy assignment in the
107-
Azure portal view.
108-
109149
## Clean up resources
110150

111-
To remove the assignment created, use the following command:
151+
To remove the policy assignment, use the following command:
112152

113-
```azurepowershell-interactive
114-
# Removes the policy assignment
115-
Remove-AzPolicyAssignment -Name 'audit-vm-manageddisks' -Scope '/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>'
153+
```azurepowershell
154+
Remove-AzPolicyAssignment -Name 'audit-vm-managed-disks' -Scope $rg.ResourceId
116155
```
117156

118157
## Next steps
119158

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

123-
To learn more about assigning policies to validate that new resources are compliant, continue to the
124-
tutorial for:
162+
To learn more how to assign policies that validate if new resources are compliant, continue to the
163+
tutorial.
125164

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

0 commit comments

Comments
 (0)