From 2c3f9581cf1521e3c1b6163f47009635fca9e998 Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Wed, 6 Mar 2024 10:43:53 +0100 Subject: [PATCH] Backport alerting docs changes to v10.4.x (#83898) * Alerting docs: update Alerting Provisioning (#83376) * Minor updates to Provisioning Index page * Add instructions to export other alerting resources * Edit example provisioning a `template` via config file * Add `Resource` column to the `Export API endpoints` table * Sort the `export` endpoint on the table in `Alerting Provisioning HTTP API` * Minor updates for clarity to `Use configuration files to provision` docs * Add `More examples` in Terraform Provisioning docs * File provisioning: rename `Useful Links` section to `More examples` * Minor grammar change * Update docs/sources/alerting/set-up/provision-alerting-resources/_index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Update docs/sources/alerting/set-up/provision-alerting-resources/_index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Update docs/sources/alerting/set-up/provision-alerting-resources/export-alerting-resources/index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Update docs/sources/alerting/set-up/provision-alerting-resources/export-alerting-resources/index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Update docs/sources/alerting/set-up/provision-alerting-resources/export-alerting-resources/index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Update docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Update docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Update docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Update docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Update docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Update docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Update docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Update docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Update docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Update docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Update docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Update docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Update docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Update docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Update docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Update docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Update docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Address requested changes to `Export` docs * export: Minor grammar change * Update docs/sources/alerting/set-up/provision-alerting-resources/export-alerting-resources/index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * Fix `doc-validator` issue with relative link * Use patch fixed version of doc-validator that better supports docs/reference destinations Signed-off-by: Jack Baldry --------- Signed-off-by: Jack Baldry Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> Co-authored-by: Jack Baldry (cherry picked from commit eb25b669c6a3aca8f5bda80f59762e1b5d6580e5) * Alerting docs: fix incorrect `docs/reference` link (cherry picked from commit c3c6ee4dcaa3ed1770ddf29b417698e19e6c1070) * Alerting docs: document `mute-timings` export endpoints (#83797) (cherry picked from commit 244589d7eac0fa839c74560e9205ccf8da7bcf87) * Alerting docs: improve visibility on the distinct options to edit provisioned resources (#83839) Alerting docs: specify the distinct options to edit provisioned resources (cherry picked from commit 019c9618f051e3819be2a2a5fbfd06a3fa5b3aa6) --- .../provision-alerting-resources/_index.md | 17 ++- .../export-alerting-resources/index.md | 127 +++++++++++++++--- .../file-provisioning/index.md | 99 ++++++++++---- .../terraform-provisioning/index.md | 1 + .../shared/alerts/alerting_provisioning.md | 111 +++++++++++++-- 5 files changed, 289 insertions(+), 66 deletions(-) diff --git a/docs/sources/alerting/set-up/provision-alerting-resources/_index.md b/docs/sources/alerting/set-up/provision-alerting-resources/_index.md index 269d85aea33..7da5fa634c3 100644 --- a/docs/sources/alerting/set-up/provision-alerting-resources/_index.md +++ b/docs/sources/alerting/set-up/provision-alerting-resources/_index.md @@ -33,8 +33,10 @@ Choose from the options below to import (or provision) your Grafana Alerting res 1. [Use configuration files to provision your alerting resources](/docs/grafana//alerting/set-up/provision-alerting-resources/file-provisioning), such as alert rules and contact points, through files on disk. {{< admonition type="note" >}} - File provisioning is not available in Grafana Cloud instances. - {{< /admonition >}} + + - You cannot edit provisioned resources from files in the Grafana UI. + - Provisioning with configuration files is not available in Grafana Cloud. + {{< /admonition >}} 1. Use [Terraform to provision alerting resources][alerting_tf_provisioning]. @@ -42,14 +44,15 @@ Choose from the options below to import (or provision) your Grafana Alerting res {{< admonition type="note" >}} The JSON output from the majority of Alerting HTTP endpoints isn't compatible for provisioning via configuration files. - Instead, use the [Export Alerting endpoints](/docs/grafana//alerting/set-up/provision-alerting-resources/export-alerting-resources#export-api-endpoints) to return or download the alerting resources in provisioning format. + + If you need the alerting resources for file provisioning, use [Export Alerting endpoints](/docs/grafana//alerting/set-up/provision-alerting-resources/export-alerting-resources#export-api-endpoints) to return or download them in provisioning format. {{< /admonition >}} ## Export alerting resources -You can export both manually created and provisioned alerting resources. For more information, refer to [Export alerting resources][alerting_export]. +You can export both manually created and provisioned alerting resources. You can also edit and export an alert rule without applying the changes. -To modify imported alert rules, you can use the **Modify export** feature to edit and then export. +For detailed instructions on the various export options, refer to [Export alerting resources][alerting_export]. ## View provisioned alerting resources @@ -61,10 +64,6 @@ To view your provisioned resources in Grafana, complete the following steps. Provisioned resources are labeled **Provisioned**, so that it is clear that they were not created manually. -**Useful Links:** - -[Grafana provisioning][provisioning] - {{% docs/reference %}} [alerting_tf_provisioning]: "/docs/grafana/ -> /docs/grafana//alerting/set-up/provision-alerting-resources/terraform-provisioning" [alerting_tf_provisioning]: "/docs/grafana-cloud/ -> /docs/grafana//alerting/set-up/provision-alerting-resources/terraform-provisioning" diff --git a/docs/sources/alerting/set-up/provision-alerting-resources/export-alerting-resources/index.md b/docs/sources/alerting/set-up/provision-alerting-resources/export-alerting-resources/index.md index 82c82706ad7..12b06c734bd 100644 --- a/docs/sources/alerting/set-up/provision-alerting-resources/export-alerting-resources/index.md +++ b/docs/sources/alerting/set-up/provision-alerting-resources/export-alerting-resources/index.md @@ -22,9 +22,23 @@ weight: 300 Export your alerting resources, such as alert rules, contact points, and notification policies for provisioning, automatically importing single folders and single groups. +There are distinct methods to export your alerting resources: + +- [Grafana UI](#export-from-the-grafana-ui) exports in Terraform format and YAML or JSON formats for file provisioning. +- [HTTP Alerting API](#http-alerting-api) exports in JSON API format used by the HTTP Alerting API. +- [HTTP Alerting API - Export endpoints](#export-api-endpoints) exports in YAML or JSON formats for file provisioning. + +{{< admonition type="note" >}} +Alerting resources imported through [file provisioning](/docs/grafana//alerting/set-up/provision-alerting-resources/file-provisioning) cannot be edited in the Grafana UI. This prevents changes made in the UI from being overridden by file provisioning during Grafana restarts. + +If you need to modify provisioned alerting resources in Grafana, refer to [edit HTTP API alerting resources in the Grafana UI](/docs/grafana//alerting/set-up/provision-alerting-resources/http-api-provisioning#edit-resources-in-the-grafana-ui) or to [edit Terraform alerting resources in the Grafana UI](/docs/grafana//alerting/set-up/provision-alerting-resources/terraform-provisioning#enable-editing-resources-in-the-grafana-ui). +{{< /admonition >}} + +## Export from the Grafana UI + The export options listed below enable you to download resources in YAML, JSON, or Terraform format, facilitating their provisioning through [configuration files](/docs/grafana//alerting/set-up/provision-alerting-resources/file-provisioning) or [Terraform][alerting_tf_provisioning]. -## Export alert rules +### Export alert rules To export alert rules from the Grafana UI, complete the following steps. @@ -36,20 +50,16 @@ To export alert rules from the Grafana UI, complete the following steps. 1. Find the group you want to export and click the **Export rule group** icon. 1. Choose the format to export in. - The exported rule data appears in different formats - YAML, JSON, Terraform. + The exported alert rule data appears in different formats - YAML, JSON, Terraform. 1. Click **Copy Code** or **Download**. - a. Choose **Copy Code** to go to an existing file and paste in the code. - - b. Choose **Download** to download a file with the exported data. - -## Modify and export alert rules without saving changes - -Use the **Modify export** mode to edit and export an alert rule without updating it. +### Modify alert rule and export rule group without saving changes {{% admonition type="note" %}} This feature is for Grafana-managed alert rules only. It is available to Admin, Viewer, and Editor roles. {{% /admonition %}} +Use the **Modify export** mode to edit and export an alert rule without updating it. The exported data includes all alert rules within the same alert group. + To export a modified alert rule without saving the modifications, complete the following steps from the Grafana UI. 1. Click **Alerts & IRM** -> **Alert rules**. @@ -58,27 +68,89 @@ To export a modified alert rule without saving the modifications, complete the f 1. Click **Export**. 1. Choose the format to export in. - The exported rule data appears in different formats - YAML, JSON, Terraform. + The exported alert rule group appears in different formats - YAML, JSON, Terraform. 1. Click **Copy Code** or **Download**. - a. Choose **Copy Code** to go to an existing file and paste in the code. +### Export contact points - b. Choose **Download** to download a file with the exported data. +To export contact points from the Grafana UI, complete the following steps. -## Export API endpoints +1. Click **Alerts & IRM** -> **Contact points**. +1. Find the contact point you want to export and click **More** -> **Export**. +1. Choose the format to export in. -You can also use the **Alerting provisioning HTTP API** to export alerting resources in YAML or JSON formats for provisioning. + The exported contact point appears in different formats - YAML, JSON, Terraform. -Note that most Alerting endpoints return a JSON format that is not compatible for provisioning via configuration files, except the ones listed below. +1. Click **Copy Code** or **Download**. -| Method | URI | Summary | -| ------ | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -| GET | /api/v1/provisioning/alert-rules/:uid/export | [Export an alert rule in provisioning file format.][export_rule] | -| GET | /api/v1/provisioning/folder/:folderUid/rule-groups/:group/export | [Export an alert rule group in provisioning file format.][export_rule_group] | -| GET | /api/v1/provisioning/alert-rules/export | [Export all alert rules in provisioning file format.][export_rules] | -| GET | /api/v1/provisioning/contact-points/export | [Export all contact points in provisioning file format.][export_contacts] | -| GET | /api/v1/provisioning/policies/export | [Export the notification policy tree in provisioning file format.][export_notifications] | +### Export templates + +Grafana currently doesn't offer an Export UI for notification templates, unlike other Alerting resources presented in this documentation. + +However, you can export it by manually copying the content template and title directly from the Grafana UI. + +1. Click **Alerts & IRM** -> **Contact points** -> **Notification templates** tab. +1. Find the template you want to export. +1. Copy the content and title. +1. Adjust it for the [file provisioning format][alerting_file_provisioning_template] or [Terraform resource][alerting_tf_provisioning_template]. + +### Export the notification policy tree + +All notification policies are provisioned through a single resource: the root of the notification policy tree. + +{{% admonition type="warning" %}} + +Since the policy tree is a single resource, provisioning it will overwrite a policy tree created through any other means. + +{{< /admonition >}} + +To export the notification policy tree from the Grafana UI, complete the following steps. + +1. Click **Alerts & IRM** -> **Notification policies**. +1. In the **Default notification policy** section, click **...** -> **Export**. +1. Choose the format to export in. + + The exported contact point appears in different formats - YAML, JSON, Terraform. + +1. Click **Copy Code** or **Download**. + +### Export mute timings + +To export mute timings from the Grafana UI, complete the following steps. + +1. Click **Alerts & IRM** -> **Notification policies**, and then the **Mute timings** tab. +1. Find the mute timing you want to export and click **Export**. +1. Choose the format to export in. + + The exported contact point appears in different formats - YAML, JSON, Terraform. + +1. Click **Copy Code** or **Download**. + +## HTTP Alerting API + +You can use the [Alerting HTTP API][alerting_http_provisioning] to return existing alerting resources in JSON and import them to another Grafana instance using the same endpoint. For instance: + +| Resource | Method / URI | Summary | +| ----------- | ------------------------------------- | ------------------------ | +| Alert rules | GET /api/v1/provisioning/alert-rules | Get all alert rules. | +| Alert rules | POST /api/v1/provisioning/alert-rules | Create a new alert rule. | + +However, note these Alerting endpoints return a JSON format that is not compatible for provisioning through configuration files or Terraform, except the endpoints listed below. + +### Export API endpoints + +The **Alerting HTTP API** provides specific endpoints for exporting alerting resources in YAML or JSON formats, facilitating [provisioning via configuration files][alerting_file_provisioning]. Currently, Terraform format is not supported. + +| Resource | Method / URI | Summary | +| ------------------------ | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | +| Alert rules | GET /api/v1/provisioning/alert-rules/export | [Export all alert rules in provisioning file format.][export_rules] | +| Alert rules | GET /api/v1/provisioning/folder/:folderUid/rule-groups/:group/export | [Export an alert rule group in provisioning file format.][export_rule_group] | +| Alert rules | GET /api/v1/provisioning/alert-rules/:uid/export | [Export an alert rule in provisioning file format.][export_rule] | +| Contact points | GET /api/v1/provisioning/contact-points/export | [Export all contact points in provisioning file format.][export_contacts] | +| Notification policy tree | GET /api/v1/provisioning/policies/export | [Export the notification policy tree in provisioning file format.][export_notifications] | +| Mute timings | GET /api/v1/provisioning/mute-timings/export | [Export all mute timings in provisioning file format.][export_mute_timings] | +| Mute timings | GET /api/v1/provisioning/mute-timings/:name/export | [Export a mute timing in provisioning file format.][export_mute_timing] | These endpoints accept a `download` parameter to download a file containing the exported resources. @@ -88,9 +160,14 @@ These endpoints accept a `download` parameter to download a file containing the [alerting_tf_provisioning]: "/docs/grafana/ -> /docs/grafana//alerting/set-up/provision-alerting-resources/terraform-provisioning" [alerting_tf_provisioning]: "/docs/grafana-cloud/ -> /docs/grafana//alerting/set-up/provision-alerting-resources/terraform-provisioning" +[alerting_tf_provisioning_template]: "/docs/grafana/ -> /docs/grafana//alerting/set-up/provision-alerting-resources/terraform-provisioning#import-contact-points-and-templates" +[alerting_tf_provisioning_template]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/alerting/set-up/provision-alerting-resources/terraform-provisioning#import-contact-points-and-templates" + [alerting_http_provisioning]: "/docs/grafana/ -> /docs/grafana//alerting/set-up/provision-alerting-resources/http-api-provisioning" [alerting_http_provisioning]: "/docs/grafana-cloud/ -> /docs/grafana//alerting/set-up/provision-alerting-resources/http-api-provisioning" +[alerting_file_provisioning_template]: "/docs/ -> /docs/grafana//alerting/set-up/provision-alerting-resources/file-provisioning#import-templates" + [export_rule]: "/docs/grafana/ -> /docs/grafana//alerting/set-up/provision-alerting-resources/http-api-provisioning/#span-idroute-get-alert-rule-exportspan-export-an-alert-rule-in-provisioning-file-format-_routegetalertruleexport_" [export_rule]: "/docs/grafana-cloud/ -> /docs/grafana//alerting/set-up/provision-alerting-resources/http-api-provisioning/#span-idroute-get-alert-rule-exportspan-export-an-alert-rule-in-provisioning-file-format-_routegetalertruleexport_" @@ -103,6 +180,12 @@ These endpoints accept a `download` parameter to download a file containing the [export_contacts]: "/docs/grafana/ -> /docs/grafana//alerting/set-up/provision-alerting-resources/http-api-provisioning/#span-idroute-get-contactpoints-exportspan-export-all-contact-points-in-provisioning-file-format-_routegetcontactpointsexport_" [export_contacts]: "/docs/grafana-cloud/ -> /docs/grafana//alerting/set-up/provision-alerting-resources/http-api-provisioning/#span-idroute-get-contactpoints-exportspan-export-all-contact-points-in-provisioning-file-format-_routegetcontactpointsexport_" +[export_mute_timing]: "/docs/grafana/ -> /docs/grafana//alerting/set-up/provision-alerting-resources/http-api-provisioning/#span-idroute-get-mute-timing-exportspan-export-a-mute-timing-in-provisioning-file-format-_routegetmutetimingexport_" +[export_mute_timing]: "/docs/grafana-cloud/ -> /docs/grafana//alerting/set-up/provision-alerting-resources/http-api-provisioning/#span-idroute-get-mute-timing-exportspan-export-a-mute-timing-in-provisioning-file-format-_routegetmutetimingexport_" + +[export_mute_timings]: "/docs/grafana/ -> /docs/grafana//alerting/set-up/provision-alerting-resources/http-api-provisioning/#span-idroute-get-mute-timings-exportspan-export-all-mute-timings-in-provisioning-file-format-_routegetmutetimingsexport_" +[export_mute_timings]: "/docs/grafana-cloud/ -> /docs/grafana//alerting/set-up/provision-alerting-resources/http-api-provisioning/#span-idroute-get-mute-timings-exportspan-export-all-mute-timings-in-provisioning-file-format-_routegetmutetimingsexport_" + [export_notifications]: "/docs/grafana/ -> /docs/grafana//alerting/set-up/provision-alerting-resources/http-api-provisioning/#span-idroute-get-policy-tree-exportspan-export-the-notification-policy-tree-in-provisioning-file-format-_routegetpolicytreeexport_" [export_notifications]: "/docs/grafana-cloud/ -> /docs/grafana//alerting/set-up/provision-alerting-resources/http-api-provisioning/#span-idroute-get-policy-tree-exportspan-export-the-notification-policy-tree-in-provisioning-file-format-_routegetpolicytreeexport_" {{% /docs/reference %}} diff --git a/docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md b/docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md index 22066714f5f..7d810107226 100644 --- a/docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md +++ b/docs/sources/alerting/set-up/provision-alerting-resources/file-provisioning/index.md @@ -30,24 +30,26 @@ For a complete guide about how Grafana provisions resources, refer to the [Provi {{< admonition type="note" >}} +- Provisioning with configuration files is not available in Grafana Cloud. + - You cannot edit provisioned resources from files in Grafana. You can only change the resource properties by changing the provisioning file and restarting Grafana or carrying out a hot reload. This prevents changes being made to the resource that would be overwritten if a file is provisioned again or a hot reload is carried out. -- Importing takes place during the initial set up of your Grafana system, but you can re-run it at any time using the [Grafana Admin API](/docs/grafana//developers/http_api/admin#reload-provisioning-configurations). +- Provisioning using configuration files takes place during the initial set up of your Grafana system, but you can re-run it at any time using the [Grafana Admin API](/docs/grafana//developers/http_api/admin#reload-provisioning-configurations). - Importing an existing alerting resource results in a conflict. First, when present, remove the resources you plan to import. {{< /admonition >}} ## Import alert rules -Create or delete alert rules in your Grafana instance(s). +Create or delete alert rules using provisioning files in your Grafana instance(s). -1. Create alert rules in Grafana. +1. Find the alert rule group in Grafana. 1. [Export][alerting_export] and download a provisioning file for your alert rules. -1. Copy the contents into a YAML or JSON configuration file in the `provisioning/alerting` directory. +1. Copy the contents into a YAML or JSON configuration file and add it to the `provisioning/alerting` directory of the Grafana instance you want to import the alerting resources to. Example configuration files can be found below. -1. Add the file(s) to your GitOps workflow, so that they deploy alongside your Grafana instance(s). +1. Restart your Grafana instance (or reload the provisioned files using the Admin API). Here is an example of a configuration file for creating alert rules. @@ -138,15 +140,15 @@ deleteRules: ## Import contact points -Create or delete contact points in your Grafana instance(s). +Create or delete contact points using provisioning files in your Grafana instance(s). -1. Create a contact point in Grafana. +1. Find the contact point in Grafana. 1. [Export][alerting_export] and download a provisioning file for your contact point. -1. Copy the contents into a YAML or JSON configuration file in the `provisioning/alerting` directory. +1. Copy the contents into a YAML or JSON configuration file and add it to the `provisioning/alerting` directory of the Grafana instance you want to import the alerting resources to. Example configuration files can be found below. -1. Add the file(s) to your GitOps workflow, so that they deploy alongside your Grafana instance(s). +1. Restart your Grafana instance (or reload the provisioned files using the Admin API). Here is an example of a configuration file for creating contact points. @@ -569,9 +571,54 @@ settings: {{< /collapse >}} +## Import templates + +Create or delete templates using provisioning files in your Grafana instance(s). + +1. Find the notification template in Grafana. +1. [Export][alerting_export] a template by copying the template content and title. +1. Copy the contents into a YAML or JSON configuration file and add it to the `provisioning/alerting` directory of the Grafana instance you want to import the alerting resources to. + + Example configuration files can be found below. + +1. Restart your Grafana instance (or reload the provisioned files using the Admin API). + +Here is an example of a configuration file for creating templates. + +```yaml +# config file version +apiVersion: 1 + +# List of templates to import or update +templates: + # organization ID, default = 1 + - orgId: 1 + # name of the template, must be unique + name: my_first_template + # content of the the template + template: | + {{ define "my_first_template" }} + Custom notification message + {{ end }} +``` + +Here is an example of a configuration file for deleting templates. + +```yaml +# config file version +apiVersion: 1 + +# List of alert rule UIDs that should be deleted +deleteTemplates: + # organization ID, default = 1 + - orgId: 1 + # name of the template, must be unique + name: my_first_template +``` + ## Import notification policies -Create or reset the notification policy tree in your Grafana instance(s). +Create or reset the notification policy tree using provisioning files in your Grafana instance(s). In Grafana, the entire notification policy tree is considered a single, large resource. Add new specific policies as sub-policies under the root policy. Since specific policies may depend on each other, you cannot provision subsets of the policy tree; the entire tree must be defined in a single place. @@ -581,13 +628,13 @@ Since the policy tree is a single resource, provisioning it will overwrite a pol {{< /admonition >}} -1. Create a notification policy in Grafana. -1. [Export][alerting_export] and download a provisioning file for your notification policy. -1. Copy the contents into a YAML or JSON configuration file in the `provisioning/alerting` directory. +1. Find the notification policy tree in Grafana. +1. [Export][alerting_export] and download a provisioning file for your notification policy tree. +1. Copy the contents into a YAML or JSON configuration file and add it to the `provisioning/alerting` directory of the Grafana instance you want to import the alerting resources to. Example configuration files can be found below. -1. Add the file(s) to your GitOps workflow, so that they deploy alongside your Grafana instance(s). +1. Restart your Grafana instance (or reload the provisioned files using the Admin API). Here is an example of a configuration file for creating notification policies. @@ -705,13 +752,15 @@ deleteTemplates: ## Import mute timings -Create or delete mute timings in your Grafana instance(s). +Create or delete mute timings via provisioning files using provisioning files in your Grafana instance(s). -1. Create a YAML or JSON configuration file. +1. Find the mute timing in Grafana. +1. [Export][alerting_export] and download a provisioning file for your mute timing. +1. Copy the contents into a YAML or JSON configuration file and add it to the `provisioning/alerting` directory of the Grafana instance you want to import the alerting resources to. Example configuration files can be found below. -1. Add the file(s) to your GitOps workflow, so that they deploy alongside your Grafana instance(s). +1. Restart your Grafana instance (or reload the provisioned files using the Admin API). Here is an example of a configuration file for creating mute timings. @@ -770,7 +819,7 @@ If you are a Kubernetes user, you can leverage file provisioning using Kubernete template: the content for my template ``` -1. Add the file(s) to your GitOps workflow, so that they deploy alongside your Grafana instance(s). +1. Restart your Grafana instance (or reload the provisioned files using the Admin API). ```yaml apiVersion: apps/v1 @@ -807,13 +856,17 @@ If you are a Kubernetes user, you can leverage file provisioning using Kubernete This eliminates the need for a persistent database to use Grafana Alerting in Kubernetes; all your provisioned resources appear after each restart or re-deployment. Grafana still requires a database for normal operation, you do not need to persist the contents of the database between restarts if all objects are provisioned using files. -**Useful Links:** +## More examples -[Grafana provisioning][provisioning] +- [Provision Grafana][provisioning] {{% docs/reference %}} + [alerting_export]: "/docs/grafana/ -> /docs/grafana//alerting/set-up/provision-alerting-resources/export-alerting-resources" -[alerting_export]: "/docs/grafana-cloud/ -> /docs/grafana//alerting/set-up/provision-alerting-resources/export-alerting-resources" -[provisioning]: "/docs/grafana/ -> /docs/grafana//administration/provisioning" -[provisioning]: "/docs/grafana-cloud/ -> /docs/grafana//administration/provisioning" +[alerting_export]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/alerting/set-up/provision-alerting-resources/export-alerting-resources" + +[provisioning]: "/docs/ -> /docs/grafana//administration/provisioning" + +[reload-provisioning-configurations]: "/docs/ -> /docs/grafana//developers/http_api/admin#reload-provisioning-configurations" + {{% /docs/reference %}} diff --git a/docs/sources/alerting/set-up/provision-alerting-resources/terraform-provisioning/index.md b/docs/sources/alerting/set-up/provision-alerting-resources/terraform-provisioning/index.md index 488ca0864d3..c215c625ace 100644 --- a/docs/sources/alerting/set-up/provision-alerting-resources/terraform-provisioning/index.md +++ b/docs/sources/alerting/set-up/provision-alerting-resources/terraform-provisioning/index.md @@ -389,6 +389,7 @@ For more examples on the concept of this guide: - Review the [tutorial to manage a Grafana Cloud stack using Terraform][provision-cloud-with-terraform]. {{% docs/reference %}} + [alerting-rules]: "/docs/grafana/ -> /docs/grafana//alerting/alerting-rules" [alerting-rules]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/alerting/alerting-rules" diff --git a/docs/sources/shared/alerts/alerting_provisioning.md b/docs/sources/shared/alerts/alerting_provisioning.md index 7be0b2d010c..eb7df8a9cac 100644 --- a/docs/sources/shared/alerts/alerting_provisioning.md +++ b/docs/sources/shared/alerts/alerting_provisioning.md @@ -36,14 +36,14 @@ For managing resources related to [data source-managed alerts]({{< relref "/docs | ------ | ---------------------------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------- | | DELETE | /api/v1/provisioning/alert-rules/:uid | [route delete alert rule](#route-delete-alert-rule) | Delete a specific alert rule by UID. | | GET | /api/v1/provisioning/alert-rules/:uid | [route get alert rule](#route-get-alert-rule) | Get a specific alert rule by UID. | +| POST | /api/v1/provisioning/alert-rules | [route post alert rule](#route-post-alert-rule) | Create a new alert rule. | +| PUT | /api/v1/provisioning/alert-rules/:uid | [route put alert rule](#route-put-alert-rule) | Update an existing alert rule. | | GET | /api/v1/provisioning/alert-rules/:uid/export | [route get alert rule export](#route-get-alert-rule-export) | Export an alert rule in provisioning file format. | | GET | /api/v1/provisioning/folder/:folderUid/rule-groups/:group | [route get alert rule group](#route-get-alert-rule-group) | Get a rule group. | +| PUT | /api/v1/provisioning/folder/:folderUid/rule-groups/:group | [route put alert rule group](#route-put-alert-rule-group) | Update the interval of a rule group or modify the rules of the group. | | GET | /api/v1/provisioning/folder/:folderUid/rule-groups/:group/export | [route get alert rule group export](#route-get-alert-rule-group-export) | Export an alert rule group in provisioning file format. | | 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. | -| POST | /api/v1/provisioning/alert-rules | [route post alert rule](#route-post-alert-rule) | Create a new alert rule. | -| PUT | /api/v1/provisioning/alert-rules/:uid | [route put alert rule](#route-put-alert-rule) | Update an existing alert rule. | -| PUT | /api/v1/provisioning/folder/:folderUid/rule-groups/:group | [route put alert rule group](#route-put-alert-rule-group) | Update the interval of a rule group or modify the rules of the group. | #### Example alert rules template @@ -130,9 +130,9 @@ For managing resources related to [data source-managed alerts]({{< relref "/docs | ------ | ------------------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------ | | 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. | -| GET | /api/v1/provisioning/contact-points/export | [route get contactpoints export](#route-get-contactpoints-export) | Export all contact points in provisioning file format. | | 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. | ### Notification policies @@ -140,18 +140,20 @@ For managing resources related to [data source-managed alerts]({{< relref "/docs | ------ | ------------------------------------ | ------------------------------------------------------------- | ---------------------------------------------------------------- | | 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. | -| 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. | | 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. | ### 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. | +| 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. | ### Templates @@ -631,6 +633,83 @@ Status: OK [MuteTimings](#mute-timings) +### Export all mute timings in provisioning file format. (_RouteGetMuteTimingsExport_) + +``` +GET /api/v1/provisioning/mute-timings/export +``` + +#### Parameters + +| Name | Source | Type | Go type | Separator | Required | Default | Description | +| -------- | ------- | ------- | -------- | --------- | :------: | -------- | --------------------------------------------------------------------------------------------------------------------------------- | +| download | `query` | boolean | `bool` | | | | Whether to initiate a download of the file or not. | +| format | `query` | string | `string` | | | `"yaml"` | Format of the downloaded file, either yaml or json. Accept header can also be used, but the query parameter will take precedence. | + +#### All responses + +| Code | Status | Description | Has headers | Schema | +| ----------------------------------------- | --------- | ----------------- | :---------: | --------------------------------------------------- | +| [200](#route-get-mute-timings-export-200) | OK | MuteTimingsExport | | [schema](#route-get-mute-timings-export-200-schema) | +| [403](#route-get-mute-timings-export-403) | Forbidden | PermissionDenied | | [schema](#route-get-mute-timings-export-403-schema) | + +#### Responses + +##### 200 - MuteTimingsExport + +Status: OK + +###### Schema + +[AlertingFileExport](#alerting-file-export) + +##### 403 - PermissionDenied + +Status: Forbidden + +###### Schema + +[PermissionDenied](#permission-denied) + +### Export a mute timing in provisioning file format. (_RouteGetMuteTimingExport_) + +``` +GET /api/v1/provisioning/mute-timings/:name/export +``` + +#### Parameters + +| Name | Source | Type | Go type | Separator | Required | Default | Description | +| -------- | ------- | ------- | -------- | --------- | :------: | -------- | --------------------------------------------------------------------------------------------------------------------------------- | +| name | `path` | string | `string` | | ✓ | | Mute timing name. | +| download | `query` | boolean | `bool` | | | | Whether to initiate a download of the file or not. | +| format | `query` | string | `string` | | | `"yaml"` | Format of the downloaded file, either yaml or json. Accept header can also be used, but the query parameter will take precedence. | + +#### All responses + +| Code | Status | Description | Has headers | Schema | +| ---------------------------------------- | --------- | ---------------- | :---------: | --------------------------------------------------- | +| [200](#route-get-mute-timing-export-200) | OK | MuteTimingExport | | [schema](#route-get-mute-timings-export-200-schema) | +| [403](#route-get-mute-timing-export-403) | Forbidden | PermissionDenied | | [schema](#route-get-mute-timings-export-403-schema) | + +#### Responses + +##### 200 - MuteTimingExport + +Status: OK + +###### Schema + +[AlertingFileExport](#alerting-file-export) + +##### 403 - PermissionDenied + +Status: Forbidden + +###### Schema + +[PermissionDenied](#permission-denied) + ### Get the notification policy tree. (_RouteGetPolicyTree_) ``` @@ -1393,6 +1472,14 @@ Status: Accepted {{% /responsive-table %}} +### MuteTimingExport + +**Properties** + +### MuteTimingsExport + +**Properties** + ### MuteTimings [][MuteTimeInterval](#mute-time-interval)