feat: Role v1 readiness (#2916)

Changes:
- resource added/adjusted
- added `account_role` resource (the old one shares the same
implementation as the new one, but it has the deprecation message) to
fit with other resources that work with roles (mostly grants)
  - added show output attribute
- data source adjusted
  - structure and attribute names adjusted to the conventions
- documentation
  - Entries added to the migration guide
- Examples adjusted (adjusted the old role documentation and replaced
deprecated role resource with the new one in the examples for other
resources)
  - Added V1 release candidate note

## Test Plan
<!-- detail ways in which this PR has been tested or needs to be tested
-->
* [x] acceptance tests adjusted to the standard ones

## References
<!-- issues documentation links, etc  -->

* [CREATE
ROLE](https://docs.snowflake.com/en/sql-reference/sql/create-role)

MIGRATION_GUIDE.md

@@ -4,6 +4,23 @@ This document is meant to help you migrate your Terraform config to the new newe
 describe deprecations or breaking changes and help you to change your configuration to keep the same (or similar) behavior
 across different versions.
 
+## v0.93.0 ➞ v0.94.0
+
+### *(new feature)* new snowflake_account_role resource
+
+Already existing `snowflake_role` was deprecated in favor of the new `snowflake_account_role`. The old resource got upgraded to
+have the same features as the new one. The only difference is the deprecation message on the old resource.
+
+New fields:
+- added `show_output` field that holds the response from SHOW ROLES. Remember that the field will be only recomputed if one of the fields (`name` or `comment`) are changed.
+
+### *(breaking change)* refactored snowflake_roles data source
+
+Changes:
+- New `in_class` filtering option to filter out roles by class name, e.g. `in_class = "SNOWFLAKE.CORE.BUDGET"`
+- `pattern` was renamed to `like`
+- output of SHOW is enclosed in `show_output`, so before, e.g. `roles.0.comment` is now `roles.0.show_output.0.comment`
+
 ## v0.92.0 ➞ v0.93.0
 
 ### general changes

docs/data-sources/roles.md

@@ -2,22 +2,65 @@
 page_title: "snowflake_roles Data Source - terraform-provider-snowflake"
 subcategory: ""
 description: |-
-  
+  Datasource used to get details of filtered roles. Filtering is aligned with the current possibilities for SHOW ROLES https://docs.snowflake.com/en/sql-reference/sql/show-roles query (like and in_class are all supported). The results of SHOW are encapsulated in one output collection.
 ---
 
-# snowflake_roles (Data Source)
+!> **V1 release candidate** This resource was reworked and is a release candidate for the V1. We do not expect significant changes in it before the V1. We will welcome any feedback and adjust the resource if needed. Any errors reported will be resolved with a higher priority. We encourage checking this resource out before the V1 release. Please follow the [migration guide](https://github.com/Snowflake-Labs/terraform-provider-snowflake/blob/main/MIGRATION_GUIDE.md#v0920--v0930) to use it.
 
+# snowflake_roles (Data Source)
 
+Datasource used to get details of filtered roles. Filtering is aligned with the current possibilities for [SHOW ROLES](https://docs.snowflake.com/en/sql-reference/sql/show-roles) query (`like` and `in_class` are all supported). The results of SHOW are encapsulated in one output collection.
 
 ## Example Usage
 
 ```terraform
-data "snowflake_roles" "this" {
+# Simple usage
+data "snowflake_roles" "simple" {
+}
+
+output "simple_output" {
+  value = data.snowflake_roles.simple.roles
+}
+
+# Filtering (like)
+data "snowflake_roles" "like" {
+  like = "role-name"
+}
+
+output "like_output" {
+  value = data.snowflake_roles.like.roles
+}
 
+# Filtering (in class)
+data "snowflake_roles" "in_class" {
+  in_class = "SNOWFLAKE.CORE.BUDGET"
 }
 
-data "snowflake_roles" "ad" {
-  pattern = "SYSADMIN"
+output "in_class_output" {
+  value = data.snowflake_roles.in_class.roles
+}
+
+# Ensure the number of roles is equal to at least one element (with the use of postcondition)
+data "snowflake_roles" "assert_with_postcondition" {
+  like = "role-name-%"
+  lifecycle {
+    postcondition {
+      condition     = length(self.roles) > 0
+      error_message = "there should be at least one role"
+    }
+  }
+}
+
+# Ensure the number of roles is equal to at exactly one element (with the use of check block)
+check "role_check" {
+  data "snowflake_roles" "assert_with_check_block" {
+    like = "role-name"
+  }
+
+  assert {
+    condition     = length(data.snowflake_roles.assert_with_check_block.roles) == 1
+    error_message = "Roles filtered by '${data.snowflake_roles.assert_with_check_block.like}' returned ${length(data.snowflake_roles.assert_with_check_block.roles)} roles where one was expected"
+  }
 }
 ```
 
@@ -26,18 +69,33 @@ data "snowflake_roles" "ad" {
 
 ### Optional
 
-- `pattern` (String) Filters the command output by object name.
+- `in_class` (String) Filters the SHOW GRANTS output by class name.
+- `like` (String) Filters the output with **case-insensitive** pattern, with support for SQL wildcard characters (`%` and `_`).
 
 ### Read-Only
 
 - `id` (String) The ID of this resource.
-- `roles` (List of Object) List of all the roles which you can view across your entire account, including the system-defined roles and any custom roles that exist. (see [below for nested schema](#nestedatt--roles))
+- `roles` (List of Object) Holds the aggregated output of all role details queries. (see [below for nested schema](#nestedatt--roles))
 
 <a id="nestedatt--roles"></a>
 ### Nested Schema for `roles`
 
 Read-Only:
 
+- `show_output` (List of Object) (see [below for nested schema](#nestedobjatt--roles--show_output))
+
+<a id="nestedobjatt--roles--show_output"></a>
+### Nested Schema for `roles.show_output`
+
+Read-Only:
+
+- `assigned_to_users` (Number)
 - `comment` (String)
+- `created_on` (String)
+- `granted_roles` (Number)
+- `granted_to_roles` (Number)
+- `is_current` (Boolean)
+- `is_default` (Boolean)
+- `is_inherited` (Boolean)
 - `name` (String)
 - `owner` (String)

docs/index.md

@@ -231,6 +231,7 @@ The Snowflake provider will use the following order of precedence when determini
 
 - [snowflake_database_old](./docs/resources/database_old)
 - [snowflake_oauth_integration](./docs/resources/oauth_integration)
+- [snowflake_role](./docs/resources/role) - use [snowflake_account_role](./docs/resources/account_role) instead
 - [snowflake_saml_integration](./docs/resources/saml_integration) - use [snowflake_saml2_integration](./docs/resources/saml2_integration) instead
 - [snowflake_unsafe_execute](./docs/resources/unsafe_execute)
 

docs/resources/account_role.md

@@ -0,0 +1,67 @@
+---
+page_title: "snowflake_account_role Resource - terraform-provider-snowflake"
+subcategory: ""
+description: |-
+  The resource is used for role management, where roles can be assigned privileges and, in turn, granted to users and other roles. When granted to roles they can create hierarchies of privilege structures. For more details, refer to the official documentation https://docs.snowflake.com/en/user-guide/security-access-control-overview.
+---
+
+!> **V1 release candidate** This resource was reworked and is a release candidate for the V1. We do not expect significant changes in it before the V1. We will welcome any feedback and adjust the resource if needed. Any errors reported will be resolved with a higher priority. We encourage checking this resource out before the V1 release. Please follow the [migration guide](https://github.com/Snowflake-Labs/terraform-provider-snowflake/blob/main/MIGRATION_GUIDE.md#v0920--v0930) to use it.
+
+# snowflake_account_role (Resource)
+
+The resource is used for role management, where roles can be assigned privileges and, in turn, granted to users and other roles. When granted to roles they can create hierarchies of privilege structures. For more details, refer to the [official documentation](https://docs.snowflake.com/en/user-guide/security-access-control-overview).
+
+## Example Usage
+
+```terraform
+## Minimal
+resource "snowflake_account_role" "minimal" {
+  name = "role_name"
+}
+
+## Complete (with every optional set)
+resource "snowflake_account_role" "complete" {
+  name    = "role_name"
+  comment = "my account role"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `name` (String)
+
+### Optional
+
+- `comment` (String)
+
+### Read-Only
+
+- `id` (String) The ID of this resource.
+- `show_output` (List of Object) Outputs the result of `SHOW ROLES` for the given role. (see [below for nested schema](#nestedatt--show_output))
+
+<a id="nestedatt--show_output"></a>
+### Nested Schema for `show_output`
+
+Read-Only:
+
+- `assigned_to_users` (Number)
+- `comment` (String)
+- `created_on` (String)
+- `granted_roles` (Number)
+- `granted_to_roles` (Number)
+- `is_current` (Boolean)
+- `is_default` (Boolean)
+- `is_inherited` (Boolean)
+- `name` (String)
+- `owner` (String)
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+terraform import snowflake_account_role.example "name"
+```

docs/resources/grant_account_role.md

@@ -16,25 +16,25 @@ description: |-
 ### grant account role to account role
 ##################################
 
-resource "snowflake_role" "role" {
+resource "snowflake_account_role" "role" {
   name = var.role_name
 }
 
-resource "snowflake_role" "parent_role" {
+resource "snowflake_account_role" "parent_role" {
   name = var.parent_role_name
 }
 
 resource "snowflake_grant_account_role" "g" {
-  role_name        = snowflake_role.role.name
-  parent_role_name = snowflake_role.parent_role.name
+  role_name        = snowflake_account_role.role.name
+  parent_role_name = snowflake_account_role.parent_role.name
 }
 
 
 ##################################
 ### grant account role to user
 ##################################
 
-resource "snowflake_role" "role" {
+resource "snowflake_account_role" "role" {
   name = var.role_name
 }
 

docs/resources/grant_application_role.md

@@ -21,13 +21,13 @@ locals {
 ##################################
 
 
-resource "snowflake_role" "role" {
+resource "snowflake_account_role" "role" {
   name = "my_role"
 }
 
 resource "snowflake_grant_application_role" "g" {
   application_role_name    = local.application_role_identifier
-  parent_account_role_name = snowflake_role.role.name
+  parent_account_role_name = snowflake_account_role.role.name
 }
 
 ##################################

docs/resources/grant_database_role.md

@@ -21,13 +21,13 @@ resource "snowflake_database_role" "database_role" {
   name     = var.database_role_name
 }
 
-resource "snowflake_role" "parent_role" {
+resource "snowflake_account_role" "parent_role" {
   name = var.parent_role_name
 }
 
 resource "snowflake_grant_database_role" "g" {
   database_role_name = "\"${var.database}\".\"${snowflake_database_role.database_role.name}\""
-  parent_role_name   = snowflake_role.parent_role.name
+  parent_role_name   = snowflake_account_role.parent_role.name
 }
 
 ##################################

docs/resources/grant_ownership.md

@@ -21,7 +21,7 @@ description: |-
 ### on object to account role
 ##################################
 
-resource "snowflake_role" "test" {
+resource "snowflake_account_role" "test" {
   name = "test_role"
 }
 
@@ -74,7 +74,7 @@ resource "snowflake_grant_ownership" "test" {
 ### on all tables in database to account role
 ##################################
 
-resource "snowflake_role" "test" {
+resource "snowflake_account_role" "test" {
   name = "test_role"
 }
 
@@ -96,7 +96,7 @@ resource "snowflake_grant_ownership" "test" {
 ### on all tables in schema to account role
 ##################################
 
-resource "snowflake_role" "test" {
+resource "snowflake_account_role" "test" {
   name = "test_role"
 }
 
@@ -123,7 +123,7 @@ resource "snowflake_grant_ownership" "test" {
 ### on future tables in database to account role
 ##################################
 
-resource "snowflake_role" "test" {
+resource "snowflake_account_role" "test" {
   name = "test_role"
 }
 
@@ -145,7 +145,7 @@ resource "snowflake_grant_ownership" "test" {
 ### on future tables in schema to account role
 ##################################
 
-resource "snowflake_role" "test" {
+resource "snowflake_account_role" "test" {
   name = "test_role"
 }
 
@@ -172,7 +172,7 @@ resource "snowflake_grant_ownership" "test" {
 ### RoleBasedAccessControl (RBAC example)
 ##################################
 
-resource "snowflake_role" "test" {
+resource "snowflake_account_role" "test" {
   name = "role"
 }
 
@@ -181,22 +181,22 @@ resource "snowflake_database" "test" {
 }
 
 resource "snowflake_grant_ownership" "test" {
-  account_role_name = snowflake_role.test.name
+  account_role_name = snowflake_account_role.test.name
   on {
     object_type = "DATABASE"
     object_name = snowflake_database.test.name
   }
 }
 
 resource "snowflake_grant_account_role" "test" {
-  role_name = snowflake_role.test.name
+  role_name = snowflake_account_role.test.name
   user_name = "username"
 }
 
 provider "snowflake" {
   profile = "default"
   alias   = "secondary"
-  role    = snowflake_role.test.name
+  role    = snowflake_account_role.test.name
 }
 
 ## With ownership on the database, the secondary provider is able to create schema on it without any additional privileges.