Edit

New-AzPolicyAssignment

Module:
Az.Resources Module

Creates a policy assignment.

Syntax

DefaultParameterSet (Default) 

New-AzPolicyAssignment
    -Name <String>
    -Scope <String>
    [-NotScope <String[]>]
    [-DisplayName <String>]
    [-Description <String>]
    [-PolicyDefinition <PSObject>]
    [-PolicySetDefinition <PSObject>]
    [-Metadata <String>]
    [-Sku <Hashtable>]
    [-AssignIdentity]
    [-Location <String>]
    [-ApiVersion <String>]
    [-Pre]
    [-DefaultProfile <IAzureContextContainer>]
    [-InformationAction <ActionPreference>]
    [-InformationVariable <String>]
    [<CommonParameters>]

PolicyParameterObjectParameterSet 

New-AzPolicyAssignment
    -Name <String>
    -Scope <String>
    -PolicyDefinition <PSObject>
    -PolicyParameterObject <Hashtable>
    [-NotScope <String[]>]
    [-DisplayName <String>]
    [-Description <String>]
    [-PolicySetDefinition <PSObject>]
    [-Metadata <String>]
    [-Sku <Hashtable>]
    [-AssignIdentity]
    [-Location <String>]
    [-ApiVersion <String>]
    [-Pre]
    [-DefaultProfile <IAzureContextContainer>]
    [-InformationAction <ActionPreference>]
    [-InformationVariable <String>]
    [<CommonParameters>]

PolicyParameterStringParameterSet 

New-AzPolicyAssignment
    -Name <String>
    -Scope <String>
    -PolicyDefinition <PSObject>
    -PolicyParameter <String>
    [-NotScope <String[]>]
    [-DisplayName <String>]
    [-Description <String>]
    [-PolicySetDefinition <PSObject>]
    [-Metadata <String>]
    [-Sku <Hashtable>]
    [-AssignIdentity]
    [-Location <String>]
    [-ApiVersion <String>]
    [-Pre]
    [-DefaultProfile <IAzureContextContainer>]
    [-InformationAction <ActionPreference>]
    [-InformationVariable <String>]
    [<CommonParameters>]

PolicySetParameterObjectParameterSet 

New-AzPolicyAssignment
    -Name <String>
    -Scope <String>
    -PolicySetDefinition <PSObject>
    -PolicyParameterObject <Hashtable>
    [-NotScope <String[]>]
    [-DisplayName <String>]
    [-Description <String>]
    [-PolicyDefinition <PSObject>]
    [-Metadata <String>]
    [-Sku <Hashtable>]
    [-AssignIdentity]
    [-Location <String>]
    [-ApiVersion <String>]
    [-Pre]
    [-DefaultProfile <IAzureContextContainer>]
    [-InformationAction <ActionPreference>]
    [-InformationVariable <String>]
    [<CommonParameters>]

PolicySetParameterStringParameterSet 

New-AzPolicyAssignment
    -Name <String>
    -Scope <String>
    -PolicySetDefinition <PSObject>
    -PolicyParameter <String>
    [-NotScope <String[]>]
    [-DisplayName <String>]
    [-Description <String>]
    [-PolicyDefinition <PSObject>]
    [-Metadata <String>]
    [-Sku <Hashtable>]
    [-AssignIdentity]
    [-Location <String>]
    [-ApiVersion <String>]
    [-Pre]
    [-DefaultProfile <IAzureContextContainer>]
    [-InformationAction <ActionPreference>]
    [-InformationVariable <String>]
    [<CommonParameters>]

Description

The New-AzPolicyAssignment cmdlet creates a policy assignment. Specify a policy and scope.

Examples

Example 1: 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 2: 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 3: 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 4: 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.

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.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-AssignIdentity

Generate and assign a Microsoft Entra identity for this policy assignment. The identity will be used when executing deployments for 'deployIfNotExists' policies. Location is required when assigning an identity.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-DefaultProfile

The credentials, account, tenant, and subscription used for communication with azure

Parameter properties

Type:IAzureContextContainer
Default value:None
Supports wildcards:False
DontShow:False
Aliases:AzContext, AzureCredential

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Description

The description for policy assignment

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-DisplayName

Specifies a display name for the policy assignment.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-InformationAction

Specifies how this cmdlet responds to an information event. The acceptable values for this parameter are:

  • Continue
  • Ignore
  • Inquire
  • SilentlyContinue
  • Stop
  • Suspend

Parameter properties

Type:ActionPreference
Default value:None
Supports wildcards:False
DontShow:False
Aliases:infa

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-InformationVariable

Specifies an information variable.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False
Aliases:iv

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Location

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

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments: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.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-Name

Specifies a name for the policy assignment.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-NotScope

The not scopes for policy assignment.

Parameter properties

Type:

String[]

Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-PolicyDefinition

Specifies a policy, as a PsPolicyDefinition object that contains the policy rule.

Parameter properties

Type:PSObject
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

DefaultParameterSet
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-PolicyParameter

The policy parameter file path or policy parameter string.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

PolicyParameterStringParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
PolicySetParameterStringParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-PolicyParameterObject

The policy parameter object.

Parameter properties

Type:Hashtable
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

PolicyParameterObjectParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
PolicySetParameterObjectParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-PolicySetDefinition

The policy set definition object.

Parameter properties

Type:PSObject
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

DefaultParameterSet
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-Pre

Indicates that this cmdlet considers pre-release API versions when it automatically determines which version to use.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments: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

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-Sku

A hash table which represents SKU properties. Defaults to the Free SKU with the values: @{Name = 'A0'; Tier = 'Free'}. To use the Standard SKU, use the values: @{Name = 'A1'; Tier = 'Standard'}.

Parameter properties

Type:Hashtable
Default value:None
Supports wildcards:False
DontShow:False
Aliases:SkuObject

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.