Start-AzPolicyRemediation

Module:

Az.PolicyInsights Module

Creates and starts a policy remediation for a policy assignment.

Syntax

ByName (Default)

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

ByResourceId

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' and 'modify' 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.

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

-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 credentials, account, tenant, and subscription used for communication with Azure.

Parameter properties

Type:	IAzureContextContainer
Default value:	None
Supports wildcards:	False
DontShow:	False
Aliases:	AzContext, 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

-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.

Parameter properties

Type:	Nullable<T>[Double]
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

-LocationFilter

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

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

Management group ID.

Parameter properties

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

Parameter sets

ByName

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

-Name

Resource name.

Parameter properties

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

Parameter sets

ByName

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

Parameter properties

Type:	Nullable<T>[Int32]
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

-PolicyAssignmentId

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

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

-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.

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

-ResourceCount

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

Parameter properties

Type:	Nullable<T>[Int32]
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

-ResourceDiscoveryMode

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

Parameter properties

Type:	String
Default value:	None
Accepted values:	ExistingNonCompliant, ReEvaluateCompliance
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

-ResourceGroupName

Resource group name.

Parameter properties

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

Parameter sets

ByName

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

-ResourceId

Resource ID.

Parameter properties

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

Parameter sets

ByResourceId

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

-Scope

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

Parameter properties

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

Parameter sets

ByName

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

Nullable<T>

Nullable<T>

Outputs

PSRemediation