From 114d87bf615b7cad0823c1bd3fc0398b100a7897 Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Mon, 5 Aug 2024 16:47:48 +0200 Subject: [PATCH] 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> --- .../shared/alerts/alerting_provisioning.md | 305 ++++++++++++++---- 1 file changed, 237 insertions(+), 68 deletions(-) diff --git a/docs/sources/shared/alerts/alerting_provisioning.md b/docs/sources/shared/alerts/alerting_provisioning.md index d8663fdfb47..b516880b53a 100644 --- a/docs/sources/shared/alerts/alerting_provisioning.md +++ b/docs/sources/shared/alerts/alerting_provisioning.md @@ -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//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//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//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": "" + }, + "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//alerting/alerting-rules/create-mimir-loki-managed-rule/), consider the following tools: + +- [mimirtool](https://grafana.com/docs/mimir//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//alert/#lokitool): to configure the Loki Ruler. + ## Paths ### 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 |