Docs: Sync all doc changes in main to v8.0.x (#35333)
This commit is contained in:
Torkel Ödegaard
@@ -43,6 +43,7 @@ With Grafana Enterprise [enhanced LDAP]({{< relref "enhanced_ldap.md" >}}), you
|
||||
|
||||
With Grafana Enterprise, you get access to new features, including:
|
||||
|
||||
- [Fine-grained access control]({{< relref "access-control/_index.md" >}}) to control access with fine-grained roles and permissions.
|
||||
- [Data source permissions]({{< relref "datasource_permissions.md" >}}) to restrict query access to specific teams and users.
|
||||
- [Data source query caching]({{< relref "query-caching.md" >}}) to temporarily store query results in Grafana to reduce data source load and rate limiting.
|
||||
- [Reporting]({{< relref "reporting.md" >}}) to generate a PDF report from any dashboard and set up a schedule to have it emailed to whoever you choose.
|
||||
|
||||
@@ -0,0 +1,60 @@
|
||||
+++
|
||||
title = "Fine-grained access control"
|
||||
description = "Grant, change, or revoke access to Grafana resources"
|
||||
keywords = ["grafana", "fine-grained-access-control", "roles", "permissions", "enterprise"]
|
||||
weight = 100
|
||||
+++
|
||||
|
||||
# Fine-grained access control
|
||||
|
||||
> **Note:** Fine-grained access control is in beta, and you can expect changes in future releases.
|
||||
|
||||
Fine-grained access control provides a standardized way of granting, changing, and revoking access when it comes to viewing and modifying Grafana resources, such as users and reports.
|
||||
Fine-grained access control works alongside the current [Grafana permissions]({{< relref "../../permissions/_index.md" >}}), and it allows you granular control of users’ actions.
|
||||
|
||||
To learn more about how fine-grained access control works, refer to [Roles]({{< relref "./roles.md" >}}) and [Permissions]({{< relref "./permissions.md" >}}).
|
||||
To use the fine-grained access control system, refer to [Fine-grained access control usage scenarios]({{< relref "./usage-scenarios.md" >}}).
|
||||
|
||||
## Access management
|
||||
|
||||
Fine-grained access control considers a) _who_ has an access (`identity`), and b) _what they can do_ and on which _Grafana resource_ (`role`).
|
||||
|
||||
You can grant, change, or revoke access to _users_ (`identity`). When an authenticated user tries to access a Grafana resource, the authorization system checks the required fine-grained permissions for the resource and determines whether or not the action is allowed. Refer to [Fine-grained permissions]({{< relref "./permissions.md" >}}) for a complete list of available permissions.
|
||||
|
||||
To grant or revoke access to your users, create or remove built-in role assignments. For more information, refer to [Built-in role assignments]({{< relref "./roles.md#built-in-role-assignments" >}}).
|
||||
|
||||
## Resources with fine-grained permissions
|
||||
|
||||
Fine-grained access control is currently available for [Reporting]({{< relref "../reporting.md" >}}) and [Managing Users]({{< relref "../../manage-users/_index.md" >}}).
|
||||
To learn more about specific endpoints where you can use access control, refer to [Permissions]({{< relref "./permissions.md" >}}) and to the relevant API guide:
|
||||
|
||||
- [Fine-grained access control API]({{< relref "../../http_api/access_control.md" >}})
|
||||
- [Admin API]({{< relref "../../http_api/admin.md" >}})
|
||||
- [Organization API]({{< relref "../../http_api/org.md" >}})
|
||||
- [Reporting API]({{< relref "../../http_api/reporting.md" >}})
|
||||
- [User API]({{< relref "../../http_api/user.md" >}})
|
||||
|
||||
## Enable fine-grained access control
|
||||
|
||||
Fine-grained access control is available behind the `accesscontrol` feature toggle in Grafana Enterprise 8.0+.
|
||||
You can enable it either in a [config file](({{< relref "../../administration/configuration.md#fconfig-file-locations" >}})) or by [configuring an environment variable](http://localhost:3002/docs/grafana/next/administration/configuration/#configure-with-environment-variables).
|
||||
|
||||
### Enable in config file
|
||||
|
||||
In your [config file](({{< relref "../../administration/configuration.md#config-file-locations" >}})), add `accesscontrol` as a [feature_toggle](({{< relref "../../administration/configuration.md#feature_toggle" >}})).
|
||||
|
||||
```
|
||||
[feature_toggles]
|
||||
# enable features, separated by spaces
|
||||
enable = accesscontrol
|
||||
```
|
||||
|
||||
### Enable with an environment variable
|
||||
|
||||
You can use `GF_FEATURE_TOGGLES_ENABLE = accesscontrol` environment variable to override the config file configuration and enable fine-grained access control.
|
||||
|
||||
Refer to [Configuring with environment variables]({{< relref "../../administration/configuration.md#configure-with-environment-variables" >}}) for more information.
|
||||
|
||||
### Verify if enabled
|
||||
|
||||
You can verify if fine-grained access control is enabled or not by sending an HTTP request to the [Check endpoint]({{< relref "../../http_api/access_control.md#check-if-enabled" >}}).
|
||||
@@ -0,0 +1,31 @@
|
||||
+++
|
||||
title = "Fine-grained access control references"
|
||||
description = "Refer to fine-grained access control references"
|
||||
keywords = ["grafana", "fine-grained-access-control", "roles", "fixed-roles", "built-in-role-assignments", "permissions", "enterprise"]
|
||||
weight = 130
|
||||
+++
|
||||
|
||||
# Fine-grained access control references
|
||||
The reference information that follows complements conceptual information about [Roles]({{< relref "./roles.md" >}}).
|
||||
|
||||
## Fine-grained access fixed roles
|
||||
|
||||
Fixed roles | Permissions | Descriptions
|
||||
--- | --- | ---
|
||||
fixed:permissions:admin:read | roles:read<br>roles:list<br>roles.builtin:list | Allows to list and get available roles and built-in role assignments.
|
||||
fixed:permissions:admin:edit | All permissions from `fixed:permissions:admin:read` and <br>roles:write<br>roles:delete<br>roles.builtin:add<br>roles.builtin:remove | Allows every read action and in addition allows to create, change and delete custom roles and create or remove built-in role assignments.
|
||||
fixed:reporting:admin:read | reports:read<br>reports:send<br>reports.settings:read | Allows to read reports and report settings.
|
||||
fixed:reporting:admin:edit | All permissions from `fixed:reporting:admin:read` and <br>reports.admin:write<br>reports:delete<br>reports.settings:write | Allows every read action for reports and in addition allows to administer reports.
|
||||
fixed:users:admin:read | users.authtoken:list<br>users.quotas:list<br>users:read<br>users.teams:read | Allows to list and get users and related information.
|
||||
fixed:users:admin:edit | All permissions from `fixed:users:admin:read` and <br>users.password:update<br>users:write<br>users:create<br>users:delete<br>users:enable<br>users:disable<br>users.permissions:update<br>users:logout<br>users.authtoken:update<br>users.quotas:update | Allows every read action for users and in addition allows to administer users.
|
||||
fixed:users:org:read | org.users:read | Allows to get user organizations.
|
||||
fixed:users:org:edit | All permissions from `fixed:users:org:read` and <br>org.users:add<br>org.users:remove<br>org.users.role:update | Allows every read action for user organizations and in addition allows to administer user organizations.
|
||||
fixed:ldap:admin:read | ldap.user:read<br>ldap.status:read | Allows to read LDAP information and status.
|
||||
fixed:ldap:admin:edit | All permissions from `fixed:ldap:admin:read` and <br>ldap.user:sync | Allows every read action for LDAP and in addition allows to administer LDAP.
|
||||
|
||||
## Default built-in role assignments
|
||||
|
||||
Built-in roles | Associated roles | Descriptions
|
||||
--- | --- | ---
|
||||
Grafana Admin | fixed:permissions:admin:edit<br>fixed:permissions:admin:read<br>fixed:reporting:admin:edit<br>fixed:reporting:admin:read<br>fixed:users:admin:edit<br>fixed:users:admin:read<br>fixed:users:org:edit<br>fixed:users:org:read<br>fixed:ldap:admin:edit<br>fixed:ldap:admin:read | Allows access to resources which [Grafana Server Admin]({{< relref "../../permissions/_index.md#grafana-server-admin-role" >}}) has permissions by default.
|
||||
Admin | fixed:users:org:edit<br>fixed:users:org:read<br>fixed:reporting:admin:edit<br>fixed:reporting:admin:read | Allows access to resource which [Admin]({{< relref "../../permissions/organization_roles.md" >}}) has permissions by default.
|
||||
@@ -0,0 +1,77 @@
|
||||
+++
|
||||
title = "Permissions"
|
||||
description = "Understand fine-grained access control permissions"
|
||||
keywords = ["grafana", "fine-grained access-control", "roles", "permissions", "enterprise"]
|
||||
weight = 115
|
||||
+++
|
||||
|
||||
# Permissions
|
||||
|
||||
A permission is an action and a scope. When creating a fine-grained access control, consider what specific action a user should be allowed to perform, and on what resources (its scope).
|
||||
|
||||
To grant permissions to a user, you create a built-in role assignment to map a role to a built-in role. A built-in role assignment *modifies* to one of the existing built-in roles in Grafana (Viewer, Editor, Admin). For more information, refer to [Built-in role assignments]({{< relref "./roles.md#built-in-role-assignments" >}}).
|
||||
|
||||
To learn more about which permissions are used for which resources, refer to [Resources with fine-grained permissions]({{< relref "./_index.md#resources-with-fine-grained-permissions" >}}).
|
||||
|
||||
action
|
||||
: The specific action on a resource defines what a user is allowed to perform if they have permission with the relevant action assigned to it.
|
||||
|
||||
scope
|
||||
: The scope describes where an action can be performed, such as reading a specific user profile. In such case, a permission is associated with the scope `users:<userId>` to the relevant role.
|
||||
|
||||
## Action definitions
|
||||
|
||||
The following list contains fine-grained access control actions.
|
||||
|
||||
Actions | Applicable scopes | Descriptions
|
||||
--- | --- | ---
|
||||
roles:list | roles:* | List available roles without permissions.
|
||||
roles:read | roles:* | Read a specific role with it's permissions.
|
||||
roles:write | permissions:delegate | Create or update a custom role.
|
||||
roles:delete | permissions:delegate | Delete a custom role.
|
||||
roles.builtin:list | roles:* | List built-in role assignments.
|
||||
roles.builtin:add | permissions:delegate | Create a built-in role assignment.
|
||||
roles.builtin:remove | permissions:delegate | Delete a built-in role assignment.
|
||||
reports.admin:create | reports:* | Create reports.
|
||||
reports.admin:write | reports:* | Update reports.
|
||||
reports:delete | reports:* | Delete reports.
|
||||
reports:read | reports:* | List all available reports or get a specific report.
|
||||
reports:send | reports:* | Send a report email.
|
||||
reports.settings:write | n/a | Update report settings.
|
||||
reports.settings:read | n/a | Read report settings.
|
||||
provisioning:reload | service:access-control | Reload provisioning files.
|
||||
users:read | global:users:* | Read or search user profiles.
|
||||
users:write | global:users:* | Update a user’s profile.
|
||||
users.teams:read | global:users:* | Read a user’s teams.
|
||||
users.authtoken:list | global:users:* | List authentication tokens that are assigned to a user.
|
||||
users.authtoken:update | global:users:* | Update authentication tokens that are assigned to a user.
|
||||
users.password:update | global:users:* | Update a user’s password.
|
||||
users:delete | global:users:* | Delete a user.
|
||||
users:create | n/a | Create a user.
|
||||
users:enable | global:users:* | Enable a user.
|
||||
users:disable | global:users:* | Disable a user.
|
||||
users.permissions:update | global:users:* | Update a user’s organization-level permissions.
|
||||
users:logout | global:users:* | Log out a user.
|
||||
users.quotas:list | global:users:* | List a user’s quotas.
|
||||
users.quotas:update | global:users:* | Update a user’s quotas.
|
||||
org.users.read | users:* | Get user profiles within an organization.
|
||||
org.users.add | users:* | Add a user to an organization.
|
||||
org.users.remove | users:* | Remove a user from an organization.
|
||||
org.users.role:update | users:* | Update the organization role (`Viewer`, `Editor`, `Admin`) for an organization.
|
||||
ldap.user:read | n/a | Get a user via LDAP.
|
||||
ldap.user:sync | n/a | Sync a user via LDAP.
|
||||
ldap.status:read | n/a | Verify the LDAP servers’ availability.
|
||||
status:accesscontrol | service:access-control | Get access-control enabled status.
|
||||
|
||||
## Scope definitions
|
||||
|
||||
The following list contains fine-grained access control scopes.
|
||||
|
||||
Scopes | Descriptions
|
||||
--- | ---
|
||||
roles:* | Restrict an action to a set of roles. For example, `roles:*` matches any role, `roles:randomuid` matches only the role with UID `randomuid` and `roles:custom:reports:{editor,viewer}` matches both `custom:reports:editor` and `custom:reports:viewer` roles.
|
||||
permissions: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.
|
||||
reports:* | Restrict an action to a set of reports. For example, `reports:*` matches any report and `reports:1` matches the report with id `1`.
|
||||
service:accesscontrol | Restrict an action to target only the fine-grained access control service. For example, you can use this in conjunction with the `provisioning:reload` or the `status:accesscontrol` actions.
|
||||
global:users:* | Restrict an action to a set of global users.
|
||||
users:* | Restrict an action to a set of users from an organization.
|
||||
@@ -0,0 +1,264 @@
|
||||
+++
|
||||
title = "Provisioning roles and assignments"
|
||||
description = "Understand how to provision roles and assignments in fine-grained access control"
|
||||
keywords = ["grafana", "fine-grained-access-control", "roles", "provisioning", "assignments", "permissions", "enterprise"]
|
||||
weight = 120
|
||||
+++
|
||||
|
||||
# Provisioning
|
||||
|
||||
You can create, change or remove [Custom roles]({{< relref "./roles.md#custom-roles" >}}) and create or remove [built-in role assignments]({{< relref "./roles.md#built-in-role-assignments" >}}), by adding one or more YAML configuration files in the [`provisioning/access-control/`]({{< relref "../../administration/configuration/#provisioning" >}}) directory.
|
||||
Refer to [Grafana provisioning]({{< relref "../../administration/configuration/#provisioning" >}}) to learn more about provisioning.
|
||||
|
||||
If you want to manage roles and built-in role assignments by API, refer to the [Fine-grained access control HTTP API]({{< relref "../../http_api/access_control/" >}}).
|
||||
|
||||
## Configuration
|
||||
|
||||
The configuration files must be placed in [`provisioning/access-control/`]({{< relref "../../administration/configuration/#provisioning" >}}).
|
||||
Grafana performs provisioning during the startup. Refer to the [Reload provisioning configurations]({{< relref "../../http_api/admin/#reload-provisioning-configurations" >}}) to understand how you can reload configuration at runtime.
|
||||
|
||||
## Manage custom roles
|
||||
|
||||
You can create, update, and delete custom roles, as well as create and remove built-in role assignments.
|
||||
|
||||
### Create or update roles
|
||||
|
||||
To create or update custom roles, you can add a list of `roles` in the configuration.
|
||||
|
||||
Every role has a [version]({{< relref "./roles.md#custom-roles" >}}) number. For each role you update, you must remember to increment it, otherwise changes won't be accounted for.
|
||||
|
||||
When you update a role, the existing role inside grafana is altered to be exactly what is specified in the YAML file, including permissions.
|
||||
|
||||
Here is an example YAML file to create a local role with a set of permissions:
|
||||
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
|
||||
# Roles to insert into the database, or roles to update in the database
|
||||
roles:
|
||||
- name: custom:users:editor
|
||||
description: "This role allows users to list, create, or update other users within the organization."
|
||||
version: 1
|
||||
orgId: 1
|
||||
permissions:
|
||||
- action: "users:read"
|
||||
scope: "users:*"
|
||||
- action: "users:write"
|
||||
scope: "users:*"
|
||||
- action: "users:create"
|
||||
scope: "users:*"
|
||||
```
|
||||
|
||||
Here is an example YAML file to create a global role with a set of permissions, where the `global:true` option makes a role global:
|
||||
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
|
||||
# Roles to insert into the database, or roles to update in the database
|
||||
roles:
|
||||
- name: custom:users:editor
|
||||
description: "This role allows users to list, create, or update other users within the organization."
|
||||
version: 1
|
||||
global: true
|
||||
permissions:
|
||||
- action: "users:read"
|
||||
scope: "users:*"
|
||||
- action: "users:write"
|
||||
scope: "users:*"
|
||||
- action: "users:create"
|
||||
scope: "users:*"
|
||||
```
|
||||
The `orgId` is lost when the role is set to global.
|
||||
|
||||
### Delete roles
|
||||
|
||||
To delete a role, you can add a list of roles under the `deleteRoles` section in the configuration file. Such a deletion is performed after a role is inserted or updated.
|
||||
|
||||
Here is an example YAML file to delete a role:
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
|
||||
# list of roles that should be deleted
|
||||
deleteRoles:
|
||||
- name: custom:reports:editor
|
||||
orgId: 1
|
||||
force: true
|
||||
```
|
||||
|
||||
### Assign your custom role to specific built-in roles
|
||||
|
||||
To assign roles to built-in roles, add said built-in roles to the `builtInRoles` section of your roles. To remove a specific assignment, remove it from the list.
|
||||
|
||||
For example, the following role is assigned to an organization editor or an organization administrator:
|
||||
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
|
||||
# Roles to insert/update in the database
|
||||
roles:
|
||||
- name: custom:users:editor
|
||||
description: "This role allows users to list/create/update other users in the organization"
|
||||
version: 1
|
||||
orgId: 1
|
||||
permissions:
|
||||
- action: "users:read"
|
||||
scope: "users:*"
|
||||
- action: "users:write"
|
||||
scope: "users:*"
|
||||
- action: "users:create"
|
||||
scope: "users:*"
|
||||
builtInRoles:
|
||||
- name: "Editor"
|
||||
- name: "Admin"
|
||||
```
|
||||
|
||||
## Manage default built-in role assignments
|
||||
|
||||
During startup, Grafana creates [default built-in role assignments]({{< relref "./roles#default-built-in-role-assignments" >}}) with [fixed roles]({{< relref "./roles#fixed-roles" >}}). You can remove and later restore those assignments with provisioning.
|
||||
|
||||
### Remove default assignment
|
||||
|
||||
To remove default built-in role assignments, use the `removeDefaultAssignments` element in the configuration file. You need to provide the built-in role name and fixed role name.
|
||||
|
||||
Here is an example:
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
|
||||
# list of default built-in role assignments that should be removed
|
||||
removeDefaultAssignments:
|
||||
- builtInRole: "Grafana server administrator"
|
||||
fixedRole: "fixed:permissions:admin"
|
||||
|
||||
```
|
||||
|
||||
### Restore default assignment
|
||||
|
||||
To restore the default built-in role assignment, use the `addDefaultAssignments` element in the configuration file. You need to provide the built-in role name and the fixed-role name.
|
||||
|
||||
Here is an example:
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
|
||||
# list of default built-in role assignments that should be added back
|
||||
addDefaultAssignments:
|
||||
- builtInRole: "Admin"
|
||||
fixedRole: "fixed:reporting:admin:read"
|
||||
```
|
||||
|
||||
## Full example of a role configuration file
|
||||
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
|
||||
# list of default built-in role assignments that should be removed
|
||||
removeDefaultAssignments:
|
||||
# <string>, must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`
|
||||
- builtInRole: "Grafana Admin"
|
||||
# <string>, must be one of the existing fixed roles
|
||||
fixedRole: "fixed:permissions:admin"
|
||||
|
||||
# list of default built-in role assignments that should be added back
|
||||
addDefaultAssignments:
|
||||
# <string>, must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`
|
||||
- builtInRole: "Admin"
|
||||
# <string>, must be one of the existing fixed roles
|
||||
fixedRole: "fixed:reporting:admin:read"
|
||||
|
||||
# list of roles that should be deleted
|
||||
deleteRoles:
|
||||
# <string> name of the role you want to create. Required if no uid is set
|
||||
- name: "custom:reports:editor"
|
||||
# <string> uid of the role. Required if no name
|
||||
uid: "customreportseditor1"
|
||||
# <int> org id. will default to Grafana's default if not specified
|
||||
orgId: 1
|
||||
# <bool> force deletion revoking all grants of the role
|
||||
force: true
|
||||
- name: "custom:global:reports:reader"
|
||||
uid: "customglobalreportsreader1"
|
||||
# <bool> overwrite org id and removes a global role
|
||||
global: true
|
||||
force: true
|
||||
|
||||
# list of roles to insert/update depending on what is available in the database
|
||||
roles:
|
||||
# <string, required> name of the role you want to create. Required
|
||||
- name: "custom:users:editor"
|
||||
# <string> uid of the role. Has to be unique for all orgs.
|
||||
uid: customuserseditor1
|
||||
# <string> description of the role, informative purpose only.
|
||||
description: "Role for our custom user editors"
|
||||
# <int> version of the role, Grafana will update the role when increased
|
||||
version: 2
|
||||
# <int> org id. will default 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"
|
||||
scope: "users:*"
|
||||
# <list> list of builtIn roles the role should be assigned to
|
||||
builtInRoles:
|
||||
# <string, required> name of the builtin role you want to assign the role to
|
||||
- name: "Editor"
|
||||
# <int> org id. will default to the role org id
|
||||
orgId: 1
|
||||
- name: "custom:global:users:reader"
|
||||
uid: "customglobalusersreader1"
|
||||
description: "Global Role for custom user readers"
|
||||
version: 1
|
||||
# <bool> overwrite org id and creates a global role
|
||||
global: true
|
||||
permissions:
|
||||
- action: "users:read"
|
||||
scope: "users:*"
|
||||
builtInRoles:
|
||||
- name: "Viewer"
|
||||
orgId: 1
|
||||
- name: "Editor"
|
||||
# <bool> overwrite org id and assign role globally
|
||||
global: true
|
||||
```
|
||||
|
||||
## Supported settings
|
||||
|
||||
The following sections detail the supported settings for roles and built-in role assignments.
|
||||
|
||||
- Refer to [Permissions]({{< relref "./permissions.md#action-definitions" >}}) for full list of valid permissions.
|
||||
- Check [Custom roles]({{< relref "./roles.md#custom-roles" >}}) to understand attributes for roles.
|
||||
- The [default org ID]({{< relref "../../administration/configuration#auto_assign_org_id" >}}) is used if `orgId` is not specified in any of the configuration blocks.
|
||||
|
||||
## Validation rules
|
||||
|
||||
A basic set of validation rules are applied to the input `yaml` files.
|
||||
|
||||
### Roles
|
||||
|
||||
- `name` must not be empty
|
||||
- `name` must not have `fixed:` prefix.
|
||||
|
||||
### Permissions
|
||||
|
||||
- `name` must not be empty
|
||||
|
||||
### Built-in role assignments
|
||||
|
||||
- `name` must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`.
|
||||
- When `orgId` is not specified, it inherits the `orgId` from `role`. For global roles the default `orgId` is used.
|
||||
- `orgId` in the `role` and in the assignment must be the same for none global roles.
|
||||
|
||||
### Role deletion
|
||||
|
||||
- Either the role `name` or `uid` must be provided
|
||||
@@ -0,0 +1,85 @@
|
||||
+++
|
||||
title = "Roles"
|
||||
description = "Understand roles in fine-grained access control"
|
||||
keywords = ["grafana", "fine-grained-access-control", "roles", "fixed-roles", "built-in-role-assignments", "permissions", "enterprise"]
|
||||
weight = 105
|
||||
+++
|
||||
|
||||
# Roles
|
||||
|
||||
A role represents set of permissions that allow you to perform specific actions on Grafana resources. Refer to [Permissions]({{< relref "./permissions.md" >}}) to understand how permissions work.
|
||||
|
||||
There are two types of roles:
|
||||
- [Fixed roles]({{< relref "./roles.md#fixed-roles" >}}), which provide granular access for specific resources within Grafana and are managed by the Grafana itself.
|
||||
- [Custom roles]({{< relref "./roles.md#custom-roles.md" >}}), which provide granular access based on the user specified set of permissions.
|
||||
|
||||
You can use [Fine-grained access control API]({{< relref "../../http_api/access_control.md" >}}) to list available roles and permissions.
|
||||
|
||||
## Role scopes
|
||||
|
||||
A role can be either _global_ or _organization local_. _Global_ roles are not mapped to any specific organization and can be reused across multiple organizations, whereas _organization local_ roles are only available for that specific organization.
|
||||
|
||||
## Fixed roles
|
||||
|
||||
Fixed roles provide convenience and guarantee of consistent behaviour by combining relevant [permissions]({{< relref "./permissions.md" >}}) together. Fixed roles are created and updated by Grafana during startup.
|
||||
There are few basic rules for fixed roles:
|
||||
|
||||
- All fixed roles are _global_.
|
||||
- All fixed roles have a `fixed:` prefix.
|
||||
- You can’t change or delete a fixed role.
|
||||
|
||||
For more information, refer to [Fine-grained access control references]({{< relref "./fine-grained-access-control-references.md#fine-grained-access-fixed-roles" >}}).
|
||||
|
||||
## Custom roles
|
||||
|
||||
Custom roles allow you to manage access to your users the way you want, by mapping [fine-grained permissions]({{< relref "./permissions.md" >}}) to it and creating [built-in role assignments]({{< ref "#built-in-role-assignments.md" >}}).
|
||||
|
||||
To create, update or delete a custom role, you can use the [Fine-grained access control API]({{< relref "../../http_api/access_control.md" >}}) or [Grafana Provisioning]({{< relref "./provisioning.md" >}}).
|
||||
|
||||
### Role name
|
||||
|
||||
A role's name is intended as a human friendly identifier for the role, helping administrators understand the purpose of a role. The name cannot be longer than 190 characters, and we recommend using ASCII characters.
|
||||
Role names must be unique within an organization.
|
||||
|
||||
Roles with names prefixed by `fixed:` are fixed roles created by Grafana and cannot be created or modified by users.
|
||||
|
||||
### Role version
|
||||
|
||||
The version of a role is a positive integer which defines the current version of the role. When updating a role, you can either omit the version field to increment the previous value by 1 or set a new version which must be strictly larger than the previous version for the update to succeed.
|
||||
|
||||
### Permissions
|
||||
|
||||
You manage access to Grafana resources by mapping [permissions]({{< relref "./permissions.md" >}}) to roles. You can create and assign roles without any permissions as placeholders.
|
||||
|
||||
### Role UID
|
||||
|
||||
Each custom role has a UID defined which is a unique identifier associated with the role allowing you to change or delete the role. You can either generate UID yourself, or let Grafana generate one for you.
|
||||
|
||||
The same UID cannot be used for roles in different organizations within the same Grafana instance.
|
||||
|
||||
## Create, update and delete roles
|
||||
|
||||
You can create, update and delete custom roles by using the [Access Control HTTP API]({{< relref "../../http_api/access_control.md" >}}) or by using [Grafana Provisioning]({{< relref "./provisioning.md" >}}).
|
||||
|
||||
By default, Grafana Server Admin has a [built-in role assignment]({{< ref "#built-in-role-assignments" >}}) which allows a user to create, update or delete custom roles.
|
||||
If a Grafana Server Admin wants to delegate that privilege to other users, they can create a custom role with relevant [permissions]({{< relref "./permissions.md" >}}) and `permissions:delegate` scope will allow those users to manage roles themselves.
|
||||
|
||||
Note that you won't be able to create, update or delete a custom role with permissions which you yourself do not have. For example, if the only permission you have is a `users:create`, you won't be able to create a role with other permissions.
|
||||
|
||||
## Built-in role assignments
|
||||
|
||||
To control what your users can access or not, you can assign or unassign [Custom roles]({{< ref "#custom-roles" >}}) or [Fixed roles]({{< ref "#fixed-roles" >}}) to the existing [Organization roles]({{< relref "../../permissions/organization_roles.md" >}}) or to [Grafana Server Admin]({{< relref "../../permissions/_index.md#grafana-server-admin-role" >}}) role.
|
||||
These assignments are called built-in role assignments.
|
||||
|
||||
During startup, Grafana will create default assignments for you. When you make any changes to the built-on role assignments, Grafana will take them into account and won’t overwrite during next start.
|
||||
|
||||
For more information, refer to [Fine-grained access control references]({{< relref "./fine-grained-access-control-references.md#default-built-in-role-assignments" >}}).
|
||||
|
||||
## Create and remove built-in role assignments
|
||||
|
||||
You can create or remove built-in role assignments using [Fine-grained access control API]({{< relref "../../http_api/access_control.md" >}}) or using [Grafana Provisioning]({{< relref "./provisioning" >}}).
|
||||
|
||||
### Scope of assignments
|
||||
|
||||
A built-in role assignment can be either _global_ or _organization local_. _Global_ assignments are not mapped to any specific organization and will be applied to all organizations, whereas _organization local_ assignments are only applied for that specific organization.
|
||||
You can only create _organization local_ assignments for _organization local_ roles.
|
||||
@@ -0,0 +1,226 @@
|
||||
+++
|
||||
title = "Fine-grained access control usage scenarios"
|
||||
description = "Fine-grained access control usage scenarios"
|
||||
keywords = ["grafana", "fine-grained-access-control", "roles", "permissions", "fine-grained-access-control-usage", "enterprise"]
|
||||
weight = 125
|
||||
+++
|
||||
|
||||
# Fine-grained access control usage scenarios
|
||||
|
||||
This guide contains several examples and usage scenarios of using fine-grained roles and permissions for controlling access to Grafana resources.
|
||||
|
||||
Before you get started, make sure to [enable fine-grained access control]({{< relref "./_index.md#enable-fine-grained-access-control" >}}).
|
||||
|
||||
## Check all built-in role assignments
|
||||
|
||||
You can use the [Fine-grained access control HTTP API]({{< relref "../../http_api/access_control.md#get-all-built-in-role-assignments" >}}) to see all available built-in role assignments.
|
||||
The response contains a mapping between one of the organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin` to the custom or fixed roles.
|
||||
|
||||
Example request:
|
||||
```
|
||||
curl --location --request GET '<grafana_url>/api/access-control/builtin-roles' --header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ='
|
||||
```
|
||||
|
||||
Example response:
|
||||
```
|
||||
{
|
||||
"Admin": [
|
||||
...
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "qQui_LCMk",
|
||||
"name": "fixed:users:org:edit",
|
||||
"description": "Allows every read action for user organizations and in addition allows to administer user organizations.",
|
||||
"global": true,
|
||||
"updated": "2021-05-17T20:49:18+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
},
|
||||
{
|
||||
"version": 1,
|
||||
"uid": "Kz9m_YjGz",
|
||||
"name": "fixed:reporting:admin:edit",
|
||||
"description": "Gives access to edit any report or the organization's general reporting settings.",
|
||||
"global": true,
|
||||
"updated": "2021-05-13T16:24:26+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
}
|
||||
...
|
||||
],
|
||||
"Grafana Admin": [
|
||||
...
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "qQui_LCMk",
|
||||
"name": "fixed:users:org:edit",
|
||||
"description": "Allows every read action for user organizations and in addition allows to administer user organizations.",
|
||||
"global": true,
|
||||
"updated": "2021-05-17T20:49:18+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
},
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "ajum_YjGk",
|
||||
"name": "fixed:users:admin:read",
|
||||
"description": "Allows to list and get users and related information.",
|
||||
"global": true,
|
||||
"updated": "2021-05-17T20:49:17+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
},
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "K3um_LCMk",
|
||||
"name": "fixed:users:admin:edit",
|
||||
"description": "Allows every read action for users and in addition allows to administer users.",
|
||||
"global": true,
|
||||
"updated": "2021-05-17T20:49:17+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
To see what permissions each of the assigned roles have, you can a [Get a role]({{< relref "../../http_api/access_control.md#get-a-role" >}}) by using an HTTP API.
|
||||
|
||||
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:org:edit",
|
||||
"description": "Allows every read action for user organizations and in addition allows to administer user organizations.",
|
||||
"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.role:update",
|
||||
"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"
|
||||
}
|
||||
```
|
||||
|
||||
## Create your first custom role
|
||||
|
||||
You can create your custom role by either using an [HTTP API]({{< relref "../../http_api/access_control.md#create-a-new-custom-role" >}}) or by using [Grafana provisioning]({{< relref "./provisioning.md" >}}).
|
||||
You can take a look at [actions and scopes]({{< relref "./provisioning.md#action-definitions" >}}) to decide what permissions would you like to map to your role.
|
||||
|
||||
Example HTTP 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",
|
||||
"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",
|
||||
"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"
|
||||
}
|
||||
```
|
||||
|
||||
Once the custom role is created, you can create a built-in role assignment by using an [HTTP API]({{< relref "../../http_api/access_control.md#create-a-built-in-role-assignment" >}}).
|
||||
If you created your role using [Grafana provisioning]({{< relref "./provisioning.md" >}}), you can also create the assignment with it.
|
||||
|
||||
Example HTTP request:
|
||||
|
||||
```
|
||||
curl --location --request POST '<grafana_url>/api/access-control/builtin-roles' \
|
||||
--header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"roleUid": "jZrmlLCkGksdka",
|
||||
"builtinRole": "Viewer",
|
||||
"global": true
|
||||
}'
|
||||
```
|
||||
|
||||
Example response:
|
||||
|
||||
```
|
||||
{
|
||||
"message": "Built-in role grant added"
|
||||
}
|
||||
```
|
||||
|
||||
## Allow Viewers to create reports
|
||||
|
||||
In order to create reports, you would need to have `reports.admin:write` permission. By default, Grafana Admin's or organization Admin can create reports as there is a [built-in role assignment]({{< relref "./roles#built-in-role-assignments" >}}) which comes with `reports.admin:write` permission.
|
||||
|
||||
If you want your users who have `Viewer` organization role to create reports, you have two options:
|
||||
|
||||
1. First option is to create a built-in role assignment and map `fixed:reporting:admin:edit` fixed role to the `Viewer` built-in role. Note that `fixed:reporting:admin:edit` fixed role allows doing more than creating reports. Refer to [fixed roles]({{< relref "./roles.md#fixed-roles" >}}) for full list of permission assignments.
|
||||
1. Second option is to [create a custom role]({{< ref "#create-your-custom-role" >}}) with `reports.admin:write` permission, and create a built-in role assignment for `Viewer` organization role.
|
||||
|
||||
## Prevent Grafana Admin from creating and inviting users
|
||||
|
||||
In order to create users, you would need to have `users:create` permission. By default, user with Grafana Admin role can create users as there is a [built-in role assignment]({{< relref "./roles#built-in-role-assignments" >}}) which comes with `users:create` permission.
|
||||
|
||||
If you want to prevent Grafana Admin from creating users, you can do the following:
|
||||
|
||||
1. [Check all built-in role assignments]({{< ref "#check-all-built-in-role-assignments" >}}) to see what built-in role assignments are available.
|
||||
1. From built-in role assignments, find the role which gives `users:create` permission. Refer to [fixed roles]({{< relref "./roles.md#fixed-roles" >}}) for full list of permission assignments.
|
||||
1. Remove the built-in role assignment by using an [Fine-grained access control HTTP API]({{< relref "../../http_api/access_control.md" >}}) or by using [Grafana provisioning]({{< relref "./provisioning" >}}).
|
||||
|
||||
## Allow Editors to create new custom roles
|
||||
|
||||
By default, Grafana Server Admin is the only user who can create and manage custom roles. If you want your users to do the same, you have two options:
|
||||
|
||||
1. First option is to create a built-in role assignment and map `fixed:permissions:admin:edit` and `fixed:permissions:admin:read` fixed roles to the `Editor` built-in role.
|
||||
1. Second option is to [create a custom role]({{< ref "#create-your-custom-role" >}}) with `roles.builtin:add` and `roles:write` permissions, and create a built-in role assignment for `Editor` organization role.
|
||||
|
||||
Note that in any scenario, your `Editor` would be able to create and manage roles only with the permissions they have, or with a subset of them.
|
||||
@@ -2,7 +2,7 @@
|
||||
title = "Auditing"
|
||||
description = "Auditing"
|
||||
keywords = ["grafana", "auditing", "audit", "logs"]
|
||||
weight = 700
|
||||
weight = 1100
|
||||
+++
|
||||
|
||||
# Auditing
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
title = "Data source permissions"
|
||||
description = "Grafana Datasource Permissions Guide "
|
||||
keywords = ["grafana", "configuration", "documentation", "datasource", "permissions", "users", "teams", "enterprise"]
|
||||
weight = 200
|
||||
weight = 500
|
||||
+++
|
||||
|
||||
# Data source permissions
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
title = "Enhanced LDAP Integration"
|
||||
description = "Grafana Enhanced LDAP Integration Guide "
|
||||
keywords = ["grafana", "configuration", "documentation", "ldap", "active directory", "enterprise"]
|
||||
weight = 300
|
||||
weight = 600
|
||||
+++
|
||||
|
||||
# Enhanced LDAP integration
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
title = "Enterprise configuration"
|
||||
description = "Enterprise configuration documentation"
|
||||
keywords = ["grafana", "configuration", "documentation", "enterprise"]
|
||||
weight = 300
|
||||
weight = 700
|
||||
+++
|
||||
|
||||
# Grafana Enterprise configuration
|
||||
@@ -133,6 +133,10 @@ Maximum number of concurrent calls to the rendering service.
|
||||
|
||||
Scale factor for rendering images. Value `2` is enough for monitor resolutions, `4` would be better for printed material. Setting a higher value affects performance and memory.
|
||||
|
||||
### max_attachment_size_mb
|
||||
|
||||
Set the maximum file size in megabytes for the CSV attachments.
|
||||
|
||||
### fonts_path
|
||||
|
||||
Path to the directory containing font files.
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
title = "Export dashboard as PDF"
|
||||
description = ""
|
||||
keywords = ["grafana", "export", "pdf", "share"]
|
||||
weight = 900
|
||||
weight = 1400
|
||||
+++
|
||||
|
||||
# Export dashboard as PDF
|
||||
|
||||
@@ -2,12 +2,12 @@
|
||||
title = "Grafana Enterprise license"
|
||||
description = "Enterprise license"
|
||||
keywords = ["grafana", "licensing", "enterprise"]
|
||||
weight = 100
|
||||
weight = 10
|
||||
+++
|
||||
|
||||
# Grafana Enterprise license
|
||||
|
||||
To run Grafana Enterprise, you need a valid license. Contact a Grafana Labs representative](https://grafana.com/contact?about=grafana-enterprise) to obtain the license. For information on how to activate your license, refer to [Activate an Enterprise license]({{< relref "./activate-license.md" >}}).
|
||||
To run Grafana Enterprise, you need a valid license. [Contact a Grafana Labs representative](https://grafana.com/contact?about=grafana-enterprise) to obtain the license. For information on how to activate your license, refer to [Activate an Enterprise license]({{< relref "./activate-license.md" >}}).
|
||||
|
||||
See also:
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
title = "Query caching"
|
||||
description = "Grafana Enterprise data source query caching"
|
||||
keywords = ["grafana", "plugins", "query", "caching"]
|
||||
weight = 110
|
||||
weight = 300
|
||||
+++
|
||||
|
||||
# Query caching
|
||||
|
||||
@@ -3,7 +3,7 @@ title = "Reporting"
|
||||
description = ""
|
||||
keywords = ["grafana", "reporting"]
|
||||
aliases = ["/docs/grafana/latest/administration/reports"]
|
||||
weight = 400
|
||||
weight = 800
|
||||
+++
|
||||
|
||||
# Reporting
|
||||
@@ -12,6 +12,9 @@ Reporting allows you to automatically generate PDFs from any of your dashboards
|
||||
|
||||
> Only available in Grafana Enterprise v6.4+.
|
||||
|
||||
> If you have [Fine-grained access Control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some actions you would need to have relevant permissions.
|
||||
Refer to specific guides to understand what permissions are required.
|
||||
|
||||
{{< figure src="/static/img/docs/enterprise/reports_list.png" max-width="500px" class="docs-image--no-shadow" >}}
|
||||
|
||||
Any changes you make to a dashboard used in a report are reflected the next time the report is sent. For example, if you change the time range in the dashboard, then the time range in the report changes as well.
|
||||
@@ -21,9 +24,13 @@ Any changes you make to a dashboard used in a report are reflected the next time
|
||||
- SMTP must be configured for reports to be sent. Refer to [SMTP]({{< relref "../administration/configuration.md#smtp" >}}) in [Configuration]({{< relref "../administration/configuration.md" >}}) for more information.
|
||||
- The Image Renderer plugin must be installed or the remote rendering service must be set up. Refer to [Image rendering]({{< relref "../administration/image_rendering.md" >}}) for more information.
|
||||
|
||||
## Access control
|
||||
|
||||
When [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) is enabled, you need to have the relevant [Permissions]({{< relref "../enterprise/access-control/permissions.md" >}}) to create and manage reports.
|
||||
|
||||
## Create or update a report
|
||||
|
||||
Currently only Organization Admins can create reports.
|
||||
Only organization admins can create reports by default. You can customize who can create reports with [fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}).
|
||||
|
||||
1. Click on the reports icon in the side menu. The Reports tab allows you to view, create, and update your reports.
|
||||
1. Enter report information. All fields are required unless otherwise indicated.
|
||||
@@ -44,6 +51,39 @@ Currently only Organization Admins can create reports.
|
||||
|
||||
{{< figure src="/static/img/docs/enterprise/reports-create-new-8.0.png" max-width="500px" class="docs-image--no-shadow" >}}
|
||||
|
||||
### Choose template variables
|
||||
|
||||
> **Note:** Available in Grafana Enterprise version 7.5+ (behind `reportVariables` feature flag) and Grafana Enterprise version 8+ without a feature flag.
|
||||
|
||||
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/_index.md" >}}) section.
|
||||
|
||||
> **Note:** The query variables saved with a report might go out of date if the results of that query change. For example, if your template variable queries for a list of hostnames and a new hostname is added, then it will not be included in the report. If that happens, the selected variables will need to be manually updated in the report. If you select the `All` value for the template variable or if you keep the dashboard's original variable selection, then the report will stay up-to-date as new values are added.
|
||||
|
||||
### Render a report with panels or rows set to repeat by a variable
|
||||
|
||||
> **Note:** Available in Grafana Enterprise v8+.
|
||||
|
||||
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/repeat-panels-or-rows.md" >}}) section.
|
||||
|
||||
#### Caveats:
|
||||
|
||||
- Rendering repeating panels for dynamic variable types (e.g. `query` variables) with selected `All` value is currently not supported. As a workaround, it is possible to individually select all the values instead.
|
||||
- If you select different template variables in a report for a dashboard with repeating rows, you might see empty space or missing values at the bottom of the report. This is because the dimensions of the panels from the dashboard are used to generate the report. To avoid this issue, use the dashboard's original template variables for the report, or make a copy of the dashboard, select the new set of template variables, and generate a report based on the copied dashboard.
|
||||
- Rendering of the repeating panels inside collapsed rows in reports is not supported.
|
||||
|
||||
### Report time range
|
||||
|
||||
> Setting custom report time range is available in Grafana Enterprise v7.2+.
|
||||
|
||||
By default, reports use the saved time range of the dashboard. Changing the time range of the report can be done by:
|
||||
|
||||
- Saving a modified time range to the dashboard.
|
||||
- Setting a time range via **Time range** field in the report form. If specified, then this custom time range overrides the one from the report's dashboard.
|
||||
|
||||
The page header of the report displays the time range for the dashboard's data queries. Dashboards set to use the browser's time zone will use the time zone on the Grafana server.
|
||||
|
||||
If the time zone is set differently between your Grafana server and its remote image renderer, then the time ranges in the report might be different between the page header and the time axes in the panels. To avoid this, set the time zone to UTC for dashboards when using a remote renderer. Each dashboard's time zone setting is visible in the [time range controls]({{< relref "../dashboards/time-range-controls.md/#dashboard-time-settings" >}}).
|
||||
|
||||
### Layout and orientation
|
||||
|
||||
> We're actively working on developing new report layout options. [Contact us](https://grafana.com/contact?about=grafana-enterprise&topic=design-process&value=reporting) if you would like to get involved in the design process.
|
||||
@@ -55,6 +95,18 @@ Simple | Landscape | v6.7+ | Generates an A4 page in landscape mode with a singl
|
||||
Grid | Portrait | v7.2+ | Generates an A4 page in portrait mode with panels arranged in the same way as at the original dashboard. | {{< figure src="/static/img/docs/enterprise/reports_grid_portrait_preview.png" max-width="500px" max-height="500px" class="docs-image--no-shadow" >}}
|
||||
Grid | Landscape | v7.2+ | Generates an A4 page in landscape mode with panels arranged in the same way as at the original dashboard. | {{< figure src="/static/img/docs/enterprise/reports_grid_landscape_preview.png" max-width="500px" class="docs-image--no-shadow" >}}
|
||||
|
||||
### CSV export
|
||||
|
||||
> **Note:** Only available in Grafana Enterprise v8.0+, with the [Grafana image renderer plugin](https://grafana.com/grafana/plugins/grafana-image-renderer) v3.0+.
|
||||
|
||||
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" >}}).
|
||||
|
||||
This feature relies on the same plugin that supports the [image rendering]({{< relref "../administration/image_rendering.md" >}}) features.
|
||||
|
||||
When the CSV file is generated, it is temporarily written to the `csv` folder in the Grafana `data` folder.
|
||||
|
||||
A background job runs every 10 minutes and removes temporary CSV files. You can configure how long a CSV file should be stored before being removed by configuring the [temp-data-lifetime]({{< relref "../administration/configuration/#temp-data-lifetime" >}}) setting. This setting also affects how long a renderer PNG file should be stored.
|
||||
|
||||
### Scheduling
|
||||
|
||||
Scheduled reports can be sent on a monthly, weekly, daily, or hourly basis. You may also disable scheduling for when you either want to send it via the API.
|
||||
@@ -112,39 +164,6 @@ The last saved version of the report will be sent to selected emails. You can us
|
||||
|
||||
{{< figure src="/static/img/docs/enterprise/reports_send_test_mail.png" max-width="500px" class="docs-image--no-shadow" >}}
|
||||
|
||||
### Report time range
|
||||
|
||||
> Setting custom report time range is available in Grafana Enterprise v7.2+.
|
||||
|
||||
By default, reports use the saved time range of the dashboard. Changing the time range of the report can be done by:
|
||||
|
||||
- Saving a modified time range to the dashboard.
|
||||
- Setting a time range via **Time range** field in the report form. If specified, then this custom time range overrides the one from the report's dashboard.
|
||||
|
||||
The page header of the report displays the time range for the dashboard's data queries. Dashboards set to use the browser's time zone will use the time zone on the Grafana server.
|
||||
|
||||
If the time zone is set differently between your Grafana server and its remote image renderer, then the time ranges in the report might be different between the page header and the time axes in the panels. To avoid this, set the time zone to UTC for dashboards when using a remote renderer. Each dashboard's time zone setting is visible in the [time range controls]({{< relref "../dashboards/time-range-controls.md/#dashboard-time-settings" >}}).
|
||||
|
||||
### Choose template variables
|
||||
|
||||
> **Note:** Available in Grafana Enterprise version 7.5+ (behind `reportVariables` feature flag) and Grafana Enterprise version 8+ without a feature flag.
|
||||
|
||||
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/_index.md" >}}) section.
|
||||
|
||||
> **Note:** The query variables saved with a report might go out of date if the results of that query change. For example, if your template variable queries for a list of hostnames and a new hostname is added, then it will not be included in the report. If that happens, the selected variables will need to be manually updated in the report. If you select the `All` value for the template variable or if you keep the dashboard's original variable selection, then the report will stay up-to-date as new values are added.
|
||||
|
||||
### Render a report with panels or rows set to repeat by a variable
|
||||
|
||||
> **Note:** Available in Grafana Enterprise v8+.
|
||||
|
||||
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/repeat-panels-or-rows.md" >}}) section.
|
||||
|
||||
#### Caveats:
|
||||
|
||||
- Rendering repeating panels for dynamic variable types (e.g. `query` variables) with selected `All` value is currently not supported. As a workaround, it is possible to individually select all the values instead.
|
||||
- If you select different template variables in a report for a dashboard with repeating rows, you might see empty space or missing values at the bottom of the report. This is because the dimensions of the panels from the dashboard are used to generate the report. To avoid this issue, use the dashboard's original template variables for the report, or make a copy of the dashboard, select the new set of template variables, and generate a report based on the copied dashboard.
|
||||
- Rendering of the repeating panels inside collapsed rows in reports is not supported.
|
||||
|
||||
## Pause report
|
||||
|
||||
> **Note:** Available in Grafana Enterprise v8+.
|
||||
@@ -174,6 +193,8 @@ concurrent_render_limit = 4
|
||||
# Set the scale factor for rendering images. 2 is enough for monitor resolutions
|
||||
# 4 would be better for printed material. Setting a higher value affects performance and memory
|
||||
image_scale_factor = 2
|
||||
# Set the maximum file size in megabytes for the CSV attachments
|
||||
max_attachment_size_mb = 10
|
||||
# Path to the directory containing font files
|
||||
fonts_path =
|
||||
# Name of the TrueType font file with regular style
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
title = "Request security"
|
||||
description = "Grafana Enterprise request security"
|
||||
keywords = ["grafana", "security", "enterprise"]
|
||||
weight = 110
|
||||
weight = 400
|
||||
+++
|
||||
|
||||
# Request security
|
||||
|
||||
@@ -3,7 +3,7 @@ title = "SAML Authentication"
|
||||
description = "Grafana SAML Authentication"
|
||||
keywords = ["grafana", "saml", "documentation", "saml-auth"]
|
||||
aliases = ["/docs/grafana/latest/auth/saml/"]
|
||||
weight = 500
|
||||
weight = 900
|
||||
+++
|
||||
|
||||
# SAML authentication
|
||||
|
||||
@@ -3,7 +3,7 @@ title = "Team sync"
|
||||
description = "Grafana Team Sync"
|
||||
keywords = ["grafana", "auth", "documentation"]
|
||||
aliases = ["/docs/grafana/latest/auth/saml/"]
|
||||
weight = 600
|
||||
weight = 1000
|
||||
+++
|
||||
|
||||
# Team sync
|
||||
|
||||
@@ -3,7 +3,7 @@ title = "Usage insights"
|
||||
description = "Understand how your Grafana instance is used"
|
||||
keywords = ["grafana", "usage-insights", "enterprise"]
|
||||
aliases = ["/docs/grafana/latest/enterprise/usage-insights/"]
|
||||
weight = 100
|
||||
weight = 200
|
||||
+++
|
||||
|
||||
# Usage insights
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
title = "Vault"
|
||||
description = ""
|
||||
keywords = ["grafana", "vault", "configuration"]
|
||||
weight = 700
|
||||
weight = 1200
|
||||
+++
|
||||
|
||||
# Vault integration
|
||||
|
||||
@@ -3,7 +3,7 @@ title = "White labeling"
|
||||
description = "Change the look of Grafana to match your corporate brand"
|
||||
keywords = ["grafana", "white-labeling", "enterprise"]
|
||||
aliases = ["/docs/grafana/latest/enterprise/white-labeling/"]
|
||||
weight = 700
|
||||
weight = 1300
|
||||
+++
|
||||
|
||||
# White labeling
|
||||
|
||||
Reference in New Issue
Block a user