New-AzPolicyAssignment
Creates a policy assignment.
Syntax
New-AzPolicyAssignment
-Name <String>
[-Scope <String>]
[-NotScope <String[]>]
[-DisplayName <String>]
[-Description <String>]
[-PolicyDefinition <PsPolicyDefinition>]
[-PolicySetDefinition <PsPolicySetDefinition>]
[-Metadata <String>]
[-EnforcementMode <PolicyAssignmentEnforcementMode>]
[-AssignIdentity]
[-IdentityType <ManagedIdentityType>]
[-IdentityId <String>]
[-Location <String>]
[-NonComplianceMessage <PsNonComplianceMessage[]>]
[-ApiVersion <String>]
[-Pre]
[-DefaultProfile <IAzureContextContainer>]
[<CommonParameters>] New-AzPolicyAssignment
-Name <String>
[-Scope <String>]
[-NotScope <String[]>]
[-DisplayName <String>]
[-Description <String>]
-PolicyDefinition <PsPolicyDefinition>
[-PolicySetDefinition <PsPolicySetDefinition>]
-PolicyParameterObject <Hashtable>
[-Metadata <String>]
[-EnforcementMode <PolicyAssignmentEnforcementMode>]
[-AssignIdentity]
[-IdentityType <ManagedIdentityType>]
[-IdentityId <String>]
[-Location <String>]
[-NonComplianceMessage <PsNonComplianceMessage[]>]
[-ApiVersion <String>]
[-Pre]
[-DefaultProfile <IAzureContextContainer>]
[<CommonParameters>] New-AzPolicyAssignment
-Name <String>
[-Scope <String>]
[-NotScope <String[]>]
[-DisplayName <String>]
[-Description <String>]
-PolicyDefinition <PsPolicyDefinition>
[-PolicySetDefinition <PsPolicySetDefinition>]
-PolicyParameter <String>
[-Metadata <String>]
[-EnforcementMode <PolicyAssignmentEnforcementMode>]
[-AssignIdentity]
[-IdentityType <ManagedIdentityType>]
[-IdentityId <String>]
[-Location <String>]
[-NonComplianceMessage <PsNonComplianceMessage[]>]
[-ApiVersion <String>]
[-Pre]
[-DefaultProfile <IAzureContextContainer>]
[<CommonParameters>] New-AzPolicyAssignment
-Name <String>
[-Scope <String>]
[-NotScope <String[]>]
[-DisplayName <String>]
[-Description <String>]
[-PolicyDefinition <PsPolicyDefinition>]
-PolicySetDefinition <PsPolicySetDefinition>
-PolicyParameterObject <Hashtable>
[-Metadata <String>]
[-EnforcementMode <PolicyAssignmentEnforcementMode>]
[-AssignIdentity]
[-IdentityType <ManagedIdentityType>]
[-IdentityId <String>]
[-Location <String>]
[-NonComplianceMessage <PsNonComplianceMessage[]>]
[-ApiVersion <String>]
[-Pre]
[-DefaultProfile <IAzureContextContainer>]
[<CommonParameters>] New-AzPolicyAssignment
-Name <String>
[-Scope <String>]
[-NotScope <String[]>]
[-DisplayName <String>]
[-Description <String>]
[-PolicyDefinition <PsPolicyDefinition>]
-PolicySetDefinition <PsPolicySetDefinition>
-PolicyParameter <String>
[-Metadata <String>]
[-EnforcementMode <PolicyAssignmentEnforcementMode>]
[-AssignIdentity]
[-IdentityType <ManagedIdentityType>]
[-IdentityId <String>]
[-Location <String>]
[-NonComplianceMessage <PsNonComplianceMessage[]>]
[-ApiVersion <String>]
[-Pre]
[-DefaultProfile <IAzureContextContainer>]
[<CommonParameters>] Description
The New-AzPolicyAssignment cmdlet creates a policy assignment. Specify a policy and scope.
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 {$_.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 4: Policy assignment at resource group level with policy parameter file
Create a file called AllowedLocations.json in the local working directory with the following content.
<#{
"listOfAllowedLocations": {
"value": [
"westus",
"westeurope",
"japanwest"
]
}
}#>
$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 gets a resource group named ResourceGroup11 by using the Get-AzResourceGroup cmdlet and stores it in the $ResourceGroup variable. The second 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.
Parameters
-ApiVersion
Specifies the version of the resource provider API to use. If you do not specify a version, this cmdlet uses the latest available version.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-AssignIdentity
Generate and assign a system assigned managed identity for this policy assignment. The identity will be used when executing deployments for 'deployIfNotExists' and 'modify' policies. Location is required when assigning an identity.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-DefaultProfile
The credentials, account, tenant, and subscription used for communication with azure
| Type: | IAzureContextContainer |
| Aliases: | AzContext, AzureRmContext, AzureCredential |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Description
The description for policy assignment
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-DisplayName
Specifies a display name for the policy assignment.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-EnforcementMode
The enforcement mode for policy assignment. Currently, valid values are Default, DoNotEnforce.
| Type: | Nullable<T>[PolicyAssignmentEnforcementMode] |
| Accepted values: | Default, DoNotEnforce |
| Position: | Named |
| Default value: | Default |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-IdentityId
Specifies the Id of the user assigned managed identity to assign to this policy assignment. This value is required if the value 'UserAssigned' is passed to the -IdentityType parameter.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-IdentityType
Specifies the type of managed identity to assign to this policy assignment. If the 'SystemAssigned' value is provided, a system assigned managed identity is generated and assigned to this policy assignment. If the 'UserAssigned' value is provided, the user assigned identity passed via its Id to the -IdentityId parameter is assigned to this policy assignment. The identity will be used when executing deployments for 'deployIfNotExists' and 'modify' policies. Location is required when assigning an identity. Permissions must be granted to the identity using New-AzRoleAssignment after the system assigned identity is created. The IdentityType parameter will be given precedence if both the AssignIdentity and the IdentityType parameter are used.
| Type: | Nullable<T>[ManagedIdentityType] |
| Accepted values: | SystemAssigned, UserAssigned, None |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Location
The location of the policy assignment's resource identity. This is required when the -IdentityType value is provided.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Metadata
The metadata for the new policy assignment. This can either be a path to a file name containing the metadata, or the metadata as a string.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Name
Specifies a name for the policy assignment.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-NonComplianceMessage
The non-compliance messages that describe why a resource is non-compliant with the policy.
| Type: | PsNonComplianceMessage[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-NotScope
The not scopes for policy assignment.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-PolicyDefinition
Specifies a policy, as a PsPolicyDefinition object that contains the policy rule.
| Type: | PsPolicyDefinition |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-PolicyParameter
The policy parameter file path or policy parameter string.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-PolicyParameterObject
The policy parameter object.
| Type: | Hashtable |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PolicySetDefinition
The policy set definition object.
| Type: | PsPolicySetDefinition |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Pre
Indicates that this cmdlet considers pre-release API versions when it automatically determines which version to use.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Scope
Specifies the scope at which to assign the policy.
For instance, to assign a policy to a resource group, specify the following:
/subscriptions/subscription ID/resourcegroups/resource group name
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
Inputs
String[]
Nullable<T>[[Microsoft.Azure.Commands.ResourceManager.Cmdlets.Entities.Policy.PolicyAssignmentEnforcementMode, Microsoft.Azure.PowerShell.Cmdlets.ResourceManager, Version=3.5.0.0, Culture=neutral, PublicKeyToken=null]]
Outputs
Related Links
Azure PowerShell
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for