New-AzPolicyAssignment

Is this page helpful?

Any additional feedback?

Feedback will be sent to Microsoft: By pressing the submit button, your feedback will be used to improve Microsoft products and services. Privacy policy.

Module:

Az.Resources

Creates a policy assignment.

Note

This is the previous version of our documentation. Please consult the most recent version for up-to-date information.

Syntax

New-AzPolicyAssignment
   -Name <String>
   [-Scope <String>]
   [-NotScope <String[]>]
   [-DisplayName <String>]
   [-Description <String>]
   [-PolicyDefinition <PsPolicyDefinition>]
   [-PolicySetDefinition <PsPolicySetDefinition>]
   [-Metadata <String>]
   [-EnforcementMode <PolicyAssignmentEnforcementMode>]
   [-AssignIdentity]
   [-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]
   [-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]
   [-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]
   [-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]
   [-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

PS C:\> $Subscription = Get-AzSubscription -SubscriptionName 'Subscription01'
PS C:\> $Policy = Get-AzPolicyDefinition -Name 'VirtualMachinePolicy'
PS C:\> 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

PS C:\> $ResourceGroup = Get-AzResourceGroup -Name 'ResourceGroup11'
PS C:\> $Policy = Get-AzPolicyDefinition -Name 'VirtualMachinePolicy'
PS C:\> New-AzPolicyAssignment -Name 'VirtualMachinePolicyAssignment' -PolicyDefinition $Policy -Scope $ResourceGroup.ResourceId

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

PS C:\> $ResourceGroup = Get-AzResourceGroup -Name 'ResourceGroup11'
PS C:\> $Policy = Get-AzPolicyDefinition -BuiltIn | Where-Object {$_.Properties.DisplayName -eq 'Allowed locations'}
PS C:\> $Locations = Get-AzLocation | where displayname -like '*east*'
PS C:\> $AllowedLocations = @{'listOfAllowedLocations'=($Locations.location)}
PS C:\> New-AzPolicyAssignment -Name 'RestrictLocationPolicyAssignment' -PolicyDefinition $Policy -Scope $ResourceGroup.ResourceId -PolicyParameterObject $AllowedLocations

The 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"
      ]
    }
}

PS C:\> $ResourceGroup = Get-AzResourceGroup -Name 'ResourceGroup11'
PS C:\> $Policy = Get-AzPolicyDefinition -BuiltIn | Where-Object {$_.Properties.DisplayName -eq 'Allowed locations'}
PS C:\> New-AzPolicyAssignment -Name 'RestrictLocationPolicyAssignment' -PolicyDefinition $Policy -Scope $ResourceGroup.ResourceId -PolicyParameter .\AllowedLocations.json

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 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 managed identity

PS C:\> $ResourceGroup = Get-AzResourceGroup -Name 'ResourceGroup11'
PS C:\> $Policy = Get-AzPolicyDefinition -Name 'VirtualMachinePolicy'
PS C:\> New-AzPolicyAssignment -Name 'VirtualMachinePolicyAssignment' -PolicyDefinition $Policy -Scope $ResourceGroup.ResourceId -Location 'eastus' -AssignIdentity

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 managed identity is automatically created and assigned to the policy assignment.

Example 6: Policy assignment with an enforcement mode property

PS C:\> $Subscription = Get-AzSubscription -SubscriptionName 'Subscription01'
PS C:\> $Policy = Get-AzPolicyDefinition -Name 'VirtualMachinePolicy'
PS C:\> New-AzPolicyAssignment -Name 'VirtualMachinePolicyAssignment' -PolicyDefinition $Policy -Scope "/subscriptions/$($Subscription.Id)" -EnforcementMode DoNotEnforce

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. The assignment is set with an EnforcementMode value of DoNotEnforce i.e. the policy effect is not enforced during resource creation or update.

Example 7: Policy assignment with non-compliance messages

PS C:\> $PolicySet = Get-AzPolicySetDefinition -Name 'VirtualMachinePolicySet'
PS C:\> $NonComplianceMessages = @(@{Message="Only DsV2 SKUs are allowed."; PolicyDefinitionReferenceId="DefRef1"}, @{Message="Virtual machines must follow cost management best practices."})
PS C:\> New-AzPolicyAssignment -Name 'VirtualMachinePolicyAssignment' -PolicySetDefinition $PolicySet -NonComplianceMessage $NonComplianceMessages

The 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
Accept pipeline input:	False
Accept wildcard characters:	False

-AssignIdentity

Generate and assign an Azure Active Directory 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. Permissions must be granted to the identity using New-AzRoleAssignment after the identity is created.

Type:	SwitchParameter
Position:	Named
Default value:	None
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
Accept pipeline input:	False
Accept wildcard characters:	False

-Description

The description for policy assignment

Type:	String
Position:	Named
Default value:	None
Accept pipeline input:	True
Accept wildcard characters:	False

-DisplayName

Specifies a display name for the policy assignment.

Type:	String
Position:	Named
Default value:	None
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
Accept pipeline input:	True
Accept wildcard characters:	False

-Location

The location of the policy assignment's resource identity. This is required when the -AssignIdentity switch is used.

Type:	String
Position:	Named
Default value:	None
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
Accept pipeline input:	True
Accept wildcard characters:	False

-Name

Specifies a name for the policy assignment.

Type:	String
Position:	Named
Default value:	None
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
Accept pipeline input:	True
Accept wildcard characters:	False

-NotScope

The not scopes for policy assignment.

Type:	String[]
Position:	Named
Default value:	None
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
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
Accept pipeline input:	True
Accept wildcard characters:	False

-PolicyParameterObject

The policy parameter object.

Type:	Hashtable
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-PolicySetDefinition

The policy set definition object.

Type:	PsPolicySetDefinition
Position:	Named
Default value:	None
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
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
Accept pipeline input:	True
Accept wildcard characters:	False

Inputs

String

String[]

PsPolicyDefinition

PsPolicySetDefinition

Nullable<T>[[Microsoft.Azure.Commands.ResourceManager.Cmdlets.Entities.Policy.PolicyAssignmentEnforcementMode, Microsoft.Azure.PowerShell.Cmdlets.ResourceManager, Version=3.5.0.0, Culture=neutral, PublicKeyToken=null]]

PsNonComplianceMessage[]

Outputs

PsPolicyAssignment

Related Links

• Get-AzPolicyDefinition
• Get-AzPolicyAssignment
• Remove-AzPolicyAssignment
• Set-AzPolicyAssignment