New-AzPolicyAssignment
Creates or updates a policy assignment.
Syntax
New-AzPolicyAssignment
-Name <String>
[-Scope <String>]
[-NotScope <String[]>]
[-DisplayName <String>]
[-Description <String>]
[-Metadata <String>]
[-EnforcementMode <String>]
[-IdentityType <String>]
[-IdentityId <String>]
[-Location <String>]
[-NonComplianceMessage <PSObject[]>]
[-Override <IOverride[]>]
[-ResourceSelector <IResourceSelector[]>]
[-BackwardCompatible]
[-DefaultProfile <PSObject>]
[-WhatIf]
[-Confirm]
[<CommonParameters>] New-AzPolicyAssignment
-Name <String>
[-Scope <String>]
[-NotScope <String[]>]
[-DisplayName <String>]
[-Description <String>]
[-Metadata <String>]
[-EnforcementMode <String>]
[-IdentityType <String>]
[-IdentityId <String>]
[-Location <String>]
[-NonComplianceMessage <PSObject[]>]
[-Override <IOverride[]>]
[-ResourceSelector <IResourceSelector[]>]
[-BackwardCompatible]
[-PolicyDefinition <PSObject>]
[-DefinitionVersion <String>]
-PolicyParameterObject <Hashtable>
[-DefaultProfile <PSObject>]
[-WhatIf]
[-Confirm]
[<CommonParameters>] New-AzPolicyAssignment
-Name <String>
[-Scope <String>]
[-NotScope <String[]>]
[-DisplayName <String>]
[-Description <String>]
[-Metadata <String>]
[-EnforcementMode <String>]
[-IdentityType <String>]
[-IdentityId <String>]
[-Location <String>]
[-NonComplianceMessage <PSObject[]>]
[-Override <IOverride[]>]
[-ResourceSelector <IResourceSelector[]>]
[-BackwardCompatible]
[-PolicyDefinition <PSObject>]
[-DefinitionVersion <String>]
-PolicyParameter <String>
[-DefaultProfile <PSObject>]
[-WhatIf]
[-Confirm]
[<CommonParameters>] New-AzPolicyAssignment
-Name <String>
[-Scope <String>]
[-NotScope <String[]>]
[-DisplayName <String>]
[-Description <String>]
[-Metadata <String>]
[-EnforcementMode <String>]
[-IdentityType <String>]
[-IdentityId <String>]
[-Location <String>]
[-NonComplianceMessage <PSObject[]>]
[-Override <IOverride[]>]
[-ResourceSelector <IResourceSelector[]>]
[-BackwardCompatible]
-PolicyDefinition <PSObject>
[-DefinitionVersion <String>]
[-DefaultProfile <PSObject>]
[-WhatIf]
[-Confirm]
[<CommonParameters>] Description
The New-AzPolicyAssignment cmdlet creates or updates a policy assignment with the given scope and name. Policy assignments apply to all resources contained within their scope. For example, when you assign a policy at resource group scope, that policy applies to all resources in the group.
Examples
Example 1: Policy assignment at subscription level
$Subscription = Get-AzSubscription -SubscriptionName 'Subscription01'
$Policy = Get-AzPolicyDefinition -Name 'VirtualMachinePolicy'
New-AzPolicyAssignment -Name 'VirtualMachinePolicyAssignment' -PolicyDefinition $Policy -Scope "/subscriptions/$($Subscription.Id)"The first command gets a subscription named Subscription01 by using the Get-AzSubscription cmdlet and stores it in the $Subscription variable. The second command gets the policy definition named VirtualMachinePolicy by using the Get-AzPolicyDefinition cmdlet and stores it in the $Policy variable. The final command assigns the policy in $Policy at the level of the subscription identified by the subscription scope string.
Example 2: Policy assignment at resource group level
$ResourceGroup = Get-AzResourceGroup -Name 'ResourceGroup11'
$Policy = Get-AzPolicyDefinition -Name 'VirtualMachinePolicy'
New-AzPolicyAssignment -Name 'VirtualMachinePolicyAssignment' -PolicyDefinition $Policy -Scope $ResourceGroup.ResourceIdThe first command gets a resource group named ResourceGroup11 by using the Get-AzResourceGroup cmdlet and stores it in the $ResourceGroup variable. The second command gets the policy definition named VirtualMachinePolicy by using the Get-AzPolicyDefinition cmdlet and stores it in the $Policy variable. The final command assigns the policy in $Policy at the level of the resource group identified by the ResourceId property of $ResourceGroup.
Example 3: Policy assignment at resource group level with policy parameter object
$ResourceGroup = Get-AzResourceGroup -Name 'ResourceGroup11'
$Policy = Get-AzPolicyDefinition -BuiltIn | Where-Object {$_.DisplayName -eq 'Allowed locations'}
$Locations = Get-AzLocation | Where-Object displayname -like '*east*'
$AllowedLocations = @{'listOfAllowedLocations'=($Locations.location)}
New-AzPolicyAssignment -Name 'RestrictLocationPolicyAssignment' -PolicyDefinition $Policy -Scope $ResourceGroup.ResourceId -PolicyParameterObject $AllowedLocationsThe first command gets a resource group named ResourceGroup11 by using the Get-AzResourceGroup cmdlet. The command stores that object in the $ResourceGroup variable. The second command gets the built-in policy definition for allowed locations by using the Get-AzPolicyDefinition cmdlet. The command stores that object in the $Policy variable. The third and fourth commands create an object containing all Azure regions with "east" in the name. The commands store that object in the $AllowedLocations variable. The final command assigns the policy in $Policy at the level of a resource group using the policy parameter object in $AllowedLocations. The ResourceId property of $ResourceGroup identifies the resource group.
Example 4: Policy assignment at resource group level with policy parameter file
'{
"listOfAllowedLocations": {
"value": [
"westus",
"westeurope",
"japanwest"
]
}
}' > .\AllowedLocations.json
$ResourceGroup = Get-AzResourceGroup -Name 'ResourceGroup11'
$Policy = Get-AzPolicyDefinition -BuiltIn | Where-Object {$_.DisplayName -eq 'Allowed locations'}
New-AzPolicyAssignment -Name 'RestrictLocationPolicyAssignment' -PolicyDefinition $Policy -Scope $ResourceGroup.ResourceId -PolicyParameter .\AllowedLocations.jsonThe first command creates a parameter file called AllowedLocations.json in the local working directory. The second command gets a resource group named ResourceGroup11 by using the Get-AzResourceGroup cmdlet and stores it in the $ResourceGroup variable. The third command gets the built-in policy definition for allowed locations by using the Get-AzPolicyDefinition cmdlet and stores it in the $Policy variable. The final command assigns the policy in $Policy at the resource group identified by the ResourceId property of $ResourceGroup using the policy parameter file AllowedLocations.json from the local working directory.
Example 5: Policy assignment with a system assigned managed identity
$ResourceGroup = Get-AzResourceGroup -Name 'ResourceGroup11'
$Policy = Get-AzPolicyDefinition -Name 'VirtualMachinePolicy'
New-AzPolicyAssignment -Name 'VirtualMachinePolicyAssignment' -PolicyDefinition $Policy -Scope $ResourceGroup.ResourceId -Location 'eastus' -IdentityType 'SystemAssigned'The first command gets a resource group named ResourceGroup11 by using the Get-AzResourceGroup cmdlet and stores it in the $ResourceGroup variable. The second command gets the policy definition named VirtualMachinePolicy by using the Get-AzPolicyDefinition cmdlet and stores it in the $Policy variable. The final command assigns the policy in $Policy to the resource group. A system assigned managed identity is automatically created and assigned to the policy assignment.
Example 6: Policy assignment with a user assigned managed identity
$ResourceGroup = Get-AzResourceGroup -Name 'ResourceGroup11'
$Policy = Get-AzPolicyDefinition -Name 'VirtualMachinePolicy'
$UserAssignedIdentity = Get-AzUserAssignedIdentity -ResourceGroupName 'ResourceGroup1' -Name 'UserAssignedIdentity1'
New-AzPolicyAssignment -Name 'VirtualMachinePolicyAssignment' -PolicyDefinition $Policy -Scope $ResourceGroup.ResourceId -Location 'eastus' -IdentityType 'UserAssigned' -IdentityId $UserAssignedIdentity.IdThe first command gets a resource group named ResourceGroup11 by using the Get-AzResourceGroup cmdlet and stores it in the $ResourceGroup variable. The second command gets the policy definition named VirtualMachinePolicy by using the Get-AzPolicyDefinition cmdlet and stores it in the $Policy variable. The third command gets the user assigned managed identity named UserAssignedIdentity1 by using the Get-AzUserAssignedIdentity cmdlet and stores it in the $UserAssignedIdentity variable. The final command assigns the policy in $Policy to the resource group. The user assigned managed identity identified by the Id property of $UserAssignedIdentity is assigned to the policy assignment by passing the Id* property to the IdentityId parameter.
Example 7: Policy assignment with an enforcement mode property
$Subscription = Get-AzSubscription -SubscriptionName 'Subscription01'
$Policy = Get-AzPolicyDefinition -Name 'VirtualMachinePolicy'
New-AzPolicyAssignment -Name 'VirtualMachinePolicyAssignment' -PolicyDefinition $Policy -Scope "/subscriptions/$($Subscription.Id)" -EnforcementMode DoNotEnforceThe first command gets a subscription named Subscription01 by using the Get-AzSubscription cmdlet and stores it in the $Subscription variable. The second command gets the policy definition named VirtualMachinePolicy by using the Get-AzPolicyDefinition cmdlet and stores it in the $Policy variable. The final command assigns the policy in $Policy at the level of the subscription identified by the subscription scope string.
The assignment is set with an EnforcementMode value of DoNotEnforce i.e. the policy effect is not enforced during resource creation or update.
Example 8: Policy assignment with non-compliance messages
$PolicySet = Get-AzPolicySetDefinition -Name 'VirtualMachinePolicySet'
$NonComplianceMessages = @(@{Message="Only DsV2 SKUs are allowed."; PolicyDefinitionReferenceId="DefRef1"}, @{Message="Virtual machines must follow cost management best practices."})
New-AzPolicyAssignment -Name 'VirtualMachinePolicyAssignment' -PolicySetDefinition $PolicySet -NonComplianceMessage $NonComplianceMessagesThe first command gets the policy set definition named VirtualMachinePolicySet by using the Get-AzPolicySetDefinition cmdlet and stores it in the $PolicySet variable. The second command creates an array of non-compliance messages. One general purpose message for the entire assignment and one message specific to a SKU restriction policy within the assigned policy set definition. The final command assigns the policy set definition in $PolicySet to the subscription with two non-compliance messages that will be shown if a resource is denied by policy.
Example 9: Policy assignment with resource selector
$Policy = Get-AzPolicyDefinition -Name 'VirtualMachinePolicy'
$ResourceSelector = @{Name = "MyLocationSelector"; Selector = @(@{Kind = "resourceLocation"; In = @("eastus", "eastus2")})}
New-AzPolicyAssignment -Name 'VirtualMachinePolicyAssignment' -PolicyDefinition $Policy -ResourceSelector $ResourceSelectorThe first command gets the policy definition named VirtualMachinePolicy by using the Get-AzPolicyDefinition cmdlet and stores it in the $Policy variable. The second command creates a resource selector object that will be used to specify the assignment should only apply to resources located in East US or East US 2 and stores it in the $ResourceSelector variable. The final command assigns the policy definition in $Policy to the subscription with the resource selector specified by $ResourceSelector.
Example 10: Policy assignment with override
$Policy = Get-AzPolicyDefinition -Name 'VirtualMachinePolicy'
$Selector = @{Kind = "resourceLocation"; In = @("eastus", "eastus2")}
$Override = @(@{Kind = "policyEffect"; Value = 'Disabled'; Selector = @($Selector)})
New-AzPolicyAssignment -Name 'VirtualMachinePolicyAssignment' -PolicyDefinition $Policy -Override $OverrideThe first command gets the policy definition named VirtualMachinePolicy by using the Get-AzPolicyDefinition cmdlet and stores it in the $Policy variable. The second command creates a location selector specifying East US or East US 2 locations and stores it in the $Selector variable. The third command creates an override object that will be used to specify that the assigned definition should have a Disabled effect in the locations identified by the $Selector object and stores it in the $Override variable. The final command assigns the policy definition in $Policy to the subscription with the override specified by $Override.
Example 11: [Backcompat] Policy assignment at resource group level with policy parameter object
$ResourceGroup = Get-AzResourceGroup -Name 'ResourceGroup11'
$Policy = Get-AzPolicyDefinition -BuiltIn | Where-Object {$_.Properties.DisplayName -eq 'Allowed locations'}
$Locations = Get-AzLocation | Where-Object displayname -like '*east*'
$AllowedLocations = @{'listOfAllowedLocations'=($Locations.location)}
New-AzPolicyAssignment -Name 'RestrictLocationPolicyAssignment' -PolicyDefinition $Policy -Scope $ResourceGroup.ResourceId -PolicyParameterObject $AllowedLocationsThe first command gets a resource group named ResourceGroup11 by using the Get-AzResourceGroup cmdlet. The command stores that object in the $ResourceGroup variable. The second command gets the built-in policy definition for allowed locations by using the Get-AzPolicyDefinition cmdlet. The command stores that object in the $Policy variable. The third and fourth commands create an object containing all Azure regions with "east" in the name. The commands store that object in the $AllowedLocations variable. The final command assigns the policy in $Policy at the level of a resource group using the policy parameter object in $AllowedLocations. The ResourceId property of $ResourceGroup identifies the resource group.
Example 12: [Backcompat] Policy assignment at resource group level with policy parameter file
'{
"listOfAllowedLocations": {
"value": [
"westus",
"westeurope",
"japanwest"
]
}
}' > .\AllowedLocations.json
$ResourceGroup = Get-AzResourceGroup -Name 'ResourceGroup11'
$Policy = Get-AzPolicyDefinition -BuiltIn | Where-Object {$_.Properties.DisplayName -eq 'Allowed locations'}
New-AzPolicyAssignment -Name 'RestrictLocationPolicyAssignment' -PolicyDefinition $Policy -Scope $ResourceGroup.ResourceId -PolicyParameter .\AllowedLocations.jsonThe first command creates a parameter file called AllowedLocations.json in the local working directory. The second command gets a resource group named ResourceGroup11 by using the Get-AzResourceGroup cmdlet and stores it in the $ResourceGroup variable. The third command gets the built-in policy definition for allowed locations by using the Get-AzPolicyDefinition cmdlet and stores it in the $Policy variable. The final command assigns the policy in $Policy at the resource group identified by the ResourceId property of $ResourceGroup using the policy parameter file AllowedLocations.json from the local working directory.
Parameters
-BackwardCompatible
Causes cmdlet to return artifacts using legacy format placing policy-specific properties in a property bag object.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Confirm
Prompts you for confirmation before running the cmdlet.
| Type: | SwitchParameter |
| Aliases: | cf |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-DefaultProfile
The DefaultProfile parameter is not functional. Use the SubscriptionId parameter when available if executing the cmdlet against a different subscription.
| Type: | PSObject |
| Aliases: | AzureRMContext, AzureCredential |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-DefinitionVersion
Indicate version of policy definition or policy set definition
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Description
This message will be part of response in case of policy violation.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-DisplayName
The display name of the policy assignment.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-EnforcementMode
The policy assignment enforcement mode. Possible values are Default and DoNotEnforce.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-IdentityId
The user identity associated with the policy. The user identity dictionary key references will be ARM resource ids in the form: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}'.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-IdentityType
The identity type. This is the only required field when adding a system or user assigned identity to a resource.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Location
The location of the policy assignment. Only required when utilizing managed identity.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Metadata
The policy assignment metadata. Metadata is an open ended object and is typically a collection of key value pairs.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Name
The name of the policy assignment.
| Type: | String |
| Aliases: | PolicyAssignmentName |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-NonComplianceMessage
The messages that describe why a resource is non-compliant with the policy. To construct, see NOTES section for NONCOMPLIANCEMESSAGE properties and create a hash table.
| Type: | PSObject[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-NotScope
The policy's excluded scopes.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Override
The policy property value override.
| Type: | IOverride[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PolicyDefinition
Accept policy definition or policy set definition object
| Type: | PSObject |
| Aliases: | PolicySetDefinition |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-PolicyParameter
The parameter values for the assigned policy rule. The keys are the parameter names.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PolicyParameterObject
The parameter values for the assigned policy rule. The keys are the parameter names.
| Type: | Hashtable |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ResourceSelector
The resource selector list to filter policies by resource properties.
| Type: | IResourceSelector[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Scope
The scope of the policy assignment. Valid scopes are: management group (format: '/providers/Microsoft.Management/managementGroups/{managementGroup}'), subscription (format: '/subscriptions/{subscriptionId}'), resource group (format: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}', or resource (format: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/[{parentResourcePath}/]{resourceType}/{resourceName}'
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-WhatIf
Shows what would happen if the cmdlet runs. The cmdlet is not run.
| Type: | SwitchParameter |
| Aliases: | wi |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Inputs
PSObject[]
String[]
Outputs
Azure PowerShell