Alerting: improve provisioning docs (#50347)

* Alerting: improve provisioning docs

* add new provisioning page

* add api docs

* fix formatting and add better descriptions

* fix typo

docs/sources/developers/http_api/_index.md

@@ -22,8 +22,7 @@ dashboards, creating users, and updating data sources.
 ## HTTP APIs
 
 - [Admin API]({{< relref "admin/" >}})
-- [Alerting Notification Channels API]({{< relref "alerting_notification_channels/" >}})
+- [Alerting Provisioning API]({{< relref "alerting_provisioning/" >}})
-- [Alerting API]({{< relref "alerting/" >}})
 - [Annotations API]({{< relref "annotations/" >}})
 - [Authentication API]({{< relref "auth/" >}})
 - [Dashboard API]({{< relref "dashboard/" >}})
@@ -43,6 +42,11 @@ dashboards, creating users, and updating data sources.
 - [Team API]({{< relref "team/" >}})
 - [User API]({{< relref "user/" >}})
 
+## Deprecated HTTP APIs
+
+- [Alerting Notification Channels API]({{< relref "alerting_notification_channels/" >}})
+- [Alerting API]({{< relref "alerting/" >}})
+
 ## Grafana Enterprise HTTP APIs
 
 Grafana Enterprise includes all of the Grafana OSS APIs as well as those that follow:

pkg/services/ngalert/api/tooling/definitions/provisioning_alert_rules.go

@@ -56,18 +56,40 @@ type AlertRulePayload struct {
 type AlertRule struct {
 	ID  int64  `json:"id"`
 	UID string `json:"uid"`
+	// required: true
 	OrgID int64 `json:"orgID"`
+	// required: true
+	// example: project_x
 	FolderUID string `json:"folderUID"`
+	// required: true
+	// minLength: 1
+	// maxLength: 190
+	// example: eval_group_1
 	RuleGroup string `json:"ruleGroup"`
+	// required: true
+	// minLength: 1
+	// maxLength: 190
+	// example: Always firing
 	Title string `json:"title"`
+	// required: true
+	// example: A
 	Condition string `json:"condition"`
+	// required: true
+	// example: [{"refId":"A","queryType":"","relativeTimeRange":{"from":0,"to":0},"datasourceUid":"-100","model":{"conditions":[{"evaluator":{"params":[0,0],"type":"gt"},"operator":{"type":"and"},"query":{"params":[]},"reducer":{"params":[],"type":"avg"},"type":"query"}],"datasource":{"type":"__expr__","uid":"__expr__"},"expression":"1 == 1","hide":false,"intervalMs":1000,"maxDataPoints":43200,"refId":"A","type":"math"}}]
 	Data []models.AlertQuery `json:"data"`
+	// readonly: true
 	Updated time.Time `json:"updated,omitempty"`
+	// required: true
 	NoDataState models.NoDataState `json:"noDataState"`
+	// required: true
 	ExecErrState models.ExecutionErrorState `json:"execErrState"`
+	// required: true
 	For time.Duration `json:"for"`
+	// example: {"runbook_url": "https://supercoolrunbook.com/page/13"}
 	Annotations map[string]string `json:"annotations,omitempty"`
+	// example: {"team": "sre-team-1"}
 	Labels map[string]string `json:"labels,omitempty"`
+	// readonly: true
 	Provenance models.Provenance `json:"provenance,omitempty"`
 }
 

pkg/services/ngalert/api/tooling/definitions/provisioning_contactpoints.go

@@ -50,7 +50,7 @@ import (
 
 // swagger:parameters RoutePutContactpoint RouteDeleteContactpoints
 type ContactPointUIDReference struct {
-	// ContactPointUID should be the contact point UID identifier
+	// UID should be the contact point unique identifier
 	// in:path
 	UID string
 }
@@ -64,16 +64,24 @@ type ContactPointPayload struct {
 // EmbeddedContactPoint is the contact point type that is used
 // by grafanas embedded alertmanager implementation.
 type EmbeddedContactPoint struct {
-	// UID is the unique identifier of the contact point. This will be
+	// UID is the unique identifier of the contact point. The UID can be
-	// automatically set be the Grafana.
+	// set by the user.
+	// example: my_external_reference
 	UID string `json:"uid"`
 	// Name is used as grouping key in the UI. Contact points with the
 	// same name will be grouped in the UI.
+	// example: webhook_1
 	Name string `json:"name" binding:"required"`
+	// required: true
+	// example: webhook
+	// enum: alertmanager, dingding, discord, email, googlechat, kafka, line, opsgenie, pagerduty, pushover, sensugo, slack, teams, telegram, threema, victorops, webhook, wecom
 	Type string `json:"type" binding:"required"`
+	// required: true
 	Settings *simplejson.Json `json:"settings" binding:"required"`
+	// example: false
 	DisableResolveMessage bool `json:"disableResolveMessage"`
-	Provenance            string           `json:"provenance"`
+	// readonly: true
+	Provenance string `json:"provenance,omitempty"`
 }
 
 const RedactedValue = "[REDACTED]"

pkg/services/ngalert/api/tooling/post.json

@@ -200,14 +200,63 @@
      "additionalProperties": {
       "type": "string"
      },
+     "example": {
+      "runbook_url": "https://supercoolrunbook.com/page/13"
+     },
      "type": "object",
      "x-go-name": "Annotations"
     },
     "condition": {
+     "example": "A",
      "type": "string",
      "x-go-name": "Condition"
     },
     "data": {
+     "example": [
+      {
+       "datasourceUid": "-100",
+       "model": {
+        "conditions": [
+         {
+          "evaluator": {
+           "params": [
+            0,
+            0
+           ],
+           "type": "gt"
+          },
+          "operator": {
+           "type": "and"
+          },
+          "query": {
+           "params": []
+          },
+          "reducer": {
+           "params": [],
+           "type": "avg"
+          },
+          "type": "query"
+         }
+        ],
+        "datasource": {
+         "type": "__expr__",
+         "uid": "__expr__"
+        },
+        "expression": "1 == 1",
+        "hide": false,
+        "intervalMs": 1000,
+        "maxDataPoints": 43200,
+        "refId": "A",
+        "type": "math"
+       },
+       "queryType": "",
+       "refId": "A",
+       "relativeTimeRange": {
+        "from": 0,
+        "to": 0
+       }
+      }
+     ],
      "items": {
       "$ref": "#/definitions/AlertQuery"
      },
@@ -215,9 +264,18 @@
      "x-go-name": "Data"
     },
     "execErrState": {
-     "$ref": "#/definitions/ExecutionErrorState"
+     "description": "\nAlerting AlertingErrState\nError ErrorErrState\nOK OkErrState",
+     "enum": [
+      "Alerting",
+      "Error",
+      "OK"
+     ],
+     "type": "string",
+     "x-go-enum-desc": "Alerting AlertingErrState\nError ErrorErrState\nOK OkErrState",
+     "x-go-name": "ExecErrState"
     },
     "folderUID": {
+     "example": "project_x",
      "type": "string",
      "x-go-name": "FolderUID"
     },
@@ -233,11 +291,22 @@
      "additionalProperties": {
       "type": "string"
      },
+     "example": {
+      "team": "sre-team-1"
+     },
      "type": "object",
      "x-go-name": "Labels"
     },
     "noDataState": {
-     "$ref": "#/definitions/NoDataState"
+     "description": "\nAlerting Alerting\nNoData NoData\nOK OK",
+     "enum": [
+      "Alerting",
+      "NoData",
+      "OK"
+     ],
+     "type": "string",
+     "x-go-enum-desc": "Alerting Alerting\nNoData NoData\nOK OK",
+     "x-go-name": "NoDataState"
     },
     "orgID": {
      "format": "int64",
@@ -248,10 +317,16 @@
      "$ref": "#/definitions/Provenance"
     },
     "ruleGroup": {
+     "example": "eval_group_1",
+     "maxLength": 190,
+     "minLength": 1,
      "type": "string",
      "x-go-name": "RuleGroup"
     },
     "title": {
+     "example": "Always firing",
+     "maxLength": 190,
+     "minLength": 1,
      "type": "string",
      "x-go-name": "Title"
     },
@@ -261,10 +336,22 @@
     },
     "updated": {
      "format": "date-time",
+     "readOnly": true,
      "type": "string",
      "x-go-name": "Updated"
     }
    },
+   "required": [
+    "orgID",
+    "folderUID",
+    "ruleGroup",
+    "title",
+    "condition",
+    "data",
+    "noDataState",
+    "execErrState",
+    "for"
+   ],
    "type": "object",
    "x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/api/tooling/definitions"
   },
@@ -673,15 +760,18 @@
    "description": "EmbeddedContactPoint is the contact point type that is used\nby grafanas embedded alertmanager implementation.",
    "properties": {
     "disableResolveMessage": {
+     "example": false,
      "type": "boolean",
      "x-go-name": "DisableResolveMessage"
     },
     "name": {
      "description": "Name is used as grouping key in the UI. Contact points with the\nsame name will be grouped in the UI.",
+     "example": "webhook_1",
      "type": "string",
      "x-go-name": "Name"
     },
     "provenance": {
+     "readOnly": true,
      "type": "string",
      "x-go-name": "Provenance"
     },
@@ -689,15 +779,41 @@
      "$ref": "#/definitions/Json"
     },
     "type": {
+     "enum": [
+      "alertmanager",
+      " dingding",
+      " discord",
+      " email",
+      " googlechat",
+      " kafka",
+      " line",
+      " opsgenie",
+      " pagerduty",
+      " pushover",
+      " sensugo",
+      " slack",
+      " teams",
+      " telegram",
+      " threema",
+      " victorops",
+      " webhook",
+      " wecom"
+     ],
+     "example": "webhook",
      "type": "string",
      "x-go-name": "Type"
     },
     "uid": {
-     "description": "UID is the unique identifier of the contact point. This will be\nautomatically set be the Grafana.",
+     "description": "UID is the unique identifier of the contact point. The UID can be\nset by the user.",
+     "example": "my_external_reference",
      "type": "string",
      "x-go-name": "UID"
     }
    },
+   "required": [
+    "type",
+    "settings"
+   ],
    "type": "object",
    "x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/api/tooling/definitions"
   },
@@ -748,10 +864,6 @@
    "x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/api/tooling/definitions"
   },
   "EvalQueriesResponse": {},
-  "ExecutionErrorState": {
-   "type": "string",
-   "x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/models"
-  },
   "ExtendedReceiver": {
    "properties": {
     "email_configs": {
@@ -1552,10 +1664,6 @@
    "type": "object",
    "x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/api/tooling/definitions"
   },
-  "NoDataState": {
-   "type": "string",
-   "x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/models"
-  },
   "NotFound": {
    "type": "object",
    "x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/api/tooling/definitions"
@@ -3255,7 +3363,6 @@
    "x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
   },
   "alertGroup": {
-   "description": "AlertGroup alert group",
    "properties": {
     "alerts": {
      "description": "alerts",
@@ -3277,7 +3384,9 @@
     "labels",
     "receiver"
    ],
-   "type": "object"
+   "type": "object",
+   "x-go-name": "AlertGroup",
+   "x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
   },
   "alertGroups": {
    "description": "AlertGroups alert groups",
@@ -3530,12 +3639,11 @@
    "x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
   },
   "gettableSilences": {
+   "description": "GettableSilences gettable silences",
    "items": {
     "$ref": "#/definitions/gettableSilence"
    },
-   "type": "array",
+   "type": "array"
-   "x-go-name": "GettableSilences",
-   "x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
   },
   "labelSet": {
    "additionalProperties": {
@@ -3664,6 +3772,7 @@
    "x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
   },
   "postableSilence": {
+   "description": "PostableSilence postable silence",
    "properties": {
     "comment": {
      "description": "comment",
@@ -3703,9 +3812,7 @@
     "matchers",
     "startsAt"
    ],
-   "type": "object",
+   "type": "object"
-   "x-go-name": "PostableSilence",
-   "x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
   },
   "receiver": {
    "properties": {
@@ -5676,7 +5783,7 @@
     "operationId": "RouteDeleteContactpoints",
     "parameters": [
      {
-      "description": "ContactPointUID should be the contact point UID identifier",
+      "description": "UID should be the contact point unique identifier",
       "in": "path",
       "name": "UID",
       "required": true,
@@ -5709,7 +5816,7 @@
     "operationId": "RoutePutContactpoint",
     "parameters": [
      {
-      "description": "ContactPointUID should be the contact point UID identifier",
+      "description": "UID should be the contact point unique identifier",
       "in": "path",
       "name": "UID",
       "required": true,

pkg/services/ngalert/api/tooling/spec.json

@@ -1871,7 +1871,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "ContactPointUID should be the contact point UID identifier",
+            "description": "UID should be the contact point unique identifier",
             "name": "UID",
             "in": "path",
             "required": true
@@ -1912,7 +1912,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "ContactPointUID should be the contact point UID identifier",
+            "description": "UID should be the contact point unique identifier",
             "name": "UID",
             "in": "path",
             "required": true
@@ -2591,31 +2591,100 @@
     },
     "AlertRule": {
       "type": "object",
+      "required": [
+        "orgID",
+        "folderUID",
+        "ruleGroup",
+        "title",
+        "condition",
+        "data",
+        "noDataState",
+        "execErrState",
+        "for"
+      ],
       "properties": {
         "annotations": {
           "type": "object",
           "additionalProperties": {
             "type": "string"
           },
-          "x-go-name": "Annotations"
+          "x-go-name": "Annotations",
+          "example": {
+            "runbook_url": "https://supercoolrunbook.com/page/13"
+          }
         },
         "condition": {
           "type": "string",
-          "x-go-name": "Condition"
+          "x-go-name": "Condition",
+          "example": "A"
         },
         "data": {
           "type": "array",
           "items": {
             "$ref": "#/definitions/AlertQuery"
           },
-          "x-go-name": "Data"
+          "x-go-name": "Data",
+          "example": [
+            {
+              "datasourceUid": "-100",
+              "model": {
+                "conditions": [
+                  {
+                    "evaluator": {
+                      "params": [
+                        0,
+                        0
+                      ],
+                      "type": "gt"
+                    },
+                    "operator": {
+                      "type": "and"
+                    },
+                    "query": {
+                      "params": []
+                    },
+                    "reducer": {
+                      "params": [],
+                      "type": "avg"
+                    },
+                    "type": "query"
+                  }
+                ],
+                "datasource": {
+                  "type": "__expr__",
+                  "uid": "__expr__"
+                },
+                "expression": "1 == 1",
+                "hide": false,
+                "intervalMs": 1000,
+                "maxDataPoints": 43200,
+                "refId": "A",
+                "type": "math"
+              },
+              "queryType": "",
+              "refId": "A",
+              "relativeTimeRange": {
+                "from": 0,
+                "to": 0
+              }
+            }
+          ]
         },
         "execErrState": {
-          "$ref": "#/definitions/ExecutionErrorState"
+          "description": "\nAlerting AlertingErrState\nError ErrorErrState\nOK OkErrState",
+          "type": "string",
+          "enum": [
+            "Alerting",
+            "Error",
+            "OK"
+          ],
+          "x-go-enum-desc": "Alerting AlertingErrState\nError ErrorErrState\nOK OkErrState",
+          "x-go-name": "ExecErrState"
         },
         "folderUID": {
           "type": "string",
-          "x-go-name": "FolderUID"
+          "x-go-name": "FolderUID",
+          "example": "project_x"
         },
         "for": {
           "$ref": "#/definitions/Duration"
@@ -2630,10 +2699,21 @@
           "additionalProperties": {
             "type": "string"
           },
-          "x-go-name": "Labels"
+          "x-go-name": "Labels",
+          "example": {
+            "team": "sre-team-1"
+          }
         },
         "noDataState": {
-          "$ref": "#/definitions/NoDataState"
+          "description": "\nAlerting Alerting\nNoData NoData\nOK OK",
+          "type": "string",
+          "enum": [
+            "Alerting",
+            "NoData",
+            "OK"
+          ],
+          "x-go-enum-desc": "Alerting Alerting\nNoData NoData\nOK OK",
+          "x-go-name": "NoDataState"
         },
         "orgID": {
           "type": "integer",
@@ -2645,11 +2725,17 @@
         },
         "ruleGroup": {
           "type": "string",
-          "x-go-name": "RuleGroup"
+          "maxLength": 190,
+          "minLength": 1,
+          "x-go-name": "RuleGroup",
+          "example": "eval_group_1"
         },
         "title": {
           "type": "string",
-          "x-go-name": "Title"
+          "maxLength": 190,
+          "minLength": 1,
+          "x-go-name": "Title",
+          "example": "Always firing"
         },
         "uid": {
           "type": "string",
@@ -2658,7 +2744,8 @@
         "updated": {
           "type": "string",
           "format": "date-time",
-          "x-go-name": "Updated"
+          "x-go-name": "Updated",
+          "readOnly": true
         }
       },
       "x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/api/tooling/definitions"
@@ -3068,31 +3155,60 @@
     "EmbeddedContactPoint": {
       "description": "EmbeddedContactPoint is the contact point type that is used\nby grafanas embedded alertmanager implementation.",
       "type": "object",
+      "required": [
+        "type",
+        "settings"
+      ],
       "properties": {
         "disableResolveMessage": {
           "type": "boolean",
-          "x-go-name": "DisableResolveMessage"
+          "x-go-name": "DisableResolveMessage",
+          "example": false
         },
         "name": {
           "description": "Name is used as grouping key in the UI. Contact points with the\nsame name will be grouped in the UI.",
           "type": "string",
-          "x-go-name": "Name"
+          "x-go-name": "Name",
+          "example": "webhook_1"
         },
         "provenance": {
           "type": "string",
-          "x-go-name": "Provenance"
+          "x-go-name": "Provenance",
+          "readOnly": true
         },
         "settings": {
           "$ref": "#/definitions/Json"
         },
         "type": {
           "type": "string",
-          "x-go-name": "Type"
+          "enum": [
+            "alertmanager",
+            " dingding",
+            " discord",
+            " email",
+            " googlechat",
+            " kafka",
+            " line",
+            " opsgenie",
+            " pagerduty",
+            " pushover",
+            " sensugo",
+            " slack",
+            " teams",
+            " telegram",
+            " threema",
+            " victorops",
+            " webhook",
+            " wecom"
+          ],
+          "x-go-name": "Type",
+          "example": "webhook"
         },
         "uid": {
-          "description": "UID is the unique identifier of the contact point. This will be\nautomatically set be the Grafana.",
+          "description": "UID is the unique identifier of the contact point. The UID can be\nset by the user.",
           "type": "string",
-          "x-go-name": "UID"
+          "x-go-name": "UID",
+          "example": "my_external_reference"
         }
       },
       "x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/api/tooling/definitions"
@@ -3146,10 +3262,6 @@
     "EvalQueriesResponse": {
       "$ref": "#/definitions/EvalQueriesResponse"
     },
-    "ExecutionErrorState": {
-      "type": "string",
-      "x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/models"
-    },
     "ExtendedReceiver": {
       "type": "object",
       "properties": {
@@ -3951,10 +4063,6 @@
       },
       "x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/api/tooling/definitions"
     },
-    "NoDataState": {
-      "type": "string",
-      "x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/models"
-    },
     "NotFound": {
       "type": "object",
       "x-go-package": "github.com/grafana/grafana/pkg/services/ngalert/api/tooling/definitions"
@@ -5654,7 +5762,6 @@
       "x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
     },
     "alertGroup": {
-      "description": "AlertGroup alert group",
       "type": "object",
       "required": [
         "alerts",
@@ -5677,6 +5784,8 @@
           "$ref": "#/definitions/receiver"
         }
       },
+      "x-go-name": "AlertGroup",
+      "x-go-package": "github.com/prometheus/alertmanager/api/v2/models",
       "$ref": "#/definitions/alertGroup"
     },
     "alertGroups": {
@@ -5934,12 +6043,11 @@
       "$ref": "#/definitions/gettableSilence"
     },
     "gettableSilences": {
+      "description": "GettableSilences gettable silences",
       "type": "array",
       "items": {
         "$ref": "#/definitions/gettableSilence"
       },
-      "x-go-name": "GettableSilences",
-      "x-go-package": "github.com/prometheus/alertmanager/api/v2/models",
       "$ref": "#/definitions/gettableSilences"
     },
     "labelSet": {
@@ -6069,6 +6177,7 @@
       "x-go-package": "github.com/prometheus/alertmanager/api/v2/models"
     },
     "postableSilence": {
+      "description": "PostableSilence postable silence",
       "type": "object",
       "required": [
         "comment",
@@ -6109,8 +6218,6 @@
           "x-go-name": "StartsAt"
         }
       },
-      "x-go-name": "PostableSilence",
-      "x-go-package": "github.com/prometheus/alertmanager/api/v2/models",
       "$ref": "#/definitions/postableSilence"
     },
     "receiver": {

pkg/services/ngalert/models/alert_rule.go

@@ -24,6 +24,7 @@ var (
 	ErrAlertRuleUniqueConstraintViolation = errors.New("a conflicting alert rule is found: rule title under the same organisation and folder should be unique")
 )
 
+// swagger:enum NoDataState
 type NoDataState string
 
 func (noDataState NoDataState) String() string {
@@ -49,6 +50,7 @@ const (
 	OK       NoDataState = "OK"
 )
 
+// swagger:enum ExecutionErrorState
 type ExecutionErrorState string
 
 func (executionErrorState ExecutionErrorState) String() string {

pkg/services/ngalert/provisioning/alert_rules.go

@@ -53,6 +53,9 @@ func (service *AlertRuleService) GetAlertRule(ctx context.Context, orgID int64,
 	return *query.Result, provenance, nil
 }
 
+// CreateAlertRule creates a new alert rule. This function will ignore any
+// interval that is set in the rule struct and use the already existing group
+// interval or the default one.
 func (service *AlertRuleService) CreateAlertRule(ctx context.Context, rule models.AlertRule, provenance models.Provenance) (models.AlertRule, error) {
 	if rule.UID == "" {
 		rule.UID = util.GenerateShortUID()
@@ -117,6 +120,9 @@ func (service *AlertRuleService) UpdateRuleGroup(ctx context.Context, orgID int6
 	})
 }
 
+// CreateAlertRule creates a new alert rule. This function will ignore any
+// interval that is set in the rule struct and fetch the current group interval
+// from database.
 func (service *AlertRuleService) UpdateAlertRule(ctx context.Context, rule models.AlertRule, provenance models.Provenance) (models.AlertRule, error) {
 	storedRule, storedProvenance, err := service.GetAlertRule(ctx, rule.OrgID, rule.UID)
 	if err != nil {