Skip to content

Commit 1033867

Browse files
ktoliverktoliver
authored
Merge pull request #87226 from DCtheGeek/dmc-policy-enforcement
Adding enforcementMode details
2 parents 6ce11a3 + af6fa4a commit 1033867

File tree

4 files changed

+243
-1
lines changed

4 files changed

+243
-1
lines changed

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

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
title: Details of the policy assignment structure
3+
description: Describes the policy assignment definition used by Azure Policy to relate policy definitions and parameters to resources for evaluation.
4+
author: DCtheGeek
5+
ms.author: dacoulte
6+
ms.date: 09/23/2019
7+
ms.topic: conceptual
8+
ms.service: azure-policy
9+
manager: carmonm
10+
---
11+
# Azure Policy assignment structure
12+
13+
Policy assignments are used by Azure Policy to define which resources are assigned while policies or
14+
initiatives. The policy assignment can determine the values of parameters for that group of
15+
resources at assignment time, making it possible to reuse policy definitions that address the same
16+
resource properties with different needs for compliance.
17+
18+
The schema used by Azure Policy can be found here: [https://docs.microsoft.com/azure/templates/microsoft.authorization/2019-01-01/policyassignments](/azure/templates/microsoft.authorization/2019-01-01/policyassignments)
19+
20+
You use JSON to create a policy assignment. The policy definition contains elements for:
21+
22+
- display name
23+
- description
24+
- metadata
25+
- enforcement mode
26+
- policy definition
27+
- parameters
28+
29+
For example, the following JSON shows a policy assignment in _DoNotEnforce_ mode with dynamic parameters:
30+
31+
```json
32+
{
33+
"properties": {
34+
"displayName": "Enforce resource naming rules",
35+
"description": "Force resource names to begin with DeptA and end with -LC",
36+
"metadata": {
37+
"assignedBy": "Cloud Center of Excellence"
38+
},
39+
"enforcementMode": "DoNotEnforce",
40+
"policyDefinitionId": "/subscriptions/{mySubscriptionID}/providers/Microsoft.Authorization/policyDefinitions/ResourceNaming",
41+
"parameters": {
42+
"prefix": {
43+
"value": "DeptA"
44+
},
45+
"suffix": {
46+
"value": "-LC"
47+
}
48+
}
49+
}
50+
}
51+
```
52+
53+
All Azure Policy samples are at [Azure Policy samples](../samples/index.md).
54+
55+
## Display name and description
56+
57+
You use **displayName** and **description** to identify the policy assignment and provide context
58+
for its use with the specific set of resources. **displayName** has a maximum length of _128_
59+
characters and **description** a maximum length of _512_ characters.
60+
61+
## Enforcement Mode
62+
63+
The **enforcementMode** property provides customers the ability to test the outcome of a policy on
64+
existing resources without initiating the policy effect or triggering entries in the [Azure Activity log](../../../azure-monitor/platform/activity-logs-overview.md).
65+
This scenario is commonly referred to as "What If" and aligns to safe deployment practices.
66+
67+
This property has the following values:
68+
69+
|Mode |JSON Value |Type |Remediate manually |Activity log entry |Description |
70+
|-|-|-|-|-|-|
71+
|Enabled |Default |string |Yes |Yes |The policy effect is enforced during resource creation or update. |
72+
|Disabled |DoNotEnforce |string |Yes |No | The policy effect isn't enforced during resource creation or update. |
73+
74+
If **enforcementMode** isn't specified in a policy or initiative definition, the value _Default_ is
75+
used. [Remediation tasks](../how-to/remediate-resources.md) can be started for [deployIfNotExists](./effects.md#deployifnotexists)
76+
policies, even when **enforcementMode** is set to _DoNotEnforce_.
77+
78+
## Policy definition ID
79+
80+
This field must be the full path name of either a policy definition or an initiative definition.
81+
`policyDefinitionId` is a string and not an array. It's recommended that if multiple policies are
82+
often assigned together, to use an [initiative](./definition-structure.md#initiatives) instead.
83+
84+
## Parameters
85+
86+
This segment of the policy assignment provides the values for the parameters defined in the [policy definition or initiative definition](./definition-structure.md#parameters).
87+
This design makes it possible to reuse a policy or initiative definition with different resources,
88+
but check for different business values or outcomes.
89+
90+
```json
91+
"parameters": {
92+
"prefix": {
93+
"value": "DeptA"
94+
},
95+
"suffix": {
96+
"value": "-LC"
97+
}
98+
}
99+
```
100+
101+
In this example, the parameters previously defined in the policy definition are `prefix` and
102+
`suffix`. This particular policy assignment sets `prefix` to **DeptA** and `suffix` to **-LC**. The
103+
same policy definition is reusable with a different set of parameters for a different department,
104+
reducing the duplication and complexity of policy definitions while providing flexibility.
105+
106+
## Next steps
107+
108+
- Learn about the [policy definition structure](./definition-structure.md).
109+
- Understand how to [programmatically create policies](../how-to/programmatically-create.md).
110+
- Learn how to [get compliance data](../how-to/getting-compliance-data.md).
111+
- Learn how to [remediate non-compliant resources](../how-to/remediate-resources.md).
112+
- Review what a management group is with [Organize your resources with Azure management groups](../../management-groups/overview.md).

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ you can specify that only certain types of virtual machines are allowed. Or, you
1717
all resources have a particular tag. Policies are inherited by all child resources. If a policy is
1818
applied to a resource group, it's applicable to all the resources in that resource group.
1919

20-
The schema used by Azure Policy can be found here: [https://schema.management.azure.com/schemas/2018-05-01/policyDefinition.json](https://schema.management.azure.com/schemas/2018-05-01/policyDefinition.json)
20+
The schema used by Azure Policy can be found here: [https://docs.microsoft.com/azure/templates/microsoft.authorization/2019-01-01/policydefinitions](/azure/templates/microsoft.authorization/2019-01-01/policydefinitions)
2121

2222
You use JSON to create a policy definition. The policy definition contains elements for:
2323

‎articles/governance/policy/concepts/evaluate-impact.md

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
title: Evaluate the impact of a new Azure policy
3+
description: Understand the process to follow when introducing a new policy into your Azure environment.
4+
author: DCtheGeek
5+
ms.author: dacoulte
6+
ms.date: 09/23/2019
7+
ms.topic: conceptual
8+
ms.service: azure-policy
9+
manager: carmonm
10+
---
11+
# Evaluate the impact of a new Azure policy
12+
13+
Azure Policy is a powerful tool for managing your Azure resources to business standards and to meet
14+
compliance needs. When people, processes, or pipelines create or update resources, Azure Policy
15+
reviews the request. When the policy definition effect is [Append](./effects.md#deny) or [DeployIfNotExists](./effects.md#deployifnotexists),
16+
Policy alters the request or adds to it. When the policy definition effect is [Audit](./effects.md#audit)
17+
or [AuditIfNotExists](./effects.md#auditifnotexists), Policy causes an Activity log entry to be
18+
created. And when the policy definition effect is [Deny](./effects.md#deny), Policy stops the
19+
creation or alteration of the request.
20+
21+
These outcomes are exactly as desired when you know the policy is defined correctly. However, it's
22+
important to validate a new policy works as intended before allowing it to change or block work. The
23+
validation must ensure only the intended resources are determined to be non-compliant and no
24+
compliant resources are incorrectly included (known as a _false positive_) in the results.
25+
26+
The recommended approach to validating a new policy definition is by following these steps:
27+
28+
- Tightly define your policy
29+
- Audit your existing resources
30+
- Audit new or updated resource requests
31+
- Deploy your policy to resources
32+
- Continuous monitoring
33+
34+
## Tightly define your policy
35+
36+
It's important to understand how the business policy is implemented as a policy definition and the
37+
relationship of Azure resources with other Azure services. This step is accomplished by
38+
[identifying the requirements](../tutorials/create-custom-policy-definition.md#identify-requirements)
39+
and
40+
[determining the resource properties](../tutorials/create-custom-policy-definition.md#determine-resource-properties).
41+
But it's also important to see beyond the narrow definition of your business policy. Does your
42+
policy state for example "All Virtual Machines must..."? What about other Azure services that make
43+
use of VMs, such as HDInsight or AKS? When defining a policy, we must consider how this policy
44+
impacts resources that are used by other services.
45+
46+
For this reason, your policy definitions should be as tightly defined and focused on the resources
47+
and the properties you need to evaluate for compliance as possible.
48+
49+
## Audit existing resources
50+
51+
Before looking to manage new or updated resources with your new policy definition, it's best to see
52+
how it evaluates a limited subset of existing resources, such as a test resource group. Use the [enforcement mode](./assignment-structure.md#enforcement-mode)
53+
_Disabled_ (DoNotEnforce) on your policy assignment to prevent the [effect](./effects.md) from
54+
triggering or activity log entries from being created.
55+
56+
This step gives you a chance to evaluate the compliance results of the new policy on existing
57+
resources without impacting work flow. Check that no compliant resources are marked as non-compliant
58+
(_false positive_) and that all the resources you expect to be non-compliant are marked correctly.
59+
After the initial subset of resources validates as expected, slowly expand the evaluation to all
60+
existing resources.
61+
62+
Evaluating existing resources in this way also provides an opportunity to remediate non-compliant
63+
resources before full implementation of the new policy. This cleanup can be done manually or through
64+
a [remediation task](../how-to/remediate-resources.md) if the policy definition effect is
65+
_DeployIfNotExists_.
66+
67+
## Audit new or updated resources
68+
69+
Once you've validated your new policy definition is reporting correctly on existing resources, it's
70+
time to look at the impact of the policy when resources get created or updated. If the policy
71+
definition supports effect parameterization, use [Audit](./effects.md#audit). This configuration
72+
allows you to monitor the creation and updating of resources to see if the new policy definition
73+
triggers an entry in Azure Activity log for a resource that is non-compliant without impacting
74+
existing work or requests.
75+
76+
It's recommended to both update and create new resources that match your policy definition to see
77+
that the _Audit_ effect is correctly being triggered when expected. Be on the lookout for resource
78+
requests that shouldn't be impacted by the new policy definition that trigger the _Audit_ effect.
79+
These impacted resources are another example of _false positives_ and must be fixed in the policy
80+
definition before full implementation.
81+
82+
In the event the policy definition is changed at this stage of testing, it's recommended to begin
83+
the validation process over with the auditing of existing resources. A change to the policy
84+
definition for a _false positive_ on new or updated resources is likely to also have an impact on
85+
existing resources.
86+
87+
## Deploy your policy to resources
88+
89+
After completing validation of your new policy definition with both existing resources and new or
90+
updated resource requests, you begin the process of implementing the policy. It's recommended to
91+
create the policy assignment for the new policy definition to a subset of all resources first, such
92+
as a resource group. After validating initial deployment, extend the scope of the policy to broader
93+
and broader levels, such as subscriptions and management groups. This expansion is achieved by
94+
removing the assignment and creating a new one at the target scopes until it's assigned to the full
95+
scope of resources intended to be covered by your new policy definition.
96+
97+
During rollout, if resources are located that should be exempt from your new policy definition,
98+
address them in one of the following ways:
99+
100+
- Update the policy definition to be more explicit to reduce unintended impact
101+
- Change the scope of the policy assignment (by removing and creating a new assignment)
102+
- Add the group of resources to the exclusion list for the policy assignment
103+
104+
Any changes to the scope (level or exclusions) should be fully validated and communicated with your
105+
security and compliance organizations to ensure there are no gaps in coverage.
106+
107+
## Monitor your policy and compliance
108+
109+
Implementing and assigning your policy definition isn't the final step. Continuously monitor the [compliance](../how-to/get-compliance-data.md)
110+
level of resources to your new policy definition and setup appropriate [Azure Monitor alerts and notifications](../../../azure-monitor/platform/alerts-overview.md)
111+
for when non-compliant devices are identified. It's also recommended to evaluate the policy
112+
definition and related assignments on a scheduled basis to validate the policy definition is meeting
113+
business policy and compliance needs. Policies should be removed if no longer needed. Policies also
114+
need updating from time to time as the underlying Azure resources evolve and add new properties and
115+
capabilities.
116+
117+
## Next steps
118+
119+
- Learn about the [policy definition structure](./definition-structure.md).
120+
- Learn about the [policy assignment structure](./assignment-structure.md).
121+
- Understand how to [programmatically create policies](../how-to/programmatically-create.md).
122+
- Learn how to [get compliance data](../how-to/getting-compliance-data.md).
123+
- Learn how to [remediate non-compliant resources](../how-to/remediate-resources.md).
124+
- Review what a management group is with [Organize your resources with Azure management groups](../../management-groups/overview.md).

‎articles/governance/policy/toc.yml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -257,6 +257,12 @@
257257
- name: Understand Policy effects
258258
displayName: order, evaluation
259259
href: ./concepts/effects.md
260+
- name: Azure Policy assignment structure
261+
displayName: parameters, enforcementmode, policyDefinitionId
262+
href: ./concepts/assignment-structure.md
263+
- name: Evaluate the impact of a new policy
264+
displayName: audit, enforcementmode, compliance
265+
href: ./concepts/evaluate-impact.md
260266
- name: Azure Policy for Kubernetes
261267
displayName: aks, rego, k8s, opa, open policy agent, gatekeeper
262268
href: ./concepts/rego-for-aks.md

0 commit comments

Comments
 (0)