Edit

New-AzPolicyDefinition

Module:
Az.Resources Module

Creates or updates a policy definition.

Syntax

Name (Default) 

New-AzPolicyDefinition
    -Name 
    -Policy 
    [-DisplayName ]
    [-Description ]
    [-Metadata ]
    [-Parameter ]
    [-Mode ]
    [-Version ]
    [-ExternalEvaluationEnforcementSettingMissingTokenAction ]
    [-ExternalEvaluationEnforcementSettingResultLifespan ]
    [-ExternalEvaluationEnforcementSettingRoleDefinitionId ]
    [-EndpointSettingKind ]
    [-EndpointSettingDetail ]
    [-DefaultProfile ]
    [-WhatIf]
    [-Confirm]
    []

ManagementGroupName 

New-AzPolicyDefinition
    -Name 
    -ManagementGroupId 
    -Policy 
    [-DisplayName ]
    [-Description ]
    [-Metadata ]
    [-Parameter ]
    [-Mode ]
    [-Version ]
    [-ExternalEvaluationEnforcementSettingMissingTokenAction ]
    [-ExternalEvaluationEnforcementSettingResultLifespan ]
    [-ExternalEvaluationEnforcementSettingRoleDefinitionId ]
    [-EndpointSettingKind ]
    [-EndpointSettingDetail ]
    [-DefaultProfile ]
    [-WhatIf]
    [-Confirm]
    []

SubscriptionId 

New-AzPolicyDefinition
    -Name 
    -SubscriptionId 
    -Policy 
    [-DisplayName ]
    [-Description ]
    [-Metadata ]
    [-Parameter ]
    [-Mode ]
    [-Version ]
    [-ExternalEvaluationEnforcementSettingMissingTokenAction ]
    [-ExternalEvaluationEnforcementSettingResultLifespan ]
    [-ExternalEvaluationEnforcementSettingRoleDefinitionId ]
    [-EndpointSettingKind ]
    [-EndpointSettingDetail ]
    [-DefaultProfile ]
    [-WhatIf]
    [-Confirm]
    []

Description

The New-AzPolicyDefinition cmdlet creates or updates a policy definition that includes a policy rule JSON format.

Examples

Example 1: Create a policy definition by using a policy file

{
   "if": {
      "field": "location",
      "notIn": ["eastus", "westus", "centralus"]
   },
   "then": {
      "effect": "audit"
   }
}

New-AzPolicyDefinition -Name 'LocationDefinition' -Policy C:\LocationPolicy.json

This command creates a policy definition named LocationDefinition that contains the policy rule specified in C:\LocationPolicy.json. Example content for the LocationPolicy.json file is provided above. Three file content formats are supported: 1. Policy rule only (example above). 2. Policy properties object. This format is displayed in the portal when editing a policy definition and may include parameters. 3. Full policy object. This format is generated by the Azure Policy export function and may include parameters.

Note: Values provided on the command line (e.g. parameters, metadata) override corresponding values present in the file.

Example 2: Create a parameterized policy definition using inline parameters

{
   "if": {
      "field": "location",
      "notIn": "[parameters('listOfAllowedLocations')]"
   },
   "then": {
      "effect": "audit"
   }
}
New-AzPolicyDefinition -Name 'LocationDefinition' -Policy C:\LocationPolicy.json -Parameter '{ "listOfAllowedLocations": { "type": "array" } }'

This command creates a policy definition named LocationDefinition that contains the policy rule specified in C:\LocationPolicy.json. The parameter definition for the policy rule is provided inline.

Example 3: Create a policy definition inline in a management group

New-AzPolicyDefinition -Name 'VMPolicyDefinition' -ManagementGroupName Dept42 -DisplayName 'Virtual Machine policy definition' -Policy '{"if":{"field":"type","equals":"Microsoft.Compute/virtualMachines"},"then":{"effect":"deny"}}'

This command creates a policy definition named VMPolicyDefinition in management group Dept42. The command specifies the policy as a string in valid JSON format.

Example 4: Create a policy definition inline with metadata

New-AzPolicyDefinition -Name 'VMPolicyDefinition' -Metadata '{"category":"Virtual Machine"}' -Policy '{"if":{"field":"type","equals":"Microsoft.Compute/virtualMachines"},"then":{"effect":"deny"}}' | Format-List

This command creates a policy definition named VMPolicyDefinition with metadata indicating its category is "Virtual Machine". The command specifies the policy as a string in valid JSON format.

Example 5: Create a policy definition inline with mode

New-AzPolicyDefinition -Name 'TagsPolicyDefinition' -Policy '{"if":{"value":"[less(length(field(''tags'')), 3)]","equals":true},"then":{"effect":"deny"}}' -Mode Indexed

This command creates a policy definition named TagsPolicyDefinition with mode "Indexed" indicating the policy should be evaluated only for resource types that support tags and location.

Example 6: Create a policy definition inline with version

New-AzPolicyDefinition -Name 'VMPolicyDefinition' -Policy '{"if":{"field":"type","equals":"Microsoft.Compute/virtualMachines"},"then":{"effect":"deny"}}' -Version '2.0.0'

This command creates a policy definition named VMPolicyDefinition with incremented version 2.0.0. The command specifies the policy as a string in valid JSON format.

Example 7: Create a policy definition with external evaluation enforcement settings

New-AzPolicyDefinition -Name 'InvokePolicy' -Policy '{"if":{"value":"[claims().isValid]","equals":false},"then":{"effect":"deny"}}' -EndpointSettingKind 'CoinFlip' -ExternalEvaluationEnforcementSettingRoleDefinitionId @( "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c" )

This command creates a policy definition named InvokePolicy with external evaluation enforcement settings to call the CoinFlip endpoint, which requires the specified role definition.

Parameters

-Confirm

Prompts you for confirmation before running the cmdlet.

Parameter properties

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

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 DefaultProfile parameter is not functional. Use the SubscriptionId parameter when available if executing the cmdlet against a different subscription.

Parameter properties

Type:PSObject
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 policy definition description.

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

The display name of the policy definition.

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

-EndpointSettingDetail

The details of the endpoint.

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

-EndpointSettingKind

The kind of the endpoint.

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

-ExternalEvaluationEnforcementSettingMissingTokenAction

What to do when evaluating an enforcement policy that requires an external evaluation and the token is missing. Possible values are Audit and Deny and language expressions are supported.

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

-ExternalEvaluationEnforcementSettingResultLifespan

The lifespan of the endpoint invocation result after which it's no longer valid.

Value is expected to follow the ISO 8601 duration format and language expressions are supported.

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

-ExternalEvaluationEnforcementSettingRoleDefinitionId

An array of the role definition Ids the assignment's MSI will need in order to invoke the endpoint.

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

-ManagementGroupId

The ID of the management group.

Parameter properties

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

Parameter sets

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

-Metadata

The policy definition metadata. Metadata is an open ended object and is typically a collection of key value pairs.

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

-Mode

The policy definition mode. Some examples are All, Indexed, Microsoft.KeyVault.Data.

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

The name of the policy definition to create.

Parameter properties

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

Parameter sets

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

-Parameter

The parameter definitions for parameters used in the policy rule. The keys are the parameter names.

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

-Policy

The policy rule.

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

-SubscriptionId

The ID of the target subscription.

Parameter properties

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

Parameter sets

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

-Version

The policy definition version in #.#.# format.

Parameter properties

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

Parameter sets

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

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Parameter properties

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

Parameter sets

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

Inputs

String

String

Outputs

IPolicyDefinition