From 73b8afe7242d485c0891a768c95ee2e278fa25b0 Mon Sep 17 00:00:00 2001
From: Karl Persson <kalle.persson@grafana.com>
Date: Tue, 1 Jun 2021 15:52:46 +0200
Subject: [PATCH] Document global role and assignment for provisioning (#34739)

---
 .../enterprise/access-control/provisioning.md | 21 ++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/docs/sources/enterprise/access-control/provisioning.md b/docs/sources/enterprise/access-control/provisioning.md
index 27a1cd5e298..1f2a13995f9 100644
--- a/docs/sources/enterprise/access-control/provisioning.md
+++ b/docs/sources/enterprise/access-control/provisioning.md
@@ -27,7 +27,7 @@ To create or update custom roles, you can add a list of `roles` in the configura
 
 Note that in order to update a role, you would need to increment the [version]({{< relref "./roles.md#custom-roles" >}}). 
 
-It is only possibly to provision [organization local]({{< relref "./roles#role-scopes" >}}) roles. For creating or updating _global_ roles, refer to the [Fine-grained access control HTTP API]({{< relref "../../http_api/access_control.md" >}}).
+When setting the global flag on a role it overwrites the `orgId`.
 
 ### Delete roles 
 
@@ -110,6 +110,21 @@ roles:
       - name: "Editor"
         # <int> org id. will default to the role org id
         orgId: 1        
+  - name: GlobalReader
+    uid: globalreader
+    description: "Global Role for custom user reader"
+    version: 1
+    # <bool> overwrite org id and creates a global role
+    global: true
+    permissions:
+      - action: "users:read"
+        scope: "users:*"
+    builtInRoles:
+      - name: "Viewer"
+        orgId: 1        
+      - name: "Editor"
+        # <bool> overwrite org id and assign role globally
+        global: true
 ```
 
 ## Supported settings
@@ -132,8 +147,8 @@ A basic set of validation rules are applied to the input `yaml` files.
 ### Built-in role assignments
 
 - `name` must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`. 
-- When `orgId` is not specified, it inherits the `orgId` from `role`.
-- `orgId` in the `role` and in the assignment must be the same.
+- When `orgId` is not specified, it inherits the `orgId` from `role`. For global roles the default `orgId` is used.
+- `orgId` in the `role` and in the assignment must be the same for none global roles. 
 
 ### Role deletion