docs/sources/administration/roles-and-permissions/access-control/rbac-grafana-provisioning/index.md
{{< admonition type="note" >}} Available in Grafana Enterprise for self-managed instances. This feature is not available in Grafana Cloud. {{< /admonition >}}
You can create, change or remove Custom roles and create or remove basic role assignments, 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 or the HTTP API.
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:
To manage and assign RBAC roles using provisioning:
Sign in to the Grafana server.
Locate the Grafana provisioning folder.
Create a new YAML in the following folder: provisioning/access-control. For example, provisioning/access-control/custom-roles.yml
Add RBAC provisioning details to the configuration file.
Refer to Manage RBAC roles and Assign RBAC roles for instructions.
Refer to example role provisioning file for a complete example of a provisioning file.
Reload the provisioning configuration file.
For more information about reloading the provisioning configuration at runtime, refer to Reload provisioning configurations.
The following example shows a complete YAML configuration file that:
---
# config file version
apiVersion: 2
# <list> list of roles to insert/update/delete
roles:
# <string, required> name of the role you want to create or update. Required.
- name: 'custom:users:writer'
# <string> uid of the role. Has to be unique for all orgs.
uid: customuserswriter1
# <string> description of the role, informative purpose only.
description: 'Create, read, write users'
# <int> version of the role. Has to be greater than the stored role version to apply updates. Increase by 1 when you change the role.
version: 2
# <int> org id. Defaults to Grafana's default if not specified.
orgId: 1
# <list> list of the permissions granted by this role.
permissions:
# <string, required> action allowed.
- action: 'users:read'
#<string> scope it applies to.
scope: 'users:*'
- action: 'users:write'
scope: 'users:*'
- action: 'users:create'
# Optional `datasourceType` for scopes `datasources:uid:<DATASOURCE_UID>`.
# If you omit it, Grafana resolves the plugin type from the data source when this file is provisioned.
# It is required if there are two datasources with the same uid.
- action: 'datasources:query'
scope: 'datasources:uid:loki-uid-here'
datasourceType: loki
- name: 'custom:global:users:reader'
# <bool> overwrite org id and creates a global role.
global: true
# <string> state of the role. Defaults to 'present'. If 'absent', role will be deleted.
state: 'absent'
# <bool> force deletion revoking all grants of the role.
force: true
- uid: 'basic_editor'
# <bool> always apply the specified changes to the role, regardless of the role version in the database
overrideRole: true
global: true
# <list> list of roles to copy permissions from.
from:
- uid: 'basic_editor'
global: true
- name: 'fixed:users:writer'
global: true
# <list> list of the permissions to add/remove on top of the copied ones.
permissions:
- action: 'users:read'
scope: 'users:*'
- action: 'users:write'
scope: 'users:*'
# <string> state of the permission. Defaults to 'present'. If 'absent', the permission will be removed.
state: absent
# <list> list role assignments to teams to create or remove.
teams:
# <string, required> name of the team you want to assign roles to. Required.
- name: 'Users writers'
# <int> org id. Will default to Grafana's default if not specified.
orgId: 1
# <list> list of roles to assign to the team
roles:
# <string> uid of the role you want to assign to the team.
- uid: 'customuserswriter1'
# <int> org id. Will default to Grafana's default if not specified.
orgId: 1
# <string> name of the role you want to assign to the team.
- name: 'fixed:users:writer'
# <bool> overwrite org id to specify the role is global.
global: true
# <string> state of the assignment. Defaults to 'present'. If 'absent', the assignment will be revoked.
state: absent