Merge pull request #279841 from davidsmatlak/ds-update-policy-doc-20240701

Stacyrch140 · web-flow · commit 609cffd260b7 · 2024-07-01T22:21:04.000-04:00
Azure Policy freshness updates
diff --git a/articles/governance/policy/concepts/attestation-structure.md b/articles/governance/policy/concepts/attestation-structure.md
@@ -1,77 +1,78 @@
 ---
 title: Details of the Azure Policy attestation structure
 description: Describes the components of the Azure Policy attestation JSON object.
-ms.date: 09/23/2022
+ms.date: 07/01/2024
 ms.topic: conceptual
 ---
+
 # Azure Policy attestation structure
 
-Attestations are used by Azure Policy to set compliance states of resources or scopes targeted by [manual policies](effects.md#manual). They also allow users to provide additional metadata or link to evidence which accompanies the attested compliance state.  
+Attestations are used by Azure Policy to set compliance states of resources or scopes targeted by [manual policies](effect-manual.md). They also allow users to provide more metadata or link to evidence that accompanies the attested compliance state.
 
 > [!NOTE]
-> Attestations can be created and managed only through Azure Policy [Azure Resource Manager (ARM) API](/rest/api/policy/attestations), [PowerShell](/powershell/module/az.policyinsights) or [Azure CLI](/cli/azure/policy/attestation). 
+> Attestations can be created and managed only through Azure Policy [Azure Resource Manager (ARM) API](/rest/api/policy/attestations), [PowerShell](/powershell/module/az.policyinsights) or [Azure CLI](/cli/azure/policy/attestation).
 
 ## Best practices
 
-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. 
+Attestations can be used to set the compliance state of an individual resource for a given manual policy. Each applicable resource requires one attestation per manual policy assignment. For ease of management, manual policies should be designed to target the scope that defines the boundary of resources whose compliance state needs to be attested.
 
-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 divides teams by subscriptions, the policy rule should target `Microsoft.Resources/subscriptions`.  
+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 divides teams by subscriptions, the policy rule should target `Microsoft.Resources/subscriptions`.
 
-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).
+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 resources.
 
 ## Example attestation
 
-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:
+The following example creates a new attestation resource that sets the compliance state for a resource group targeted by a manual policy assignment:
 
 ```http
 PUT http://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.PolicyInsights/attestations/{name}?api-version=2019-10-01
 ```
 
 ## Request body
 
-Below is a sample attestation resource JSON object:
+The following code is a sample attestation resource JSON object:
 
 ```json
 "properties": {
-    "policyAssignmentId": "/subscriptions/{subscriptionID}/providers/microsoft.authorization/policyassignments/{assignmentID}",
-    "policyDefinitionReferenceId": "{definitionReferenceID}",
-    "complianceState": "Compliant",
-    "expiresOn": "2023-07-14T00:00:00Z",
-    "owner": "{AADObjectID}",
-    "comments": "This subscription has passed a security audit. See attached details for evidence",
-    "evidence": [
-        {
-          "description": "The results of the security audit.",
-          "sourceUri": "https://gist.github.com/contoso/9573e238762c60166c090ae16b814011"
-        },
-        {
-          "description": "Description of the attached evidence document.",
-          "sourceUri": "https://storagesamples.blob.core.windows.net/sample-container/contingency_evidence_adendum.docx"
-        },
-    ],
-    "assessmentDate": "2022-11-14T00:00:00Z",
-    "metadata": {
-         "departmentId": "{departmentID}"
-     }
+  "policyAssignmentId": "/subscriptions/{subscriptionID}/providers/microsoft.authorization/policyassignments/{assignmentID}",
+  "policyDefinitionReferenceId": "{definitionReferenceID}",
+  "complianceState": "Compliant",
+  "expiresOn": "2023-07-14T00:00:00Z",
+  "owner": "{AADObjectID}",
+  "comments": "This subscription has passed a security audit. See attached details for evidence",
+  "evidence": [
+    {
+      "description": "The results of the security audit.",
+      "sourceUri": "https://gist.github.com/contoso/9573e238762c60166c090ae16b814011"
+    },
+    {
+      "description": "Description of the attached evidence document.",
+      "sourceUri": "https://contoso.blob.core.windows.net/contoso-container/contoso_file.docx"
+    },
+  ],
+  "assessmentDate": "2022-11-14T00:00:00Z",
+  "metadata": {
+    "departmentId": "{departmentID}"
+  }
 }
 ```
 
-|Property  |Description  |
-|---------|---------|
-|`policyAssignmentId`     |Required assignment ID for which the state is being set. |
-|`policyDefinitionReferenceId`     |Optional definition reference ID, if within a policy initiative. |
-|`complianceState`     |Desired state of the resources. Allowed values are `Compliant`, `NonCompliant`, and `Unknown`. |
-|`expiresOn`     |Optional date on which the compliance state should revert from the attested compliance state to the default state |
-|`owner`     |Optional Azure AD object ID of responsible party. |
-|`comments`     |Optional description of why state is being set. |
-|`evidence`     |Optional array of links to attestation evidence. |
-|`assessmentDate`     |Date at which the evidence was assessed. |
-|`metadata`     |Optional additional information about the attestation. |
+| Property | Description |
+| ---- | ---- |
+| `policyAssignmentId` | Required assignment ID for which the state is being set. |
+| `policyDefinitionReferenceId` | Optional definition reference ID, if within a policy initiative. |
+| `complianceState` | Desired state of the resources. Allowed values are `Compliant`, `NonCompliant`, and `Unknown`. |
+| `expiresOn` | Optional date on which the compliance state should revert from the attested compliance state to the default state. |
+| `owner` | Optional Microsoft Entra ID object ID of responsible party. |
+| `comments` | Optional description of why state is being set. |
+| `evidence` | Optional array of links to attestation evidence. |
+| `assessmentDate` | Date at which the evidence was assessed. |
+| `metadata` | Optional additional information about the attestation. |
 
-Because attestations are a separate resource from policy assignments, they have their own lifecycle. You can PUT, GET and DELETE attestations using the ARM API.  Attestations are removed if the related manual policy assignment or policyDefinitionReferenceId are deleted, or if a resource unique to the attestation is deleted.  See the [Policy REST API Reference](/rest/api/policy) for more details.
+Because attestations are a separate resource from policy assignments, they have their own lifecycle. You can PUT, GET, and DELETE attestations using the Azure Resource Manager API. Attestations are removed if the related manual policy assignment or `policyDefinitionReferenceId` are deleted, or if a resource unique to the attestation is deleted. For more information, go to [Policy REST API Reference](/rest/api/policy) for more details.
 
 ## Next steps
 
-- Review [Understanding policy effects](effects.md).
-- Study the [initiative definition structure](./initiative-definition-structure.md)
-- Review examples at [Azure Policy samples](../samples/index.md).
+- [Azure Policy definitions effect basics](effect-basics.md).
+- [Azure Policy initiative definition structure](./initiative-definition-structure.md).
+- [Azure Policy samples](../samples/index.md).
diff --git a/articles/governance/policy/concepts/policy-applicability.md b/articles/governance/policy/concepts/policy-applicability.md
@@ -1,28 +1,29 @@
 ---
 title: Azure Policy applicability logic
 description: Describes the rules Azure Policy uses to determine whether the policy is applied to its assigned resources.
-ms.date: 09/22/2022
+ms.date: 07/01/2024
 ms.topic: conceptual
 ---
+
 # What is applicability in Azure Policy?
 
-When a policy definition is assigned to a scope, Azure Policy determines which resources in that scope should be considered for compliance evaluation. A resource will only be assessed for compliance if it's considered **applicable** to the given policy assignment.
+When a policy definition is assigned to a scope, Azure Policy determines which resources in that scope should be considered for compliance evaluation. A resource is only assessed for compliance if it's considered **applicable** to the given policy assignment.
 
-Applicability is determined by several factors:
+Several factors determine applicability:
 - **Conditions** in the `if` block of the [policy rule](../concepts/definition-structure-policy-rule.md#conditions).
 - **Mode** of the policy definition.
 - **Excluded scopes** specified in the assignment.
 - **Resource selectors** specified in the assignment.
 - **Exemptions** of resources or resource hierarchies.
 
-Condition(s) in the `if` block of the policy rule are evaluated for applicability in slightly different ways based on the effect.
+Conditions in the `if` block of the policy rule are evaluated for applicability in slightly different ways based on the effect.
 
 > [!NOTE]
 > Applicability is different from compliance, and the logic used to determine each is different. If a resource is **applicable** that means it is relevant to the policy. If a resource is **compliant** that means it adheres to the policy. Sometimes only certain conditions from the policy rule impact applicability, while all conditions of the policy rule impact compliance state.
 
 ## Resource Manager modes
 
-### -IfNotExists policy effects
+### ifNotExists policy effects
 
 The applicability of `AuditIfNotExists` and `DeployIfNotExists` policies is based off the entire `if` condition of the policy rule. When the `if` evaluates to false, the policy isn't applicable.
 
@@ -32,16 +33,16 @@ Azure Policy evaluates only `type`, `name`, and `kind` conditions in the policy
 
 Following are special cases to the previously described applicability logic:
 
-|Scenario  |Result  |
-|---------|---------|
-|Any invalid aliases in the `if` conditions     |The policy isn't applicable |
-|When the `if` conditions consist of only `kind` conditions     |The policy is applicable to all resources |
-|When the `if` conditions consist of only `name` conditions     |The policy is applicable to all resources |
-|When the `if` conditions consist of only `type` and `kind` conditions     |Only `type` conditions are considered when deciding applicability |
-|When the `if` conditions consist of only `type` and `name` conditions     |Only `type` conditions are considered when deciding applicability |
-|When the `if` conditions consist of `type`, `kind`, and other conditions |Both `type` and `kind` conditions are considered when deciding applicability |
-|When the `if` conditions consist of `type`, `name`, and other conditions |Both `type` and `name` conditions are considered when deciding applicability |
-|When any conditions (including deployment parameters) include a `location` condition     |Won't be applicable to subscriptions |
+| Scenario | Result |
+| ---- | ---- |
+| Any invalid aliases in the `if` conditions | The policy isn't applicable |
+| When the `if` conditions consist of only `kind` conditions | The policy is applicable to all resources |
+| When the `if` conditions consist of only `name` conditions | The policy is applicable to all resources |
+| When the `if` conditions consist of only `type` and `kind` conditions | Only `type` conditions are considered when deciding applicability |
+| When the `if` conditions consist of only `type` and `name` conditions | Only `type` conditions are considered when deciding applicability |
+| When the `if` conditions consist of `type`, `kind`, and other conditions | Both `type` and `kind` conditions are considered when deciding applicability |
+| When the `if` conditions consist of `type`, `name`, and other conditions | Both `type` and `name` conditions are considered when deciding applicability |
+| When any conditions (including deployment parameters) include a `location` condition | Isn't applicable to subscriptions |
 
 
 ## Resource provider modes
@@ -52,34 +53,33 @@ The applicability of `Microsoft.Kubernetes.Data` policies is based off the entir
 
 ### Microsoft.KeyVault.Data, Microsoft.ManagedHSM.Data, Microsoft.DataFactory.Data, and Microsoft.MachineLearningServices.v2.Data
 
-Policies with these RP Modes are applicable if the `type` condition of the policy rule evaluates to true. The `type` refers to component type.
+Policies with these resource provider modes are applicable if the `type` condition of the policy rule evaluates to true. The `type` refers to component type.
 
 Key Vault component types:
-- Microsoft.KeyVault.Data/vaults/certificates
-- Microsoft.KeyVault.Data/vaults/keys
-- Microsoft.KeyVault.Data/vaults/secrets
+- `Microsoft.KeyVault.Data/vaults/certificates`
+- `Microsoft.KeyVault.Data/vaults/keys`
+- `Microsoft.KeyVault.Data/vaults/secrets`
 
-Managed HSM component type:
-- Microsoft.ManagedHSM.Data/managedHsms/keys
+Managed Hardware Security Module (HSM) component type:
+- `Microsoft.ManagedHSM.Data/managedHsms/keys`
 
 Azure Data Factory component type:
-- Microsoft.DataFactory.Data/factories/outboundTraffic
+- `Microsoft.DataFactory.Data/factories/outboundTraffic`
 
 Azure Machine Learning component type:
-- Microsoft.MachineLearningServices.v2.Data/workspaces/deployments
+- `Microsoft.MachineLearningServices.v2.Data/workspaces/deployments`
 
 ### Microsoft.Network.Data
 
 Policies with mode `Microsoft.Network.Data` are applicable if the `type` and `name` conditions of the policy rule evaluate to true. The `type` refers to  component type:
-- Microsoft.Network/virtualNetworks
+- `Microsoft.Network/virtualNetworks`
 
 ## Not Applicable Resources
 
 There could be situations in which resources are applicable to an assignment based on conditions or scope, but they shouldn't be applicable due to business reasons. At that time, it would be best to apply [exclusions](./assignment-structure.md#excluded-scopes) or [exemptions](./exemption-structure.md). To learn more on when to use either, review [scope comparison](./scope.md#scope-comparison)
 
 > [!NOTE]
-> By design, Azure Policy does not evaluate resources under the `Microsoft.Resources` resource provider (RP) from
-policy evaluation, except for subscriptions and resource groups.
+> By design, Azure Policy does not evaluate resources under the `Microsoft.Resources` resource provider from policy evaluation, except for subscriptions and resource groups.
 
 ## Next steps
 
