feat: Role v1 readiness

MIGRATION_GUIDE.md

@@ -20,6 +20,20 @@ They are all described in short in the [changes before v1 doc](./v1-preparations
 ### old grant resources removal
 Following the [announcement](https://github.com/Snowflake-Labs/terraform-provider-snowflake/discussions/2736) we have removed the old grant resources. The two resources [snowflake_role_ownership_grant](https://registry.terraform.io/providers/Snowflake-Labs/snowflake/latest/docs/resources/role_ownership_grant) and [snowflake_user_ownership_grant](https://registry.terraform.io/providers/Snowflake-Labs/snowflake/latest/docs/resources/user_ownership_grant) were not listed in the announcement, but they were also marked as deprecated ones. We are removing them too to conclude the grants redesign saga.
 
+### *(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:
+- `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`
+
 ### *(new feature)* Api authentication resources
 Added new api authentication resources, i.e.:
 - `snowflake_api_authentication_integration_with_authorization_code_grant`

docs/data-sources/roles.md

@@ -2,22 +2,56 @@
 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
 }
 
-data "snowflake_roles" "ad" {
-  pattern = "SYSADMIN"
+# 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 +60,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.