Skip to content

Commit 511113d

Browse files
Court72Court72
authored
Merge pull request #115433 from plzm/cosmosdb-policy
Cosmos DB | Add Azure policy support article
2 parents 6848dff + 85c750b commit 511113d

File tree

4 files changed

+124
-0
lines changed

4 files changed

+124
-0
lines changed

‎articles/cosmos-db/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -570,6 +570,8 @@
570570
href: online-backup-and-restore.md
571571
- name: Compliance
572572
href: compliance.md
573+
- name: Azure Policy support
574+
href: policy.md
573575
- name: Service quotas
574576
href: concepts-limits.md
575577
- name: Cassandra, MongoDB, and other APIs

‎articles/cosmos-db/media/policy/available-definitions.png

45.3 KB
Loading

‎articles/cosmos-db/media/policy/compliance.png

33.8 KB
Loading

‎articles/cosmos-db/policy.md

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
title: Use Azure Policy to implement governance and controls for Azure Cosmos DB resources
3+
description: Learn how to use Azure Policy to implement governance and controls for Cosmos DB resources.
4+
author: plzm
5+
ms.author: paelaz
6+
ms.service: cosmos-db
7+
ms.topic: conceptual
8+
ms.date: 05/20/2020
9+
10+
---
11+
12+
# Use Azure Policy to implement governance and controls for Azure Cosmos DB resources
13+
14+
[Azure Policy](../governance/policy/overview.md) helps to enforce organizational governance standards, assess resource compliance, and implement automatic remediation. Common use cases include security, cost management, and configuration consistency.
15+
16+
Azure Policy provides built-in policy definitions. You can create custom policy definitions for scenarios that are not addressed by the built-in policy definitions. See the [Azure Policy documentation](../governance/policy/overview.md) for more details.
17+
18+
## Assign a built-in policy definition
19+
20+
Policy definitions describe resource compliance conditions and the effect to take if a condition is met. Policy _assignments_ are created from policy _definitions_. You can use built-in or custom policy definitions for your Azure Cosmos DB resources. Policy assignments are scoped to an Azure management group, an Azure subscription, or a resource group and they are applied to the resources within the selected scope. Optionally, you can exclude specific resources from the scope.
21+
22+
You can create policy assignments with the [Azure portal](../governance/policy/assign-policy-portal.md), [Azure PowerShell](../governance/policy/assign-policy-powershell.md), [Azure CLI](../governance/policy/assign-policy-azurecli.md), or [ARM template](../governance/policy/assign-policy-template.md).
23+
24+
To create a policy assignment from a built-in policy definition for Azure Cosmos DB, use the steps in [create a policy assignment with the Azure portal](../governance/policy/assign-policy-portal.md) article.
25+
26+
At the step to select a policy definition, enter `Cosmos DB` in the Search field to filter the list of available built-in policy definitions. Select one of the available built-in policy definitions, and then choose **Select** to continue creating the policy assignment.
27+
28+
> [!TIP]
29+
> You can also use the built-in policy definition names shown in the **Available Definitions** pane with Azure PowerShell, Azure CLI, or ARM templates to create policy assignments.
30+
31+
:::image type="content" source="./media/policy/available-definitions.png" alt-text="Search for Cosmos DB built-in policy definitions":::
32+
33+
## Create a custom policy definition
34+
35+
For specific scenarios that are not addressed by built-in policies, you can create [a custom policy definition](../governance/policy/tutorials/create-custom-policy-definition.md). Later you create a Policy _assignment_ from your custom policy _definition_.
36+
37+
### Property types and property aliases in policy rules
38+
39+
Use the [custom policy definition steps](../governance/policy/tutorials/create-custom-policy-definition.md) to identify the resource properties and property aliases, which are required to create policy rules.
40+
41+
To identify Azure Cosmos DB specific property aliases, use the namespace `Microsoft.DocumentDB` with one of the methods shown in the custom policy definition steps article.
42+
43+
#### Use the Azure CLI:
44+
```azurecli-interactive
45+
# Login first with az login if not using Cloud Shell
46+
47+
# Get Azure Policy aliases for namespace Microsoft.DocumentDB
48+
az provider show --namespace Microsoft.DocumentDB --expand "resourceTypes/aliases" --query "resourceTypes[].aliases[].name"
49+
```
50+
51+
#### Use Azure PowerShell:
52+
```azurepowershell-interactive
53+
# Login first with Connect-AzAccount if not using Cloud Shell
54+
55+
# Use Get-AzPolicyAlias to list aliases for Microsoft.DocumentDB namespace
56+
(Get-AzPolicyAlias -NamespaceMatch 'Microsoft.DocumentDB').Aliases
57+
```
58+
59+
These commands output the list of property alias names for Azure Cosmos DB property. The following is an excerpt from the output:
60+
61+
```json
62+
[
63+
"Microsoft.DocumentDB/databaseAccounts/sku.name",
64+
"Microsoft.DocumentDB/databaseAccounts/virtualNetworkRules[*]",
65+
"Microsoft.DocumentDB/databaseAccounts/virtualNetworkRules[*].id",
66+
"Microsoft.DocumentDB/databaseAccounts/isVirtualNetworkFilterEnabled",
67+
"Microsoft.DocumentDB/databaseAccounts/consistencyPolicy.defaultConsistencyLevel",
68+
"Microsoft.DocumentDB/databaseAccounts/enableAutomaticFailover",
69+
"Microsoft.DocumentDB/databaseAccounts/Locations",
70+
"Microsoft.DocumentDB/databaseAccounts/Locations[*]",
71+
"Microsoft.DocumentDB/databaseAccounts/Locations[*].locationName",
72+
"..."
73+
]
74+
```
75+
76+
You can use any of these property alias names in the [custom policy definition rules](../governance/policy/tutorials/create-custom-policy-definition.md#policy-rule).
77+
78+
The following is an example policy definition that checks if an Azure Cosmos DB SQL database's provisioned throughput is greater than a maximum allowed limit of 400 RU/s. A custom policy definition includes two rules: one to check for the specific type of property alias, and the second one for the specific property of the type. Both rules use the alias names.
79+
80+
```json
81+
"policyRule": {
82+
"if": {
83+
"allOf": [
84+
{
85+
"field": "type",
86+
"equals": "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/throughputSettings"
87+
},
88+
{
89+
"field": "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/throughputSettings/default.resource.throughput",
90+
"greater": 400
91+
}
92+
]
93+
}
94+
}
95+
```
96+
97+
Custom policy definitions can be used to create policy assignments just like the built-in policy definitions are used.
98+
99+
## Policy compliance
100+
101+
After the policy assignments are created, Azure Policy evaluates the resources in the assignment's scope. Each resource's _compliance_ with the policy is assessed. The _effect_ specified in the policy is then applied to non-compliant resources.
102+
103+
You can review the compliance results and remediation details in the [Azure portal](../governance/policy/how-to/get-compliance-data.md#portal) or via the [Azure CLI](../governance/policy/how-to/get-compliance-data.md#command-line) or the [Azure Monitor logs](../governance/policy/how-to/get-compliance-data.md#azure-monitor-logs).
104+
105+
The following screenshot shows two example policy assignments. One assignment is based on a built-in policy definition, which checks that the Azure Cosmos DB resources are deployed only to the allowed Azure regions. The other assignment is based on a custom policy definition. This assignment checks that the provisioned throughput on Azure Cosmos DB resources does not exceed a specified maximum limit.
106+
107+
After the policy assignments are deployed, the compliance dashboard shows evaluation results. Note that this can take up to 30 minutes after deploying a policy assignment.
108+
109+
The screenshot shows the following compliance evaluation results:
110+
111+
- Zero out of one Azure Cosmos DB accounts in the specified scope are compliant with the policy assignment to check that resources were deployed to allowed regions.
112+
- One out of two Azure Cosmos DB database or collection resources in the specified scope are compliant with the policy assignment to check for provisioned throughput exceeding the specified maximum limit.
113+
114+
:::image type="content" source="./media/policy/compliance.png" alt-text="Search for Cosmos DB built-in policy definitions":::
115+
116+
To remediate the non-compliant resources, see the [remediated with Azure Policy](../governance/policy/how-to/remediate-resources.md) article.
117+
118+
## Next Steps
119+
120+
- [Review sample custom policy definitions for Azure Cosmos DB](https://github.com/Azure/azure-policy/tree/master/samples/CosmosDB)
121+
- [Create a policy assignment in the Azure portal](../governance/policy/assign-policy-portal.md)
122+
- [Review Azure Policy built-in policy definitions for Azure Cosmos DB](./policy-samples.md)

0 commit comments

Comments
 (0)