IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-02-25 18:55:37 -06:00
Code Issues Packages Projects Releases Wiki Activity

Alerting docs: Update Alerting provisioning HTTP API (#91493)

Browse Source 
* Remove `Consumes` info

* Remove `top-level` content negotiation/Produces

* Remove `Version Information`

* Better distinguish between Grafana and Data source managed alerts

* Add note for Enterprise RBAC permissions

* Minor changes for clarity

* Add examples

* Minor copy change

* Update docs/sources/shared/alerts/alerting_provisioning.md

Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com>

* Update docs/sources/shared/alerts/alerting_provisioning.md

Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com>

* Update docs/sources/shared/alerts/alerting_provisioning.md

Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com>

---------

Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com>
This commit is contained in:
Pepe Cano
2024-08-05 16:47:48 +02:00
committed by GitHub
parent 9a2c9647ee
commit 114d87bf61
1 changed files with 237 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

305
docs/sources/shared/alerts/alerting_provisioning.md
View File

@@ -6,29 +6,15 @@ labels:
title: 'Alerting Provisioning HTTP API '
---
The Alerting provisioning API can be used to create, modify, and delete resources relevant to [Grafana-managed alerts]({{< relref "/docs/grafana/latest/alerting/alerting-rules/create-grafana-managed-rule" >}}). It is the one used by our [Grafana Terraform provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs).
The Alerting Provisioning HTTP API can be used to create, modify, and delete resources relevant to Grafana-managed alerts. This API is the one used by our [Grafana Terraform provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs).
To manage resources related to [data source-managed alerts]({{< relref "/docs/grafana/latest/alerting/alerting-rules/create-grafana-managed-rule" >}}), including recording rules, use the [Mimir tool](https://grafana.com/docs/mimir/latest/manage/tools/mimirtool/) and [Cortex tool](https://github.com/grafana/cortex-tools#cortextool).
For more information on the differences between Grafana-managed and data source-managed alerts, refer to [Introduction to alert rules](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/alerting/fundamentals/alert-rules/).
## Information
> If you are running Grafana Enterprise, you need to add specific permissions for some endpoints. For more information, refer to [Role-based access control permissions](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/access-control/custom-role-actions-scopes/).
### Version
## Grafana-managed endpoints
1.1.0
## Content negotiation
### Consumes
- application/json
### Produces
- application/json
- text/yaml
- application/yaml
## All endpoints
Note that the JSON format from most of the following endpoints is not fully compatible with [provisioning via configuration JSON files](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/alerting/set-up/provision-alerting-resources/file-provisioning/).
### Alert rules
@@ -45,13 +31,18 @@ To manage resources related to [data source-managed alerts]({{< relref "/docs/gr
| GET | /api/v1/provisioning/alert-rules | [route get alert rules](#route-get-alert-rules) | Get all the alert rules. |
| GET | /api/v1/provisioning/alert-rules/export | [route get alert rules export](#route-get-alert-rules-export) | Export all alert rules in provisioning file format. |
#### Example alert rules template
**Example request for new alert rule:**
```http
POST /api/v1/provisioning/alert-rules
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```json
{
"title": "TEST-API_1",
"ruleGroup": "API",
"folderUID": "FOLDER",
"folderUID": "SET_FOLDER_UID",
"noDataState": "OK",
"execErrState": "OK",
"for": "5m",
@@ -72,7 +63,7 @@ To manage resources related to [data source-managed alerts]({{< relref "/docs/gr
"from": 600,
"to": 0
},
"datasourceUid": " XXXXXXXXX-XXXXXXXXX-XXXXXXXXXX",
"datasourceUid": "XXXXXXXXX-XXXXXXXXX-XXXXXXXXXX",
"model": {
"expr": "up",
"hide": false,
@@ -122,6 +113,99 @@ To manage resources related to [data source-managed alerts]({{< relref "/docs/gr
}
]
}
```
#### Example Response:
```http
HTTP/1.1 201 Created
Content-Type: application/json
```
### Contact points
| Method | URI | Name | Summary |
| ------ | ------------------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------ |
| DELETE | /api/v1/provisioning/contact-points/:uid | [route delete contactpoints](#route-delete-contactpoints) | Delete a contact point. |
| GET | /api/v1/provisioning/contact-points | [route get contactpoints](#route-get-contactpoints) | Get all the contact points. |
| POST | /api/v1/provisioning/contact-points | [route post contactpoints](#route-post-contactpoints) | Create a contact point. |
| PUT | /api/v1/provisioning/contact-points/:uid | [route put contactpoint](#route-put-contactpoint) | Update an existing contact point. |
| GET | /api/v1/provisioning/contact-points/export | [route get contactpoints export](#route-get-contactpoints-export) | Export all contact points in provisioning file format. |
**Example Request for all the contact points:**
```http
GET /api/v1/provisioning/contact-points
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
```
### Notification policies
| Method | URI | Name | Summary |
| ------ | ------------------------------------ | ------------------------------------------------------------- | ---------------------------------------------------------------- |
| DELETE | /api/v1/provisioning/policies | [route reset policy tree](#route-reset-policy-tree) | Clears the notification policy tree. |
| GET | /api/v1/provisioning/policies | [route get policy tree](#route-get-policy-tree) | Get the notification policy tree. |
| PUT | /api/v1/provisioning/policies | [route put policy tree](#route-put-policy-tree) | Sets the notification policy tree. |
| GET | /api/v1/provisioning/policies/export | [route get policy tree export](#route-get-policy-tree-export) | Export the notification policy tree in provisioning file format. |
**Example Request for exporting the notification policy tree in YAML format:**
```http
GET /api/v1/provisioning/policies/export?format=yaml
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response:**
```http
HTTP/1.1 200 OK
Content-Type: text/yaml
apiVersion: 1
policies:
- orgId: 1
receiver: My Contact Email Point
group_by:
- grafana_folder
- alertname
routes:
- receiver: My Contact Email Point
object_matchers:
- - monitor
- =
- testdata
mute_time_intervals:
- weekends
```
### Mute timings
| Method | URI | Name | Summary |
| ------ | ---------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------- |
| DELETE | /api/v1/provisioning/mute-timings/:name | [route delete mute timing](#route-delete-mute-timing) | Delete a mute timing. |
| GET | /api/v1/provisioning/mute-timings/:name | [route get mute timing](#route-get-mute-timing) | Get a mute timing. |
| GET | /api/v1/provisioning/mute-timings | [route get mute timings](#route-get-mute-timings) | Get all the mute timings. |
| POST | /api/v1/provisioning/mute-timings | [route post mute timing](#route-post-mute-timing) | Create a new mute timing. |
| PUT | /api/v1/provisioning/mute-timings/:name | [route put mute timing](#route-put-mute-timing) | Replace an existing mute timing. |
| GET | /api/v1/provisioning/mute-timings/export | [route get mute timings export](#route-get-mute-timings-export) | Export all mute timings in provisioning file format. |
| GET | /api/v1/provisioning/mute-timings/:name/export | [route get mute timing export](#route-get-mute-timing-export) | Export a mute timing in provisioning file format. |
**Example Request for all mute timings:**
```http
GET /api/v1/provisioning/mute-timings
Accept: application/json
@@ -134,6 +218,34 @@ To manage resources related to [data source-managed alerts]({{< relref "/docs/gr
```http
HTTP/1.1 200 OK
Content-Type: application/json
```
### Templates
| Method | URI | Name | Summary |
| ------ | ------------------------------------ | ----------------------------------------------- | ----------------------------------------- |
| DELETE | /api/v1/provisioning/templates/:name | [route delete template](#route-delete-template) | Delete a template. |
| GET | /api/v1/provisioning/templates/:name | [route get template](#route-get-template) | Get a notification template. |
| GET | /api/v1/provisioning/templates | [route get templates](#route-get-templates) | Get all notification templates. |
| PUT | /api/v1/provisioning/templates/:name | [route put template](#route-put-template) | Create or update a notification template. |
**Example Request for all notification templates:**
```http
GET /api/v1/provisioning/templates
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
```
### Edit resources in the Grafana UI
@@ -143,6 +255,38 @@ To manage resources related to [data source-managed alerts]({{< relref "/docs/gr
- `PUT /api/v1/provisioning/folder/{FolderUID}/rule-groups/{Group}` (calling this endpoint will change provenance for all alert rules within the alert group)
- `POST /api/v1/provisioning/contact-points`
- `POST /api/v1/provisioning/mute-timings`
- `PUT /api/v1/provisioning/policies`
- `PUT /api/v1/provisioning/templates/{name}`
To reset the notification policy tree to the default and unlock it for editing in the Grafana UI, use the `DELETE /api/v1/provisioning/policies` endpoint.
## Data source-managed resources
The Alerting Provisioning HTTP API can only be used to manage Grafana-managed alert resources. To manage resources related to [data source-managed alerts](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/alerting/alerting-rules/create-mimir-loki-managed-rule/), consider the following tools:
- [mimirtool](https://grafana.com/docs/mimir/<GRAFANA_VERSION>/manage/tools/mimirtool/): to interact with the Mimir alertmanager and ruler configuration.
- [cortex-tools](https://github.com/grafana/cortex-tools#cortextool): to interact with the Cortex alertmanager and ruler configuration.
- [lokitool](https://grafana.com/docs/loki/<GRAFANA_VERSION>/alert/#lokitool): to configure the Loki Ruler.
## Paths
### <span id="route-delete-alert-rule"></span> Delete a specific alert rule by UID. (_RouteDeleteAlertRule_)
```
DELETE /api/v1/provisioning/alert-rules/:uid
```
#### Parameters
{{% responsive-table %}}
| Name | Source | Type | Go type | Separator | Required | Default | Description |
| -------------------------- | -------- | ------ | -------- | --------- | :------: | ------- | --------------------------------------------------------- |
| UID | `path` | string | `string` | | ✓ | | Alert rule UID |
| X-Disable-Provenance: true | `header` | string | `string` | | | | Allows editing of provisioned resources in the Grafana UI |
{{% /responsive-table %}}
#### All responses
| Code | Status | Description | Has headers | Schema |
@@ -155,6 +299,38 @@ To manage resources related to [data source-managed alerts]({{< relref "/docs/gr
Status: No Content
###### <span id="route-delete-alert-rule-204-schema"></span> Schema
### <span id="route-delete-contactpoints"></span> Delete a contact point. (_RouteDeleteContactpoints_)
```
DELETE /api/v1/provisioning/contact-points/:uid
```
#### Parameters
| Name | Source | Type | Go type | Separator | Required | Default | Description |
| ---- | ------ | ------ | -------- | --------- | :------: | ------- | ------------------------------------------ |
| UID | `path` | string | `string` | | ✓ | | UID is the contact point unique identifier |
#### All responses
| Code | Status | Description | Has headers | Schema |
| -------------------------------------- | ---------- | ------------------------------------------- | :---------: | ------------------------------------------------ |
| [204](#route-delete-contactpoints-204) | No Content | The contact point was deleted successfully. | | [schema](#route-delete-contactpoints-204-schema) |
#### Responses
##### <span id="route-delete-contactpoints-204"></span> 204 - The contact point was deleted successfully.
Status: No Content
###### <span id="route-delete-contactpoints-204-schema"></span> Schema
### <span id="route-delete-mute-timing"></span> Delete a mute timing. (_RouteDeleteMuteTiming_)
```
DELETE /api/v1/provisioning/mute-timings/:name
```
#### Parameters
@@ -164,7 +340,36 @@ To manage resources related to [data source-managed alerts]({{< relref "/docs/gr
| name | `path` | string | `string` | | ✓ | | Mute timing name |
#### All responses
## Edit resources in the Grafana UI
| Code | Status | Description | Has headers | Schema |
| ------------------------------------ | ---------- | ----------------------------------------- | :---------: | ---------------------------------------------- |
| [204](#route-delete-mute-timing-204) | No Content | The mute timing was deleted successfully. | | [schema](#route-delete-mute-timing-204-schema) |
#### Responses
##### <span id="route-delete-mute-timing-204"></span> 204 - The mute timing was deleted successfully.
Status: No Content
###### <span id="route-delete-mute-timing-204-schema"></span> Schema
### <span id="route-delete-template"></span> Delete a template. (_RouteDeleteTemplate_)
```
DELETE /api/v1/provisioning/templates/:name
```
#### Parameters
| Name | Source | Type | Go type | Separator | Required | Default | Description |
| ---- | ------ | ------ | -------- | --------- | :------: | ------- | ------------- |
| name | `path` | string | `string` | | ✓ | | Template Name |
#### All responses
| Code | Status | Description | Has headers | Schema |
| --------------------------------- | ---------- | -------------------------------------- | :---------: | ------------------------------------------- |
| [204](#route-delete-template-204) | No Content | The template was deleted successfully. | | [schema](#route-delete-template-204-schema) |
#### Responses
@@ -177,6 +382,14 @@ By default, you cannot edit API-provisioned alerting resources in Grafana. To en
### <span id="route-get-alert-rule"></span> Get a specific alert rule by UID. (_RouteGetAlertRule_)
```
GET /api/v1/provisioning/alert-rules/:uid
```
#### Parameters
| Name | Source | Type | Go type | Separator | Required | Default | Description |
| ---- | ------ | ------ | -------- | --------- | :------: | ------- | -------------- |
| UID | `path` | string | `string` | | ✓ | | Alert rule UID |
#### All responses
@@ -216,10 +429,6 @@ Status: No Content
- text/hcl
#### Parameters
#### Consumes
- application/json
| Name | Source | Type | Go type | Separator | Required | Default | Description |
| -------- | ------- | ------- | -------- | --------- | :------: | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
@@ -884,10 +1093,6 @@ Status: Not Found
### <span id="route-put-alert-rule"></span> Update an existing alert rule. (_RoutePutAlertRule_)
#### Consumes
- application/json
```
PUT /api/v1/provisioning/alert-rules/:uid
```
@@ -930,10 +1135,6 @@ Status: Bad Request
[ValidationError](#validation-error)
### <span id="route-put-alert-rule-group"></span> Update the interval or alert rules of a rule group. (_RoutePutAlertRuleGroup_)
#### Consumes
- application/json
```
PUT /api/v1/provisioning/folder/:folderUid/rule-groups/:group
@@ -976,10 +1177,6 @@ Status: Bad Request
###### <span id="route-put-alert-rule-group-400-schema"></span> Schema
[ValidationError](#validation-error)
#### Consumes
- application/json
### <span id="route-put-contactpoint"></span> Update an existing contact point. (_RoutePutContactpoint_)
@@ -1022,10 +1219,6 @@ Status: Bad Request
###### <span id="route-put-contactpoint-400-schema"></span> Schema
#### Consumes
- application/json
[ValidationError](#validation-error)
### <span id="route-put-mute-timing"></span> Replace an existing mute timing. (_RoutePutMuteTiming_)
@@ -1069,10 +1262,6 @@ Status: Bad Request
###### <span id="route-put-mute-timing-400-schema"></span> Schema
#### Consumes
- application/json
[ValidationError](#validation-error)
### <span id="route-put-policy-tree"></span> Sets the notification policy tree. (_RoutePutPolicyTree_)
@@ -1117,10 +1306,6 @@ Status: Bad Request
[ValidationError](#validation-error)
#### Consumes
- application/json
### <span id="route-put-template"></span> Create or update a notification template. (_RoutePutTemplate_)
```
@@ -1164,10 +1349,6 @@ Status: Bad Request
[ValidationError](#validation-error)
#### Consumes
- application/json
### <span id="route-reset-policy-tree"></span> Clears the notification policy tree. (_RouteResetPolicyTree_)
```
@@ -1211,10 +1392,6 @@ Status: Bad Request
| refId | string | `string` | | | RefID is the unique identifier of the query, set by the frontend call. | |
| relativeTimeRange | [RelativeTimeRange](#relative-time-range) | `RelativeTimeRange` | | | | |
#### Consumes
- application/json
{{% /responsive-table %}}
### <span id="alert-query-export"></span> AlertQueryExport
@@ -1257,10 +1434,6 @@ Status: Bad Request
{{% /responsive-table %}}
### <span id="alert-rule-group"></span> AlertRuleGroup
#### Consumes
- application/json
**Properties**
@@ -1304,10 +1477,6 @@ Status: Bad Request
| groups | [][AlertRuleGroupExport](#alert-rule-group-export) | `[]*AlertRuleGroupExport` | | | | |
| policies | [][NotificationPolicyExport](#notification-policy-export) | `[]*NotificationPolicyExport` | | | | |
#### Consumes
- application/json
{{% /responsive-table %}}
### <span id="contact-point-export"></span> ContactPointExport