New-AzPolicyDefinition
Creates or updates a policy definition.
Syntax
Name (Default)
New-AzPolicyDefinition
-Name <String>
-Policy <String>
[-DisplayName <String>]
[-Description <String>]
[-Metadata <String>]
[-Parameter <String>]
[-Mode <String>]
[-Version <String>]
[-ExternalEvaluationEnforcementSettingMissingTokenAction <String>]
[-ExternalEvaluationEnforcementSettingResultLifespan <String>]
[-ExternalEvaluationEnforcementSettingRoleDefinitionId <String[]>]
[-EndpointSettingKind <String>]
[-EndpointSettingDetail <String>]
[-DefaultProfile <PSObject>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
ManagementGroupName
New-AzPolicyDefinition
-Name <String>
-ManagementGroupName <String>
-Policy <String>
[-DisplayName <String>]
[-Description <String>]
[-Metadata <String>]
[-Parameter <String>]
[-Mode <String>]
[-Version <String>]
[-ExternalEvaluationEnforcementSettingMissingTokenAction <String>]
[-ExternalEvaluationEnforcementSettingResultLifespan <String>]
[-ExternalEvaluationEnforcementSettingRoleDefinitionId <String[]>]
[-EndpointSettingKind <String>]
[-EndpointSettingDetail <String>]
[-DefaultProfile <PSObject>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
SubscriptionId
New-AzPolicyDefinition
-Name <String>
-SubscriptionId <String>
-Policy <String>
[-DisplayName <String>]
[-Description <String>]
[-Metadata <String>]
[-Parameter <String>]
[-Mode <String>]
[-Version <String>]
[-ExternalEvaluationEnforcementSettingMissingTokenAction <String>]
[-ExternalEvaluationEnforcementSettingResultLifespan <String>]
[-ExternalEvaluationEnforcementSettingRoleDefinitionId <String[]>]
[-EndpointSettingKind <String>]
[-EndpointSettingDetail <String>]
[-DefaultProfile <PSObject>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
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.
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
-ManagementGroupName
The ID of the management group.
Parameter properties
Type: String
Default value: None Supports wildcards: False DontShow: False
Parameter sets
ManagementGroupName
Position: Named Mandatory: True Value from pipeline: False Value from pipeline by property name: True Value from remaining arguments: False
The policy definition metadata.
Metadata is an open ended object and is typically a collection of key value pairs.
Type: String
Default value: None Supports wildcards: False DontShow: False
(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 .
Outputs
