diff --git a/docs/sources/administration/roles-and-permissions/_index.md b/docs/sources/administration/roles-and-permissions/_index.md index c8135836fa1..7a33d940a15 100644 --- a/docs/sources/administration/roles-and-permissions/_index.md +++ b/docs/sources/administration/roles-and-permissions/_index.md @@ -35,10 +35,10 @@ For Grafana Cloud users, Grafana Support is not authorised to make org role chan ## Grafana server administrators -A Grafana server administrator manages server-wide settings and access to resources such as organizations, users, and licenses. Grafana includes a default server administrator that you can use to manage all of Grafana, or you can divide that responsibility among other server administrators that you create. +A Grafana server administrator (sometimes referred to as a **Grafana Admin**) manages server-wide settings and access to resources such as organizations, users, and licenses. Grafana includes a default server administrator that you can use to manage all of Grafana, or you can divide that responsibility among other server administrators that you create. -{{< admonition type="note" >}} -The server administrator role does not mean that the user is also a Grafana [organization administrator](#organization-roles). +{{< admonition type="caution" >}} +The server administrator role is distinct from the [organization administrator](#organization-roles) role. {{< /admonition >}} A server administrator can perform the following tasks: @@ -50,7 +50,7 @@ A server administrator can perform the following tasks: - Upgrade the server to Grafana Enterprise. {{< admonition type="note" >}} -The server administrator role does not exist in Grafana Cloud. +The server administrator (Grafana Admin) role does not exist in Grafana Cloud. {{< /admonition >}} To assign or remove server administrator privileges, see [Server user management](../user-management/server-user-management/assign-remove-server-admin-privileges/). diff --git a/docs/sources/administration/roles-and-permissions/access-control/manage-rbac-roles/index.md b/docs/sources/administration/roles-and-permissions/access-control/manage-rbac-roles/index.md index 40a6d3645af..b0f35087efc 100644 --- a/docs/sources/administration/roles-and-permissions/access-control/manage-rbac-roles/index.md +++ b/docs/sources/administration/roles-and-permissions/access-control/manage-rbac-roles/index.md @@ -53,6 +53,11 @@ refs: destination: /docs/grafana//administration/roles-and-permissions/access-control/custom-role-actions-scopes/ - pattern: /docs/grafana-cloud/ destination: /docs/grafana-cloud/account-management/authentication-and-permissions/access-control/custom-role-actions-scopes/ + rbac-terraform-provisioning: + - pattern: /docs/grafana/ + destination: /docs/grafana//administration/roles-and-permissions/access-control/rbac-terraform-provisioning/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/account-management/authentication-and-permissions/access-control/rbac-terraform-provisioning/ rbac-grafana-provisioning: - pattern: /docs/grafana/ destination: /docs/grafana//administration/roles-and-permissions/access-control/rbac-grafana-provisioning/ @@ -145,7 +150,13 @@ Refer to the [RBAC HTTP API](ref:api-rbac-get-a-role) for more details. ## Create custom roles -This section shows you how to create a custom RBAC role using Grafana provisioning and the HTTP API. +This section shows you how to create a custom RBAC role using Grafana provisioning or the HTTP API. + +Creating and editing custom roles is not currently possible in the Grafana UI. To manage custom roles, use one of the following methods: + +- [Provisioning](ref:rbac-grafana-provisioning) (for self-managed instances) +- [HTTP API](ref:api-rbac-create-a-new-custom-role) +- [Terraform](ref:rbac-terraform-provisioning) Create a custom role when basic roles and fixed roles do not meet your permissions requirements. @@ -153,14 +164,101 @@ Create a custom role when basic roles and fixed roles do not meet your permissio - [Plan your RBAC rollout strategy](ref:plan-rbac-rollout-strategy). - Determine which permissions you want to add to the custom role. To see a list of actions and scope, refer to [RBAC permissions, actions, and scopes](ref:custom-role-actions-scopes). -- [Enable role provisioning](ref:rbac-grafana-provisioning). - Ensure that you have permissions to create a custom role. - By default, the Grafana Admin role has permission to create custom roles. - A Grafana Admin can delegate the custom role privilege to another user by creating a custom role with the relevant permissions and adding the `permissions:type:delegate` scope. -### Create custom roles using provisioning +### Create custom roles using the HTTP API -[File-based provisioning](ref:rbac-grafana-provisioning) is one method you can use to create custom roles. +The following examples show you how to create a custom role using the Grafana HTTP API. For more information about the HTTP API, refer to [Create a new custom role](ref:api-rbac-create-a-new-custom-role). + +{{< admonition type="note" >}} +When you create a custom role you can only give it the same permissions you already have. For example, if you only have `users:create` permissions, then you can't create a role that includes other permissions. +{{< /admonition >}} + +The following example creates a `custom:users:admin` role and assigns the `users:create` action to it. + +**Example request** + +``` +curl --location --request POST '/api/access-control/roles/' \ +--header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "version": 1, + "uid": "jZrmlLCkGksdka", + "name": "custom:users:admin", + "displayName": "custom users admin", + "description": "My custom role which gives users permissions to create users", + "global": true, + "permissions": [ + { + "action": "users:create" + } + ] +}' +``` + +**Example response** + +``` +{ + "version": 1, + "uid": "jZrmlLCkGksdka", + "name": "custom:users:admin", + "displayName": "custom users admin", + "description": "My custom role which gives users permissions to create users", + "global": true, + "permissions": [ + { + "action": "users:create" + "updated": "2021-05-17T22:07:31.569936+02:00", + "created": "2021-05-17T22:07:31.569935+02:00" + } + ], + "updated": "2021-05-17T22:07:31.564403+02:00", + "created": "2021-05-17T22:07:31.564403+02:00" +} +``` + +Refer to the [RBAC HTTP API](ref:api-rbac-create-a-new-custom-role) for more details. + +### Create custom roles using Terraform + +You can use the [Grafana Terraform provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs) to manage custom roles and their assignments. This is the recommended method for Grafana Cloud users who want to manage RBAC as code. For more information, refer to [Provisioning RBAC with Terraform](ref:rbac-terraform-provisioning). + +The following example creates a custom role and assigns it to a team: + +```terraform +resource "grafana_role" "custom_folder_manager" { + name = "custom:folders:manager" + description = "Custom role for reading and creating folders" + uid = "custom-folders-manager" + version = 1 + global = true + + permissions { + action = "folders:read" + scope = "folders:*" + } + + permissions { + action = "folders:create" + scope = "folders:uid:general" # Allows creating folders at the root level + } +} + +resource "grafana_role_assignment" "custom_folder_manager_assignment" { + role_uid = grafana_role.custom_folder_manager.uid + teams = [""] +} +``` + +For more information, refer to the [`grafana_role`](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/role) and [`grafana_role_assignment`](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/role_assignment) documentation in the Terraform Registry. + +### Create custom roles using file-based provisioning + +You can use [file-based provisioning](ref:rbac-grafana-provisioning) to create custom roles for self-managed instances. 1. Open the YAML configuration file and locate the `roles` section. @@ -251,61 +349,6 @@ roles: state: 'absent' ``` -### Create custom roles using the HTTP API - -The following examples show you how to create a custom role using the Grafana HTTP API. For more information about the HTTP API, refer to [Create a new custom role](ref:api-rbac-create-a-new-custom-role). - -{{< admonition type="note" >}} -You cannot create a custom role with permissions that you do not have. For example, if you only have `users:create` permissions, then you cannot create a role that includes other permissions. -{{< /admonition >}} - -The following example creates a `custom:users:admin` role and assigns the `users:create` action to it. - -**Example request** - -``` -curl --location --request POST '/api/access-control/roles/' \ ---header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "version": 1, - "uid": "jZrmlLCkGksdka", - "name": "custom:users:admin", - "displayName": "custom users admin", - "description": "My custom role which gives users permissions to create users", - "global": true, - "permissions": [ - { - "action": "users:create" - } - ] -}' -``` - -**Example response** - -``` -{ - "version": 1, - "uid": "jZrmlLCkGksdka", - "name": "custom:users:admin", - "displayName": "custom users admin", - "description": "My custom role which gives users permissions to create users", - "global": true, - "permissions": [ - { - "action": "users:create" - "updated": "2021-05-17T22:07:31.569936+02:00", - "created": "2021-05-17T22:07:31.569935+02:00" - } - ], - "updated": "2021-05-17T22:07:31.564403+02:00", - "created": "2021-05-17T22:07:31.564403+02:00" -} -``` - -Refer to the [RBAC HTTP API](ref:api-rbac-create-a-new-custom-role) for more details. - ## Update basic role permissions If the default basic role definitions do not meet your requirements, you can change their permissions. diff --git a/docs/sources/administration/roles-and-permissions/access-control/rbac-grafana-provisioning/index.md b/docs/sources/administration/roles-and-permissions/access-control/rbac-grafana-provisioning/index.md index 06f9699533b..fe45a620bc5 100644 --- a/docs/sources/administration/roles-and-permissions/access-control/rbac-grafana-provisioning/index.md +++ b/docs/sources/administration/roles-and-permissions/access-control/rbac-grafana-provisioning/index.md @@ -6,7 +6,6 @@ description: Learn about RBAC Grafana provisioning and view an example YAML prov file that configures Grafana role assignments. labels: products: - - cloud - enterprise menuTitle: Provisioning RBAC with Grafana title: Provisioning RBAC with Grafana @@ -52,11 +51,13 @@ refs: # Provisioning RBAC with Grafana {{< admonition type="note" >}} -Available in [Grafana Enterprise](/docs/grafana//introduction/grafana-enterprise/) and [Grafana Cloud](/docs/grafana-cloud). +Available in [Grafana Enterprise](/docs/grafana//introduction/grafana-enterprise/) for self-managed instances. This feature is not available in Grafana Cloud. {{< /admonition >}} You can create, change or remove [Custom roles](ref:manage-rbac-roles-create-custom-roles-using-provisioning) and create or remove [basic role assignments](ref:assign-rbac-roles-assign-a-fixed-role-to-a-basic-role-using-provisioning), by adding one or more YAML configuration files in the `provisioning/access-control/` directory. +Because this method requires access to the file system where Grafana is running, it's only available for self-managed Grafana instances. To provision RBAC in Grafana Cloud, use [Terraform](ref:rbac-terraform-provisioning) or the [HTTP API](ref:api-rbac-create-and-manage-custom-roles). + Grafana performs provisioning during startup. After you make a change to the configuration file, you can reload it during runtime. You do not need to restart the Grafana server for your changes to take effect. **Before you begin:**