Skip to content

Commit 7473a13

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #232080 from kenieva/remediation-concept
Add new policy remediation structure page
2 parents a06f835 + b023f8e commit 7473a13

File tree

2 files changed

+127
-8
lines changed

2 files changed

+127
-8
lines changed

‎articles/governance/policy/concepts/remediation-structure.md

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
title: Details of the policy remediation task structure
3+
description: Describes the policy remediation task definition used by Azure Policy to bring resources into compliance.
4+
ms.date: 11/03/2022
5+
ms.topic: conceptual
6+
ms.author: kenieva
7+
author: kenieva
8+
---
9+
# Azure Policy remediation task structure
10+
11+
The Azure Policy remediation task feature is used to bring resources into compliance established from a definition and assignment. Resources that are non-compliant to a [modify](./effects.md#modify) or [deployIfNotExist](./effects.md#deployifnotexists) definition assignment, can be brought into compliance using a remediation task. Remediation task deploys the deployIFNotExist template or the modify operations to the selected non-compliant resources using the identity specified in the assignment. See [policy assignment structure](./assignment-structure.md#identity). to understand how the identity is define and [remediate non-compliant resources tutorial](../how-to/remediate-resources.md#configure-the-managed-identity) to configure the identity.
12+
13+
> [!NOTE]
14+
> Remediation tasks remediate exisiting resources that are not compliant. Resources that are newly created or updated that are applicable to a deployIfNotExist or modify definition assignment are automatically remediated.
15+
16+
You use JavaScript Object Notation (JSON) to create a policy remediation task. The policy remediation task contains elements for:
17+
18+
- [display name](#display-name-and-description)
19+
- [description](#display-name-and-description)
20+
- [policy assignment](#policy-assignment-id)
21+
- [policy definitions within an initiative](#policy-definition-id)
22+
- [resource count and parallel deployments](#resource-count-and-parallel-deployments)
23+
- [failure threshold](#failure-threshold)
24+
- [remediation filters](#remediation-filters)
25+
- [resource discovery mode](#resource-discovery-mode)
26+
- [provisioning state and deployment summary](#provisioning-state-and-deployment-summary)
27+
28+
29+
For example, the following JSON shows a policy remediation task for policy definition named `requiredTags` a part of
30+
an initiative assignment named `resourceShouldBeCompliantInit` with all default settings.
31+
32+
```json
33+
{
34+
"id": "/subscriptions/{subId}/resourceGroups/ExemptRG/providers/Microsoft.PolicyInsights/remediations/remediateNotCompliant",
35+
"apiVersion": "2021-10-01",
36+
"name": "remediateNotCompliant",
37+
"type": "Microsoft.PolicyInsights/remediations",
38+
"properties": {
39+
"policyAssignmentId": "/subscriptions/{mySubscriptionID}/providers/Microsoft.Authorization/policyAssignments/resourceShouldBeCompliantInit",
40+
"policyDefinitionReferenceIds": "requiredTags",
41+
"resourceCount": 42,
42+
"parallelDeployments": 6,
43+
"failureThreshold": {
44+
"percentage": 0.1
45+
}
46+
}
47+
}
48+
```
49+
Steps on how to trigger a remediation task at [how to remediate non-compliant resources guide](../how-to/remediate-resources.md)
50+
51+
> [!NOTE]
52+
> These settings cannot be changed once the remediation task has started.
53+
54+
55+
## Display name and description
56+
57+
You use **displayName** and **description** to identify the policy remediation task and provide context for
58+
its use. **displayName** has a maximum length of _128_ characters and
59+
**description** a maximum length of _512_ characters.
60+
61+
## Policy assignment ID
62+
63+
This field must be the full path name of either a policy assignment or an initiative assignment.
64+
`policyAssignmentId` is a string and not an array. This property defines which assignment the parent
65+
resource hierarchy or individual resource to remediate.
66+
67+
## Policy definition ID
68+
69+
If the `policyAssignmentId` is for an initiative assignment, the **policyDefinitionReferenceId** property must be used to specify which policy definition(s) in the initiative the subject resource(s) are to be remediated. As a remediation can only remediation in a scope of one definition,
70+
this property is a _string_. The value must match the value in the initiative definition in the
71+
`policyDefinitions.policyDefinitionReferenceId` field.
72+
73+
## Resource count and parallel deployments
74+
75+
Use **resource count** to determine how many non-compliant resources to remediate in a given remediation task. The default value is 500, with the maximum number being 50,000. **Parallel deployments** determines how many of those resources to remediate at the same time. The allowed range is between 1 to 30 with the default value being 10.
76+
77+
> [!NOTE]
78+
> Parallel deployments are the number of deployments within a singular remediation task with a maxmimum of 30. 100 remediation tasks can be ran simultaneously in the tenant.
79+
80+
## Failure threshold
81+
82+
An optional property used to specify whether the remediation task should fail if the percentage of failures exceeds the given threshold. The **failure threshold** is represented as a percentage number from 0 to 100. By default, the failure threshold is 100%, meaning that the remediation task will continue to remediate other resources even if resources fail to remediate.
83+
84+
## Remediation filters
85+
86+
An optional property refines what resources are applicable to the remediation task. The allowed filter is resource location. Unless specified, resources from any region can be remediated.
87+
88+
## Resource discovery mode
89+
90+
This property decides how to discover resources that are eligible for remediation. For a resource to be eligible, it must be non-compliant. By default, this property is set to `ExistingNonCompliant`. It could also be set to `ReEvaluateCompliance`, which will trigger a new compliance scan for that assignment and remediate any resources that are found non-compliant.
91+
92+
## Provisioning state and deployment summary
93+
94+
Once a remediation task is created, **provisioning state** and **deployment summary** properties are populated. **Provisioning state** indicates the status of the remediation task. Allow values are `Running`, `Canceled`, `Cancelling`, `Failed`, `Complete`, or `Succeeded`. **Deployment summary** is an array property indicating the number of deployments along with number of successful and failed deployments.
95+
96+
Sample of remediation task that completed successfully:
97+
98+
```json
99+
{
100+
"id": "/subscriptions/{subId}/resourceGroups/ExemptRG/providers/Microsoft.PolicyInsights/remediations/remediateNotCompliant",
101+
"Type": "Microsoft.PolicyInsights/remediations",
102+
"Name": "remediateNotCompliant",
103+
"PolicyAssignmentId": "/subscriptions/{mySubscriptionID}/providers/Microsoft.Authorization/policyAssignments/resourceShouldBeCompliantInit",
104+
"policyDefinitionReferenceIds": "requiredTags",
105+
"resourceCount": 42,
106+
"parallelDeployments": 6,
107+
"failureThreshold": {
108+
"percentage": 0.1
109+
},
110+
"ProvisioningState": "Succeeded",
111+
"DeploymentSummary": {
112+
"TotalDeployments": 42,
113+
"SuccessfulDeployments": 42,
114+
"FailedDeployments": 0
115+
},
116+
}
117+
```
118+
119+
## Next steps
120+
121+
- Understand how to [determine causes of non-compliance](../how-to/determine-non-compliance.md).
122+
- Learn how to [get compliance data](../how-to/get-compliance-data.md).
123+
- Learn how to [remediate non-compliant resources](../how-to/remediate-resources.md).
124+
- Understand how to [react to Azure Policy state change events](./event-overview.md).
125+
- Learn about the [policy definition structure](./definition-structure.md).
126+
- Learn about the [policy assignment structure](./assignment-structure.md).

‎articles/governance/policy/how-to/remediate-resources.md

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -315,14 +315,7 @@ This step is only applicable when using [Option 1](#option-1-create-a-remediatio
315315

316316
1. If the remediation task is initiated from an initiative assignment, select the policy to remediate from the drop-down. One **deployIfNotExists** or **modify** policy can be remediated through a single Remediation task at a time.
317317

318-
1. Optionally modify remediation settings on the **New remediation task** page:
319-
320-
- **Failure Threshold percentage** - Used to specify whether the remediation task should fail if the percentage of failures exceeds the given threshold. Provided as a number between 0 to 100. By default, the failure threshold is 100%.
321-
- **Resource Count** - Determines how many non-compliant resources to remediate in a given remediation task. The default value is 500 (the previous limit). The maximum number is 50,000 resources.
322-
- **Parallel Deployments** - Determines how many resources to remediate at the same time. The allowed values are 1 to 30 resources at a time. The default value is 10.
323-
324-
> [!NOTE]
325-
> These settings cannot be changed once the remediation task has started.
318+
1. Optionally modify remediation settings on the page. For information on what each setting controls, see [remediation task structure](../concepts/remediation-structure.md).
326319

327320
1. On the same page, filter the resources to remediate by using the **Scope**
328321
ellipses to pick child resources from where the policy is assigned (including down to the

0 commit comments

Comments
 (0)