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

[v10.0.x] [feat] docs; update admonition syntax (#68857)

Browse Source 
[feat] docs; update admonition syntax (#68842)

* [feat] docs; update admonition syntax

- Standardizes according to style conventions: https://grafana.com/docs/writers-toolkit/style-guide/style-conventions/#admonitions
- Prepares docs for better, uniform admonition style.

* Remove false positives and irregularities

* false positive removal

* Update docs/sources/datasources/mysql/_index.md

* Update docs/sources/developers/angular_deprecation/angular-plugins.md

* fix link errors

* Prettify some nested blockquotes

* remoe unnecessary admonition

(cherry picked from commit 1c4bb9ca00)

Co-authored-by: Matt Dodson <47385188+MattDodsonEnglish@users.noreply.github.com>
This commit is contained in:
Grot (@grafanabot)
2023-05-23 07:47:49 -05:00
committed by GitHub
co-authored by Matt Dodson
parent defce65315
commit 1e8c28eff4
144 changed files with 1840 additions and 405 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/administration/api-keys/index.md
+9 -3
View File
@@ -17,7 +17,9 @@ An API key is a randomly generated string that external systems use to interact
When you create an API key, you specify a **Role** that determines the permissions associated with the API key. Role permissions control that actions the API key can perform on Grafana resources.
> **Note:** If you use Grafana v9.1 or newer, use service accounts instead of API keys. For more information, refer to [Grafana service accounts]({{< relref "../service-accounts/" >}}).
{{% admonition type="note" %}}
If you use Grafana v9.1 or newer, use service accounts instead of API keys. For more information, refer to [Grafana service accounts]({{< relref "../service-accounts/" >}}).
{{% /admonition %}}
{{< section >}}
@@ -61,7 +63,9 @@ For more information about the benefits of service accounts, refer to [Grafana s
The service account endpoints generate a machine user for authentication instead of using API keys. When you migrate an API key to a service account, a service account will be created with a service account token.
> **Note:** If you are using API keys for authentication, we recommend that you migrate your integration to the service account authentication method. The API key will continue to work. You can locate the API key in the [Grafana service account tokens]({{< relref "../service-accounts/#service-account-tokens" >}}) details.
{{% admonition type="note" %}}
If you're currently using API keys for authentication, we strongly recommend to use Grafana Service Accounts instead. Rest assured, when migrating to Service Accounts, your existing API keys will continue working as before. To find the migrated API keys, navigate to the Service Accounts section and select the Service Account Tokens tab. For more information, please refer to the [Grafana service account tokens]({{< relref "../service-accounts/#service-account-tokens" >}}) details.
{{% /admonition %}}
## Ways of migrating API keys to service accounts
@@ -256,7 +260,9 @@ resource "grafana_service_account_token" "sat-foo" {
This section shows you how to migrate your Terraform configuration for Grafana cloud stack API keys to Grafana cloud stack service accounts. For migration your cloud stack api keys, use the `grafana_cloud_stack_service_account` and `gafana_cloud_stack_service_account_token` resources see [Grafana Cloud Stack Service Accounts in Terraform](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_stack_service_account).
> **Note:** This is only relevant for Grafana Cloud **Stack** API keys `grafana_cloud_stack_api_key`. Grafana Cloud API keys resource `grafana_cloud_api_key` are not deprecated and should be used for authentication for managing your Grafana cloud.
{{% admonition type="note" %}}
This is only relevant for Grafana Cloud **Stack** API keys `grafana_cloud_stack_api_key`. Grafana Cloud API keys resource `grafana_cloud_api_key` are not deprecated and should be used for authentication for managing your Grafana cloud.
{{% /admonition %}}
#### Steps
docs/sources/administration/data-source-management/index.md
+18 -6
View File
@@ -21,7 +21,9 @@ Only users with the organization admin role can add data sources.
Before you can create your first dashboard, you need to add your data source.
> **Note:** Only users with the organization admin role can add data sources.
{{% admonition type="note" %}}
Only users with the organization admin role can add data sources.
{{% /admonition %}}
**To add a data source:**
@@ -36,7 +38,9 @@ Before you can create your first dashboard, you need to add your data source.
You can configure data source permissions to allow or deny certain users the ability to query or edit a data source. Each data source’s configuration includes a Permissions tab where you can restrict data source permissions to specific users, teams, or roles.
> **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud).
{{% /admonition %}}
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 to which they have access. Additionally, by default, data sources can be edited by the user who created the data source, as well as users with the `Admin` role.
@@ -83,11 +87,15 @@ When query caching is enabled, Grafana temporarily stores the results of data so
Query caching works for all backend data sources. You can enable the cache globally and configure the cache duration (also called Time to Live, or TTL).
> **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% /admonition %}}
The following cache backends are available: in-memory, Redis, and Memcached.
> **Note:** Storing cached queries in-memory can increase Grafana's memory footprint. In production environments, a Redis or Memcached backend is highly recommended.
{{% admonition type="note" %}}
Storing cached queries in-memory can increase Grafana's memory footprint. In production environments, a Redis or Memcached backend is highly recommended.
{{% /admonition %}}
When a panel queries a cached data source, the time until this query fetches fresh data is determined by the panel's **interval.** This means that wider panels and dashboards with shorter time ranges fetch new data more frequently than narrower panels and dashboards with longer time ranges.
@@ -136,7 +144,9 @@ You can optionally override a data source's configured TTL for individual dashbo
{{< figure max-width="500px" src="/media/docs/grafana/per-panel-cache-ttl-9-4.png" caption="Set Cache TTL for a single panel" >}}
> **Note:** If query caching is enabled and the Cache tab is not visible in a data source's settings, then query caching is not available for that data source.
{{% admonition type="note" %}}
If query caching is enabled and the Cache tab is not visible in a data source's settings, then query caching is not available for that data source.
{{% /admonition %}}
To configure global settings for query caching, refer to the [Query caching section of Enterprise Configuration]({{< relref "../../setup-grafana/configure-grafana/enterprise-configuration/#caching" >}}).
@@ -155,7 +165,9 @@ To disable query caching for an entire Grafana instance, set the `enabled` flag
If you experience performance issues or repeated queries become slower to execute, consider clearing your cache.
> **Note:** This action impacts all cache-enabled data sources. If you are using Memcached, the system clears all data from the Memcached instance.
{{% admonition type="note" %}}
This action impacts all cache-enabled data sources. If you are using Memcached, the system clears all data from the Memcached instance.
{{% /admonition %}}
1. Click **Connections** in the left-side menu.
1. Under Your Connections, click **Data sources**.
docs/sources/administration/organization-management/index.md
+3 -1
View File
@@ -88,7 +88,9 @@ For more information about adding users to an organization, refer to [Add a user
This action permanently removes an organization from your Grafana server.
> **Warning:** Deleting the organization also deletes all teams and dashboards associated the organization.
{{% admonition type="warning" %}}
Deleting the organization also deletes all teams and dashboards associated the organization.
{{% /admonition %}}
### Before you begin
docs/sources/administration/organization-preferences/index.md
+3 -1
View File
@@ -194,7 +194,9 @@ Users with the Grafana Server Admin flag on their account or access to the confi
default_home_dashboard_path = data/main-dashboard.json
```
> **Note:** On Linux, Grafana uses `/usr/share/grafana/public/dashboards/home.json` as the default home dashboard location.
{{% admonition type="note" %}}
On Linux, Grafana uses `/usr/share/grafana/public/dashboards/home.json` as the default home dashboard location.
{{% /admonition %}}
### Set the home dashboard for your organization
docs/sources/administration/plugin-management/index.md
+6 -2
View File
@@ -49,7 +49,9 @@ With [RBAC]({{< relref "../roles-and-permissions/access-control/#about-rbac" >}}
By default, Viewers, Editors and Admins have access to all App Plugins that their organization role allows them to access, thanks to the `fixed:plugins.app:reader` role.
> **Note:** Revoking this RBAC role from some users, will prevent them from accessing app plugins. But granting this RBAC role to users will only allow them to see app plugins their organization role allows them to see.
{{% admonition type="note" %}}
Revoking this RBAC role from some users, will prevent them from accessing app plugins. But granting this RBAC role to users will only allow them to see app plugins their organization role allows them to see.
{{% /admonition %}}
To prevent users from seeing an app plugin, refer to [this permissions scenarios]({{< relref "../roles-and-permissions/access-control/plan-rbac-rollout-strategy#prevent-viewers-from-accessing-an-app-plugin" >}}).
@@ -197,7 +199,9 @@ If you've allowed loading of an unsigned plugin, then Grafana writes a warning m
WARN[06-01|16:45:59] Running an unsigned plugin pluginID=<plugin id>
```
> **Note:** If you're developing a plugin, then you can enable development mode to allow all unsigned plugins.
{{% admonition type="note" %}}
If you're developing a plugin, then you can enable development mode to allow all unsigned plugins.
{{% /admonition %}}
## Learn more
docs/sources/administration/provisioning/index.md
+40 -18
View File
@@ -27,10 +27,12 @@ See [Configuration]({{< relref "../../setup-grafana/configure-grafana/" >}}) for
- Custom configuration from `$WORKING_DIR/conf/custom.ini`
- The custom configuration file path can be overridden using the `--config` parameter
> **Note:** If you have installed Grafana using the `deb` or `rpm`
> packages, then your configuration file is located at
> `/etc/grafana/grafana.ini`. This path is specified in the Grafana
> init.d script using `--config` file parameter.
{{% admonition type="note" %}}
If you have installed Grafana using the `deb` or `rpm`
packages, then your configuration file is located at
`/etc/grafana/grafana.ini`. This path is specified in the Grafana
init.d script using `--config` file parameter.
{{% /admonition %}}
### Using Environment Variables
@@ -67,7 +69,9 @@ Currently we do not provide any scripts/manifests for configuring Grafana. Rathe
## Data sources
> **Note:** Available in Grafana v5.0 and higher.
{{% admonition type="note" %}}
Available in Grafana v5.0 and higher.
{{% /admonition %}}
You can manage data sources in Grafana by adding YAML configuration files in the [`provisioning/datasources`]({{< relref "../../setup-grafana/configure-grafana#provisioning" >}}) directory.
Each config file can contain a list of `datasources` to add or update during startup.
@@ -167,7 +171,9 @@ To provision the rest of a data source's settings, include them as a JSON blob i
Common settings in the [built-in core data sources]({{< relref "../../datasources#built-in-core-data-sources" >}}) include:
> **Note:** Data sources tagged with _HTTP\*_ communicate using the HTTP protocol, which includes all core data source plugins except MySQL, PostgreSQL, and MSSQL.
{{% admonition type="note" %}}
Data sources tagged with _HTTP\*_ communicate using the HTTP protocol, which includes all core data source plugins except MySQL, PostgreSQL, and MSSQL.
{{% /admonition %}}
| Name | Type | Data source | Description |
| ----------------------------- | ------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -229,7 +235,9 @@ For examples of specific data sources' JSON data, refer to that [data source's d
Secure JSON data is a map of settings that will be encrypted with [secret key]({{< relref "../../setup-grafana/configure-grafana#secret_key" >}}) from the Grafana config. The purpose of this is only to hide content from the users of the application. This should be used for storing TLS Cert and password that Grafana will append to the request on the server side. All of these settings are optional.
> **Note:** The _HTTP\*_ tag denotes data sources that communicate using the HTTP protocol, including all core data source plugins except MySQL, PostgreSQL, and MSSQL.
{{% admonition type="note" %}}
The _HTTP\*_ tag denotes data sources that communicate using the HTTP protocol, including all core data source plugins except MySQL, PostgreSQL, and MSSQL.
{{% /admonition %}}
| Name | Type | Data source | Description |
| ----------------- | ------ | ---------------------------------- | -------------------------------------------------------- |
@@ -264,12 +272,16 @@ datasources:
## Plugins
> **Note:** Available in Grafana v7.1 and higher.
{{% admonition type="note" %}}
Available in Grafana v7.1 and higher.
{{% /admonition %}}
You can manage plugin applications in Grafana by adding one or more YAML config files in the [`provisioning/plugins`]({{< relref "../../setup-grafana/configure-grafana#provisioning" >}}) directory. Each config file can contain a list of `apps` that will be updated during start up. Grafana updates each app to match the configuration file.
> **Note:** This feature enables you to provision plugin configurations, not the plugins themselves.
> The plugins must already be installed on the Grafana instance.
{{% admonition type="note" %}}
This feature enables you to provision plugin configurations, not the plugins themselves.
The plugins must already be installed on the Grafana instance.
{{% /admonition %}}
### Example plugin configuration file
@@ -356,10 +368,12 @@ If the dashboard in the JSON file contains an [UID]({{< relref "../../dashboards
When Grafana starts, it updates/inserts all dashboards available in the configured folders. If you modify the file, then the dashboard is also updated.
By default, Grafana deletes dashboards in the database if the file is removed. You can disable this behavior using the `disableDeletion` setting.
> **Note:** Provisioning allows you to overwrite existing dashboards
> which leads to problems if you re-use settings that are supposed to be unique.
> Be careful not to re-use the same `title` multiple times within a folder
> or `uid` within the same installation as this will cause weird behaviors.
{{% admonition type="note" %}}
Provisioning allows you to overwrite existing dashboards
which leads to problems if you re-use settings that are supposed to be unique.
Be careful not to re-use the same `title` multiple times within a folder
or `uid` within the same installation as this will cause weird behaviors.
{{% /admonition %}}
### Provision folders structure from filesystem to Grafana
@@ -393,9 +407,13 @@ providers:
`server` and `application` will become new folders in Grafana menu.
> **Note:** `folder` and `folderUid` options should be empty or missing to make `foldersFromFilesStructure` work.
{{% admonition type="note" %}}
`folder` and `folderUid` options should be empty or missing to make `foldersFromFilesStructure` work.
{{% /admonition %}}
> **Note:** To provision dashboards to the General folder, store them in the root of your `path`.
{{% admonition type="note" %}}
To provision dashboards to the General folder, store them in the root of your `path`.
{{% /admonition %}}
## Alerting
@@ -403,7 +421,9 @@ For information on provisioning Grafana Alerting, refer to [Provision Grafana Al
## Alert Notification Channels
> **Note:** Alert Notification Channels are part of legacy alerting, which is deprecated and will be removed in Grafana 10. Use the Provision contact points section in [Create and manage alerting resources using file provisioning]({{< relref "../../alerting/set-up/provision-alerting-resources/file-provisioning" >}}).
{{% admonition type="note" %}}
Alert Notification Channels are part of legacy alerting, which is deprecated and will be removed in Grafana 10. Use the Provision contact points section in [Create and manage alerting resources using file provisioning]({{< relref "../../alerting/set-up/provision-alerting-resources/file-provisioning" >}}).
{{% /admonition %}}
Alert Notification Channels can be provisioned by adding one or more YAML config files in the [`provisioning/notifiers`](/administration/configuration/#provisioning) directory.
@@ -475,7 +495,9 @@ delete_notifiers:
The following sections detail the supported settings and secure settings for each alert notification type. Secure settings are stored encrypted in the database and you add them to `secure_settings` in the YAML file instead of `settings`.
> **Note:** Secure settings is supported since Grafana v7.2.
{{% admonition type="note" %}}
Secure settings is supported since Grafana v7.2.
{{% /admonition %}}
#### Alert notification `pushover`
docs/sources/administration/recorded-queries/index.md
+6 -2
View File
@@ -21,11 +21,15 @@ 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 "../../introduction/grafana-enterprise/" >}}).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}).
{{% /admonition %}}
## How recorded queries work
> **Note:** An administrator must configure a Prometheus data source and associate it with a [Remote write target](#remote-write-target) before recorded queries can be used.
{{% admonition type="note" %}}
An administrator must configure a Prometheus data source and associate it with a [Remote write target](#remote-write-target) before recorded queries can be used.
{{% /admonition %}}
Recorded queries only work with backend data source plugins. Refer to [Backend data source plugin](/tutorials/build-a-data-source-backend-plugin/) for more information about backend data source plugins. You can recorded three types of queries:
docs/sources/administration/roles-and-permissions/_index.md
+12 -4
View File
@@ -20,13 +20,17 @@ You can assign a user one of three types of permissions:
- Organization permissions: Manage access to dashboards, alerts, plugins, teams, playlists, and other resources for an entire organization. The available roles are Viewer, Editor, and Admin.
- Dashboard and folder permission: Manage access to dashboards and folders
> **Note**: If you are running Grafana Enterprise, you can also control access to data sources and use role-based access control to grant user access to read and write permissions to specific Grafana resources. For more information about access control options available with Grafana Enterprise, refer to [Grafana Enterprise user permissions features](#grafana-enterprise-user-permissions-features).
{{% admonition type="note" %}}
If you are running Grafana Enterprise, you can also control access to data sources and use role-based access control to grant user access to read and write permissions to specific Grafana resources. For more information about access control options available with Grafana Enterprise, refer to [Grafana Enterprise user permissions features](#grafana-enterprise-user-permissions-features).
{{% /admonition %}}
## Grafana server administrators
A Grafana server administrator manages server-wide settings and access to resources such as organizations, users, and licenses. Grafana includes a default server administrator that you can use to manage all of Grafana, or you can divide that responsibility among other server administrators that you create.
> **Note:** The server administrator role does not mean that the user is also a Grafana [organization administrator]({{< relref "#organization-roles" >}}).
{{% admonition type="note" %}}
The server administrator role does not mean that the user is also a Grafana [organization administrator]({{< relref "#organization-roles" >}}).
{{% /admonition %}}
A server administrator can perform the following tasks:
@@ -36,7 +40,9 @@ A server administrator can perform the following tasks:
- View Grafana server statistics, including total users and active sessions
- Upgrade the server to Grafana Enterprise.
> **Note:** The server administrator role does not exist in Grafana Cloud.
{{% admonition type="note" %}}
The server administrator role does not exist in Grafana Cloud.
{{% /admonition %}}
To assign or remove server administrator privileges, see [Server user management]({{< relref "../user-management/server-user-management/assign-remove-server-admin-privileges/" >}}).
@@ -112,7 +118,9 @@ For more information about assigning dashboard permissions, refer to [Grant dash
If you have access to the Grafana server, you can modify the default editor role so that editors can use administrator permissions to manage dashboard folders, dashboards, and teams that they create.
> **Note**: This permission does not allow editors to manage folders, dashboards, and teams that they do not create.
{{% admonition type="note" %}}
This permission does not allow editors to manage folders, dashboards, and teams that they do not create.
{{% /admonition %}}
This setting can be used to enable self-organizing teams to administer their own dashboards.
docs/sources/administration/roles-and-permissions/access-control/_index.md
+6 -2
View File
@@ -18,7 +18,9 @@ weight: 120
# Role-based access control (RBAC)
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% /admonition %}}
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.
@@ -62,7 +64,9 @@ Each basic role is comprised of a number of _permissions_. For example, the view
- `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.
{{% admonition type="note" %}}
You can't have a Grafana user without a basic role assigned.
{{% /admonition %}}
#### Basic role modification
docs/sources/administration/roles-and-permissions/access-control/assign-rbac-roles/index.md
+3 -1
View File
@@ -11,7 +11,9 @@ weight: 40
# Assign RBAC roles
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% /admonition %}}
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.
docs/sources/administration/roles-and-permissions/access-control/configure-rbac/index.md
+3 -1
View File
@@ -9,7 +9,9 @@ weight: 30
# Configure RBAC in Grafana
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% /admonition %}}
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" >}}).
docs/sources/administration/roles-and-permissions/access-control/custom-role-actions-scopes/index.md
+3 -1
View File
@@ -10,7 +10,9 @@ weight: 80
# RBAC permissions, actions, and scopes
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% /admonition %}}
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.
docs/sources/administration/roles-and-permissions/access-control/manage-rbac-roles/index.md
+10 -4
View File
@@ -12,7 +12,9 @@ weight: 50
# Manage RBAC roles
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% /admonition %}}
This section includes instructions for how to view permissions associated with roles, create custom roles, and update and delete roles.
@@ -192,7 +194,9 @@ roles:
The following examples show you how to create a custom role using the Grafana HTTP API. For more information about the HTTP API, refer to [Create a new custom role]({{< 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.
{{% admonition type="note" %}}
You cannot create a custom role with permissions that you do not have. For example, if you only have `users:create` permissions, then you cannot create a role that includes other permissions.
{{% /admonition %}}
The following example creates a `custom:users:admin` role and assigns the `users:create` action to it.
@@ -301,8 +305,10 @@ roles:
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.
{{% admonition type="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.
Make sure to **increment** the role version for the changes to be accounted for.
{{% /admonition %}}
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.
docs/sources/administration/roles-and-permissions/access-control/plan-rbac-rollout-strategy/index.md
+9 -3
View File
@@ -11,7 +11,9 @@ weight: 20
# Plan your RBAC rollout strategy
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% /admonition %}}
An RBAC rollout strategy helps you determine _how_ you want to implement RBAC prior to assigning RBAC roles to users and teams.
@@ -60,7 +62,9 @@ Consider the following guidelines when you determine if you should modify basic
- **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 "../../../organization-management/" >}}) 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.
{{% admonition type="note" %}}
Changes that you make to basic roles impact the role definition for all [organizations]({{< relref "../../../organization-management/" >}}) 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.
{{% /admonition %}}
- **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.
@@ -77,7 +81,9 @@ Use any of the following methods to assign RBAC roles to users and teams.
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!
{{% admonition type="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!
{{% /admonition %}}
### Provide internal viewer employees with the ability to use Explore, but prevent external viewer contractors from using Explore
docs/sources/administration/roles-and-permissions/access-control/rbac-fixed-basic-role-definitions/index.md
+10 -4
View File
@@ -11,7 +11,9 @@ weight: 70
# RBAC role definitions
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% /admonition %}}
The following tables list permissions associated with basic and fixed roles.
@@ -108,10 +110,14 @@ For more information about the permissions required to access alert rules, refer
### Grafana OnCall roles (beta)
> **Note:** Available from Grafana 9.4 in early access.
{{% admonition type="note" %}}
Available from Grafana 9.4 in early access.
{{% /admonition %}}
> **Note:** This feature is behind the `accessControlOnCall` feature toggle.
> You can enable feature toggles through configuration file or environment variables. See configuration [docs]({{< relref "../../../../setup-grafana/configure-grafana/#feature_toggles" >}}) for details.
{{% admonition type="note" %}}
This feature is behind the `accessControlOnCall` feature toggle.
You can enable feature toggles through configuration file or environment variables. See configuration [docs]({{< relref "../../../../setup-grafana/configure-grafana/#feature_toggles" >}}) for details.
{{% /admonition %}}
If you are using [Grafana OnCall](https://grafana.com/docs/oncall/latest/get-started/), you can try out the integration between Grafana OnCall and RBAC.
This will allow you to control access to different OnCall features using the following RBAC roles:
docs/sources/administration/roles-and-permissions/access-control/rbac-grafana-provisioning/index.md
+3 -1
View File
@@ -11,7 +11,9 @@ weight: 60
# Provisioning RBAC with Grafana
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% /admonition %}}
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.
docs/sources/administration/roles-and-permissions/access-control/rbac-terraform-provisioning/index.md
+3 -1
View File
@@ -10,7 +10,9 @@ weight: 60
# Provisioning RBAC with Terraform
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% /admonition %}}
You can create, change or remove [Custom roles](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/role) and create or remove [basic and custom role assignments](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/role_assignment), by using [Terraform's Grafana provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs).
docs/sources/administration/roles-and-permissions/access-control/troubleshooting/index.md
+7 -3
View File
@@ -27,7 +27,9 @@ filters = accesscontrol:debug accesscontrol.evaluator:debug dashboard.permission
## Enable audit logging
> **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 7.3 and later, and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 7.3 and later, and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% /admonition %}}
You can enable auditing in the Grafana configuration file.
@@ -45,8 +47,10 @@ Learn more about [access control audit logs]({{< relref "../../../../setup-grafa
This happens when an instance is downgraded from a version that uses RBAC to a version that uses the legacy access control, and dashboard, folder or data source permissions are updated.
These permission updates will not be applied to RBAC, so permissions will be out of sync when the instance is next upgraded to a version with RBAC.
> **Note:** the steps provided below will set all dashboard, folder and data source permissions to what they are set to with the legacy access control.
> If you have made dashboard, folder or data source permission updates with RBAC enabled, these updates will be wiped.
{{% admonition type="note" %}}
the steps provided below will set all dashboard, folder and data source permissions to what they are set to with the legacy access control.
If you have made dashboard, folder or data source permission updates with RBAC enabled, these updates will be wiped.
{{% /admonition %}}
To resynchronize the permissions:
docs/sources/administration/service-accounts/index.md
+10 -4
View File
@@ -17,7 +17,9 @@ weight: 800
You can use a service account to run automated workloads in Grafana, such as dashboard provisioning, configuration, or report generation. Create service accounts and tokens to authenticate applications, such as Terraform, with the Grafana API.
> **Note:** Service accounts will eventually replace [API keys]({{< relref "../api-keys/" >}}) as the primary way to authenticate applications that interact with Grafana.
{{% admonition type="note" %}}
Service accounts will eventually replace [API keys]({{< relref "../api-keys/" >}}) as the primary way to authenticate applications that interact with Grafana.
{{% /admonition %}}
A common use case for creating a service account is to perform operations on automated or triggered tasks. You can use service accounts to:
@@ -28,7 +30,9 @@ A common use case for creating a service account is to perform operations on aut
In [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}), you can also use service accounts in combination with [role-based access control]({{< relref "../roles-and-permissions/access-control/" >}}) to grant very specific permissions to applications that interact with Grafana.
> **Note:** Service accounts can only act in the organization they are created for. If you have the same task that is needed for multiple organizations, we recommend creating service accounts in each organization.
{{% admonition type="note" %}}
Service accounts can only act in the organization they are created for. If you have the same task that is needed for multiple organizations, we recommend creating service accounts in each organization.
{{% /admonition %}}
{{< vimeo 742056367 >}}
@@ -174,8 +178,10 @@ To list your token's permissions, use the `/api/access-control/user/permissions`
#### Example
> **Note:** The following command output is shortened to show only the relevant content.
> Authorize your request with the token whose permissions you want to check.
{{% admonition type="note" %}}
The following command output is shortened to show only the relevant content.
Authorize your request with the token whose permissions you want to check.
{{% /admonition %}}
```bash
curl -H "Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7FDsNSLAa_54e2f8be" -X GET '<grafana_url>/api/access-control/user/permissions' | jq
docs/sources/administration/user-management/manage-dashboard-permissions/index.md
+6 -2
View File
@@ -37,7 +37,9 @@ When you grant folder permissions, that setting applies to all dashboards and su
For example, if a user with the viewer organization role requires editor (or admin) access to a dashboard, you can assign those elevated permissions on an individual basis.
> **Note**: If you have assigned a user dashboard folder permissions, you cannot also assign the user permission to dashboards contained in the folder.
{{% admonition type="note" %}}
If you have assigned a user dashboard folder permissions, you cannot also assign the user permission to dashboards contained in the folder.
{{% /admonition %}}
Grant dashboard permissions when you want to restrict or enhance dashboard access for users who do not have permissions defined in the associated folder.
@@ -63,7 +65,9 @@ By default, the viewer organization role does not allow viewers to create dashbo
This modification is useful for public Grafana installations where you want anonymous users to be able to edit panels and queries but not save or create new dashboards.
> **Note**: If you use Grafana Enterprise and customize users' permissions using RBAC, the RBAC permissions override the functionality enabled by the `viewers_can_edit` flag.
{{% admonition type="note" %}}
If you use Grafana Enterprise and customize users' permissions using RBAC, the RBAC permissions override the functionality enabled by the `viewers_can_edit` flag.
{{% /admonition %}}
### Before you begin
docs/sources/administration/user-management/manage-org-users/index.md
+15 -5
View File
@@ -32,13 +32,17 @@ You can see a list of users with accounts in your Grafana organization. If neces
1. Sign in to Grafana as an organization administrator.
1. Navigate to **Administration > Users**.
> **Note:** If you have [server administrator]({{< relref "../../roles-and-permissions/#grafana-server-administrators" >}}) permissions, you can also [view a global list of users]({{< relref "../server-user-management#view-a-list-of-users" >}}) in the Server Admin section of Grafana.
{{% admonition type="note" %}}
If you have [server administrator]({{< relref "../../roles-and-permissions/#grafana-server-administrators" >}}) permissions, you can also [view a global list of users]({{< relref "../server-user-management#view-a-list-of-users" >}}) in the Server Admin section of Grafana.
{{% /admonition %}}
## Change a user's organization permissions
Update user permissions when you want to enhance or restrict a user's access to organization resources. For more information about organization permissions, refer to [Organization roles]({{< relref "../../roles-and-permissions/#organization-roles" >}}).
> **Note:** Organization roles sync from the authentication provider on user sign-in. To prevent synchronization of organization roles from the authentication provider regardless of their role in the authentication provider, then refer to the `skip_org_role_sync` setting in your Grafana configuration. Refer to [skip org role sync]({{< relref "../../../setup-grafana/configure-grafana/#authgrafana_com-skip_org_role_sync" >}}) for more information.
{{% admonition type="note" %}}
Organization roles sync from the authentication provider on user sign-in. To prevent synchronization of organization roles from the authentication provider regardless of their role in the authentication provider, then refer to the `skip_org_role_sync` setting in your Grafana configuration. Refer to [skip org role sync]({{< relref "../../../setup-grafana/configure-grafana/#authgrafana_com-skip_org_role_sync" >}}) for more information.
{{% /admonition %}}
### Before you begin
@@ -56,7 +60,9 @@ Update user permissions when you want to enhance or restrict a user's access to
1. Select the role that you want to assign.
1. Click **Update**.
> **Note:** If you have [server administrator]({{< relref "../../roles-and-permissions/#grafana-server-administrators" >}}) permissions, you can also [change a user's organization permissions]({{< relref "../server-user-management/change-user-org-permissions/" >}}) in the Server Admin section.
{{% admonition type="note" %}}
If you have [server administrator]({{< relref "../../roles-and-permissions/#grafana-server-administrators" >}}) permissions, you can also [change a user's organization permissions]({{< relref "../server-user-management/change-user-org-permissions/" >}}) in the Server Admin section.
{{% /admonition %}}
## Invite a user to join an organization
@@ -65,7 +71,9 @@ When you invite users to join an organization, you assign the **Admin**, **Edito
- If you know that the user already has access Grafana and you know their user name, then you issue an invitation by entering their user name.
- If the user is new to Grafana, then use their email address to issue an invitation. The system automatically creates the user account on first sign in.
> **Note:** If you have [server administrator]({{< relref "../../roles-and-permissions/#grafana-server-administrators" >}}) permissions, you can also manually [add a user to an organization]({{< relref "../server-user-management/add-remove-user-to-org/" >}}).
{{% admonition type="note" %}}
If you have [server administrator]({{< relref "../../roles-and-permissions/#grafana-server-administrators" >}}) permissions, you can also manually [add a user to an organization]({{< relref "../server-user-management/add-remove-user-to-org/" >}}).
{{% /admonition %}}
### Before you begin
@@ -99,7 +107,9 @@ If the invitee is not already a user, the system adds them.
Periodically review invitations you have sent so that you can see a list of users that have not yet accepted the invitation or cancel a pending invitation.
> **Note:** The **Pending Invites** button is only visible if there are unanswered invitations.
{{% admonition type="note" %}}
The **Pending Invites** button is only visible if there are unanswered invitations.
{{% /admonition %}}
### Before you begin
docs/sources/administration/user-management/server-user-management/_index.md
+6 -2
View File
@@ -37,7 +37,9 @@ You can see a list of users with accounts on your Grafana server. This action mi
1. Sign in to Grafana as a server administrator.
1. Click **Administration** in the left-side menu, and then **Users**.
> **Note:** If you have [organization administrator]({{< relref "../../roles-and-permissions/#organization-roles" >}}) permissions and _not_ [server administrator]({{< relref "../../roles-and-permissions/#grafana-server-administrators" >}}) permissions, you can still [view of list of users in a given organization]({{< relref "../manage-org-users/#view-a-list-of-organization-users" >}}).
{{% admonition type="note" %}}
If you have [organization administrator]({{< relref "../../roles-and-permissions/#organization-roles" >}}) permissions and _not_ [server administrator]({{< relref "../../roles-and-permissions/#grafana-server-administrators" >}}) permissions, you can still [view of list of users in a given organization]({{< relref "../manage-org-users/#view-a-list-of-organization-users" >}}).
{{% /admonition %}}
## View user details
@@ -115,7 +117,9 @@ When you configure advanced authentication using Oauth, SAML, LDAP, or the Auth
When you create a user, the system assigns the user viewer permissions in a default organization, which you can change. You can now [add a user to a second organization]({{< relref "add-remove-user-to-org/" >}}).
> **Note:** If you have [organization administrator]({{< relref "../../roles-and-permissions/#organization-roles" >}}) permissions and _not_ [server administrator]({{< relref "../../roles-and-permissions/#grafana-server-administrators" >}}) permissions, you can still add users by [inviting a user to join an organization]({{< relref "../manage-org-users#invite-a-user-to-join-an-organization" >}}).
{{% admonition type="note" %}}
If you have [organization administrator]({{< relref "../../roles-and-permissions/#organization-roles" >}}) permissions and _not_ [server administrator]({{< relref "../../roles-and-permissions/#grafana-server-administrators" >}}) permissions, you can still add users by [inviting a user to join an organization]({{< relref "../manage-org-users#invite-a-user-to-join-an-organization" >}}).
{{% /admonition %}}
## Force a user to log out of Grafana
docs/sources/administration/user-management/server-user-management/add-remove-user-to-org/index.md
+3 -1
View File
@@ -38,7 +38,9 @@ You are required to specify an Admin role for each organization. The first user
The next time the user signs in, they will be able to navigate to their new organization using the Switch Organizations option in the user profile menu.
> **Note:** If you have [organization administrator]({{< relref "../../../roles-and-permissions#organization-roles" >}}) permissions and _not_ [server administrator]({{< relref "../../../roles-and-permissions#grafana-server-administrators" >}}) permissions, you can still [invite a user to join an organization]({{< relref "../../manage-org-users#invite-a-user-to-join-an-organization" >}}).
{{% admonition type="note" %}}
If you have [organization administrator]({{< relref "../../../roles-and-permissions#organization-roles" >}}) permissions and _not_ [server administrator]({{< relref "../../../roles-and-permissions#grafana-server-administrators" >}}) permissions, you can still [invite a user to join an organization]({{< relref "../../manage-org-users#invite-a-user-to-join-an-organization" >}}).
{{% /admonition %}}
## Remove a user from an organization
docs/sources/administration/user-management/server-user-management/assign-remove-server-admin-privileges/index.md
+3 -1
View File
@@ -11,7 +11,9 @@ weight: 20
Grafana server administrators are responsible for creating users, organizations, and managing permissions. For more information about the server administration role, refer to [Grafana server administrators]({{< relref "../../../roles-and-permissions#grafana-server-administrators" >}}).
> **Note:** Server administrators are "super-admins" with full permissions to create, read, update, and delete all resources and users in all organizations, as well as update global settings such as licenses. Only grant this permission to trusted users.
{{% admonition type="note" %}}
Server administrators are "super-admins" with full permissions to create, read, update, and delete all resources and users in all organizations, as well as update global settings such as licenses. Only grant this permission to trusted users.
{{% /admonition %}}
## Before you begin
docs/sources/administration/user-management/server-user-management/grant-editor-admin-permissions/index.md
+3 -1
View File
@@ -16,7 +16,9 @@ When `editors_can_admin` is enabled:
- Users with the Editor role in an organization are Administrators for new dashboards and folders they create, meaning they can edit dashboard permissions. To learn more about dashboard permissions, refer to [Manage dashboard permissions]({{< relref "../../manage-dashboard-permissions/" >}}).
- Users with the Editor role in an organization can create teams, and they are Administrators of the teams they create. To learn more about team permissions, refer to [Team management]({{< relref "../../../team-management/" >}}).
> **Note**: If you use Grafana Enterprise and customize users' permissions using RBAC, the RBAC permissions override the functionality enabled by the `editors_can_admin` flag.
{{% admonition type="note" %}}
If you use Grafana Enterprise and customize users' permissions using RBAC, the RBAC permissions override the functionality enabled by the `editors_can_admin` flag.
{{% /admonition %}}
## Before you begin
docs/sources/administration/user-management/user-preferences/index.md
+3 -1
View File
@@ -22,7 +22,9 @@ You can also view important information about your account, such as the organiza
You can change your Grafana password at any time.
> **Note**: If your Grafana instance uses an <!--[external authentication provider]({{< relref "../../../setup-grafana/configure-security/configure-authentication/" >}})--> external authentication provider, then you might not be able to change your password in Grafana. Contact your Grafana administrator for more information.
{{% admonition type="note" %}}
If your Grafana instance uses an external authentication provider, then you might not be able to change your password in Grafana. Contact your Grafana administrator for more information.
{{% /admonition %}}
**To change your password**: