update policy def datasource docs and error messages (hashicorp#20510)

wuxu92 · Feb 17, 2023 · b55de71 · b55de71
1 parent 2829439
commit b55de71
Show file tree

Hide file tree

Showing 3 changed files with 4 additions and 4 deletions.
diff --git a/CHANGELOG-v2.md b/CHANGELOG-v2.md
@@ -1099,7 +1099,7 @@ FEATURES:
 ENHANCEMENTS:
 
 * `azurerm_api_management_named_value` - support for system managed identities ([#12938](https://github.com/hashicorp/terraform-provider-azurerm/issues/12938))
-* `azurerm_application_insights_smart_detection_rule` - support all currenly availible rules in the SDK ([#12857](https://github.com/hashicorp/terraform-provider-azurerm/issues/12857))
+* `azurerm_application_insights_smart_detection_rule` - support all currently available rules in the SDK ([#12857](https://github.com/hashicorp/terraform-provider-azurerm/issues/12857))
 * `azurerm_function_app` - add support for `dotnet_framework_version` in ([#12883](https://github.com/hashicorp/terraform-provider-azurerm/issues/12883))
 * `azurerm_resource_group` - conditionally (based on the `prevent_deletion_if_contains_resources` features flag - see the 'Upgrade Notes' section) checking for nested Resources during deletion of the Resource Group and raising an error if Resources are found ([#12657](https://github.com/hashicorp/terraform-provider-azurerm/issues/12657))
 

diff --git a/internal/services/policy/policy.go b/internal/services/policy/policy.go
@@ -37,12 +37,12 @@ func getPolicyDefinitionByDisplayName(ctx context.Context, client *policy.Defini
 
 	// we found none
 	if len(results) == 0 {
-		return policy.Definition{}, fmt.Errorf("loading Policy Definition List: could not find policy '%s'", displayName)
+		return policy.Definition{}, fmt.Errorf("loading Policy Definition List: could not find policy '%s'. has the policies name changed? list available with `az policy definition list`", displayName)
 	}
 
 	// we found more than one
 	if len(results) > 1 {
-		return policy.Definition{}, fmt.Errorf("loading Policy Definition List: found more than one policy '%s'", displayName)
+		return policy.Definition{}, fmt.Errorf("loading Policy Definition List: found more than one (%d) policy '%s'", len(results), displayName)
 	}
 
 	return results[0], nil

diff --git a/website/docs/d/policy_definition.html.markdown b/website/docs/d/policy_definition.html.markdown
@@ -28,7 +28,7 @@ output "id" {
 
 * `display_name` - Specifies the display name of the Policy Definition. Conflicts with `name`.
 
-~> **NOTE** As `display_name` is not unique errors may occur when there are multiple policy definitions with same display name.
+~> **NOTE** Looking up policies by `display_name` is not recommended by the Azure Policy team as the property is not unique nor immutable. As such errors may occur when there are multiple policy definitions with same display name or the display name is changed. To avoid these types of errors you may wish to use the `name` property instead.
 
 * `management_group_name` - (Optional) Only retrieve Policy Definitions from this Management Group.