add warnings to custom roles docs

hashicorp · Aug 27, 2018 · 2fc22d6 · 2fc22d6
1 parent b36397c
commit 2fc22d6
Show file tree

Hide file tree

Showing 2 changed files with 14 additions and 2 deletions.
diff --git a/website/docs/r/google_organization_iam_custom_role.html.markdown b/website/docs/r/google_organization_iam_custom_role.html.markdown
@@ -13,6 +13,13 @@ Allows management of a customized Cloud IAM organization role. For more informat
 and
 [API](https://cloud.google.com/iam/reference/rest/v1/organizations.roles).
 
+~> **Warning:** Note that custom roles in GCP have the concept of a soft-delete. There are two issues that may arise
+ from this and how roles are propagated. 1) creating a role may involve undeleting and then updating a role with the
+ same name, possibly causing confusing behavior between undelete and update. 2) A deleted role is permanently deleted
+ after 7 days, but it can take up to 30 more days (i.e. between 7 and 37 days after deletion) before the role name is
+ made available again. This means a deleted role that has been deleted for more than 7 days cannot be changed at all
+ by Terraform, and new roles cannot share that name.
+
 ## Example Usage
 
 This snippet creates a customized IAM organization role.

diff --git a/website/docs/r/google_project_iam_custom_role.html.markdown b/website/docs/r/google_project_iam_custom_role.html.markdown
@@ -13,6 +13,13 @@ Allows management of a customized Cloud IAM project role. For more information s
 and
 [API](https://cloud.google.com/iam/reference/rest/v1/projects.roles).
 
+~> **Warning:** Note that custom roles in GCP have the concept of a soft-delete. There are two issues that may arise
+ from this and how roles are propagated. 1) creating a role may involve undeleting and then updating a role with the
+ same name, possibly causing confusing behavior between undelete and update. 2) A deleted role is permanently deleted
+ after 7 days, but it can take up to 30 more days (i.e. between 7 and 37 days after deletion) before the role name is
+ made available again. This means a deleted role that has been deleted for more than 7 days cannot be changed at all
+ by Terraform, and new roles cannot share that name.
+
 ## Example Usage
 
 This snippet creates a customized IAM role.
@@ -45,8 +52,6 @@ The following arguments are supported:
 
 * `description` - (Optional) A human-readable description for the role.
 
-* `deleted` - (Optional) The current deleted state of the role. Defaults to `false`.
-
 ## Import
 
 Customized IAM project role can be imported using their URI, e.g.