Share via

New-AzureRmPolicyAssignment

Module:
AzureRM.Resources Module

Creates a policy assignment.

Warning

The AzureRM PowerShell module has been officially deprecated as of February 29, 2024. Users are advised to migrate from AzureRM to the Az PowerShell module to ensure continued support and updates.

Although the AzureRM module may still function, it's no longer maintained or supported, placing any continued use at the user's discretion and risk. Please refer to our migration resources for guidance on transitioning to the Az module.

Syntax

DefaultParameterSet (Default) 

New-AzureRmPolicyAssignment
    -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-AzureRmPolicyAssignment
    -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-AzureRmPolicyAssignment
    -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-AzureRmPolicyAssignment
    -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-AzureRmPolicyAssignment
    -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-AzureRmPolicyAssignment cmdlet creates a policy assignment. Specify a policy and scope.

Examples

Example 1: Policy assignment at resource group level

PS C:\> $ResourceGroup = Get-AzureRmResourceGroup -Name 'ResourceGroup11'
PS C:\> $Policy = Get-AzureRmPolicyDefinition -Name 'VirtualMachinePolicy'
PS C:\> New-AzureRmPolicyAssignment -Name 'VirtualMachinePolicyAssignment' -PolicyDefinition $Policy -Scope $ResourceGroup.ResourceId

The first command gets a resource group named ResourceGroup11 by using the Get-AzureRMResourceGroup cmdlet and stores it in the $ResourceGroup variable. The second command gets the policy definition named VirtualMachinePolicy by using the Get-AzureRmPolicyDefinition 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-AzureRmResourceGroup -Name 'ResourceGroup11'
PS C:\> $Policy = Get-AzureRmPolicyDefinition -BuiltIn | Where-Object {$_.Properties.DisplayName -eq 'Allowed locations'}
PS C:\> $Locations = Get-AzureRmLocation | where displayname -like '*east*'
PS C:\> $AllowedLocations = @{'listOfAllowedLocations'=($Locations.location)}
PS C:\> New-AzureRmPolicyAssignment -Name 'RestrictLocationPolicyAssignment' -PolicyDefinition $Policy -Scope $ResourceGroup.ResourceId -PolicyParameterObject $AllowedLocations

The first command gets a resource group named ResourceGroup11 by using the Get-AzureRMResourceGroup 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-AzureRmPolicyDefinition 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-AzureRmResourceGroup -Name 'ResourceGroup11'
PS C:\> $Policy = Get-AzureRmPolicyDefinition -BuiltIn | Where-Object {$_.Properties.DisplayName -eq 'Allowed locations'}
PS C:\> New-AzureRmPolicyAssignment -Name 'RestrictLocationPolicyAssignment' -PolicyDefinition $Policy -Scope $ResourceGroup.ResourceId -PolicyParameter .\AllowedLocations.json

The first command gets a resource group named ResourceGroup11 by using the Get-AzureRMResourceGroup cmdlet and stores it in the $ResourceGroup variable. The second command gets the built-in policy definition for allowed locations by using the Get-AzureRmPolicyDefinition 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-AzureRmResourceGroup -Name 'ResourceGroup11'
PS C:\> $Policy = Get-AzureRmPolicyDefinition -Name 'VirtualMachinePolicy'
PS C:\> New-AzureRmPolicyAssignment -Name 'VirtualMachinePolicyAssignment' -PolicyDefinition $Policy -Scope $ResourceGroup.ResourceId -Location 'eastus' -AssignIdentity

The first command gets a resource group named ResourceGroup11 by using the Get-AzureRMResourceGroup cmdlet and stores it in the $ResourceGroup variable. The second command gets the policy definition named VirtualMachinePolicy by using the Get-AzureRmPolicyDefinition 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:AzureRmContext, 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.