Start-AzPolicyRemediation

Reference

Module:: Az.PolicyInsights

Creates and starts a policy remediation for a policy assignment.

Syntax

Start-AzPolicyRemediation
     -Name <String>
     [-Scope <String>]
     [-ManagementGroupName <String>]
     [-ResourceGroupName <String>]
     -PolicyAssignmentId <String>
     [-PolicyDefinitionReferenceId <String>]
     [-LocationFilter <String[]>]
     [-ResourceDiscoveryMode <String>]
     [-ResourceCount <Int32>]
     [-ParallelDeploymentCount <Int32>]
     [-FailureThreshold <Double>]
     [-AsJob]
     [-DefaultProfile <IAzureContextContainer>]
     [-WhatIf]
     [-Confirm]
     [<CommonParameters>]

Start-AzPolicyRemediation
     -ResourceId <String>
     -PolicyAssignmentId <String>
     [-PolicyDefinitionReferenceId <String>]
     [-LocationFilter <String[]>]
     [-ResourceDiscoveryMode <String>]
     [-ResourceCount <Int32>]
     [-ParallelDeploymentCount <Int32>]
     [-FailureThreshold <Double>]
     [-AsJob]
     [-DefaultProfile <IAzureContextContainer>]
     [-WhatIf]
     [-Confirm]
     [<CommonParameters>]

Description

The Start-AzPolicyRemediation cmdlet creates a policy remediation for a particular policy assignment. All non-compliant resources at or below the remediation's scope will be remediated. Remediation is only supported for policies with the 'deployIfNotExists' effect.

Examples

Example 1: Start a remediation at subscription scope

$policyAssignmentId = "/subscriptions/f0710c27-9663-4c05-19f8-1b4be01e86a5/providers/Microsoft.Authorization/policyAssignments/2deae24764b447c29af7c309"
Set-AzContext -Subscription "My Subscription"
Start-AzPolicyRemediation -PolicyAssignmentId $policyAssignmentId -Name "remediation1"

This command creates a new policy remediation in subscription 'My Subscription' for the given policy assignment.

Example 2: Start a remediation at management group scope with optional filters

$policyAssignmentId = "/providers/Microsoft.Management/managementGroups/mg1/providers/Microsoft.Authorization/policyAssignments/pa1"
Start-AzPolicyRemediation -ManagementGroupName "mg1" -PolicyAssignmentId $policyAssignmentId -Name "remediation1" -LocationFilter "westus","eastus"

This command creates a new policy remediation in management group 'mg1' for the given policy assignment. Only resources in the 'westus' or 'eastus' locations will be remediated.

Example 3: Start a remediation at resource group scope for a policy set definition assignment

$policyAssignmentId = "/subscriptions/f0710c27-9663-4c05-19f8-1b4be01e86a5/resourceGroups/myRG/providers/Microsoft.Authorization/policyAssignments/2deae24764b447c29af7c309"
Start-AzPolicyRemediation -ResourceGroupName "myRG" -PolicyAssignmentId $policyAssignmentId -PolicyDefinitionReferenceId "0349234412441" -Name "remediation1"

This command creates a new policy remediation in resource group 'myRG' for the given policy assignment. The policy assignment assigns a policy set definition (also known as an initiative). The policy definition reference ID indicates which policy within the initiative should be remediated.

Example 4: Start a remediation and wait for it to complete in the background

$policyAssignmentId = "/subscriptions/f0710c27-9663-4c05-19f8-1b4be01e86a5/providers/Microsoft.Authorization/policyAssignments/2deae24764b447c29af7c309"
Set-AzContext -Subscription f0710c27-9663-4c05-19f8-1b4be01e86a5
$job = Start-AzPolicyRemediation -PolicyAssignmentId $policyAssignmentId -Name "remediation1" -AsJob
$job | Wait-Job
$remediation = $job | Receive-Job

This command starts a new policy remediation in subscription 'My Subscription' for the given policy assignment. It will wait for the remediation to complete before returning the final remediation status.

Example 5: Start a remediation that will discover non-compliant resources before remediating

$policyAssignmentId = "/subscriptions/f0710c27-9663-4c05-19f8-1b4be01e86a5/providers/Microsoft.Authorization/policyAssignments/2deae24764b447c29af7c309"
Set-AzContext -Subscription "My Subscription"
Start-AzPolicyRemediation -PolicyAssignmentId $policyAssignmentId -Name "remediation1" -ResourceDiscoveryMode ReEvaluateCompliance

This command creates a new policy remediation in subscription 'My Subscription' for the given policy assignment. The compliance state of resources in the subscription will be re-evaluated against the policy assignment and non-compliant resources will be remediated.

Example 6: Start a remediation that will remediate up to 10,000 non-compliant resources

$policyAssignmentId = "/subscriptions/f0710c27-9663-4c05-19f8-1b4be01e86a5/providers/Microsoft.Authorization/policyAssignments/2deae24764b447c29af7c309"
Set-AzContext -Subscription "My Subscription"
Start-AzPolicyRemediation -PolicyAssignmentId $policyAssignmentId -Name "remediation1" -ResourceCount 10000

Example 7: Start a remediation that will remediate 30 resources in parallel

$policyAssignmentId = "/subscriptions/f0710c27-9663-4c05-19f8-1b4be01e86a5/providers/Microsoft.Authorization/policyAssignments/2deae24764b447c29af7c309"
Set-AzContext -Subscription "My Subscription"
Start-AzPolicyRemediation -PolicyAssignmentId $policyAssignmentId -Name "remediation1" -ParallelDeploymentCount 30

Example 8: Start a remediation that will terminate if more than half of the remediation deployments fail

$policyAssignmentId = "/subscriptions/f0710c27-9663-4c05-19f8-1b4be01e86a5/providers/Microsoft.Authorization/policyAssignments/2deae24764b447c29af7c309"
Set-AzContext -Subscription "My Subscription"
Start-AzPolicyRemediation -PolicyAssignmentId $policyAssignmentId -Name "remediation1" -FailureThreshold 0.5

Parameters

-AsJob

Run cmdlet in the background.

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

-Confirm

Prompts you for confirmation before running the cmdlet.

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

-FailureThreshold

Number between 0.0 to 1.0 representing the percentage failure threshold. The remediation will fail if the percentage of failed remediation operations (i.e. failed deployments) exceeds this threshold.

Type:	Nullable<T>[Double]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-LocationFilter

The resource locations that should be included in the remediation. Resources that don't reside in these locations will not be remediated.

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

-ManagementGroupName

Management group ID.

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

-Name

Resource name.

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

-ParallelDeploymentCount

How many resources to remediate at any given time. Can be used to control the pace of the remediation. If not provided, the default parallel deployments value is used.

Type:	Nullable<T>[Int32]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-PolicyAssignmentId

Policy assignment ID. E.g. '/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/policyAssignments/{assignmentName}'.

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

-PolicyDefinitionReferenceId

Gets the policy definition reference ID of the individual definition that is being remediated. Required when the policy assignment assigns a policy set definition.

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

-ResourceCount

Maximum number of non-compliant resources that will be remediated. If not provided, the default resource count is used.

Type:	Nullable<T>[Int32]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-ResourceDiscoveryMode

Describes how the remediation task will discover resources that need to be remediated. ReEvaluateCompliance is not supported when remediating management group scopes.

Type:	String
Accepted values:	ExistingNonCompliant, ReEvaluateCompliance
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-ResourceGroupName

Resource group name.

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

-ResourceId

Resource ID.

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

-Scope

Scope of the resource. E.g. '/subscriptions/{subscriptionId}/resourceGroups/{rgName}'.

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

-WhatIf

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

Type:	SwitchParameter
Aliases:	wi
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Inputs

String

String[]

Nullable<T>[[System.Int32, System.Private.CoreLib, Version=7.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e]]

Nullable<T>[[System.Double, System.Private.CoreLib, Version=7.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e]]

Outputs

PSRemediation

Share via