Skip to content

Commit 773b70a

Browse files
authored
Clarify best practices for attestations
1 parent c3fd9e5 commit 773b70a

File tree

1 file changed

+12
-3
lines changed

1 file changed

+12
-3
lines changed

articles/governance/policy/concepts/attestation-structure.md

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,23 @@ author: timwarner-msft
1111
Attestations are used by Azure Policy to set compliance states of resources or scopes targeted by [manual policies](effects.md#manual-preview). They also allow users to provide additional metadata or link to evidence which accompanies the attested compliance state.
1212

1313
> [!NOTE]
14-
> In preview, Attestations are available only through the Azure Resource Manager (ARM) API.
14+
> In preview, Attestations are available only through the [Azure Resource Manager (ARM) API](rest/api/policy/attestations).
1515
16-
Below is an example of creating a new attestation resource which sets the compliance state for resources within a desired resource group:
16+
## Best practices
17+
18+
Attestations can be used to set the compliance state of an individual resource for a given manual policy. This means that each applicable resource requires one attestation per manual policy assignment. For ease of management, manual policies should be designed to target the scope which defines the boundary of resources whose compliance state needs to be attested.
19+
20+
For example, suppose an organization divides teams by resource group, and each team is required to attest to development of procedures for handling resources within that resource group. In this scenario, the conditions of the policy rule should specify that type equals `Microsoft.Resources/resourceGroups`. This way, one attestation is required for the resource group, rather than for each individual resource within. Similarly, if the organization deivides teams by subscriptions, the policy rule should target `Microsoft.Resources/subscriptions`.
21+
22+
Typically, the provided evidence should correspond with relevant scopes of the organizational structure. This pattern prevents the need to duplicate evidence across many attestations. Such duplications would make manual policies difficult to manage, and indicate that the policy definition targets the wrong resource(s).
23+
24+
## Example attestation
25+
26+
Below is an example of creating a new attestation resource which sets the compliance state for a resource group targeted by a manual policy assignment:
1727

1828
```http
1929
PUT http://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.PolicyInsights/attestations/{name}?api-version=2019-10-01
2030
```
21-
Attestations can be used to set the compliance state of an individual resource or a scope. A resource can have one attestation for an individual manual policy assignment.
2231

2332
## Request body
2433

0 commit comments

Comments
 (0)