public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: Refactor administration docs (#50592)

Browse Source 
* Move data source management to administration

* Move RBAC to administration

* Move team management up a docs org level

* Combine and rename admin preferences docs

* Move plugin management to administration

* Combine plugin management docs

* Combine API key docs

* Combine service account docs

* Combine server user management docs

* Move datasource management to administration

* Move enterprise licenses to administration

* Move CLI out of admin, update links to admin

* Merge org user management docs

* Restructure to Torkel's plan

* Fix typo

* Weigh admin topics for navigation

* Weigh administration topics and align to Torkel's plan

* Move server user management from server admin to admin/user management

* Move configure docker image to setup guide

* Move the remaining server admin docs to the root admin directory

* Reweight docker config
This commit is contained in:
Garrett Guillotte
2022-06-16 21:09:16 +02:00
committed by GitHub
parent c043a8818a
commit 845cebdee2
105 changed files with 1602 additions and 1710 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/enterprise/_index.md
+2 -2
View File
@@ -58,8 +58,8 @@ With [enhanced LDAP integration]({{< relref "../setup-grafana/configure-security
Grafana Enterprise adds the following features:
- [Role-based access control]({{< relref "access-control/" >}}) to control access with role-based permissions.
- [Data source permissions]({{< relref "datasource_permissions/" >}}) to restrict query access to specific teams and users.
- [Role-based access control]({{< relref "../administration/roles-and-permissions/access-control/" >}}) to control access with role-based permissions.
- [Data source permissions]({{< relref "../administration/data-source-management/" >}}) to restrict query access to specific teams and users.
- [Data source query caching]({{< relref "query-caching/" >}}) to temporarily store query results in Grafana to reduce data source load and rate limiting.
- [Reporting]({{< relref "reporting/" >}}) to generate a PDF report from any dashboard and set up a schedule to have it emailed to whoever you choose.
- [Export dashboard as PDF]({{< relref "export-pdf/" >}})
docs/sources/enterprise/access-control/_index.md
-16
View File
@@ -1,16 +0,0 @@
---
aliases:
- /docs/grafana/latest/enterprise/access-control/
description: RBAC provides a standardized way of granting, changing, and revoking
access when it comes to viewing and modifying Grafana resources, such as users and
reports.
menuTitle: Role-based access control (RBAC)
title: Grafana Role-based access control (RBAC)
weight: 120
---
# Role-based access control (RBAC)
RBAC provides a standardized way of granting, changing, and revoking access when it comes to viewing and modifying Grafana resources, such as dashboards, reports, and administrative settings.
{{< section >}}
docs/sources/enterprise/access-control/about-rbac.md
-111
View File
@@ -1,111 +0,0 @@
---
aliases:
- /docs/grafana/latest/enterprise/access-control/
- /docs/grafana/latest/enterprise/access-control/about-rbac/
- /docs/grafana/latest/enterprise/access-control/roles/
description: Role-based access control (RBAC) provides a standardized way of granting,
changing, and revoking access so that users can view and modify Grafana resources,
such as users and reports.
menuTitle: About RBAC
title: About RBAC in Grafana
weight: 10
---
# About RBAC
Role-based access control (RBAC) provides a standardized way of granting, changing, and revoking access so that users can view and modify Grafana resources, such as users and reports.
RBAC extends Grafana basic roles that are included in Grafana OSS, and enables you more granular control of users’ actions.
By using RBAC you can provide users with permissions that extend the permissions available with basic roles. For example, you can use RBAC to:
- Modify existing basic roles: for example, enable an editor to create reports
- Assign fixed roles to users and teams: for example, grant an engineering team the ability to create data sources
- Create custom roles: for example, a role that allows users to create and edit dashboards, but not delete them
RBAC roles contain multiple permissions, each of which has an action and a scope:
- **Role:** `fixed:datasources:reader`
- **Permission:**
- **Action:** `datasources:read`
- **Scope:** `datasources:*`
## Basic roles
Basic roles are the standard roles that are available in Grafana OSS. If you have purchased a Grafana Enterprise license, you can still use basic roles.
Grafana includes the following basic roles:
- Grafana administrator
- Organization administrator
- Editor
- Viewer
Each basic role is comprised of a number of _permissions_. For example, the viewer basic role contains the following permissions among others:
- `Action: datasources.id:read, Scope: datasources:*`: Enables the viewer to see the ID of a data source.
- `Action: orgs:read`: Enables the viewer to see their organization details
- `Action: annotations:read, Scope: annotations:*`: Enables the viewer to see annotations that other users have added to a dashboard.
- `Action: annotations:create, Scope: annotations:type:dashboard`: Enables the viewer to add annotations to a dashboard.
- `Action: annotations:write, Scope: annotations:type:dashboard`: Enables the viewer to modify annotations of a dashboard.
- `Action: annotations:delete, Scope: annotations:type:dashboard`: Enables the viewer to remove annotations from a dashboard.
> **Note:** You can't have a Grafana user without a basic role assigned.
### Basic role modification
You can use RBAC to modify the permissions associated with any basic role, which changes what viewers, editors, or admins can do. You can't delete basic roles.
Note that any modification to any of these basic role is not propagated to the other basic roles.
For example, if you modify Viewer basic role and grant additional permission, Editors or Admins won't have that additional grant.
For more information about the permissions associated with each basic role, refer to [Basic role definitions]({{< relref "rbac-fixed-basic-role-definitions/#basic-role-assignments" >}}).
To interact with the API and view or modify basic roles permissions, refer to [the table]({{< relref "manage-rbac-roles/#basic-role-uid-mapping" >}}) that maps basic role names to the associated UID.
## Fixed roles
Grafana Enterprise includes the ability for you to assign discrete fixed roles to users, teams, and service accounts. This gives you fine-grained control over user permissions than you would have with basic roles alone. These roles are called "fixed" because you cannot change or delete fixed roles. You can also create _custom_ roles of your own; see more information in the [custom roles section]({{< relref "#custom-roles" >}}) below.
Assign fixed roles when the basic roles do not meet your permission requirements. For example, you might want a user with the basic viewer role to also edit dashboards. Or, you might want anyone with the editor role to also add and manage users. Fixed roles provide users more granular access to create, view, and update the following Grafana resources:
- [Alerting]({{< relref "../../alerting/" >}})
- [Annotations]({{< relref "../../dashboards/annotations/" >}})
- [API keys]({{< relref "../../administration/api-keys/" >}})
- [Dashboards and folders]({{< relref "../../dashboards/" >}})
- [Data sources]({{< relref "../../datasources/" >}})
- [Explore]({{< relref "../../explore/" >}})
- [Folders]({{< relref "../../dashboards/dashboard-folders/" >}})
- [LDAP]({{< relref "../../setup-grafana/configure-security/configure-authentication/ldap/" >}})
- [Licenses]({{< relref "../license/" >}})
- [Organizations]({{< relref "../../administration/manage-organizations/" >}})
- [Provisioning]({{< relref "../../administration/provisioning/" >}})
- [Reports]({{< relref "../reporting/" >}})
- [Roles]({{< relref "../../administration/manage-users-and-permissions/" >}})
- [Settings]({{< relref "../settings-updates/" >}})
- [Service accounts]({{< relref "../../administration/service-accounts/" >}})
- [Teams]({{< relref "../../administration/manage-users-and-permissions/manage-teams/" >}})
- [Users]({{< relref "../../administration/manage-users-and-permissions/manage-server-users/" >}})
To learn more about the permissions you can grant for each resource, refer to [RBAC role definitions]({{< relref "rbac-fixed-basic-role-definitions/" >}}).
## Custom roles
If you are a Grafana Enterprise customer, you can create custom roles to manage user permissions in a way that meets your security requirements.
Custom roles contain unique combinations of permissions _actions_ and _scopes_. An action defines the action a use can perform on a Grafana resource. For example, the `teams.roles:read` action allows a user to see a list of roles associated with each team.
A scope describes where an action can be performed. For example, the `teams:id:1` scope restricts the user's action to the team with ID `1`. When paired with the `teams.roles:read` action, this permission prohibits the user from viewing the roles for teams other than team `1`.
Consider creating a custom role when fixed roles do not meet your permissions requirements.
### Custom role creation
You can use either of the following methods to create, assign, and manage custom roles:
- Grafana provisioning: You can use a YAML file to configure roles. For more information about using provisioning to create custom roles, refer to [Manage RBAC roles]({{< relref "manage-rbac-roles/" >}}). For more information about using provisioning to assign RBAC roles to users or teams, refer to [Assign RBAC roles]({{< relref "assign-rbac-roles/" >}}).
- RBAC API: As an alternative, you can use the Grafana HTTP API to create and manage roles. For more information about the HTTP API, refer to [RBAC API]({{< relref "../../developers/http_api/access_control/" >}}).
## Limitation
If you have created a folder with the name `General` or `general`, you cannot manage its permissions with RBAC.
If you set [folder permissions]({{< relref "../../administration/manage-users-and-permissions/manage-dashboard-permissions/" >}}) for a folder named `General` or `general`, the system disregards the folder when RBAC is enabled.
docs/sources/enterprise/access-control/assign-rbac-roles.md
-192
View File
@@ -1,192 +0,0 @@
---
aliases:
- /docs/grafana/latest/enterprise/access-control/assign-rbac-roles/
- /docs/grafana/latest/enterprise/access-control/manage-role-assignments/manage-built-in-role-assignments/
- /docs/grafana/latest/enterprise/access-control/manage-role-assignments/manage-user-role-assignments/
description: Learn how to assign RBAC roles to users and teams in Grafana.
menuTitle: Assign RBAC roles
title: Assign Grafana RBAC roles
weight: 40
---
# Assign RBAC roles
In this topic you'll learn how to use the role picker, provisioning, and the HTTP API to assign fixed and custom roles to users and teams.
## Assign fixed roles in the UI using the role picker
This section describes how to:
- Assign a fixed role to a user or team as an organization administrator.
- Assign a fixed role to a user as a server administrator. This approach enables you to assign a fixed role to a user in multiple organizations, without needing to switch organizations.
In both cases, the assignment applies only to the user or team within the affected organization, and no other organizations. For example, if you grant the user the **Data source editor** role in the **Main** organization, then the user can edit data sources in the **Main** organization, but not in other organizations.
> **Note:** After you apply your changes, user and team permissions update immediately, and the UI reflects the new permissions the next time they reload their browser or visit another page.
<br/>
**Before you begin:**
- [Plan your RBAC rollout strategy]({{< relref "plan-rbac-rollout-strategy/" >}}).
- Identify the fixed roles that you want to assign to the user or team.
For more information about available fixed roles, refer to [RBAC role definitions]({{< relref "rbac-fixed-basic-role-definitions/" >}}).
- Ensure that your own user account has the correct permissions:
- If you are assigning permissions to a user or team within an organization, you must have organization administrator or server administrator permissions.
- If you are assigning permissions to a user who belongs to multiple organizations, you must have server administrator permissions.
- Your Grafana user can also assign fixed role if it has either the `fixed:roles:writer` fixed role assigned to the same organization to which you are assigning RBAC to a user, or a custom role with `users.roles:add` and `users.roles:remove` permissions.
- Your own user account must have the roles you are granting. For example, if you would like to grant the `fixed:users:writer` role to a team, you must have that role yourself.
<br/>
**To assign a fixed role to a user or team:**
1. Sign in to Grafana.
2. Switch to the organization that contains the user or team.
For more information about switching organizations, refer to [Switch organizations](../../administration/manage-user-preferences/_index.md#switch-organizations).
3. Hover your cursor over **Configuration** (the gear icon) in the left navigation menu, and click **Users** or **Teams**.
4. In the **Role** column, select the fixed role that you want to assign to the user or team.
5. Click **Update**.
![User role picker in an organization](/static/img/docs/enterprise/user_role_picker_in_org.png)
**To assign a fixed role as a server administrator:**
1. Sign in to Grafana, hover your cursor over **Server Admin** (the shield icon) in the left navigation menu, and click **Users**.
1. Click a user.
1. In the **Organizations** section, select a role within an organization that you want to assign to the user.
1. Click **Update**.
![User role picker in Organization](/static/img/docs/enterprise/user_role_picker_global.png)
## Assign fixed or custom roles to a team using provisioning
Instead of using the Grafana role picker, you can use file-based provisioning to assign fixed roles to teams. If you have a large number of teams, provisioning can provide an easier approach to assigning and managing role assignments.
**Before you begin:**
- Refer to [Role provisioning]({{< relref "rbac-provisioning/#rbac-provisioning" >}})
- Ensure that the team to which you are adding the fixed role exists. For more information about creating teams, refer to [Manage teams]({{< relref "../../administration/manage-users-and-permissions/manage-teams/" >}})
**To assign a role to a team:**
1. Open the YAML configuration file.
1. Refer to the following table to add attributes and values.
| Attribute | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `roles` | Enter the custom role or custom roles you want to create/update. |
| `roles > name` | Enter the name of the custom role. |
| `roles > version` | Enter the custom role version number. Role assignments are independent of the role version number. |
| `roles > global` | Enter `true`. You can specify the `orgId` otherwise. |
| `roles > permissions` | Enter the permissions `action` and `scope` values. For more information about permissions actions and scopes, refer to [RBAC permissions, actions, and scopes]({{< relref "custom-role-actions-scopes/" >}}) |
| `teams` | Enter the team or teams to which you are adding the custom role. |
| `teams > orgId` | Because teams belong to organizations, you must add the `orgId` value. |
| `teams > name` | Enter the name of the team. |
| `teams > roles` | Enter the custom or fixed role or roles that you want to grant to the team. |
| `teams > roles > name` | Enter the name of the role. |
| `teams > roles > global` | Enter `true`, or specify `orgId` of the role you want to assign to the team. Fixed roles are global. |
For more information about managing custom roles, refer to [Create custom roles using provisioning]({{< relref "manage-rbac-roles/#create-custom-roles-using-provisioning" >}}).
1. Reload the provisioning configuration file.
For more information about reloading the provisioning configuration at runtime, refer to [Reload provisioning configurations]({{< relref "../../developers/http_api/admin/#reload-provisioning-configurations" >}}).
The following example creates the `custom:users:writer` role and assigns it to the `user writers` and `user admins` teams along with the `fixed:users:writer` role:
The following example:
- Creates the `custom:users:writer` role.
- Assigns the `custom:users:writer` role and the `fixed:users:writer` role to the `user admins` and `user writers` teams.
```yaml
# config file version
apiVersion: 2
# Roles to insert/update in the database
roles:
- name: 'custom:users:writer'
description: 'List/update other users in the organization'
version: 1
global: true
permissions:
- action: 'org.users:read'
scope: 'users:*'
- action: 'org.users:write'
scope: 'users:*'
# Assignments to teams
teams:
- name: 'user writers'
orgId: 1
roles:
# Custom role assignment
- name: 'custom:users:writer'
global: true
# Fixed role assignment
- name: 'fixed:users:writer'
global: true
- name: 'user admins'
orgId: 1
roles:
- name: 'custom:users:writer'
global: true
- name: 'fixed:users:writer'
global: true
```
> **Note**: The roles don't have to be defined in the provisioning configuration files to be assigned. If roles exist in the database, they can be assigned.
**Remove a role assignment from a team:**
If you want to remove an assignment from a team, add `state: absent` to the `teams > roles` section, and reload the configuration file.
The following example:
- Creates the `custom:users:writer` role
- Assigns the `custom:users:writer` role and the `fixed:users:writer` role to the `user admins` team
- Removes the `custom:users:writer` and the `fixed:users:writer` assignments from the `user writers` team, if those assignments exist.
```yaml
# config file version
apiVersion: 2
# Roles to insert/update in the database
roles:
- name: 'custom:users:writer'
description: 'List/update other users in the organization'
version: 1
global: true
permissions:
- action: 'org.users:read'
scope: 'users:*'
- action: 'org.users:write'
scope: 'users:*'
# Assignments to teams
teams:
- name: 'user writers'
orgId: 1
roles:
- name: 'fixed:users:writer'
global: true
state: 'absent' # Remove assignment
- name: 'custom:users:writer'
global: true
state: 'absent' # Remove assignment
- name: 'user admins'
orgId: 1
roles:
- name: 'fixed:users:writer'
global: true
- name: 'custom:users:writer'
global: true
```
> **Note**: The roles don't have to be defined in the provisioning configuration files to be revoked. If roles exist in the database, they can be revoked.
docs/sources/enterprise/access-control/configure-rbac.md
-24
View File
@@ -1,24 +0,0 @@
---
aliases:
- /docs/grafana/latest/enterprise/access-control/configure-rbac/
description: Learn how to configure RBAC.
menuTitle: Configure RBAC
title: Configure RBAC in Grafana
weight: 30
---
# Configure RBAC in Grafana
The table below describes all RBAC configuration options. Like any other Grafana configuration, you can apply these options as [environment variables]({{< relref "../../setup-grafana/configure-grafana/#configure-with-environment-variables" >}}).
| Setting | Required | Description | Default |
| ------------------ | -------- | ---------------------------------------------------------------------------- | ------- |
| `permission_cache` | No | Enable to use in memory cache for loading and evaluating users' permissions. | `true` |
## Example RBAC configuration
```bash
[rbac]
permission_cache = true
```
docs/sources/enterprise/access-control/custom-role-actions-scopes.md
-155
View File
@@ -1,155 +0,0 @@
---
aliases:
- /docs/grafana/latest/enterprise/access-control/custom-role-actions-scopes/
- /docs/grafana/latest/enterprise/access-control/permissions/
description: Learn about Grafana RBAC permissions, actions, and scopes.
menuTitle: RBAC permissions, actions, and scopes
title: Grafana RBAC permissions, actions, and scopes
weight: 80
---
# RBAC permissions, actions, and scopes
A permission is comprised of an action and a scope. When creating a custom role, consider the actions the user can perform and the resource(s) on which they can perform those actions.
To learn more about the Grafana resources to which you can apply RBAC, refer to [Resources with RBAC permissions]({{< relref "about-rbac/#fixed-roles" >}}).
- **Action:** An action describes what tasks a user can perform on a resource.
- **Scope:** A scope describes where an action can be performed, such as reading a specific user profile. In this example, a permission is associated with the scope `users:<userId>` to the relevant role.
## Action definitions
The following list contains role-based access control actions.
| Action | Applicable scope | Description |
| ------------------------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `alert.instances.external:read` | `datasources:*`<br>`datasources:uid:*` | Read alerts and silences in data sources that support alerting. |
| `alert.instances.external:write` | `datasources:*`<br>`datasources:uid:*` | Manage alerts and silences in data sources that support alerting. |
| `alert.instances:create` | n/a | Create silences in the current organization. |
| `alert.instances:read` | n/a | Read alerts and silences in the current organization. |
| `alert.instances:write` | n/a | Update and expire silences in the current organization. |
| `alert.notifications.external:read` | `datasources:*`<br>`datasources:uid:*` | Read templates, contact points, notification policies, and mute timings in data sources that support alerting. |
| `alert.notifications.external:write` | `datasources:*`<br>`datasources:uid:*` | Manage templates, contact points, notification policies, and mute timings in data sources that support alerting. |
| `alert.notifications:write` | n/a | Manage templates, contact points, notification policies, and mute timings in the current organization. |
| `alert.notifications:read` | n/a | Read all templates, contact points, notification policies, and mute timings in the current organization. |
| `alert.rules.external:read` | `datasources:*`<br>`datasources:uid:*` | Read alert rules in data sources that support alerting (Prometheus, Mimir, and Loki) |
| `alert.rules.external:write` | `datasources:*`<br>`datasources:uid:*` | Create, update, and delete alert rules in data sources that support alerting (Mimir and Loki). |
| `alert.rules:create` | `folders:*`<br>`folders:uid:*` | Create Grafana alert rules in a folder. Combine this permission with `folders:read` in a scope that includes the folder and `datasources:query` in the scope of data sources the user can query. |
| `alert.rules:delete` | `folders:*`<br>`folders:uid:*` | Delete Grafana alert rules in a folder. Combine this permission with `folders:read` in a scope that includes the folder and `datasources:query` in the scope of data sources the user can query. |
| `alert.rules:read` | `folders:*`<br>`folders:uid:*` | Read Grafana alert rules in a folder. Combine this permission with `folders:read` in a scope that includes the folder and `datasources:query` in the scope of data sources the user can query. |
| `alert.rules:write` | `folders:*`<br>`folders:uid:*` | Update Grafana alert rules in a folder. Combine this permission with `folders:read` in a scope that includes the folder and `datasources:query` in the scope of data sources the user can query. |
| `alert.provisioning:read` | n/a | Read all Grafana alert rules, notification policies, etc via provisioning API. Permissions to folders and datasource are not required. |
| `alert.provisioning:write` | n/a | Update all Grafana alert rules, notification policies, etc via provisioning API. Permissions to folders and datasource are not required. |
| `annotations:create` | `annotations:*`<br>`annotations:type:*` | Create annotations. |
| `annotations:delete` | `annotations:*`<br>`annotations:type:*` | Delete annotations. |
| `annotations:read` | `annotations:*`<br>`annotations:type:*` | Read annotations and annotation tags. |
| `annotations:write` | `annotations:*`<br>`annotations:type:*` | Update annotations. |
| `apikeys:create` | n/a | Create API keys. |
| `apikeys:read` | `apikeys:*`<br>`apikeys:id:*` | Read API keys. |
| `apikeys:delete` | `apikeys:*`<br>`apikeys:id:*` | Delete API keys. |
| `dashboards.permissions:read` | `dashboards:*`<br>`dashboards:uid:*`<br>`folders:*`<br>`folders:uid:*` | Read permissions for one or more dashboards. |
| `dashboards.permissions:write` | `dashboards:*`<br>`dashboards:uid:*`<br>`folders:*`<br>`folders:uid:*` | Update permissions for one or more dashboards. |
| `dashboards:create` | `folders:*`<br>`folders:uid:*` | Create dashboards in one or more folders. |
| `dashboards:delete` | `dashboards:*`<br>`dashboards:uid:*`<br>`folders:*`<br>`folders:uid:*` | Delete one or more dashboards. |
| `dashboards:read` | `dashboards:*`<br>`dashboards:uid:*`<br>`folders:*`<br>`folders:uid:*` | Read one or more dashboards. |
| `dashboards:write` | `dashboards:*`<br>`dashboards:uid:*`<br>`folders:*`<br>`folders:uid:*` | Update one or more dashboards. |
| `datasources.id:read` | `datasources:*`<br>`datasources:uid:*` | Read data source IDs. |
| `datasources.permissions:read` | `datasources:*`<br>`datasources:uid:*` | List data source permissions. |
| `datasources.permissions:write` | `datasources:*`<br>`datasources:uid:*` | Update data source permissions. |
| `datasources:create` | n/a | Create data sources. |
| `datasources:delete` | `datasources:*`<br>`datasources:uid:*` | Delete data sources. |
| `datasources:explore` | n/a | Enable access to the **Explore** tab. |
| `datasources:query` | `datasources:*`<br>`datasources:uid:*` | Query data sources. |
| `datasources:read` | `datasources:*`<br>`datasources:uid:*` | List data sources. |
| `datasources:write` | `datasources:*`<br>`datasources:uid:*` | Update data sources. |
| `folders.permissions:read` | `folders:*`<br>`folders:uid:*` | Read permissions for one or more folders. |
| `folders.permissions:write` | `folders:*`<br>`folders:uid:*` | Update permissions for one or more folders. |
| `folders:create` | n/a | Create folders. |
| `folders:delete` | `folders:*`<br>`folders:uid:*` | Delete one or more folders. |
| `folders:read` | `folders:*`<br>`folders:uid:*` | Read one or more folders. |
| `folders:write` | `folders:*`<br>`folders:uid:*` | Update one or more folders. |
| `ldap.config:reload` | n/a | Reload the LDAP configuration. |
| `ldap.status:read` | n/a | Verify the availability of the LDAP server or servers. |
| `ldap.user:read` | n/a | Read users via LDAP. |
| `ldap.user:sync` | n/a | Sync users via LDAP. |
| `licensing.reports:read` | n/a | Get custom permission reports. |
| `licensing:delete` | n/a | Delete the license token. |
| `licensing:read` | n/a | Read licensing information. |
| `licensing:write` | n/a | Update the license token. |
| `org.users:write` | `users:*` <br> `users:id:*` | Update the organization role (`Viewer`, `Editor`, or `Admin`) of a user. |
| `org.users:add` | `users:*` | Add a user to an organization. |
| `org.users:read` | `users:*` <br> `users:id:*` | Get user profiles within an organization. |
| `org.users:remove` | `users:*` <br> `users:id:*` | Remove a user from an organization. |
| `org:create` | n/a | Create an organization. |
| `orgs.preferences:read` | `orgs:*` <br> `orgs:id:*` | Read organization preferences. |
| `orgs.preferences:write` | `orgs:*` <br> `orgs:id:*` | Update organization preferences. |
| `orgs.quotas:read` | `orgs:*` <br> `orgs:id:*` | Read organization quotas. |
| `orgs.quotas:write` | `orgs:*` <br> `orgs:id:*` | Update organization quotas. |
| `orgs:delete` | `orgs:*` <br> `orgs:id:*` | Delete one or more organizations. |
| `orgs:read` | `orgs:*` <br> `orgs:id:*` | Read one or more organizations. |
| `orgs:write` | `orgs:*` <br> `orgs:id:*` | Update one or more organizations. |
| `provisioning:reload` | `provisioners:*` | Reload provisioning files. To find the exact scope for specific provisioner, see [Scope definitions]({{< relref "#scope-definitions" >}}). |
| `reports:create` | n/a | Create reports. |
| `reports:write` | `reports:*` <br> `reports:id:*` | Update reports. |
| `reports.settings:read` | n/a | Read report settings. |
| `reports.settings:write` | n/a | Update report settings. |
| `reports:delete` | `reports:*` <br> `reports:id:*` | Delete reports. |
| `reports:read` | `reports:*` | List all available reports or get a specific report. |
| `reports:send` | `reports:*` | Send a report email. |
| `roles:delete` | `permissions:type:delegate` | Delete a custom role. |
| `roles:read` | `roles:*` <br> `roles:uid:*` | List roles and read a specific with its permissions. |
| `roles:write` | `permissions:type:delegate` | Create or update a custom role. |
| `roles:write` | `permissions:type:escalate` | Reset basic roles to their default permissions. |
| `server.stats:read` | n/a | Read Grafana instance statistics. |
| `settings:read` | `settings:*`<br>`settings:auth.saml:*`<br>`settings:auth.saml:enabled` (property level) | Read the [Grafana configuration settings]({{< relref "../../setup-grafana/configure-grafana/" >}}) |
| `settings:write` | `settings:*`<br>`settings:auth.saml:*`<br>`settings:auth.saml:enabled` (property level) | Update any Grafana configuration settings that can be [updated at runtime]({{< relref "../settings-updates/" >}}). |
| `status:accesscontrol` | `services:accesscontrol` | Get access-control enabled status. |
| `teams.permissions:read` | `teams:*`<br>`teams:id:*` | Read members and External Group Synchronization setup for teams. |
| `teams.permissions:write` | `teams:*`<br>`teams:id:*` | Add, remove and update members and manage External Group Synchronization setup for teams. |
| `teams.roles:add` | `permissions:type:delegate` | Assign a role to a team. |
| `teams.roles:read` | `teams:*` | List roles assigned directly to a team. |
| `teams.roles:remove` | `permissions:type:delegate` | Unassign a role from a team. |
| `teams:create` | n/a | Create teams. |
| `teams:delete` | `teams:*`<br>`teams:id:*` | Delete one or more teams. |
| `teams:read` | `teams:*`<br>`teams:id:*` | Read one or more teams and team preferences. |
| `teams:write` | `teams:*`<br>`teams:id:*` | Update one or more teams and team preferences. |
| `users.authtoken:read` | `global.users:*` <br> `global.users:id:*` | List authentication tokens that are assigned to a user. |
| `users.authtoken:write` | `global.users:*` <br> `global.users:id:*` | Update authentication tokens that are assigned to a user. |
| `users.password:write` | `global.users:*` <br> `global.users:id:*` | Update a user’s password. |
| `users.permissions:read` | `users:*` | List permissions of a user. |
| `users.permissions:write` | `global.users:*` <br> `global.users:id:*` | Update a user’s organization-level permissions. |
| `users.quotas:read` | `global.users:*` <br> `global.users:id:*` | List a user’s quotas. |
| `users.quotas:write` | `global.users:*` <br> `global.users:id:*` | Update a user’s quotas. |
| `users.roles:add` | `permissions:type:delegate` | Assign a role to a user. |
| `users.roles:read` | `users:*` | List roles assigned directly to a user. |
| `users.roles:remove` | `permissions:type:delegate` | Unassign a role from a user. |
| `users:create` | n/a | Create a user. |
| `users:delete` | `global.users:*` <br> `global.users:id:*` | Delete a user. |
| `users:disable` | `global.users:*` <br> `global.users:id:*` | Disable a user. |
| `users:enable` | `globa.users:*` <br> `global.users:id:*` | Enable a user. |
| `users:logout` | `global.users:*` <br> `global.users:id:*` | Sign out a user. |
| `users:read` | `global.users:*` | Read or search user profiles. |
| `users:write` | `global.users:*` <br> `global.users:id:*` | Update a user’s profile. |
## Scope definitions
The following list contains role-based access control scopes.
| Scopes | Descriptions |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `annotations:*`<br>`annotations:type:*` | Restrict an action to a set of annotations. For example, `annotations:*` matches any annotation, `annotations:type:dashboard` matches annotations associated with dashboards and `annotations:type:organization` matches organization annotations. |
| `apikeys:*`<br>`apikeys:id:*` | Restrict an action to a set of API keys. For example, `apikeys:*` matches any API key, `apikey:id:1` matches the API key whose id is `1`. |
| `dashboards:*`<br>`dashboards:uid:*` | Restrict an action to a set of dashboards. For example, `dashboards:*` matches any dashboard, and `dashboards:uid:1` matches the dashboard whose UID is `1`. |
| `datasources:*`<br>`datasources:uid:*` | Restrict an action to a set of data sources. For example, `datasources:*` matches any data source, and `datasources:uid:1` matches the data source whose UID is `1`. |
| `folders:*`<br>`folders:uid:*` | Restrict an action to a set of folders. For example, `folders:*` matches any folder, and `folders:uid:1` matches the folder whose UID is `1`. |
| `global.users:*` <br> `global.users:id:*` | Restrict an action to a set of global users. For example, `global.users:*` matches any user and `global.users:id:1` matches the user whose ID is `1`. |
| `orgs:*` <br> `orgs:id:*` | Restrict an action to a set of organizations. For example, `orgs:*` matches any organization and `orgs:id:1` matches the organization whose ID is `1`. |
| `permissions:type:delegate` | The scope is only applicable for roles associated with the Access Control itself and indicates that you can delegate your permissions only, or a subset of it, by creating a new role or making an assignment. |
| `permissions:type:escalate` | The scope is required to trigger the reset of basic roles permissions. It indicates that users might acquire additional permissions they did not previously have. |
| `provisioners:*` | Restrict an action to a set of provisioners. For example, `provisioners:*` matches any provisioner, and `provisioners:accesscontrol` matches the role-based access control [provisioner]({{< relref "custom-role-actions-scopes/" >}}). |
| `reports:*` <br> `reports:id:*` | Restrict an action to a set of reports. For example, `reports:*` matches any report and `reports:id:1` matches the report whose ID is `1`. |
| `roles:*` <br> `roles:uid:*` | Restrict an action to a set of roles. For example, `roles:*` matches any role and `roles:uid:randomuid` matches only the role whose UID is `randomuid`. |
| `services:accesscontrol` | Restrict an action to target only the role-based access control service. You can use this in conjunction with the `status:accesscontrol` actions. |
| `settings:*` | Restrict an action to a subset of settings. For example, `settings:*` matches all settings, `settings:auth.saml:*` matches all SAML settings, and `settings:auth.saml:enabled` matches the enable property on the SAML settings. |
| `teams:*` <br> `teams:id:*` | Restrict an action to a set of teams from an organization. For example, `teams:*` matches any team and `teams:id:1` matches the team whose ID is `1`. |
| `users:*` <br> `users:id:*` | Restrict an action to a set of users from an organization. For example, `users:*` matches any user and `users:id:1` matches the user whose ID is `1`. |
docs/sources/enterprise/access-control/manage-rbac-roles.md
-371
View File
@@ -1,371 +0,0 @@
---
aliases:
- /docs/grafana/latest/enterprise/access-control/manage-rbac-roles/
- /docs/grafana/latest/enterprise/access-control/manage-role-assignments/
- /docs/grafana/latest/enterprise/access-control/provisioning/
description: Learn how to view permissions associated with roles, create custom roles,
and update and delete roles in Grafana.
menuTitle: Manage RBAC roles
title: Manage Grafana RBAC roles
weight: 50
---
# Manage RBAC roles
This section includes instructions for how to view permissions associated with roles, create custom roles, and update and delete roles.
The following example includes the base64 username:password Basic Authorization. You cannot use authorization tokens in the request.
### List permissions associated with roles
Use a `GET` command to see the actions and scopes associated with a role. For more information about seeing a list of permissions for each role, refer to [Get a role]({{< relref "../../developers/http_api/access_control/#get-a-role" >}}).
To see the permissions associated with basic roles, refer to the following basic role UIDs:
| Basic role | UID |
| --------------- | --------------------- |
| `Viewer` | `basic_viewer` |
| `Editor` | `basic_editor` |
| `Admin` | `basic_admin` |
| `Grafana Admin` | `basic_grafana_admin` |
**Example request**
```
curl --location --request GET '<grafana_url>/api/access-control/roles/qQui_LCMk' --header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ='
```
**Example response**
```
{
"version": 2,
"uid": "qQui_LCMk",
"name": "fixed:users:writer",
"displayName": "User writer",
"description": "Read and update all attributes and settings for all users in Grafana: update user information, read user information, create or enable or disable a user, make a user a Grafana administrator, sign out a user, update a user’s authentication token, or update quotas for all users.",
"global": true,
"permissions": [
{
"action": "org.users:add",
"scope": "users:*",
"updated": "2021-05-17T20:49:18+02:00",
"created": "2021-05-17T20:49:18+02:00"
},
{
"action": "org.users:read",
"scope": "users:*",
"updated": "2021-05-17T20:49:18+02:00",
"created": "2021-05-17T20:49:18+02:00"
},
{
"action": "org.users:remove",
"scope": "users:*",
"updated": "2021-05-17T20:49:18+02:00",
"created": "2021-05-17T20:49:18+02:00"
},
{
"action": "org.users:write",
"scope": "users:*",
"updated": "2021-05-17T20:49:18+02:00",
"created": "2021-05-17T20:49:18+02:00"
}
],
"updated": "2021-05-17T20:49:18+02:00",
"created": "2021-05-13T16:24:26+02:00"
}
```
Refer to the [RBAC HTTP API]({{< relref "../../developers/http_api/access_control/#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.
Create a custom role when basic roles and fixed roles do not meet your permissions requirements.
**Before you begin:**
- [Plan your RBAC rollout strategy]({{< relref "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]({{< relref "custom-role-actions-scopes/" >}}).
- [Enable role provisioning]({{< relref "rbac-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
File-based provisioning is one method you can use to create custom roles.
1. Open the YAML configuration file and locate the `roles` section.
1. Refer to the following table to add attributes and values.
| Attribute | Description |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | A human-friendly identifier for the role that helps administrators understand the purpose of a role. `name` is required and cannot be longer than 190 characters. We recommend that you use ASCII characters. Role names must be unique within an organization. |
| `uid` | A unique identifier associated with the role. The UID enables you to change or delete the role. You can either generate a UID yourself, or let Grafana generate one for you. You cannot use the same UID within the same Grafana instance. |
| `orgId` | Identifies the organization to which the role belongs. The [default org ID]({{< relref "../../setup-grafana/configure-grafana/#auto_assign_org_id" >}}) is used if you do not specify `orgId`. |
| `global` | Global roles are not associated with any specific organization, which means that you can reuse them across all organizations. This setting overrides `orgId`. |
| `displayName` | Human-friendly text that is displayed in the UI. Role display name cannot be longer than 190 ASCII-based characters. For fixed roles, the display name is shown as specified. If you do not set a display name the display name replaces `':'` (a colon) with `' '` (a space). |
| `description` | Human-friendly text that describes the permissions a role provides. |
| `group` | Organizes roles in the role picker. |
| `version` | A positive integer that defines the current version of the role, which prevents overwriting newer changes. |
| `hidden` | Hidden roles do not appear in the role picker. |
| `state` | State of the role. Defaults to `present`, but if set to `absent` the role will be removed. |
| `force` | Can be used in addition to state `absent`, to force the removal of a role and all its assignments. |
| `from` | An optional list of roles from which you want to copy permissions. |
| `permissions` | Provides users access to Grafana resources. For a list of permissions, refer to [RBAC permissions actions and scopes]({{< relref "rbac-fixed-basic-role-definitions/" >}}). If you do not know which permissions to assign, you can create and assign roles without any permissions as a placeholder. Using the `from` attribute, you can specify additional permissions or permissions to remove by adding a `state` to your permission list. |
1. Reload the provisioning configuration file.
For more information about reloading the provisioning configuration at runtime, refer to [Reload provisioning configurations]({{< relref "../../developers/http_api/admin/#reload-provisioning-configurations" >}}).
The following example creates a local role:
```yaml
# config file version
apiVersion: 2
roles:
- name: custom:users:writer
description: 'List, create, or update other users.'
version: 1
orgId: 1
permissions:
- action: 'users:read'
scope: 'global.users:*'
- action: 'users:write'
scope: 'global.users:*'
- action: 'users:create'
```
The following example creates a hidden global role. The `global: true` option creates a global role, and the `hidden: true` option hides the role from the role picker.
```yaml
# config file version
apiVersion: 2
roles:
- name: custom:users:writer
description: 'List, create, or update other users.'
version: 1
global: true
hidden: true
permissions:
- action: 'users:read'
scope: 'global.users:*'
- action: 'users:write'
scope: 'global.users:*'
- action: 'users:create'
```
The following example creates a global role based on other fixed roles. The `from` option contains the roles from which we want to
copy permissions. The permission `state: absent` option can be used to specify permissions to exclude from the copy.
```yaml
# config file version
apiVersion: 2
roles:
- name: custom:org.users:writer
description: 'List and remove other users from the organization.'
version: 1
global: true
from:
- name: 'fixed:org.users:reader'
global: true
- name: 'fixed:org.users:writer'
global: true
permissions:
- action: 'org.users:write'
scope: 'users:*'
state: 'absent'
- action: 'org.users:add'
scope: 'users:*'
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]({{< relref "../../developers/http_api/access_control/#create-a-new-custom-role" >}}).
> **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.
The following example creates a `custom:users:admin` role and assigns the `users:create` action to it.
**Example request**
```
curl --location --request POST '<grafana_url>/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]({{< relref "../../developers/http_api/access_control/#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.
**Before you begin:**
- Determine the permissions you want to add or remove from a basic role. For more information about the permissions associated with basic roles, refer to [RBAC role definitions]({{< relref "rbac-fixed-basic-role-definitions/#basic-role-assignments" >}}).
**To change permissions from a basic role:**
1. Open the YAML configuration file and locate the `roles` section.
1. Refer to the following table to add attributes and values.
| Attribute | Description |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | The name of the basic role you want to update. You can specify a `uid` instead of a role name. The role `name` or the `uid` are required. |
| `orgId` | Identifies the organization to which the role belongs. `global` can be used instead to specify it's a global role. |
| `version` | Identifies the version of the role, which prevents overwriting newer changes. |
| `from` | List of roles from which to copy permissions. |
| `permissions > state` | The state of the permission. You can set it to `absent` to ensure it exclusion from the copy list. |
1. Reload the provisioning configuration file.
For more information about reloading the provisioning configuration at runtime, refer to [Reload provisioning configurations]({{< relref "../../developers/http_api/admin/#reload-provisioning-configurations" >}}).
The following example modifies the `Grafana Admin` basic role permissions.
- Permissions to list, grant, and revoke roles to teams are removed.
- Permission to read and write Grafana folders is added.
```yaml
# config file version
apiVersion: 2
roles:
- name: 'basic:grafana_admin'
global: true
version: 3
from:
- name: 'basic:grafana_admin'
global: true
permissions:
# Permissions to remove
- action: 'teams.roles:read'
scope: 'teams:*'
state: 'absent'
- action: 'teams.roles:remove'
scope: 'permissions:type:delegate'
state: 'absent'
- action: 'teams.roles:add'
scope: 'permissions:type:delegate'
state: 'absent'
# Permissions to add
- action: 'folders:read'
scope: 'folder:*'
- action: 'folders:write'
scope: 'folder:*'
```
> **Note**: You can add multiple `fixed`, `basic` or `custom` roles to the `from` section. Their permissions will be copied and added to the basic role.
> <br/> **Note**: Make sure to **increment** the role version for the changes to be accounted for.
You can also change basic roles' permissions using the API. Refer to the [RBAC HTTP API]({{< relref "../../developers/http_api/access_control/#update-a-role" >}}) for more details.
## Reset basic roles to their default
This section describes how to reset the basic roles to their default:
1. Open the YAML configuration file and locate the `roles` section.
1. Grant the `action: "roles:write", scope: "permissions:type:escalate` permission to `Grafana Admin`. Note that this permission has not been granted to any basic roles by default, because users could acquire more permissions than they previously had through the basic role permissions reset.
```yaml
apiVersion: 2
roles:
- name: 'basic:grafana_admin'
global: true
version: 3
from:
- name: 'basic:grafana_admin'
global: true
permissions:
# Permission allowing to reset basic roles
- action: 'roles:write'
scope: 'permissions:type:escalate'
```
1. As a `Grafana Admin`, call the API endpoint to reset the basic roles to their default. Refer to the [RBAC HTTP API]({{< relref "../../developers/http_api/access_control/#reset-basic-roles-to-their-default" >}}) for more details.
## Delete a custom role using Grafana provisioning
Delete a custom role when you no longer need it. When you delete a custom role, the custom role is removed from users and teams to which it is assigned.
**Before you begin:**
- Identify the role or roles that you want to delete.
- Ensure that you have access to the YAML configuration file.
**To delete a custom role:**
1. Open the YAML configuration file and locate the `roles` section.
1. Refer to the following table to add attributes and values.
| Attribute | Description |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `name` | The name of the custom role you want to delete. You can specify a `uid` instead of a role name. The role `name` or the `uid` are required. |
| `orgId` | Identifies the organization to which the role belongs. |
| `state` | The state of the role set to `absent` to trigger its removal. |
| `force` | When set to `true`, the roles are removed even if there are existing assignments. |
1. Reload the provisioning configuration file.
For more information about reloading the provisioning configuration at runtime, refer to [Reload provisioning configurations]({{< relref "../../developers/http_api/admin/#reload-provisioning-configurations" >}}).
The following example deletes a custom role:
```yaml
# config file version
apiVersion: 2
roles:
- name: 'custom:reports:editor'
orgId: 1
state: 'absent'
force: true
```
You can also delete a custom role using the API. Refer to the [RBAC HTTP API]({{< relref "../../developers/http_api/access_control/#delete-a-custom-role" >}}) for more details.
docs/sources/enterprise/access-control/plan-rbac-rollout-strategy.md
-240
View File
@@ -1,240 +0,0 @@
---
aliases:
- /docs/grafana/latest/enterprise/access-control/plan-rbac-rollout-strategy/
- /docs/grafana/latest/enterprise/access-control/usage-scenarios/
description: Plan your RBAC rollout strategy before you begin assigning roles to users
and teams.
menuTitle: Plan your RBAC rollout strategy
title: Plan your Grafana RBAC rollout strategy
weight: 20
---
# Plan your RBAC rollout strategy
An RBAC rollout strategy helps you determine _how_ you want to implement RBAC prior to assigning RBAC roles to users and teams.
Your rollout strategy should help you answer the following questions:
- Should I assign basic roles to users, or should I assign fixed roles or custom roles to users?
- When should I create custom roles?
- To which entities should I apply fixed and custom roles? Should I apply them to users, teams? Should I modify the basic roles permissions instead?
- How do I roll out permissions in a way that makes them easy to manage?
- Which approach should I use when assigning roles? Should I use the Grafana UI, provisioning, or the API?
## Review basic role and fixed role definitions
As a first step in determining your permissions rollout strategy, we recommend that you become familiar with basic role and fixed role definitions. In addition to assigning fixed roles to any user and team, you can also modify basic roles permissions, which changes what a Viewer, Editor, or Admin can do. This flexibility means that there are many combinations of role assignments for you to consider. If you have a large number of Grafana users and teams, we recommend that you make a list of which fixed roles you might want to use.
To learn more about basic roles and fixed roles, refer to the following documentation:
- [Basic role definitions]({{< relref "rbac-fixed-basic-role-definitions/#basic-role-assignments" >}})
- [Fixed role definitions]({{< relref "rbac-fixed-basic-role-definitions/#fixed-role-definitions" >}})
## User and team considerations
RBAC is a flexible and powerful feature with many possible permissions assignment combinations available. Consider the follow guidelines when assigning permissions to users and teams.
- **Assign roles to users** when you have a one-off scenario where a small number of users require access to a resource or when you want to assign temporary access. If you have a large number of users, this approach can be difficult to manage as you scale your use of Grafana. For example, a member of your IT department might need the `fixed:licensing:reader` and `fixed:licensing:writer` roles so that they can manage your Grafana Enterprise license.
- **Assign roles to teams** when you have a subset of users that align to your organizational structure, and you want all members of the team to have the same level of access. For example, all members of a particular engineering team might need the `fixed:reports:reader` and `fixed:reports:writer` roles to be able to manage reports.
When you assign additional users to a team, the system automatically assigns permissions to those users.
### Authentication provider considerations
You can take advantage of your current authentication provider to manage user and team permissions in Grafana. When you map users and teams to SAML and LDAP groups, you can synchronize those assignments with Grafana.
For example:
1. Map SAML, LDAP, or Oauth roles to Grafana basic roles (viewer, editor, or admin).
2. Use the Grafana Enterprise team sync feature to synchronize teams from your SAML, LDAP, or Oauth provider to Grafana. For more information about team sync, refer to [Team sync]({{< relref "../../setup-grafana/configure-security/configure-team-sync/" >}}).
3. Within Grafana, assign RBAC permissions to users and teams.
## When to modify basic roles or create custom roles
Consider the following guidelines when you determine if you should modify basic roles or create custom roles.
- **Modify basic roles** when Grafana's definitions of what viewers, editors, and admins can do does not match your definition of these roles. You can add or remove permissions from any basic role.
> **Note:** Changes that you make to basic roles impact the role definition for all [organizations]({{< relref "../../administration/manage-organizations/" >}}) in the Grafana instance. For example, when you add the `fixed:users:writer` role's permissions to the viewer basic role, all viewers in any org in the Grafana instance can create users within that org.
- **Create custom roles** when fixed role definitions don't meet you permissions requirements. For example, the `fixed:dashboards:writer` role allows users to delete dashboards. If you want some users or teams to be able to create and update but not delete dashboards, you can create a custom role with a name like `custom:dashboards:creator` that lacks the `dashboards:delete` permission.
## How to assign RBAC roles
Use any of the following methods to assign RBAC roles to users and teams.
- **Grafana UI:** Use the Grafana UI when you want to assign a limited number of RBAC roles to users and teams. The UI contains a role picker that you can use to select roles.
- **Grafana HTTP API:** Use the Grafana HTTP API if you would like to automate role assignment.
- **Terraform:** Use Terraform to assign and manage user and team role assignments if you use Terraform for provisioning.
- **Grafana provisioning:** Grafana provisioning provides a robust approach to assigning, removing, and deleting roles. Within a single YAML file you can include multiple role assignment and removal entries.
## Permissions scenarios
We've compiled the following permissions rollout scenarios based on current Grafana implementations.
> **Note:** If you have a use case that you'd like to share, feel free to contribute to this docs page. We'd love to hear from you!
### Provide internal viewer employees with the ability to use Explore, but prevent external viewer contractors from using Explore
1. In Grafana, create a team with the name `Internal employees`.
1. Assign the `fixed:datasources:querier` role to the `Internal employees` team.
1. Add internal employees to the `Internal employees` team, or map them from a SAML, LDAP, or Oauth team using [Team Sync]({{< relref "../../setup-grafana/configure-security/configure-team-sync/" >}}).
1. Assign the viewer role to both internal employees and contractors.
### Limit viewer, editor, or admin permissions
1. Review the list of permissions associated with the basic role.
1. [Change the permissions of the basic role]({{< relref "manage-rbac-roles/#update-basic-role-permissions" >}}).
### Allow only members of one team to manage Alerts
1. Create an `Alert Managers` team, and assign that team all applicable Alerting fixed roles.
1. Add users to the `Alert Managers` team.
1. Remove all permissions with actions prefixed with `alert.` from the Viewer, Editor, and Admin basic roles.
### Provide dashboards to users in two or more geographies
1. Create a folder for each geography, for example, create a `US` folder and an `EU` folder.
1. Add dashboards to each folder.
1. Use folder permissions to add US-based users as Editors to the `US` folder and assign EU-based users as Editors to the `EU` folder.
### Create a custom role to access alerts in a specific folder
To see an alert rule in Grafana, the user must have read access to the folder that stores the alert rule, permission to read alerts in the folder, and permission to query all data sources that the rule uses.
The API command in this example is based on the following:
- A `Test-Folder` with ID `92`
- Two data sources: `DS1` with UID `_oAfGYUnk`, and `DS2` with UID `YYcBGYUnk`
- An alert rule that is stored in `Test-Folder` and queries the two data sources.
The following request creates a custom role that includes permissions to access the alert rule:
```
curl --location --request POST '<grafana_url>/api/access-control/roles/' \
--header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
--header 'Content-Type: application/json' \
--data-raw '{
"version": 1,
"name": "custom:alerts.reader.in.folder.123",
"displayName": "Read-only access to alerts in folder Test-Folder",
"description": "Let user query DS1 and DS2, and read alerts in folder Test-Folders",
"group":"Custom",
"global": true,
"permissions": [
{
"action": "folders:read",
"scope": "folders:uid:YEcBGYU22"
},
{
"action": "alert.rules:read",
"scope": "folders:uid:YEcBGYU22"
},
{
"action": "datasources:query",
"scope": "datasources:uid:_oAfGYUnk"
},
{
"action": "datasources:query",
"scope": "datasources:uid:YYcBGYUnk"
}
]
}'
```
### Enable an editor to create custom roles
By default, only a Grafana Server Admin can create and manage custom roles. If you want your `Editors` to do the same, [update the `Editor` basic role permissions]({{< ref "./manage-rbac-roles.md#update-basic-role-permissions" >}}). There are two ways to achieve this:
- Add the `fixed:roles:writer` role permissions to the `basic:editor` role using the `role > from` list of your provisioning file:
```yaml
apiVersion: 2
roles:
- name: 'basic:editor'
global: true
version: 3
from:
- name: 'basic:editor'
global: true
- name: 'fixed:roles:writer'
global: true
```
- Or add the following permissions to the `basic:editor` role, using provisioning or the [RBAC HTTP API]({{< relref "../../developers/http_api/access_control/#update-a-role" >}}):
| action | scope |
| -------------- | --------------------------- |
| `roles:read` | `roles:*` |
| `roles:write` | `permissions:type:delegate` |
| `roles:delete` | `permissions:type:delegate` |
> **Note:** Any user or service account with the ability to modify roles can only create, update, or delete roles with permissions they have been granted. For example, a user with the `Editor` role would be able to create and manage roles only with the permissions they have or with a subset of them.
### Enable viewers to create reports
If you want your `Viewers` to create reports, [update the `Viewer` basic role permissions]({{< ref "./manage-rbac-roles.md#update-basic-role-permissions" >}}). There are two ways to achieve this:
- Add the `fixed:reports:writer` role permissions to the `basic:viewer` role using the `role > from` list of your provisioning file:
```yaml
apiVersion: 2
roles:
- name: 'basic:viewer'
global: true
version: 3
from:
- name: 'basic:viewer'
global: true
- name: 'fixed:reports:writer'
global: true
```
> **Note:** The `fixed:reports:writer` role assigns more permissions than just creating reports. For more information about fixed role permission assignments, refer to [Fixed role definitions]({{< relref "rbac-fixed-basic-role-definitions/#fixed-role-definitions" >}}).
- Add the following permissions to the `basic:viewer` role, using provisioning or the [RBAC HTTP API]({{< relref "../../developers/http_api/access_control/#update-a-role" >}}):
| Action | Scope |
| ---------------- | ------------------------------- |
| `reports:create` | n/a |
| `reports:write` | `reports:*` <br> `reports:id:*` |
| `reports:read` | `reports:*` |
| `reports:send` | `reports:*` |
### Prevent a Grafana Admin from creating and inviting users
To prevent a Grafana Admin from creating users and inviting them to join an organization, you must [update a basic role permissions]({{< ref "./manage-rbac-roles.md#update-basic-role-permissions" >}}).
The permissions to remove are:
| Action | Scope |
| --------------- | --------- |
| `users:create` | |
| `org.users:add` | `users:*` |
There are two ways to achieve this:
- Use the `role > from` list and `permission > state` option of your provisioning file:
```yaml
apiVersion: 2
roles:
- name: 'basic:editor'
global: true
version: 3
from:
- name: 'basic:editor'
global: true
permissions:
- action: 'users:create'
state: 'absent'
- action: 'org.users:add'
scope: 'users:*'
state: 'absent'
```
- Or use [RBAC HTTP API]({{< relref "../../developers/http_api/access_control/#update-a-role" >}}).
docs/sources/enterprise/access-control/rbac-fixed-basic-role-definitions.md
-93
View File
@@ -1,93 +0,0 @@
---
aliases:
- /docs/grafana/latest/enterprise/access-control/fine-grained-access-control-references/
- /docs/grafana/latest/enterprise/access-control/rbac-fixed-basic-role-definitions/
description: This topic includes a table that lists permission associated with Grafana
fixed and basic roles.
menuTitle: RBAC role definitions
title: Grafana RBAC role definitions
weight: 70
---
# RBAC role definitions
The following tables list permissions associated with basic and fixed roles.
## Basic role assignments
| Basic role | Associated fixed roles | Description |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Grafana Admin | `fixed:roles:reader`<br>`fixed:roles:writer`<br>`fixed:users:reader`<br>`fixed:users:writer`<br>`fixed:org.users:reader`<br>`fixed:org.users:writer`<br>`fixed:ldap:reader`<br>`fixed:ldap:writer`<br>`fixed:stats:reader`<br>`fixed:settings:reader`<br>`fixed:settings:writer`<br>`fixed:provisioning:writer`<br>`fixed:organization:reader`<br>`fixed:organization:maintainer`<br>`fixed:licensing:reader`<br>`fixed:licensing:writer` | Default [Grafana server administrator]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions/#grafana-server-administrators" >}}) assignments. |
| Admin | `fixed:reports:reader`<br>`fixed:reports:writer`<br>`fixed:datasources:reader`<br>`fixed:datasources:writer`<br>`fixed:organization:writer`<br>`fixed:datasources.permissions:reader`<br>`fixed:datasources.permissions:writer`<br>`fixed:teams:writer`<br>`fixed:dashboards:reader`<br>`fixed:dashboards:writer`<br>`fixed:dashboards.permissions:reader`<br>`fixed:dashboards.permissions:writer`<br>`fixed:folders:reader`<br>`fixes:folders:writer`<br>`fixed:folders.permissions:reader`<br>`fixed:folders.permissions:writer`<br>`fixed:alerting:writer`<br>`fixed:apikeys:reader`<br>`fixed:apikeys:writer`<br>`fixed:alerting.provisioning:writer` | Default [Grafana organization administrator]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions/#organization-users-and-permissions" >}}) assignments. |
| Editor | `fixed:datasources:explorer`<br>`fixed:dashboards:creator`<br>`fixed:folders:creator`<br>`fixed:annotations:writer`<br>`fixed:teams:creator` if the `editors_can_admin` configuration flag is enabled<br>`fixed:alerting:writer` | Default [Editor]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions/#organization-users-and-permissions" >}}) assignments. |
| Viewer | `fixed:datasources:id:reader`<br>`fixed:organization:reader`<br>`fixed:annotations:reader`<br>`fixed:annotations.dashboard:writer`<br>`fixed:alerting:reader` | Default [Viewer]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions/#organization-users-and-permissions" >}}) assignments. |
## Fixed role definitions
| Fixed role | Permissions | Description |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fixed:alerting.instances:writer` | All permissions from `fixed:alerting.instances:reader` and<br> `alert.instances:create`<br>`alert.instances:write` for organization scope <br> `alert.instances.external:write` for scope `datasources:*` | Create, update and expire all silences in the organization produced by Grafana, Mimir, and Loki.[\*](#alerting-roles) |
| `fixed:alerting.instances:reader` | `alert.instances:read` for organization scope <br> `alert.instances.external:read` for scope `datasources:*` | Read all alerts and silences in the organization produced by Grafana Alerts and Mimir and Loki alerts and silences.[\*](#alerting-roles) |
| `fixed:alerting.notifications:writer` | All permissions from `fixed:alerting.notifications:reader` and<br>`alert.notifications:write`for organization scope<br>`alert.notifications.external:read` for scope `datasources:*` | Create, update, and delete contact points, templates, mute timings and notification policies for Grafana and external Alertmanager.[\*](#alerting-roles) |
| `fixed:alerting.notifications:reader` | `alert.notifications:read` for organization scope<br>`alert.notifications.external:read` for scope `datasources:*` | Read all Grafana and Alertmanager contact points, templates, and notification policies.[\*](#alerting-roles) |
| `fixed:alerting.rules:writer` | All permissions from `fixed:alerting.rules:reader` and <br> `alert.rule:create` <br> `alert.rule:write` <br> `alert.rule:delete` for scope `folders:*` <br> `alert.rules.external:write` for scope `datasources:*` | Create, update, and delete all\* Grafana, Mimir, and Loki alert rules.[\*](#alerting-roles) |
| `fixed:alerting.rules:reader` | `alert.rule:read` for scope `folders:*` <br> `alert.rules.external:read` for scope `datasources:*` | Read all\* Grafana, Mimir, and Loki alert rules.[\*](#alerting-roles) |
| `fixed:alerting:writer` | All permissions from `fixed:alerting.rules:writer` <br>`fixed:alerting.instances:writer`<br>`fixed:alerting.notifications:writer` | Create, update, and delete Grafana, Mimir, Loki and Alertmanager alert rules\*, silences, contact points, templates, mute timings, and notification policies.[\*](#alerting-roles) |
| `fixed:alerting:reader` | All permissions from `fixed:alerting.rules:reader` <br>`fixed:alerting.instances:reader`<br>`fixed:alerting.notifications:reader` | Read-only permissions for all Grafana, Mimir, Loki and Alertmanager alert rules\*, alerts, contact points, and notification policies.[\*](#alerting-roles) |
| `fixed:alerting.provisioning:writer` | `alert.provisioning:read` and `alert.provisioning:write` | Create, update and delete Grafana alert rules, notification policies, contact points, templates, etc via provisioning API. [\*](#alerting-roles) |
| `fixed:annotations.dashboard:writer` | `annotations:write` <br>`annotations.create`<br> `annotations:delete` for scope `annotations:type:dashboard` | Create, update and delete dashboard annotations and annotation tags. |
| `fixed:annotations:reader` | `annotations:read` for scopes `annotations:type:*` | Read all annotations and annotation tags. |
| `fixed:annotations:writer` | All permissions from `fixed:annotations:reader` <br>`annotations:write` <br>`annotations.create`<br> `annotations:delete` for scope `annotations:type:*` | Read, create, update and delete all annotations and annotation tags. |
| `fixed:apikeys:reader` | `apikeys:read` for scope `apikeys:*` | Read all api keys. |
| `fixed:apikeys:writer` | All permissions from `fixed:apikeys:reader` and <br> `apikeys:create` <br> `apikeys:delete` for scope `apikeys:*` | Read, create, delete all api keys. |
| `fixed:dashboards.permissions:reader` | `dashboards.permissions:read` | Read all dashboard permissions. |
| `fixed:dashboards.permissions:writer` | All permissions from `fixed:dashboards.permissions:reader` and <br>`dashboards.permissions:write` | Read and update all dashboard permissions. |
| `fixed:dashboards:creator` | `dashboards:create`<br>`folders:read` | Create dashboards. |
| `fixed:dashboards:reader` | `dashboards:read` | Read all dashboards. |
| `fixed:dashboards:writer` | All permissions from `fixed:dashboards:reader` and <br>`dashboards:write`<br>`dashboards:edit`<br>`dashboards:delete`<br>`dashboards:create`<br>`dashboards.permissions:read`<br>`dashboards.permissions:write` | Read, create, update, and delete all dashboards. |
| `fixed:datasources.permissions:reader` | `datasources.permissions:read` | Read data source permissions. |
| `fixed:datasources.permissions:writer` | All permissions from `fixed:datasources.permissions:reader` and <br>`datasources.permissions:write` | Create, read, or delete permissions of a data source. |
| `fixed:datasources:explorer` | `datasources:explore` | Enable the Explore feature. Data source permissions still apply, you can only query data sources for which you have query permissions. |
| `fixed:datasources:id:reader` | `datasources.id:read` | Read the ID of a data source based on its name. |
| `fixed:datasources:reader` | `datasources:read`<br>`datasources:query` | Read and query data sources. |
| `fixed:datasources:writer` | All permissions from `fixed:datasources:reader` and <br>`datasources:create`<br>`datasources:write`<br>`datasources:delete` | Read, query, create, delete, or update a data source. |
| `fixed:folders.permissions:reader` | `folders.permissions:read` | Read all folder permissions. |
| `fixed:folders.permissions:writer` | All permissions from `fixed:folders.permissions:reader` and <br>`folders.permissions:write` | Read and update all folder permissions. |
| `fixed:folders:creator` | `folders:create` | Create folders. |
| `fixed:folders:reader` | `folders:read`<br>`dashboards:read` | Read all folders and dashboards. |
| `fixed:folders:writer` | All permissions from `fixed:dashboards:writer` and <br>`folders:read`<br>`folders:write`<br>`folders:create`<br>`folders:delete`<br>`folders.permissions:read`<br>`folders.permissions:write` | Read, create, update, and delete all folders and dashboards. |
| `fixed:ldap:reader` | `ldap.user:read`<br>`ldap.status:read` | Read the LDAP configuration and LDAP status information. |
| `fixed:ldap:writer` | All permissions from `fixed:ldap:reader` and <br>`ldap.user:sync`<br>`ldap.config:reload` | Read and update the LDAP configuration, and read LDAP status information. |
| `fixed:licensing:reader` | `licensing:read`<br>`licensing.reports:read` | Read licensing information and licensing reports. |
| `fixed:licensing:writer` | All permissions from `fixed:licensing:viewer` and <br>`licensing:write`<br>`licensing:delete` | Read licensing information and licensing reports, update and delete the license token. |
| `fixed:org.users:reader` | `org.users:read` | Read users within a single organization. |
| `fixed:org.users:writer` | All permissions from `fixed:org.users:reader` and <br>`org.users:add`<br>`org.users:remove`<br>`org.users:write` | Within a single organization, add a user, invite a user, read information about a user and their role, remove a user from that organization, or change the role of a user. |
| `fixed:organization:maintainer` | All permissions from `fixed:organization:reader` and <br> `orgs:write`<br>`orgs:create`<br>`orgs:delete`<br>`orgs.quotas:write` | Create, read, write, or delete an organization. Read or write its quotas. This role needs to be assigned globally. |
| `fixed:organization:reader` | `orgs:read`<br>`orgs.quotas:read` | Read an organization and its quotas. |
| `fixed:organization:writer` | All permissions from `fixed:organization:reader` and <br> `orgs:write`<br>`orgs.preferences:read`<br>`orgs.preferences:write` | Read an organization, its quotas, or its preferences. Update organization properties, or its preferences. |
| `fixed:provisioning:writer` | `provisioning:reload` | Reload provisioning. |
| `fixed:reports:reader` | `reports:read`<br>`reports:send`<br>`reports.settings:read` | Read all reports and shared report settings. |
| `fixed:reports:writer` | All permissions from `fixed:reports:reader` and <br>`reports:create`<br>`reports:write`<br>`reports:delete`<br>`reports.settings:write` | Create, read, update, or delete all reports and shared report settings. |
| `fixed:roles:reader` | `roles:read`<br>`teams.roles:read`<br>`users.roles:read`<br>`users.permissions:read` | Read all access control roles, roles and permissions assigned to users, teams. |
| `fixed:roles:writer` | All permissions from `fixed:roles:reader` and <br>`roles:write`<br>`roles:delete`<br>`teams.roles:add`<br>`teams.roles:remove`<br>`users.roles:add`<br>`users.roles:remove` | Create, read, update, or delete all roles, assign or unassign roles to users, teams. |
| `fixed:roles:resetter` | `roles:write` with scope `permissions:type:escalate` | Reset basic roles to their default. |
| `fixed:settings:reader` | `settings:read` | Read Grafana instance settings. |
| `fixed:settings:writer` | All permissions from `fixed:settings:reader` and<br>`settings:write` | Read and update Grafana instance settings. |
| `fixed:stats:reader` | `server.stats:read` | Read Grafana instance statistics. |
| `fixed:teams:creator` | `teams:create`<br>`org.users:read` | Create a team and list organization users (required to manage the created team). |
| `fixed:teams:writer` | `teams:create`<br>`teams:delete`<br>`teams:read`<br>`teams:write`<br>`teams.permissions:read`<br>`teams.permissions:write` | Create, read, update and delete teams and manage team memberships. |
| `fixed:users:reader` | `users:read`<br>`users.quotas:read`<br>`users.authtoken:read`<br>` | Read all users and their information, such as team memberships, authentication tokens, and quotas. |
| `fixed:users:writer` | All permissions from `fixed:users:reader` and <br>`users:write`<br>`users:create`<br>`users:delete`<br>`users:enable`<br>`users:disable`<br>`users.password:write`<br>`users.permissions:write`<br>`users:logout`<br>`users.authtoken:write`<br>`users.quotas:write` | Read and update all attributes and settings for all users in Grafana: update user information, read user information, create or enable or disable a user, make a user a Grafana administrator, sign out a user, update a user’s authentication token, or update quotas for all users. |
### Alerting roles
If alerting is [enabled]({{< relref "../../alerting/migrating-alerts/opt-out/" >}}), you can use predefined roles to manage user access to alert rules, alert instances, and alert notification settings and create custom roles to limit user access to alert rules in a folder.
Access to Grafana alert rules is an intersection of many permissions:
- Permission to read a folder. For example, the fixed role `fixed:folders:reader` includes the action `folders:read` and a folder scope `folders:id:`.
- Permission to query **all** data sources that a given alert rule uses. If a user cannot query a given data source, they cannot see any alert rules that query that data source.
There is only one exclusion at this moment. Role `fixed:alerting.provisioning:writer` does not require user to have any additional permissions and provides access to all aspects of the alerting configuration via special provisioning API.
For more information about the permissions required to access alert rules, refer to [Create a custom role to access alerts in a folder]({{< relref "plan-rbac-rollout-strategy/#create-a-custom-role-to-access-alerts-in-a-folder" >}}).
docs/sources/enterprise/access-control/rbac-provisioning.md
-118
View File
@@ -1,118 +0,0 @@
---
aliases:
- /docs/grafana/latest/enterprise/access-control/rbac-provisioning/
description: Learn about RBAC provisioning and view an example YAML provisioning file
that configures Grafana role assignments.
menuTitle: RBAC provisioning
title: Grafana RBAC provisioning
weight: 60
---
# Grafana RBAC provisioning
You can create, change or remove [Custom roles]({{< relref "manage-rbac-roles/#create-custom-roles-using-provisioning" >}}) and create or remove [basic role assignments]({{< relref "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.
If you choose to use provisioning to assign and manage role, you must first enable it.
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:**
- Ensure that you have access to files on the server where Grafana is running.
**To manage and assign RBAC roles using provisioning:**
1. Sign in to the Grafana server.
2. Locate the Grafana provisioning folder.
3. Create a new YAML in the following folder: **provisioning/access-control**. For example, `provisioning/access-control/custom-roles.yml`
4. Add RBAC provisioning details to the configuration file. See [manage RBAC roles]({{< relref "manage-rbac-roles/" >}}) and [assign RBAC roles]({{< relref "assign-rbac-roles/" >}}) for instructions, and see this [example role provisioning file]({{< relref "rbac-provisioning/#example" >}}) for a complete example of a provisioning file.
5. Reload the provisioning configuration file.
For more information about reloading the provisioning configuration at runtime, refer to [Reload provisioning configurations]({{< relref "../../developers/http_api/admin/#reload-provisioning-configurations" >}}).
## Example role configuration file using Grafana provisioning
The following example shows a complete YAML configuration file that:
- Create custom roles
- Delete custom roles
- Update basic roles permissions
- Assign roles to teams
- Revoke assignments of roles to teams
## Example
```yaml
---
# 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, Grafana will update the role when increased.
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'
- 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'
version: 2
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
```
docs/sources/enterprise/datasource_permissions.md
-74
View File
@@ -1,74 +0,0 @@
---
aliases:
- /docs/grafana/latest/enterprise/datasource_permissions/
- /docs/sources/permissions/datasource_permissions/
description: Grafana Datasource Permissions Guide
keywords:
- grafana
- configuration
- documentation
- datasource
- permissions
- users
- teams
- enterprise
title: Data source permissions
weight: 500
---
# Data source permissions
Data source permissions allow you to restrict access for users to query a data source. For each data source there is a permission page that allows you to enable permissions and restrict query permissions to specific **Users** and **Teams**.
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise" >}}) and [Grafana Cloud Pro and Advanced]({{< ref "/docs/grafana-cloud" >}}).
## Enable data source permissions
{{< figure src="/static/img/docs/enterprise/datasource_permissions_enable_still.png" class="docs-image--no-shadow docs-image--right" max-width= "600px" animated-gif="/static/img/docs/enterprise/datasource_permissions_enable.gif" >}}
By default, data sources in an organization can be queried by any user in that organization. For example, a user with the `Viewer` role can issue any possible query to a data source, not just
queries that exist on dashboards they have access to.
When permissions are enabled for a data source in an organization, the user who created the datasource can edit the datasource and in addition, viewers can query the datasource.
**Enable permissions for a data source:**
1. Navigate to **Configuration > Data Sources**.
1. Select the data source you want to enable permissions for.
1. On the Permissions tab, click **Enable**.
<div class="clearfix"></div>
> **Caution:** Enabling permissions for the default data source makes users not listed in the permissions unable to invoke queries. Panels using default data source will return `Access denied to data source` error for those users.
## Allow users and teams to query a data source
{{< figure src="/static/img/docs/enterprise/datasource_permissions_add_still.png" class="docs-image--no-shadow docs-image--right" max-width= "600px" animated-gif="/static/img/docs/enterprise/datasource_permissions_add.gif" >}}
After you have enabled permissions for a data source you can assign query permissions to users and teams which will allow access to query the data source.
**Assign query permission to users and teams:**
1. Navigate to **Configuration > Data Sources**.
1. Select the data source you want to assign query permissions for.
1. On the Permissions tab, click **Add Permission**.
1. Select **Team** or **User**.
1. Select the entity you want to allow query access and then click **Save**.
<div class="clearfix"></div>
## Disable data source permissions
{{< figure src="/static/img/docs/enterprise/datasource_permissions_disable_still.png" class="docs-image--no-shadow docs-image--right" max-width= "600px" animated-gif="/static/img/docs/enterprise/datasource_permissions_disable.gif" >}}
If you have enabled permissions for a data source and want to return data source permissions to the default, then you can disable permissions with a click of a button.
Note that _all_ existing permissions created for the data source will be deleted.
**Disable permissions for a data source:**
1. Navigate to **Configuration > Data Sources**.
1. Select the data source you want to disable permissions for.
1. On the Permissions tab, click **Disable Permissions**.
<div class="clearfix"></div>
docs/sources/enterprise/export-pdf.md
+1 -1
View File
@@ -15,7 +15,7 @@ weight: 1400
You can generate and save PDF files from any of your dashboards.
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise" >}}).
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise/" >}}).
1. In the upper right corner of the dashboard that you want to export as PDF, click the **Share dashboard** icon.
1. On the PDF tab, select the layout option for exported dashboard: **Portrait** or **Landscape**.
docs/sources/enterprise/license/_index.md
-21
View File
@@ -1,21 +0,0 @@
---
aliases:
- /docs/grafana/latest/enterprise/license/
description: Enterprise license
keywords:
- grafana
- licensing
- enterprise
title: Grafana Enterprise license
weight: 10
---
# Grafana Enterprise license
When you become a Grafana Enterprise customer, you gain access to Grafana's premium observability features, including enterprise data source plugins, reporting, and role-based access control. In order to use these [enhanced features of Grafana Enterprise]({{< relref "../" >}}), you must purchase and activate a Grafana Enterprise license.
To purchase a license directly from Grafana Labs, [Contact a Grafana Labs representative](https://grafana.com/contact?about=grafana-enterprise). To activate an Enterprise license purchased from Grafana Labs, refer to [Activate an Enterprise license]({{< relref "activate-license/" >}}).
You can also purchase a Grafana Enterprise license through the AWS Marketplace. To learn more about activating a license purchased through AWS, refer to [Activate a Grafana Enterprise license purchased through AWS Marketplace]({{< relref "activate-aws-marketplace-license/" >}}).
{{< section >}}
docs/sources/enterprise/license/activate-aws-marketplace-license/_index.md
-19
View File
@@ -1,19 +0,0 @@
---
aliases:
- /docs/grafana/latest/enterprise/license/activate-aws-marketplace-license/
description: Activate Enterprise license purchased through AWS Marketplace
keywords:
- grafana
- aws
- marketplace
- enterprise
- license
title: Activate a Grafana Enterprise license purchased through AWS Marketplace
weight: 400
---
# Activate a Grafana Enterprise license purchased through AWS Marketplace
AWS Marketplace is a convenient place for AWS customers to buy and manage a license for Grafana Enterprise versions 8.3.0 and later.
{{< section >}}
docs/sources/enterprise/license/activate-aws-marketplace-license/about-ge-license-through-aws.md
-32
View File
@@ -1,32 +0,0 @@
---
aliases:
- /docs/grafana/latest/enterprise/activate-aws-marketplace-license/about-ge-license-through-aws/
- /docs/grafana/latest/enterprise/license/activate-aws-marketplace-license/about-ge-license-through-aws/
description: About Grafana Enterprise licenses from AWS Marketplace
keywords:
- grafana
- about
- enterprise
- overview
- aws
- marketplace
title: About Grafana Enterprise licenses from AWS Marketplace
weight: 100
---
# About Grafana Enterprise licenses from AWS Marketplace
AWS Marketplace is a convenient place for AWS customers to buy and manage a license for Grafana Enterprise versions 8.3.0 and later.
You can deploy Grafana Enterprise in the following ways:
- Using AWS services like ECS, EKS or EC2.
- In an instance outside AWS.
In each case, you must activate the Grafana Enterprise license purchased in AWS Marketplace to take advantage of Grafana Enterprise observability features. Grafana Enterprise licenses purchased through AWS Marketplace are subject to the same [restrictions]({{< relref "../license-restrictions/" >}}) as Grafana Enterprise licensed purchased directly from Grafana Labs.
> To purchase a license directly from Grafana Labs or learn more about other Grafana offerings, [Contact a Grafana Labs representative](https://grafana.com/contact?about=grafana-enterprise).
## Before you begin
Become an AWS customer. Only AWS customers have access to purchase services through AWS Marketplace. To learn more about becoming an AWS customer, refer to [Sign up for AWS](https://portal.aws.amazon.com/billing/signup#/start).
docs/sources/enterprise/license/activate-aws-marketplace-license/activate-license-on-ecs.md
-113
View File
@@ -1,113 +0,0 @@
---
aliases:
- /docs/grafana/latest/enterprise/activate-aws-marketplace-license/activate-license-on-ecs/
- /docs/grafana/latest/enterprise/license/activate-aws-marketplace-license/activate-license-on-ecs/
description: Activate a Grafana Enterprise license from AWS Marketplace on ECS
keywords:
- grafana
- ecs
- enterprise
- aws
- marketplace
- activate
title: Activate a Grafana Enterprise license from AWS Marketplace on ECS
weight: 250
---
# Activate a Grafana Enterprise license from AWS Marketplace on ECS
If you have purchased a Grafana Enterprise subscription through AWS Marketplace, you must activate it in order to use Grafana Enterprise data source plugins and features in Grafana.
## Before you begin
- Purchase a subscription to [Grafana Enterprise from AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-dlncd4kzt5kx6).
- Be sure that the IAM user that was used to purchase Grafana Enterprise has permission to manage subscriptions, create new IAM users and roles, and create access policies.
To activate your license, complete the following tasks.
## Task 1: Deploy Grafana Enterprise on Amazon ECS
1. Deploy Grafana Enterprise on Amazon ECS.
For more information about deploying an application on Amazon ECS, refer to [Creating an Amazon ECS service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/create-service.html).
1. As you create the Amazon ECS service, use the Grafana Enterprise version 8.3.0 or later container image.
For example, enter `grafana/grafana-enterprise:8.3.3`.
> Only Grafana Enterprise versions 8.3.0 and later support licenses granted through AWS Marketplace.
## Task 2: Configure Grafana for high availability
Grafana requires that you configure a database to hold dashboards, users, and other persistent data.
### Before you begin
- Ensure that you have a supported Grafana database available.
- For a list of supported databases, refer to [Supported databases]({{< relref "../../../setup-grafana/installation/#supported-databases" >}}).
- For information about creating a database, refer to [Creating an Amazon RDS DB instance](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_CreateDBInstance.html).
- Review the information required to connect to the RDS DB instance. For more information, refer to [Connecting to an Amazon RDS DB instance](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_CommonTasks.Connect.html).
To configure Grafana for high availability:
1. In AWS ECS, use environment variables to update the `database` parameters.
For a list of database parameters, refer to [Configuration]({{< relref "../../../setup-grafana/configure-grafana/#database" >}}).
1. Create a revision of the task definition for the ECS Task that runs Grafana Enterprise.
For more information about creating a task, refer to [Updating a task definition using the classic console](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/update-task-definition.html).
1. Within the new revision, edit the Grafana Enterprise container for this task, and add the following environment variables to the container:
```
GF_DATABASE_TYPE=[database type]
GF_DATABASE_HOST=[database address and port]
GF_DATABASE_NAME=[database name]
GF_DATABASE_USER=[database username]
GF_DATABASE_PASSWORD=[database password]
```
> For more information about how to update your ECS service with an environment variable, refer to [Updating a service using the new console](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/update-service-console-v2.html).
## Task 3: Configure Grafana Enterprise to validate its license with AWS
In this task you configure Grafana Enterprise to validate the license with AWS instead of Grafana Labs.
1. In AWS IAM, create an access policy with the following permissions:
- `"license-manager:CheckoutLicense"`
- `"license-manager:ListReceivedLicenses"`
- `"license-manager:GetLicenseUsage"`
- `"license-manager:CheckInLicense"`
For more information about creating an access policy, refer to [Creating IAM policies (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html).
For more information about AWS license permissions, refer to [Actions, resources, and condition keys for AWS License Manager](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awslicensemanager.html).
1. Create an Elastic Container Service task role and attach the policy you created in the previous step.
For more information about creating a task role, refer to [IAM Roles for Tasks](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html).
1. Create a revision of the task definition for the ECS Task that runs Grafana Enterprise.
For more information about creating a revision of the task definition, refer to [Updating a task definition using the classic console](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/update-task-definition.html).
1. Within the new revision, perform the following steps:
a. Update the Task Role of your ECS Task to the role that you created, with permission to access license information.
b. Edit the Grafana Enterprise container for this task, and add the following environment variable to the container:
```
GF_ENTERPRISE_LICENSE_VALIDATION_TYPE=aws
```
For more information about how to update your ECS service with an environment variable, refer to [Updating a service using the new console](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/update-service-console-v2.html).
### Task 4: Start or restart Grafana
1. To restart Grafana and activate your license, update the service running Grafana to use the latest revision of the task definition that you created.
1. After you update the service, navigate to your Grafana instance, sign in with Grafana Admin credentials, and navigate to the **Statistics and Licensing** page to validate that your license is active.
For more information about validating that your license is active, refer to [Determine the number of active users for each licensed role](../../license-restrictions/#determine-the-number-of-active-users-for-each-licensed-role).
docs/sources/enterprise/license/activate-aws-marketplace-license/activate-license-on-eks.md
-126
View File
@@ -1,126 +0,0 @@
---
aliases:
- /docs/grafana/latest/enterprise/activate-aws-marketplace-license/activate-license-on-eks/
- /docs/grafana/latest/enterprise/license/activate-aws-marketplace-license/activate-license-on-eks/
description: Activate a Grafana Enterprise license from AWS Marketplace on EKS
keywords:
- grafana
- enterprise
- aws
- marketplace
- eks
- activate
title: Activate a Grafana Enterprise license from AWS Marketplace on EKS
weight: 200
---
# Activate a Grafana Enterprise license from AWS Marketplace on EKS
If you have purchased a Grafana Enterprise subscription through AWS Marketplace, you must activate it in order to use Grafana Enterprise data source plugins and features in Grafana.
## Before you begin:
- Purchase a subscription to [Grafana Enterprise from AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-dlncd4kzt5kx6).
- Be sure that the IAM user that was used to purchase Grafana Enterprise has permission to manage subscriptions, create new IAM users and roles, and create access policies.
To activate your license, complete the following tasks:
## Task 1: Deploy Grafana Enterprise on Amazon EKS
1. Deploy Grafana Enterprise on Amazon EKS.
For more information about deploying an application on Amazon EKS, refer to [Getting started with Amazon EKS – AWS Management Console and AWS CLI](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-console.html).
For more information about installing Grafana on Kubernetes using the Helm Chart, refer to the [Grafana Helm Chart](https://github.com/grafana/helm-charts/tree/main/charts/grafana#readme).
1. Use `kubectl set image deployment/my-release grafana=grafana/grafana-enterprise:<version>` to update the container image to Grafana Enterprise version 8.3.0 or later.
For example, enter `grafana/grafana-enterprise:8.3.3`.
> Only Grafana Enterprise versions 8.3.0 and later support licenses granted through AWS Marketplace.
## Task 2: Configure Grafana for high availability
Grafana requires that you configure a database to hold dashboards, users, and other persistent data.
### Before you begin
- Ensure that you have a supported Grafana database available.
- For a list of supported databases, refer to [Supported databases]({{< relref "../../../setup-grafana/installation/#supported-databases" >}}).
- For information about creating a database, refer to [Creating an Amazon RDS DB instance](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_CreateDBInstance.html).
- Review the information required to connect to the RDS DB instance. For more information, refer to [Connecting to an Amazon RDS DB instance](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_CommonTasks.Connect.html).
To configure Grafana for high availability, choose **one** of the following options:
- **Option 1:** Use `kubectl edit configmap grafana` to edit `grafana.ini` add the following section to the configuration:
```
[database]
type = [database type]
host = [database address and port]
name = [database name]
user = [database username]
password = [database password]
```
- **Option 2:** use `kubectl edit deployment my-release` to edit the pod `env` variables and add the following database variables:
```
- name: GF_DATABASE_TYPE
value: [database type]
- name: GF_DATABASE_HOST
value: [database address and port]
- name: GF_DATABASE_NAME
value: [database name]
- name: GF_DATABASE_USER
value: [database username]
- name: GF_DATABASE_PASSWORD
value: [database password]
```
For more information on Grafana High Availability setup, refer to [Set up Grafana for high availability]({{< relref "../../../setup-grafana/set-up-for-high-availability/" >}}).
## Task 3: Configure Grafana Enterprise to validate its license with AWS
In this task, you configure Grafana Enterprise to validate the license with AWS instead of Grafana Labs.
1. In AWS IAM, assign the following permissions to the Node IAM role (if you are using a Node Group), or the Pod Execution role (if you are using a Fargate profile):
- `"license-manager:CheckoutLicense"`
- `"license-manager:ListReceivedLicenses"`
- `"license-manager:GetLicenseUsage"`
- `"license-manager:CheckInLicense"`
For more information about creating an access policy, refer to [Creating IAM policies (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html).
For more information about AWS license permissions, refer to [Actions, resources, and condition keys for AWS License Manager](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awslicensemanager.html).
1. Choose **one** of the following options to update the [license_validation_type]({{< relref "../../../setup-grafana/configure-grafana/enterprise-configuration/#license_validation_type" >}}) configuration to `aws`:
- **Option 1:** Use `kubectl edit configmap grafana` to edit `grafana.ini` add the following section to the configuration:
```
[enterprise]
license_validation_type=aws
```
- **Option 2:** Use `kubectl edit deployment my-release` to edit the pod `env` variables and add the following variable:
```
name: GF_ENTERPRISE_LICENSE_VALIDATION_TYPE
value: aws
```
### Task 4: Start or restart Grafana
To activate Grafana Enterprise features, you must start (or restart) Grafana.
To restart Grafana on a Kubernetes cluster,
1. Run the command `kubectl rollout restart deployment my-release`.
1. After you update the service, navigate to your Grafana instance, sign in with Grafana Admin credentials, and navigate to the Statistics and Licensing page to validate that your license is active.
For more information about restarting Grafana, refer to [Restart Grafana]({{< relref "../../../setup-grafana/restart-grafana/" >}}).
> If you experience issues when you update the EKS cluster, refer to [Amazon EKS troubleshooting](https://docs.aws.amazon.com/eks/latest/userguide/troubleshooting.html).
docs/sources/enterprise/license/activate-aws-marketplace-license/activate-license-on-instance-outside-aws.md
-130
View File
@@ -1,130 +0,0 @@
---
aliases:
- /docs/grafana/latest/enterprise/activate-aws-marketplace-license/activate-license-on-instance-outside-aws/
- /docs/grafana/latest/enterprise/license/activate-aws-marketplace-license/activate-license-on-instance-outside-aws/
description: Activate a Grafana Enterprise license from AWS on an instance deployed
outside of AWS
keywords:
- grafana
- enterprise
- aws
- marketplace
- activate
title: Activate a Grafana Enterprise license from AWS on an instance deployed outside
of AWS
weight: 300
---
# Activate a Grafana Enterprise license from AWS on an instance deployed outside of AWS
While AWS Marketplace lists ECS and EKS as the supported environments for Grafana Enterprise, you can apply a Grafana Enterprise license from AWS Marketplace to any Grafana instance with network access to the AWS licensing service.
## Before you begin
- Purchase a subscription to [Grafana Enterprise from AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-dlncd4kzt5kx6).
- Be sure that the IAM user that was used to purchase Grafana Enterprise has permission to manage subscriptions, create new IAM users, and create access policies.
- Be sure there is network access between AWS and the environment where you intend to run Grafana. Network access is required because your Grafana instance communicates with the [AWS License Manager endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/licensemanager.html) to retrieve license and subscription information. Grafana instances with access to the public internet will have access to AWS license manager.
To activate a Grafana Enterprise license from AWS on a Grafana Enterprise instance deployed outside of AWS, complete the following tasks.
## Task 1: Install Grafana Enterprise
To install Grafana, refer to the documentation specific to your implementation.
- [Install Grafana]({{< relref "../../../setup-grafana/installation" >}}).
- [Run Grafana Docker image]({{< relref "../../../setup-grafana/installation/docker/" >}}).
- [Deploy Grafana on Kubernetes]({{< relref "../../../setup-grafana/installation/kubernetes/#deploy-grafana-enterprise-on-kubernetes" >}}).
## Task 2: Create an AWS IAM user with access to your Grafana Enterprise license
To retrieve your license, Grafana Enterprise requires access to your AWS account and license information. To grant access, create an IAM user in AWS with access to the license, and pass its credentials as environment variables on the host or container where Grafana is running. These environment variables allow Grafana to retrieve license details from AWS.
1. In the AWS License Manager service, create an IAM policy with the following permissions:
- `"license-manager:CheckoutLicense"`
- `"license-manager:ListReceivedLicenses"`
- `"license-manager:GetLicenseUsage"`
- `"license-manager:CheckInLicense"`
For more information about creating a policy in AWS, refer to [Creating IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html).
For more information about AWS Identity and Access Management, refer to [IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html).
1. To limit the policy to obtain usage data just for Grafana Enterprise, in the **Resources** section of the policy, specify your license ARN.
You can find your license ID in the **Granted Licenses** section of [AWS License Manager](https://console.aws.amazon.com/license-manager/home).
The policy JSON should look similar to the following example:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": "license-manager:GetLicenseUsage",
"Resource": "arn:aws:license-manager::[YOUR_ACCOUNT]:license:[YOUR_LICENSE_ID]"
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": [
"license-manager:CheckoutLicense",
"license-manager:ListReceivedLicenses",
"license-manager:CheckInLicense"
],
"Resource": "*"
}
]
}
```
1. Create an IAM user and choose access key credentials as its authentication method.
For more information about creating an IAM user, refer to [IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html).
For more information about access key credentials, refer to [Managing access keys for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html).
1. Attach the policy you created to the IAM user.
1. Add the following values as environment variables to the host or container running Grafana:
- AWS region
- IAM user's access key ID
- IAM user's secret access key
The environment variables should look similar to the following example:
```
AWS_ACCESS_KEY_ID=ABCD5E75FGHIJKTM7
AWS_SECRET_ACCESS_KEY=k8fhYAQVy+5NhCejhe6HeSjSphjRuy+12C06
AWS_REGION=us-east-1
```
## Task 3: Configure Grafana Enterprise to validate its license with AWS
In this task you configure Grafana Enterprise to validate the license with AWS instead of Grafana Labs.
Choose one of the following options to update the [license_validation_type]({{< relref "../../../setup-grafana/configure-grafana/enterprise-configuration/#license_validation_type" >}}) configuration to `aws`:
- **Option 1:** In the `[enterprise]` section of the grafana.ini configuration file, add `license_validation_type=aws`.
For example:
```
[enterprise]
license_validation_type=aws
```
- **Option 2:** Add the following environment variable to the container or host:
```
GF_ENTERPRISE_LICENSE_VALIDATION_TYPE=aws
```
## Task 4: Start or restart Grafana
To activate Grafana Enterprise features, start (or restart) Grafana.
For information about restarting Grafana, refer to [Restart Grafana]({{< relref "../../../setup-grafana/restart-grafana/" >}}).
docs/sources/enterprise/license/activate-aws-marketplace-license/manage-license-in-aws-marketplace.md
-41
View File
@@ -1,41 +0,0 @@
---
aliases:
- /docs/grafana/latest/enterprise/activate-aws-marketplace-license/manage-license-in-aws-marketplace/
- /docs/grafana/latest/enterprise/license/activate-aws-marketplace-license/manage-license-in-aws-marketplace/
description: Manage your Grafana Enterprise license in AWS Marketplace
keywords:
- grafana
- enterprise
- aws
- marketplace
- manage
- add
- remove
- users
title: Manage your Grafana Enterprise license in AWS Marketplace
weight: 400
---
## Manage your Grafana Enterprise license in AWS Marketplace
You can use AWS Marketplace to make the following modifications to your Grafana Enterprise license:
- Add active users
- Remove active users
- Cancel your subscription to Grafana Enterprise.
**To modify your Grafana Enterprise subscription in AWS Marketplace:**
1. Open the AWS Console and navigate to [Subscription Management](https://console.aws.amazon.com/marketplace/home/subscriptions#/subscriptions).
1. Update your license.
1. Sign in to Grafana as a Server Administrator.
1. Hover over **Server Admin** in the navigation bar and click **Statistics and Licensing**.
1. In the **Token** section under **Enterprise License**, click **Renew License**.
This action retrieves updated license information from AWS.
> To learn more about licensing and active users, refer to [Understanding Grafana Enterprise licensing]({{< relref "../license-restrictions/" >}}).
docs/sources/enterprise/license/activate-aws-marketplace-license/transfer-ge-license.md
-30
View File
@@ -1,30 +0,0 @@
---
aliases:
- /docs/grafana/latest/enterprise/activate-aws-marketplace-license/transfer-ge-license/
- /docs/grafana/latest/enterprise/license/activate-aws-marketplace-license/transfer-ge-license/
description: Transfer your AWS Marketplace Grafana Enterprise license
keywords:
- grafana
- enterprise
- aws
- marketplace
- transfer
- move
title: Transfer your AWS Marketplace Grafana Enterprise license
weight: 400
---
# Transfer your AWS Marketplace Grafana Enterprise license
You can transfer your AWS Marketplace Grafana Enterprise license to another Grafana Enterprise instance. The transfer process requires that you first remove your license from one instance, and then apply the license to another instance.
> When you remove an Enterprise license, the system immediately disables all Grafana Enterprise features.
To remove an Enterprise license from a Grafana Enterprise instance, perform one of the following steps:
- If you are using Amazon ECS or Amazon EKS, remove the `GF_ENTERPRISE_LICENSE_VALIDATION_TYPE` environment variable from the container.
- If you have deployed Grafana Enterprise outside of AWS, remove the `aws` license_validation_type value from the grafana.ini configuration file.
It can take the system up to one hour to clear the license. After the system clears the license, you can apply the same license to another Grafana Enterprise instance.
To determine that the system has returned your license, check the license details in AWS License Manager.
docs/sources/enterprise/license/activate-license.md
-86
View File
@@ -1,86 +0,0 @@
---
aliases:
- /docs/grafana/latest/enterprise/activate-license/
- /docs/grafana/latest/enterprise/license/activate-license/
description: Activate an Enterprise license
keywords:
- grafana
- licensing
- enterprise
title: Activate an Enterprise license
weight: 100
---
# Activate an Enterprise license
Follow these steps to activate your Grafana Enterprise license:
## Step 1. Download your license file
To download your Grafana Enterprise license:
1. Sign in to your [Grafana Cloud](https://grafana.com) account.
1. Go to **My Account** and select an organization from the drop-down menu at the top left of the page. On the Overview page for each organization, you can see a section for Grafana Enterprise licenses. Click **Details** next to a license.
1. At the bottom of the license details page, select **Download token** to download the `license.jwt` file that contains your license.
## Step 2. Add your license to a Grafana instance
There is more than one way to add the license to a Grafana instance:
### Upload the license file via the Grafana server administrator page
This is the preferred option for single instance installations of Grafana Enterprise.
1. Sign in as a Grafana server administrator.
1. Navigate to **Server Admin > Upgrade** within Grafana.
1. Click **Upload license token file**.
1. Select your license file, and upload it.
### Put the `license.jwt` file into the data directory of Grafana
On Linux systems, the data directory is usually at `/var/lib/grafana`.
You can also configure a custom location for the license file using the grafana.ini setting:
```bash
[enterprise]
license_path = /company/secrets/license.jwt
```
This setting can also be set with an environment variable, which is useful if you're running Grafana with Docker and have a custom volume where you have placed the license file. In this case, set the environment variable `GF_ENTERPRISE_LICENSE_PATH` to point to the location of your license file.
### Set the content of the license file as a configuration option
You can add a license by pasting the content of the `license.jwt`
to the grafana.ini configuration file:
```bash
[enterprise]
license_text = eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aGlzIjoiaXMiLCJub3QiOiJhIiwidmFsaWQiOiJsaWNlbnNlIn0.bxDzxIoJlYMwiEYKYT_l2s42z0Y30tY-6KKoyz9RuLE
```
This option can be set using the `GF_ENTERPRISE_LICENSE_TEXT`
environment variable.
## Step 3. Ensure that the license file's root URL matches the root_url configuration option
Update the [`root_url`]({{< relref "../../setup-grafana/configure-grafana/#root-url" >}}) in your configuration. It should be the URL that users type in their browsers to access the frontend, not the node hostname(s).
This is important, because as part of the validation checks at startup, Grafana compares the license URL to the [`root_url`]({{< relref "../../setup-grafana/configure-grafana/#root-url" >}}) in your configuration.
In your configuration file:
```
[server]
root_url = https://grafana.example.com/
```
Or with an environment variable:
```
GF_SERVER_ROOT_URL=https://grafana.example.com/
```
## Step 4. Restart Grafana
To finalize the installation of Grafana Enterprise, restart Grafana to enable all Grafana Enterprise features. Refer to [restart Grafana]({{< relref "../../setup-grafana/restart-grafana/" >}}) for more information.
docs/sources/enterprise/license/license-expiration.md
-92
View File
@@ -1,92 +0,0 @@
---
aliases:
- /docs/grafana/latest/enterprise/license-expiration/
- /docs/grafana/latest/enterprise/license/license-expiration/
description: ''
keywords:
- grafana
- licensing
title: License expiration
weight: 200
---
# License expiration
If your license has expired, most of Grafana keeps working as normal. Some enterprise functionality stops or runs with reduced functionality and Grafana displays a banner informing the users that Grafana is running on an expired license. Your Grafana admin needs to upload a new license file to restore full functionality.
> Replace your license as soon as possible. Running Grafana Enterprise with an expired license is unsupported and can lead to unexpected consequences.
## Update your license
1. Locate your current `license.jwt` file. In a standard installation it is stored inside the Grafana data directory, which on a typical Linux installation is in `/var/lib/grafana/data`. This location might be overridden in the ini file [Configuration]({{< relref "../../setup-grafana/configure-grafana/" >}}).
```ini
[enterprise]
license_path = /path/to/your/license.jwt
```
The configuration file's location may also be overridden by the `GF_ENTERPRISE_LICENSE_PATH` environment variable.
2. Log in to your [Grafana Cloud Account](https://grafana.com/login) and make sure you're in the correct organization in the dropdown at the top of the page.
3. Under the **Grafana Enterprise** section in the menu bar to the left, choose licenses and download the currently valid license with which you want to run Grafana. If you cannot see a valid license on Grafana.com, please contact your account manager at Grafana Labs to renew your subscription.
4. Replace the current `license.jwt`-file with the one you've just downloaded.
5. [Restart Grafana]({{< relref "../../setup-grafana/restart-grafana/" >}}).
## If your license expires
If your Grafana Enterprise license expires, you can expect the following changes in feature behavior.
### Data source permissions
Your current data source permissions will keep working as expected, but you'll be unable to add new data source permissions until the license has been renewed.
### LDAP authentication
- LDAP synchronization is not affected by an expired license.
- Team sync debugging is unavailable.
### SAML authentication
SAML authentication is not affected by an expired license.
### Role-based access control (RBAC)
- Creating, updating and deleting custom roles is not available.
- Modifying permissions for custom roles is not available.
### Reporting
- You're unable to configure new reports or generate previews.
- Existing reports continue to be sent.
### Enterprise plugins
Enterprise plugins might stop working.
### White labeling
The white labeling feature is turned off, meaning that any white labeling options will not have any effect.
### Usage insights
Exporting usage insights logs to Loki will be turned off for licenses expired for more than 7 days.
All the other usage insights features are turned off as soon as the license expires, meaning that you will not be able to see dashboard usage, presence indicators, or use improved search. Grafana continues to collect usage data and you will have access to it as soon as you update your license.
### Vault integration
Vault integration is not affected by an expired license.
### Auditing
Auditing is not affected by an expired license.
### License restrictions
The concurrent session limit remains active for seven days after the expiration date, after which it will be turned off.
The active users limit is turned off immediately.
### Settings updates at runtime
Settings updates at runtime are not affected by an expired license.
docs/sources/enterprise/license/license-restrictions.md
-75
View File
@@ -1,75 +0,0 @@
---
aliases:
- /docs/grafana/latest/enterprise/license-restrictions/
- /docs/grafana/latest/enterprise/license/license-restrictions/
description: Grafana Enterprise license restrictions
keywords:
- grafana
- licensing
- enterprise
title: License restrictions
weight: 300
---
# Grafana Enterprise license restrictions
When you become a Grafana Enterprise customer, you receive a license that governs your use of Grafana Enterprise.
## Active users limit
Your Grafana license includes a maximum number of active users.
- An _active user_ is a user who has signed in to Grafana within the last 30 days. This is a rolling window that is updated daily.
- When you reach the maximum number of active users, only currently active users (users who have signed in over the past 30 days) can sign in. When a new user or a previously-inactive user tries to sign in, the user will see an error message indicating that Grafana has reached its license limit.
- The user's role, number of dashboards that a user can view or edit, and the number of organizations that they can access does not affect the active user count.
- A license limit banner appears to administrators when Grafana reaches its active user limit; editors and viewers do not see the banner.
### Determine the number of active users
To determine the number of active users:
1. Sign in to Grafana Enterprise as a System Administrator.
1. Click **Server Admin** (the shield icon).
1. Click **Statistics and licensing**.
1. Review the utilization count on the **Utilization** panel.
## Tiered licensing (deprecated)
A tiered license defines dashboard viewers, and dashboard editors and administrators, as two distinct user types that each have their own user limit.
As of Grafana Enterprise version 9.0, Grafana only counts and enforces the _total_ number of active users in your Grafana instance. For example, if you purchase 150 active users, you can have 20 admins, 70 editors, and 60 viewers, or you can have 150 admins. Grafana will enforce the total number of active users even if you use a license that grants a specific number of admins or editors and a certain number of viewers. This is a more permissive policy than before, which gives you the flexibility to change users' roles.
If you are running a pre-9.0 version of Grafana Enterprise, please refer to the documentation for that version to learn more about license enforcement in your current version.
## Additional license restrictions
Your license is controlled by the following rules:
**License expiration date:** The license includes an expiration date, which is the date when a license becomes inactive.
As the license expiration date approaches, you will see a banner in Grafana that encourages you to renew. To learn about how to renew your license and what happens in Grafana when a license expires, refer to [License expiration]({{< relref "license-expiration/" >}}).
**Grafana License URL:** Your license does not work with an instance of Grafana with a different root URL.
The License URL is the complete URL of your Grafana instance, for example `https://grafana.your-company.com/`. It is defined in the [root_url]({{< relref "../../setup-grafana/configure-grafana/#root_url">}}) configuration setting.
**Concurrent sessions limit**: As of Grafana Enterprise 7.5, users can initiate up to three concurrent sessions of Grafana.
The system creates a session when a user signs in to Grafana from a new device, a different browser, or an incognito window. If a user signs in to Grafana from another tab or window within the same browser, only one session is used.
When a user reaches the session limit, the fourth connection succeeds and the longest inactive session is signed out.
## Request usage billing
You can request Grafana Labs to activate usage billing which allows an unlimited number of active users. When usage billing is enabled, Grafana does not enforce active user limits or display warning banners. Instead, you are charged for active users that exceed the limit, according to your customer contract.
Usage billing involves a contractual agreement between you and Grafana Labs, and it is only available if Grafana Enterprise is configured to [automatically refresh its license token]({{< relref "../../setup-grafana/configure-grafana/enterprise-configuration/#auto_refresh_license" >}}).
## Request a change to your license
To increase the number of licensed users within Grafana, extend a license, or change your licensed URL, contact [Grafana support](https://grafana.com/profile/org#support) or your Grafana Labs account team. They will update your license, which you can activate from within Grafana.
For instructions about how to activate your license after it is updated, refer to [Activate an Enterprise license]({{< relref "activate-license/" >}}).
docs/sources/enterprise/query-caching.md
+1 -1
View File
@@ -17,7 +17,7 @@ When query caching is enabled, Grafana temporarily stores the results of data so
Query caching works for all backend data sources, and queries sent through the data source proxy. You can enable the cache globally and configure the cache duration (also called Time to Live, or TTL).
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise" >}}) and [Grafana Cloud Pro and Advanced]({{< ref "/docs/grafana-cloud" >}}).
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise/" >}}) and [Grafana Cloud Pro and Advanced]({{< ref "/docs/grafana-cloud" >}}).
The following cache backends are available: in-memory, Redis, and Memcached.
docs/sources/enterprise/recorded-queries.md
+1 -1
View File
@@ -17,7 +17,7 @@ Recorded queries allow you to see trends over time by taking a snapshot of a dat
For our plugins that do not return time series, it might be useful to plot historical data. For example, you might want to query ServiceNow to see a history of request response times but it can only return current point-in-time metrics.
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise" >}}).
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise/" >}}).
## How recorded queries work
docs/sources/enterprise/reporting.md
+10 -10
View File
@@ -65,7 +65,7 @@ Only organization admins can create reports by default. You can customize who ca
### Choose template variables
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise" >}}) version 7.5 and later behind the `reportVariables` feature flag, Grafana Enterprise version 8.0 and later without a feature flag, and [Grafana Cloud Pro and Advanced]({{< ref "/docs/grafana-cloud" >}}).
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise/" >}}) version 7.5 and later behind the `reportVariables` feature flag, Grafana Enterprise version 8.0 and later without a feature flag, and [Grafana Cloud Pro and Advanced]({{< ref "/docs/grafana-cloud" >}}).
You can configure report-specific template variables for the dashboard on the report page. The variables that you select will override the variables from the dashboard, and they are used when rendering a PDF file of the report. For detailed information about using template variables, refer to the [Templates and variables]({{< relref "../variables/" >}}) section.
@@ -73,7 +73,7 @@ You can configure report-specific template variables for the dashboard on the re
### Render a report with panels or rows set to repeat by a variable
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise" >}}) version 8.0 and later, and [Grafana Cloud Pro and Advanced]({{< ref "/docs/grafana-cloud" >}}).
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise/" >}}) version 8.0 and later, and [Grafana Cloud Pro and Advanced]({{< ref "/docs/grafana-cloud" >}}).
You can include dynamic dashboards with panels or rows, set to repeat by a variable, into reports. For detailed information about setting up repeating panels or rows in dashboards, refer to the [Repeat panels or rows]({{< relref "../panels/add-panels-dynamically/" >}}) section.
@@ -85,7 +85,7 @@ You can include dynamic dashboards with panels or rows, set to repeat by a varia
### Report time range
> **Note:** You can set custom report time ranges in [Grafana Enterprise]({{< relref "../enterprise" >}}) 7.2+ and [Grafana Cloud Pro and Advanced]({{< ref "/docs/grafana-cloud" >}}).
> **Note:** You can set custom report time ranges in [Grafana Enterprise]({{< relref "../enterprise/" >}}) 7.2+ and [Grafana Cloud Pro and Advanced]({{< ref "/docs/grafana-cloud" >}}).
By default, reports use the saved time range of the dashboard. Changing the time range of the report can be done by:
@@ -109,7 +109,7 @@ If the time zone is set differently between your Grafana server and its remote i
### CSV export
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise" >}}) 8+ with the [Grafana image renderer plugin](https://grafana.com/grafana/plugins/grafana-image-renderer) v3.0+, and [Grafana Cloud Pro and Advanced]({{< ref "/docs/grafana-cloud" >}}).
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise/" >}}) 8+ with the [Grafana image renderer plugin](https://grafana.com/grafana/plugins/grafana-image-renderer) v3.0+, and [Grafana Cloud Pro and Advanced]({{< ref "/docs/grafana-cloud" >}}).
You can attach a CSV file to the report email for each table panel on the selected dashboard, along with the PDF report. By default, CSVs larger than 10Mb won't be sent to avoid email servers to reject the email. You can increase or decrease this limit in the [reporting configuration]({{< relref "#rendering-configuration" >}}).
@@ -121,7 +121,7 @@ A background job runs every 10 minutes and removes temporary CSV files. You can
### Scheduling
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise" >}}) version 8.0 and later, and [Grafana Cloud Pro and Advanced]({{< ref "/docs/grafana-cloud" >}}).
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise/" >}}) version 8.0 and later, and [Grafana Cloud Pro and Advanced]({{< ref "/docs/grafana-cloud" >}}).
> The scheduler was significantly changed in Grafana Enterprise version 8.1.
Scheduled reports can be sent once, or repeated on an hourly, daily, weekly, or monthly basis, or sent at custom intervals. You can also disable scheduling by selecting **Never**, for example to send the report via the API.
@@ -144,7 +144,7 @@ When you schedule a report with a monthly frequency, and set the start date betw
### Send a test email
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise" >}}) version 7.0 and later, and [Grafana Cloud Pro and Advanced]({{< ref "/docs/grafana-cloud" >}}).
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise/" >}}) version 7.0 and later, and [Grafana Cloud Pro and Advanced]({{< ref "/docs/grafana-cloud" >}}).
1. In the report, click **Send test email**.
1. In the Email field, enter the email address or addresses that you want to test, separated by semicolon.
@@ -157,19 +157,19 @@ The last saved version of the report will be sent to selected emails. You can us
### Pause a report
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise" >}}) version 8.0 and later, and [Grafana Cloud Pro and Advanced]({{< ref "/docs/grafana-cloud" >}}).
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise/" >}}) version 8.0 and later, and [Grafana Cloud Pro and Advanced]({{< ref "/docs/grafana-cloud" >}}).
You can pause sending of reports from the report list view by clicking the pause icon. The report will not be sent according to its schedule until it is resumed by clicking the resume button on the report row.
### Add multiple dashboards to a report
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise" >}}) version 9.0 and later, and [Grafana Cloud Pro and Advanced]({{< relref "/grafana-cloud" >}}).
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise/" >}}) version 9.0 and later, and [Grafana Cloud Pro and Advanced]({{< relref "grafana-cloud/" >}}).
You can add more than one dashboard to a report. Additional dashboards will be rendered as new pages in the same PDF file, or additional images if you chose to embed images in your report email. Note: you cannot add the same dashboard to a report twice.
### Embed a dashboard as an image into a report
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise" >}}) version 9.0 and later, and [Grafana Cloud Pro and Advanced]({{< relref "/grafana-cloud" >}}).
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise/" >}}) version 9.0 and later, and [Grafana Cloud Pro and Advanced]({{< relref "grafana-cloud/" >}}).
You can send a report email with an image of the dashboard embedded in the email itself, instead of attached as a PDF. In this case, the email recipients can see the dashboard at a glance instead of having to open the PDF.
@@ -212,7 +212,7 @@ font_italic = DejaVuSansCondensed-Oblique.ttf
## Report settings
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise" >}}) version 7.2 and later, and [Grafana Cloud Pro and Advanced]({{< ref "/docs/grafana-cloud" >}}).
> **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise/" >}}) version 7.2 and later, and [Grafana Cloud Pro and Advanced]({{< ref "/docs/grafana-cloud" >}}).
You can configure organization-wide report settings in the **Settings** tab on the **Reporting** page. Settings are applied to all the reports for current organization.