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

update docs, simplify actions and scopes (#47067)

Browse Source
This commit is contained in:
Ieva
2022-04-04 13:53:58 +01:00
committed by GitHub
parent 473fa6d997
commit bc9b5325a0
11 changed files with 106 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/enterprise/access-control/fine-grained-access-control-references.md
+5 -2
View File
@@ -50,6 +50,9 @@ The reference information that follows complements conceptual information about
| `fixed:folders:writer` | All permissions from `fixed:dashboards:writer` and <br>`folders:read`<br>`folders:write`<br>`folders:create`<br>`folders:delete`<br>`folders.permissions:read`<br>`folders.permissions:write` | Read, create, update, and delete all folders and dashboards. |
| `fixed:folders.permissions:reader` | `folders.permissions:read` | Read all folder permissions. |
| `fixed:folders.permissions:writer` | All permissions from `fixed:folders.permissions:reader` and <br>`folders.permissions:write` | Read and update all folder permissions. |
| `fixed:annotations:reader` | `annotations:read` | Read all annotations and annotation tags. |
| `fixed:annotations.dashboard:writer` | `annotations:write` <br>`annotations.create`<br> `annotations:delete` for scope `annotations:type:dashboard` | Create, update and delete dashboard annotations and annotation tags. |
| `fixed:annotations:writer` | `annotations:write` <br>`annotations.create`<br> `annotations:delete` for scope `annotations:type:*` | Create, update and delete all annotations and annotation tags. |
## Default built-in role assignments
@@ -57,5 +60,5 @@ The reference information that follows complements conceptual information about
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Grafana Admin | `fixed:roles:reader`<br>`fixed:roles:writer`<br>`fixed:users:reader`<br>`fixed:users:writer`<br>`fixed:org.users:reader`<br>`fixed:org.users:writer`<br>`fixed:ldap:reader`<br>`fixed:ldap:writer`<br>`fixed:stats:reader`<br>`fixed:settings:reader`<br>`fixed:settings:writer`<br>`fixed:provisioning:writer`<br>`fixed:organization:reader`<br>`fixed:organization:maintainer`<br>`fixed:licensing:reader`<br>`fixed:licensing:writer` | Default [Grafana server administrator]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions.md#grafana-server-administrators" >}}) assignments. |
| Admin | `fixed:reports:reader`<br>`fixed:reports:writer`<br>`fixed:datasources:reader`<br>`fixed:datasources:writer`<br>`fixed:organization:writer`<br>`fixed:datasources.permissions:reader`<br>`fixed:datasources.permissions:writer`<br>`fixed:teams:writer`<br>`fixed:dashboards:reader`<br>`fixed:dashboards:writer`<br>`fixed:dashboards.permissions:reader`<br>`fixed:dashboards.permissions:writer`<br>`fixed:folders:reader`<br>`fixes:folders:writer`<br>`fixed:folders.permissions:reader`<br>`fixed:folders.permissions:writer` | Default [Grafana organization administrator]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions.md#organization-users-and-permissions" >}}) assignments. |
| Editor | `fixed:datasources:explorer`<br>`fixed:dashboards:creator`<br>`fixed:folders:creator`<br>`fixed:teams:creator` if the `editors_can_admin` configuration flag is enabled | Default [Editor]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions.md#organization-users-and-permissions" >}}) assignments. |
| Viewer | `fixed:datasources:id:reader`<br>`fixed:organization:reader` | Default [Viewer]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions.md#organization-users-and-permissions" >}}) assignments. |
| Editor | `fixed:datasources:explorer`<br>`fixed:dashboards:creator`<br>`fixed:folders:creator`<br>`fixed:annotations:writer`<br>`fixed:teams:creator` if the `editors_can_admin` configuration flag is enabled | Default [Editor]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions.md#organization-users-and-permissions" >}}) assignments. |
| Viewer | `fixed:datasources:id:reader`<br>`fixed:organization:reader`<br>`fixed:annotations:reader`<br>`fixed:annotations.dashboard:writer` | Default [Viewer]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions.md#organization-users-and-permissions" >}}) assignments. |
docs/sources/enterprise/access-control/permissions.md
+20 -15
View File
@@ -113,23 +113,28 @@ The following list contains fine-grained access control actions.
| `folders:delete` | `folders:*`<br>`folders:id:*` | Delete one or more folders. |
| `folers.permissions:read` | `folders:*`<br>`folders:id:*` | Read permissions for one or more folders. |
| `folders.permissions:write` | `folders:*`<br>`folders:id:*` | Update permissions for one or more folders. |
| `annotations.read` | `annotations:*`<br>`annotations:type:*` | Read annotations and annotation tags. |
| `annotations.create` | `annotations:*`<br>`annotations:type:*` | Create annotations. |
| `annotations.write` | `annotations:*`<br>`annotations:type:*` | Update annotations. |
| `annotations.delete` | `annotations:*`<br>`annotations:type:*` | Delete annotations. |
## Scope definitions
The following list contains fine-grained access control scopes.
| Scopes | Descriptions |
| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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. |
| `roles:*` <br> `roles:uid:*` | Restrict an action to a set of roles. For example, `roles:*` matches any role and `roles:uid:randomuid` matches only the role whose UID is `randomuid`. |
| `reports:*` <br> `reports:id:*` | Restrict an action to a set of reports. For example, `reports:*` matches any report and `reports:id:1` matches the report whose ID is `1`. |
| `services:accesscontrol` | Restrict an action to target only the fine-grained access control service. You can use this in conjunction with the `status:accesscontrol` actions. |
| `global.users:*` <br> `global.users:id:*` | Restrict an action to a set of global users. For example, `global.users:*` matches any user and `global.users:id:1` matches the user whose ID is `1`. |
| `teams:*` <br> `teams:id:*` | Restrict an action to a set of teams from an organization. For example, `teams:*` matches any team and `teams:id:1` matches the team whose ID is `1`. |
| `users:*` <br> `users:id:*` | Restrict an action to a set of users from an organization. For example, `users:*` matches any user and `users:id:1` matches the user whose ID is `1`. |
| `orgs:*` <br> `orgs:id:*` | Restrict an action to a set of organizations. For example, `orgs:*` matches any organization and `orgs:id:1` matches the organization whose ID is `1`. |
| `settings:*` | Restrict an action to a subset of settings. For example, `settings:*` matches all settings, `settings:auth.saml:*` matches all SAML settings, and `settings:auth.saml:enabled` matches the enable property on the SAML settings. |
| `provisioners:*` | Restrict an action to a set of provisioners. For example, `provisioners:*` matches any provisioner, and `provisioners:accesscontrol` matches the fine-grained access control [provisioner]({{< relref "./provisioning.md" >}}). |
| `datasources:*`<br>`datasources:id:*`<br>`datasources:uid:*`<br>`datasources:name:*` | Restrict an action to a set of data sources. For example, `datasources:*` matches any data source, and `datasources:name:postgres` matches the data source named `postgres`. |
| `folders:*`<br>`folders:id:*` | Restrict an action to a set of folders. For example, `folders:*` matches any folder, and `folders:id:1` matches the folder whose ID is `1`. |
| `dashboards:*`<br>`dashboards:id:*` | Restrict an action to a set of dashboards. For example, `dashboards:*` matches any dashboard, and `dashboards:id:1` matches the dashboard whose ID is `1`. |
| Scopes | Descriptions |
| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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. |
| `roles:*` <br> `roles:uid:*` | Restrict an action to a set of roles. For example, `roles:*` matches any role and `roles:uid:randomuid` matches only the role whose UID is `randomuid`. |
| `reports:*` <br> `reports:id:*` | Restrict an action to a set of reports. For example, `reports:*` matches any report and `reports:id:1` matches the report whose ID is `1`. |
| `services:accesscontrol` | Restrict an action to target only the fine-grained access control service. You can use this in conjunction with the `status:accesscontrol` actions. |
| `global.users:*` <br> `global.users:id:*` | Restrict an action to a set of global users. For example, `global.users:*` matches any user and `global.users:id:1` matches the user whose ID is `1`. |
| `teams:*` <br> `teams:id:*` | Restrict an action to a set of teams from an organization. For example, `teams:*` matches any team and `teams:id:1` matches the team whose ID is `1`. |
| `users:*` <br> `users:id:*` | Restrict an action to a set of users from an organization. For example, `users:*` matches any user and `users:id:1` matches the user whose ID is `1`. |
| `orgs:*` <br> `orgs:id:*` | Restrict an action to a set of organizations. For example, `orgs:*` matches any organization and `orgs:id:1` matches the organization whose ID is `1`. |
| `settings:*` | Restrict an action to a subset of settings. For example, `settings:*` matches all settings, `settings:auth.saml:*` matches all SAML settings, and `settings:auth.saml:enabled` matches the enable property on the SAML settings. |
| `provisioners:*` | Restrict an action to a set of provisioners. For example, `provisioners:*` matches any provisioner, and `provisioners:accesscontrol` matches the fine-grained access control [provisioner]({{< relref "./provisioning.md" >}}). |
| `datasources:*`<br>`datasources:id:*`<br>`datasources:uid:*`<br>`datasources:name:*` | Restrict an action to a set of data sources. For example, `datasources:*` matches any data source, and `datasources:name:postgres` matches the data source named `postgres`. |
| `folders:*`<br>`folders:id:*` | Restrict an action to a set of folders. For example, `folders:*` matches any folder, and `folders:id:1` matches the folder whose ID is `1`. |
| `dashboards:*`<br>`dashboards:id:*` | Restrict an action to a set of dashboards. For example, `dashboards:*` matches any dashboard, and `dashboards:id:1` matches the dashboard whose ID is `1`. |
| `annotations:*`<br>`annotations:type:*` | Restrict an action to a set of annotations. For example, `annotations:*` matches any annotation, `annotations:type:dashboard` matches annotations associated with dashboards and `annotations:type:organization` matches organization annotations. |
docs/sources/http_api/annotations.md
+63 -4
View File
@@ -5,14 +5,25 @@ keywords = ["grafana", "http", "documentation", "api", "annotation", "annotation
aliases = ["/docs/grafana/latest/http_api/annotations/"]
+++
# Annotations resources / actions
# Annotations API
This is the API documentation for the new Grafana Annotations feature released in Grafana 4.6. Annotations are saved in the Grafana database (sqlite, mysql or postgres). Annotations can be global annotations that can be shown on any dashboard by configuring an annotation data source - they are filtered by tags. Or they can be tied to a panel on a dashboard and are then only shown on that panel.
This is the API documentation for the new Grafana Annotations feature released in Grafana 4.6. Annotations are saved in the Grafana database (sqlite, mysql or postgres). Annotations can be organization annotations that can be shown on any dashboard by configuring an annotation data source - they are filtered by tags. Or they can be tied to a panel on a dashboard and are then only shown on that panel.
> If you are running Grafana Enterprise and have [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, access to endpoints will be controlled by Fine-grained access control permissions.
> Refer to specific endpoints to understand what permissions are required.
## Find Annotations
`GET /api/annotations?from=1506676478816&to=1507281278816&tags=tag1&tags=tag2&limit=100`
#### Required permissions
See note in the [introduction]({{< ref "#annotations-api" >}}) for an explanation.
| Action | Scope |
| ---------------- | -------------- |
| annotations:read | annotations:\* |
**Example Request**:
```http
@@ -32,7 +43,7 @@ Query Parameters:
- `panelId`: number. Optional. Find annotations that are scoped to a specific panel
- `userId`: number. Optional. Find annotations created by a specific user
- `type`: string. Optional. `alert`|`annotation` Return alerts or user created annotations
- `tags`: string. Optional. Use this to filter global annotations. Global annotations are annotations from an annotation data source that are not connected specifically to a dashboard or panel. To do an "AND" filtering with multiple tags, specify the tags parameter multiple times e.g. `tags=tag1&tags=tag2`.
- `tags`: string. Optional. Use this to filter organization annotations. Organization annotations are annotations from an annotation data source that are not connected specifically to a dashboard or panel. To do an "AND" filtering with multiple tags, specify the tags parameter multiple times e.g. `tags=tag1&tags=tag2`.
**Example Response**:
@@ -85,13 +96,21 @@ Content-Type: application/json
## Create Annotation
Creates an annotation in the Grafana database. The `dashboardId` and `panelId` fields are optional.
If they are not specified then a global annotation is created and can be queried in any dashboard that adds
If they are not specified then an organization annotation is created and can be queried in any dashboard that adds
the Grafana annotations data source. When creating a region annotation include the timeEnd property.
The format for `time` and `timeEnd` should be epoch numbers in millisecond resolution.
`POST /api/annotations`
#### Required permissions
See note in the [introduction]({{< ref "#annotations-api" >}}) for an explanation.
| Action | Scope |
| ------------------ | ----------------------- |
| annotations:create | annotations:type:<type> |
**Example Request**:
```http
@@ -132,6 +151,14 @@ format (string with multiple tags being separated by a space).
`POST /api/annotations/graphite`
#### Required permissions
See note in the [introduction]({{< ref "#annotations-api" >}}) for an explanation.
| Action | Scope |
| ------------------ | ----------------------------- |
| annotations:create | annotations:type:organization |
**Example Request**:
```http
@@ -165,6 +192,14 @@ Content-Type: application/json
Updates all properties of an annotation that matches the specified id. To only update certain property, consider using the [Patch Annotation](#patch-annotation) operation.
#### Required permissions
See note in the [introduction]({{< ref "#annotations-api" >}}) for an explanation.
| Action | Scope |
| ----------------- | ----------------------- |
| annotations:write | annotations:type:<type> |
**Example Request**:
```http
@@ -202,6 +237,14 @@ Updates one or more properties of an annotation that matches the specified id.
This operation currently supports updating of the `text`, `tags`, `time` and `timeEnd` properties.
#### Required permissions
See note in the [introduction]({{< ref "#annotations-api" >}}) for an explanation.
| Action | Scope |
| ----------------- | ----------------------- |
| annotations:write | annotations:type:<type> |
**Example Request**:
```http
@@ -233,6 +276,14 @@ Content-Type: application/json
Deletes the annotation that matches the specified id.
#### Required permissions
See note in the [introduction]({{< ref "#annotations-api" >}}) for an explanation.
| Action | Scope |
| ------------------ | ----------------------- |
| annotations:delete | annotations:type:<type> |
**Example Request**:
```http
@@ -259,6 +310,14 @@ Content-Type: application/json
Find all the event tags created in the annotations.
#### Required permissions
See note in the [introduction]({{< ref "#annotations-api" >}}) for an explanation.
| Action | Scope |
| ---------------- | ----- |
| annotations:read | N/A |
**Example Request**:
```http