Skip to content

Commit c5df291

Browse files
American-DipperAmerican-Dipper
authored
Merge pull request #271279 from davidsmatlak/ds-restructure-policy-effects-20240404
Restructure Azure Policy effect article
2 parents 5744a93 + 3e974b5 commit c5df291

18 files changed

+1105
-1096
lines changed

‎articles/governance/index.yml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ metadata:
1111
ms.topic: hub-page
1212
author: davidsmatlak
1313
ms.author: davidsmatlak
14-
ms.date: 01/05/2024
14+
ms.date: 04/08/2024
1515

1616
highlightedContent:
1717
items:
@@ -49,8 +49,8 @@ productDirectory:
4949
text: Azure Policy glossary
5050
- url: ./policy/concepts/definition-structure-basics.md
5151
text: Policy definition structure
52-
- url: ./policy/concepts/effects.md
53-
text: Azure Policy effects
52+
- url: ./policy/concepts/effect-basics.md
53+
text: Azure Policy effect
5454
- url: ./policy/index.yml
5555
text: See more >
5656
- title: Azure Blueprints

‎articles/governance/policy/.openpublishing.redirection.policy.json

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -814,6 +814,11 @@
814814
"source_path_from_root": "/articles/governance/policy/concepts/definition-structure.md",
815815
"redirect_url": "/azure/governance/policy/concepts/definition-structure-basics",
816816
"redirect_document_id": false
817+
},
818+
{
819+
"source_path_from_root": "/articles/governance/policy/concepts/effects.md",
820+
"redirect_url": "/azure/governance/policy/concepts/effect-basics",
821+
"redirect_document_id": false
817822
}
818823
]
819824
}

‎articles/governance/policy/concepts/effect-add-to-network-group.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: Azure Policy definitions addToNetworkGroup effect
3+
description: Azure Policy definitions addToNetworkGroup effect determines how compliance is managed and reported.
4+
ms.date: 04/08/2024
5+
ms.topic: conceptual
6+
---
7+
8+
# Azure Policy definitions addToNetworkGroup effect
9+
10+
The `addToNetworkGroup` effect is used in Azure Virtual Network Manager to define dynamic network group membership. This effect is specific to `Microsoft.Network.Data` [policy mode](./definition-structure.md#resource-provider-modes) definitions only.
11+
12+
With network groups, your policy definition includes your conditional expression for matching virtual networks meeting your criteria, and specifies the destination network group where any matching resources are placed. The `addToNetworkGroup` effect is used to place resources in the destination network group.
13+
14+
To learn more, go to [Configuring Azure Policy with network groups in Azure Virtual Network Manager](../../../virtual-network-manager/concept-azure-policy-integration.md).
15+
16+
## Next steps
17+
18+
- Review examples at [Azure Policy samples](../samples/index.md).
19+
- Review the [Azure Policy definition structure](definition-structure-basics.md).
20+
- Understand how to [programmatically create policies](../how-to/programmatically-create.md).
21+
- Learn how to [get compliance data](../how-to/get-compliance-data.md).
22+
- Learn how to [remediate non-compliant resources](../how-to/remediate-resources.md).
23+
- Review [Azure management groups](../../management-groups/overview.md).

‎articles/governance/policy/concepts/effect-append.md

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: Azure Policy definitions append effect
3+
description: Azure Policy definitions append effect determines how compliance is managed and reported.
4+
ms.date: 04/08/2024
5+
ms.topic: conceptual
6+
---
7+
8+
# Azure Policy definitions append effect
9+
10+
The `append` effect is used to add more fields to the requested resource during creation or update. A common example is specifying allowed IPs for a storage resource.
11+
12+
> [!IMPORTANT]
13+
> `append` is intended for use with non-tag properties. While `append` can add tags to a resource during a create or update request, it's recommended to use the [modify](./effect-modify.md) effect for tags instead.
14+
15+
## Append evaluation
16+
17+
The `append` effect evaluates before the request gets processed by a Resource Provider during the creation or updating of a resource. Append adds fields to the resource when the `if` condition of the policy rule is met. If the append effect would override a value in the original request with a different value, then it acts as a deny effect and rejects the request. To append a new value to an existing array, use the `[*]` version of the alias.
18+
19+
When a policy definition using the append effect is run as part of an evaluation cycle, it doesn't make changes to resources that already exist. Instead, it marks any resource that meets the `if` condition as non-compliant.
20+
21+
## Append properties
22+
23+
An append effect only has a `details` array, which is required. Because `details` is an array, it can take either a single `field/value` pair or multiples. Refer to [definition structure](./definition-structure-policy-rule.md#fields) for the list of acceptable fields.
24+
25+
## Append examples
26+
27+
Example 1: Single `field/value` pair using a non-`[*]` [alias](./definition-structure-alias.md) with an array `value` to set IP rules on a storage account. When the non-`[*]` alias is an array, the effect appends the `value` as the entire array. If the array already exists, a `deny` event occurs from the conflict.
28+
29+
```json
30+
"then": {
31+
"effect": "append",
32+
"details": [
33+
{
34+
"field": "Microsoft.Storage/storageAccounts/networkAcls.ipRules",
35+
"value": [
36+
{
37+
"action": "Allow",
38+
"value": "134.5.0.0/21"
39+
}
40+
]
41+
}
42+
]
43+
}
44+
```
45+
46+
Example 2: Single `field/value` pair using an `[*]` [alias](./definition-structure-alias.md) with an array `value` to set IP rules on a storage account. When you use the `[*]` alias, the effect appends the `value` to a potentially pre-existing array. Arrays that don't exist are created.
47+
48+
```json
49+
"then": {
50+
"effect": "append",
51+
"details": [
52+
{
53+
"field": "Microsoft.Storage/storageAccounts/networkAcls.ipRules[*]",
54+
"value": {
55+
"value": "40.40.40.40",
56+
"action": "Allow"
57+
}
58+
}
59+
]
60+
}
61+
```
62+
63+
## Next steps
64+
65+
- Review examples at [Azure Policy samples](../samples/index.md).
66+
- Review the [Azure Policy definition structure](definition-structure-basics.md).
67+
- Understand how to [programmatically create policies](../how-to/programmatically-create.md).
68+
- Learn how to [get compliance data](../how-to/get-compliance-data.md).
69+
- Learn how to [remediate non-compliant resources](../how-to/remediate-resources.md).
70+
- Review [Azure management groups](../../management-groups/overview.md).

‎articles/governance/policy/concepts/effect-audit-if-not-exists.md

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
title: Azure Policy definitions auditIfNotExists effect
3+
description: Azure Policy definitions auditIfNotExists effect determines how compliance is managed and reported.
4+
ms.date: 04/08/2024
5+
ms.topic: conceptual
6+
---
7+
8+
# Azure Policy definitions auditIfNotExists effect
9+
10+
The `auditIfNotExists` effect enables auditing of resources _related_ to the resource that matches the `if` condition, but don't have the properties specified in the `details` of the `then` condition.
11+
12+
## AuditIfNotExists evaluation
13+
14+
`auditIfNotExists` runs after a Resource Provider processed a create or update resource request and returned a success status code. The audit occurs if there are no related resources or if the resources defined by `ExistenceCondition` don't evaluate to true. For new and updated resources, Azure Policy adds a `Microsoft.Authorization/policies/audit/action` operation to the activity log and marks the resource as non-compliant. When triggered, the resource that satisfied the `if` condition is the resource that is marked as non-compliant.
15+
16+
## AuditIfNotExists properties
17+
18+
The `details` property of the AuditIfNotExists effects has all the subproperties that define the related resources to match.
19+
20+
- `type` (required)
21+
- Specifies the type of the related resource to match.
22+
- If `type` is a resource type underneath the `if` condition resource, the policy queries for resources of this `type` within the scope of the evaluated resource. Otherwise, policy queries within the same resource group or subscription as the evaluated resource depending on the `existenceScope`.
23+
- `name` (optional)
24+
- Specifies the exact name of the resource to match and causes the policy to fetch one specific resource instead of all resources of the specified type.
25+
- When the condition values for `if.field.type` and `then.details.type` match, then `name` becomes _required_ and must be `[field('name')]`, or `[field('fullName')]` for a child resource. However, an [audit](./effect-audit.md) effect should be considered instead.
26+
27+
> [!NOTE]
28+
>
29+
> `type` and `name` segments can be combined to generically retrieve nested resources.
30+
>
31+
> To retrieve a specific resource, you can use `"type": "Microsoft.ExampleProvider/exampleParentType/exampleNestedType"` and `"name": "parentResourceName/nestedResourceName"`.
32+
>
33+
> To retrieve a collection of nested resources, a wildcard character `?` can be provided in place of the last name segment. For example, `"type": "Microsoft.ExampleProvider/exampleParentType/exampleNestedType"` and `"name": "parentResourceName/?"`. This can be combined with field functions to access resources related to the evaluated resource, such as `"name": "[concat(field('name'), '/?')]"`."
34+
35+
- `resourceGroupName` (optional)
36+
- Allows the matching of the related resource to come from a different resource group.
37+
- Doesn't apply if `type` is a resource that would be underneath the `if` condition resource.
38+
- Default is the `if` condition resource's resource group.
39+
- `existenceScope` (optional)
40+
- Allowed values are _Subscription_ and _ResourceGroup_.
41+
- Sets the scope of where to fetch the related resource to match from.
42+
- Doesn't apply if `type` is a resource that would be underneath the `if` condition resource.
43+
- For _ResourceGroup_, would limit to the resource group in `resourceGroupName` if specified. If `resourceGroupName` isn't specified, would limit to the `if` condition resource's resource group, which is the default behavior.
44+
- For _Subscription_, queries the entire subscription for the related resource. Assignment scope should be set at subscription or higher for proper evaluation.
45+
- Default is _ResourceGroup_.
46+
- `evaluationDelay` (optional)
47+
- Specifies when the existence of the related resources should be evaluated. The delay is only
48+
used for evaluations that are a result of a create or update resource request.
49+
- Allowed values are `AfterProvisioning`, `AfterProvisioningSuccess`, `AfterProvisioningFailure`,
50+
or an ISO 8601 duration between 0 and 360 minutes.
51+
- The _AfterProvisioning_ values inspect the provisioning result of the resource that was
52+
evaluated in the policy rule's `if` condition. `AfterProvisioning` runs after provisioning is
53+
complete, regardless of outcome. Provisioning that takes more than six hours, is treated as a
54+
failure when determining _AfterProvisioning_ evaluation delays.
55+
- Default is `PT10M` (10 minutes).
56+
- Specifying a long evaluation delay might cause the recorded compliance state of the resource to
57+
not update until the next
58+
[evaluation trigger](../how-to/get-compliance-data.md#evaluation-triggers).
59+
- `existenceCondition` (optional)
60+
- If not specified, any related resource of `type` satisfies the effect and doesn't trigger the
61+
audit.
62+
- Uses the same language as the policy rule for the `if` condition, but is evaluated against
63+
each related resource individually.
64+
- If any matching related resource evaluates to true, the effect is satisfied and doesn't trigger
65+
the audit.
66+
- Can use [field()] to check equivalence with values in the `if` condition.
67+
- For example, could be used to validate that the parent resource (in the `if` condition) is in
68+
the same resource location as the matching related resource.
69+
70+
## AuditIfNotExists example
71+
72+
Example: Evaluates Virtual Machines to determine whether the Antimalware extension exists then audits when missing.
73+
74+
```json
75+
{
76+
"if": {
77+
"field": "type",
78+
"equals": "Microsoft.Compute/virtualMachines"
79+
},
80+
"then": {
81+
"effect": "auditIfNotExists",
82+
"details": {
83+
"type": "Microsoft.Compute/virtualMachines/extensions",
84+
"existenceCondition": {
85+
"allOf": [
86+
{
87+
"field": "Microsoft.Compute/virtualMachines/extensions/publisher",
88+
"equals": "Microsoft.Azure.Security"
89+
},
90+
{
91+
"field": "Microsoft.Compute/virtualMachines/extensions/type",
92+
"equals": "IaaSAntimalware"
93+
}
94+
]
95+
}
96+
}
97+
}
98+
}
99+
```
100+
101+
## Next steps
102+
103+
- Review examples at [Azure Policy samples](../samples/index.md).
104+
- Review the [Azure Policy definition structure](definition-structure-basics.md).
105+
- Understand how to [programmatically create policies](../how-to/programmatically-create.md).
106+
- Learn how to [get compliance data](../how-to/get-compliance-data.md).
107+
- Learn how to [remediate non-compliant resources](../how-to/remediate-resources.md).
108+
- Review [Azure management groups](../../management-groups/overview.md).

‎articles/governance/policy/concepts/effect-audit.md

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
title: Azure Policy definitions audit effect
3+
description: Azure Policy definitions audit effect determines how compliance is managed and reported.
4+
ms.date: 04/08/2024
5+
ms.topic: conceptual
6+
---
7+
8+
# Azure Policy definitions audit effect
9+
10+
The `audit` effect is used to create a warning event in the activity log when evaluating a non-compliant resource, but it doesn't stop the request.
11+
12+
## Audit evaluation
13+
14+
Audit is the last effect checked by Azure Policy during the creation or update of a resource. For a Resource Manager mode, Azure Policy then sends the resource to the Resource Provider. When evaluating a create or update request for a resource, Azure Policy adds a `Microsoft.Authorization/policies/audit/action` operation to the activity log and marks the resource as non-compliant. During a standard compliance evaluation cycle, only the compliance status on the resource is updated.
15+
16+
## Audit properties
17+
18+
For a Resource Manager mode, the audit effect doesn't have any other properties for use in the `then` condition of the policy definition.
19+
20+
For a Resource Provider mode of `Microsoft.Kubernetes.Data`, the audit effect has the following subproperties of `details`. Use of `templateInfo` is required for new or updated policy definitions as `constraintTemplate` is deprecated.
21+
22+
- `templateInfo` (required)
23+
- Can't be used with `constraintTemplate`.
24+
- `sourceType` (required)
25+
- Defines the type of source for the constraint template. Allowed values: `PublicURL` or `Base64Encoded`.
26+
- If `PublicURL`, paired with property `url` to provide location of the constraint template. The location must be publicly accessible.
27+
28+
> [!WARNING]
29+
> Don't use SAS URIs, URL tokens, or anything else that could expose secrets in plain text.
30+
31+
- If `Base64Encoded`, paired with property `content` to provide the base 64 encoded constraint template. See [Create policy definition from constraint template](../how-to/extension-for-vscode.md) to create a custom definition from an existing [Open Policy Agent](https://www.openpolicyagent.org/) (OPA) Gatekeeper v3 [constraint template](https://open-policy-agent.github.io/gatekeeper/website/docs/howto/#constraint-templates).
32+
- `constraint` (deprecated)
33+
- Can't be used with `templateInfo`.
34+
- The CRD implementation of the Constraint template. Uses parameters passed via `values` as `{{ .Values.<valuename> }}`. In example 2 below, these values are `{{ .Values.excludedNamespaces }}` and `{{ .Values.allowedContainerImagesRegex }}`.
35+
- `constraintTemplate` (deprecated)
36+
- Can't be used with `templateInfo`.
37+
- Must be replaced with `templateInfo` when creating or updating a policy definition.
38+
- The Constraint template CustomResourceDefinition (CRD) that defines new Constraints. The template defines the Rego logic, the Constraint schema, and the Constraint parameters that are passed via `values` from Azure Policy. For more information, go to [Gatekeeper constraints](https://open-policy-agent.github.io/gatekeeper/website/docs/howto/#constraints).
39+
- `constraintInfo` (optional)
40+
- Can't be used with `constraint`, `constraintTemplate`, `apiGroups`, `kinds`, `scope`, `namespaces`, `excludedNamespaces`, or `labelSelector`.
41+
- If `constraintInfo` isn't provided, the constraint can be generated from `templateInfo` and policy.
42+
- `sourceType` (required)
43+
- Defines the type of source for the constraint. Allowed values: `PublicURL` or `Base64Encoded`.
44+
- If `PublicURL`, paired with property `url` to provide location of the constraint. The location must be publicly accessible.
45+
46+
> [!WARNING]
47+
> Don't use SAS URIs or tokens in `url` or anything else that could expose a secret.
48+
49+
- `namespaces` (optional)
50+
- An _array_ of
51+
[Kubernetes namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)
52+
to limit policy evaluation to.
53+
- An empty or missing value causes policy evaluation to include all namespaces not defined in _excludedNamespaces_.
54+
- `excludedNamespaces` (optional)
55+
- An _array_ of [Kubernetes namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) to exclude from policy evaluation.
56+
- `labelSelector` (optional)
57+
- An _object_ that includes _matchLabels_ (object) and _matchExpression_ (array) properties to allow specifying which Kubernetes resources to include for policy evaluation that matched the provided [labels and selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/).
58+
- An empty or missing value causes policy evaluation to include all labels and selectors, except
59+
namespaces defined in _excludedNamespaces_.
60+
- `scope` (optional)
61+
- A _string_ that includes the [scope](https://open-policy-agent.github.io/gatekeeper/website/docs/howto/#the-match-field) property to allow specifying if cluster-scoped or namespaced-scoped resources are matched.
62+
- `apiGroups` (required when using _templateInfo_)
63+
- An _array_ that includes the [API groups](https://kubernetes.io/docs/reference/using-api/#api-groups) to match. An empty array (`[""]`) is the core API group.
64+
- Defining `["*"]` for _apiGroups_ is disallowed.
65+
- `kinds` (required when using _templateInfo_)
66+
- An _array_ that includes the [kind](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields)
67+
of Kubernetes object to limit evaluation to.
68+
- Defining `["*"]` for _kinds_ is disallowed.
69+
- `values` (optional)
70+
- Defines any parameters and values to pass to the Constraint. Each value must exist and match a property in the validation `openAPIV3Schema` section of the Constraint template CRD.
71+
72+
## Audit example
73+
74+
Example 1: Using the audit effect for Resource Manager modes.
75+
76+
```json
77+
"then": {
78+
"effect": "audit"
79+
}
80+
```
81+
82+
Example 2: Using the audit effect for a Resource Provider mode of `Microsoft.Kubernetes.Data`. The additional information in `details.templateInfo` declares use of `PublicURL` and sets `url` to the location of the Constraint template to use in Kubernetes to limit the allowed container images.
83+
84+
```json
85+
"then": {
86+
"effect": "audit",
87+
"details": {
88+
"templateInfo": {
89+
"sourceType": "PublicURL",
90+
"url": "https://store.policy.core.windows.net/kubernetes/container-allowed-images/v1/template.yaml",
91+
},
92+
"values": {
93+
"imageRegex": "[parameters('allowedContainerImagesRegex')]"
94+
},
95+
"apiGroups": [
96+
""
97+
],
98+
"kinds": [
99+
"Pod"
100+
]
101+
}
102+
}
103+
```
104+
105+
## Next steps
106+
107+
- Review examples at [Azure Policy samples](../samples/index.md).
108+
- Review the [Azure Policy definition structure](definition-structure-basics.md).
109+
- Understand how to [programmatically create policies](../how-to/programmatically-create.md).
110+
- Learn how to [get compliance data](../how-to/get-compliance-data.md).
111+
- Learn how to [remediate non-compliant resources](../how-to/remediate-resources.md).
112+
- Review [Azure management groups](../../management-groups/overview.md).

0 commit comments

Comments
 (0)