Alerting docs: Update Alerting provisioning HTTP API (#91493)
* 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
brendamuir
@@ -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
|
||||
|
||||
{
|
||||
"id": 1,
|
||||
"uid": "XXXXXXXXX",
|
||||
"orgID": 1,
|
||||
"folderUID": "SET_FOLDER_UID",
|
||||
"ruleGroup": "API3",
|
||||
"title": "TEST-API_1",
|
||||
"condition": "B",
|
||||
"data": [
|
||||
{
|
||||
"refId": "A",
|
||||
"queryType": "",
|
||||
"relativeTimeRange": {
|
||||
"from": 600,
|
||||
"to": 0
|
||||
},
|
||||
"datasourceUid": "XXXXXXXXX-XXXXXXXXX-XXXXXXXXXX",
|
||||
"model": {
|
||||
"expr": "up",
|
||||
"hide": false,
|
||||
"intervalMs": 1000,
|
||||
"maxDataPoints": 43200,
|
||||
"refId": "A"
|
||||
}
|
||||
},
|
||||
{
|
||||
"refId": "B",
|
||||
"queryType": "",
|
||||
"relativeTimeRange": {
|
||||
"from": 0,
|
||||
"to": 0
|
||||
},
|
||||
"datasourceUid": "-100",
|
||||
"model": {
|
||||
"conditions": [
|
||||
{
|
||||
"evaluator": {
|
||||
"params": [
|
||||
6
|
||||
],
|
||||
"type": "gt"
|
||||
},
|
||||
"operator": {
|
||||
"type": "and"
|
||||
},
|
||||
"query": {
|
||||
"params": [
|
||||
"A"
|
||||
]
|
||||
},
|
||||
"reducer": {
|
||||
"params": [],
|
||||
"type": "last"
|
||||
},
|
||||
"type": "query"
|
||||
}
|
||||
],
|
||||
"datasource": {
|
||||
"type": "__expr__",
|
||||
"uid": "-100"
|
||||
},
|
||||
"hide": false,
|
||||
"intervalMs": 1000,
|
||||
"maxDataPoints": 43200,
|
||||
"refId": "B",
|
||||
"type": "classic_conditions"
|
||||
}
|
||||
}
|
||||
],
|
||||
"updated": "2024-08-02T13:19:32.609640048Z",
|
||||
"noDataState": "OK",
|
||||
"execErrState": "OK",
|
||||
"for": "5m",
|
||||
"annotations": {
|
||||
"summary": "test_api_1"
|
||||
},
|
||||
"labels": {
|
||||
"API": "test1"
|
||||
},
|
||||
"provenance": "api",
|
||||
"isPaused": false,
|
||||
"notification_settings": null,
|
||||
"record": null
|
||||
}
|
||||
```
|
||||
|
||||
### Contact points
|
||||
@@ -134,6 +218,34 @@ To manage resources related to [data source-managed alerts]({{< relref "/docs/gr
|
||||
| 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
|
||||
|
||||
[
|
||||
{
|
||||
"uid": "",
|
||||
"name": "email receiver",
|
||||
"type": "email",
|
||||
"settings": {
|
||||
"addresses": "<example@email.com>"
|
||||
},
|
||||
"disableResolveMessage": false
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Notification policies
|
||||
|
||||
| Method | URI | Name | Summary |
|
||||
@@ -143,6 +255,38 @@ To manage resources related to [data source-managed alerts]({{< relref "/docs/gr
|
||||
| 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 |
|
||||
@@ -155,6 +299,38 @@ To manage resources related to [data source-managed alerts]({{< relref "/docs/gr
|
||||
| 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
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
|
||||
[
|
||||
{
|
||||
"name": "weekends",
|
||||
"time_intervals": [
|
||||
{
|
||||
"weekdays": [
|
||||
"saturday",
|
||||
"sunday"
|
||||
]
|
||||
}
|
||||
],
|
||||
"version": "",
|
||||
"provenance": "file"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Templates
|
||||
|
||||
| Method | URI | Name | Summary |
|
||||
@@ -164,7 +340,36 @@ To manage resources related to [data source-managed alerts]({{< relref "/docs/gr
|
||||
| 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. |
|
||||
|
||||
## Edit resources in the Grafana UI
|
||||
**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
|
||||
|
||||
[
|
||||
{
|
||||
"name": "custom_email.message",
|
||||
"template": "{{ define \"custom_email.message\" }}\n Custom alert!\n{{ end }}",
|
||||
"provenance": "file"
|
||||
},
|
||||
{
|
||||
"name": "custom_email.subject",
|
||||
"template": "{{ define \"custom_email.subject\" }}\n{{ len .Alerts.Firing }} firing alert(s), {{ len .Alerts.Resolved }} resolved alert(s)\n{{ end }}",
|
||||
"provenance": "file"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Edit resources in the Grafana UI
|
||||
|
||||
By default, you cannot edit API-provisioned alerting resources in Grafana. To enable editing these resources in the Grafana UI, add the `X-Disable-Provenance` header to the following requests in the API:
|
||||
|
||||
@@ -177,6 +382,14 @@ By default, you cannot edit API-provisioned alerting resources in Grafana. To en
|
||||
|
||||
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_)
|
||||
@@ -216,10 +429,6 @@ Status: No Content
|
||||
DELETE /api/v1/provisioning/contact-points/:uid
|
||||
```
|
||||
|
||||
#### Consumes
|
||||
|
||||
- application/json
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Source | Type | Go type | Separator | Required | Default | Description |
|
||||
@@ -884,10 +1093,6 @@ Status: Not Found
|
||||
POST /api/v1/provisioning/alert-rules
|
||||
```
|
||||
|
||||
#### Consumes
|
||||
|
||||
- application/json
|
||||
|
||||
#### Parameters
|
||||
|
||||
{{% responsive-table %}}
|
||||
@@ -930,10 +1135,6 @@ Status: Bad Request
|
||||
POST /api/v1/provisioning/contact-points
|
||||
```
|
||||
|
||||
#### Consumes
|
||||
|
||||
- application/json
|
||||
|
||||
#### Parameters
|
||||
|
||||
{{% responsive-table %}}
|
||||
@@ -976,10 +1177,6 @@ Status: Bad Request
|
||||
POST /api/v1/provisioning/mute-timings
|
||||
```
|
||||
|
||||
#### Consumes
|
||||
|
||||
- application/json
|
||||
|
||||
#### Parameters
|
||||
|
||||
{{% responsive-table %}}
|
||||
@@ -1022,10 +1219,6 @@ Status: Bad Request
|
||||
PUT /api/v1/provisioning/alert-rules/:uid
|
||||
```
|
||||
|
||||
#### Consumes
|
||||
|
||||
- application/json
|
||||
|
||||
#### Parameters
|
||||
|
||||
{{% responsive-table %}}
|
||||
@@ -1069,10 +1262,6 @@ Status: Bad Request
|
||||
PUT /api/v1/provisioning/folder/:folderUid/rule-groups/:group
|
||||
```
|
||||
|
||||
#### Consumes
|
||||
|
||||
- application/json
|
||||
|
||||
#### Parameters
|
||||
|
||||
{{% responsive-table %}}
|
||||
@@ -1117,10 +1306,6 @@ Status: Bad Request
|
||||
PUT /api/v1/provisioning/contact-points/:uid
|
||||
```
|
||||
|
||||
#### Consumes
|
||||
|
||||
- application/json
|
||||
|
||||
#### Parameters
|
||||
|
||||
{{% responsive-table %}}
|
||||
@@ -1164,10 +1349,6 @@ Status: Bad Request
|
||||
PUT /api/v1/provisioning/mute-timings/:name
|
||||
```
|
||||
|
||||
#### Consumes
|
||||
|
||||
- application/json
|
||||
|
||||
#### Parameters
|
||||
|
||||
{{% responsive-table %}}
|
||||
@@ -1211,10 +1392,6 @@ Status: Bad Request
|
||||
PUT /api/v1/provisioning/policies
|
||||
```
|
||||
|
||||
#### Consumes
|
||||
|
||||
- application/json
|
||||
|
||||
#### Parameters
|
||||
|
||||
{{% responsive-table %}}
|
||||
@@ -1257,10 +1434,6 @@ Status: Bad Request
|
||||
PUT /api/v1/provisioning/templates/:name
|
||||
```
|
||||
|
||||
#### Consumes
|
||||
|
||||
- application/json
|
||||
|
||||
{{% responsive-table %}}
|
||||
|
||||
#### Parameters
|
||||
@@ -1304,10 +1477,6 @@ Status: Bad Request
|
||||
DELETE /api/v1/provisioning/policies
|
||||
```
|
||||
|
||||
#### Consumes
|
||||
|
||||
- application/json
|
||||
|
||||
#### All responses
|
||||
|
||||
| Code | Status | Description | Has headers | Schema |
|
||||
|
||||
Reference in New Issue
Block a user