From e662bd8b541fd33769b9fff9f280b45d3c2755a4 Mon Sep 17 00:00:00 2001
From: Vardan Torosyan <vardants@gmail.com>
Date: Fri, 10 Oct 2025 10:48:58 +0200
Subject: [PATCH] Docs: Clarify role assignment to users and teams when using
 terraform (#112209)

---
 .../rbac-terraform-provisioning/index.md      | 32 ++++++++++++-------
 1 file changed, 21 insertions(+), 11 deletions(-)

diff --git a/docs/sources/administration/roles-and-permissions/access-control/rbac-terraform-provisioning/index.md b/docs/sources/administration/roles-and-permissions/access-control/rbac-terraform-provisioning/index.md
index 8dde070b315..3f3f6da58b0 100644
--- a/docs/sources/administration/roles-and-permissions/access-control/rbac-terraform-provisioning/index.md
+++ b/docs/sources/administration/roles-and-permissions/access-control/rbac-terraform-provisioning/index.md
@@ -95,7 +95,7 @@ provider "grafana" {
 
 ## Provision basic roles
 
-The following example shows how to assign basic roles to users, teams, and service accounts. Basic roles are predefined in Grafana and provide a set of permissions for common use cases.
+The following example shows how to assign basic roles to users and service accounts. Basic roles are predefined in Grafana and provide a set of permissions for common use cases.
 
 | Basic role      | UID                   |
 | --------------- | --------------------- |
@@ -107,11 +107,11 @@ The following example shows how to assign basic roles to users, teams, and servi
 
 You can use any of the basic role UIDs from the table above in your role assignments. For example, to assign the "None" role, use `basic_none` as the `role_uid`.
 
-```terraform
-resource "grafana_team" "viewer_team" {
-  name = "terraform_viewer_team"
-}
+{{< admonition type="note" >}}
+You can't assign basic roles to teams. To grant team permissions, assign a fixed or custom role to the team.
+{{< /admonition >}}
 
+```terraform
 resource "grafana_user" "editor_user" {
   email    = "terraform_editor@example.com"
   login    = "terraform_editor_user"
@@ -122,12 +122,6 @@ resource "grafana_service_account" "admin_sa" {
   name = "terraform_admin_sa"
 }
 
-# Assign Viewer role to a team
-resource "grafana_role_assignment" "viewer_role_assignment" {
-  role_uid = "basic_viewer"
-  teams    = [grafana_team.viewer_team.id]
-}
-
 # Assign Editor role to a user
 resource "grafana_role_assignment" "editor_role_assignment" {
   role_uid = "basic_editor"
@@ -141,6 +135,22 @@ resource "grafana_role_assignment" "admin_role_assignment" {
 }
 ```
 
+### Assign a fixed or custom role to a team
+
+Use fixed or custom roles to grant permissions to teams:
+
+```terraform
+resource "grafana_team" "writers_team" {
+  name = "terraform_writers_team"
+}
+
+# Assign a fixed role to a team
+resource "grafana_role_assignment" "writers_team_fixed_role" {
+  role_uid = "fixed:dashboards:writer"
+  teams    = [grafana_team.writers_team.id]
+}
+```
+
 ### Provision basic role to multiple users
 
 ```terraform