HTTP API로 알림 리소스 관리

HTTP API로 알림 리소스 관리 (Use the HTTP API to manage alerting resources)

Alerting Provisioning HTTP API는 Grafana 관리형 알림(Grafana-managed alerts)과 관련된 리소스를 만들고·수정하고·삭제하는 데 사용할 수 있어요. 이 API는 Grafana Terraform 공급자가 사용하는 API이기도 해요.

출처: 문서

본문

Grafana Enterprise를 실행 중이라면 일부 엔드포인트에 특정 권한을 추가해야 해요. 자세한 내용은 "Role-based access control permissions" 문서를 참고하세요.

Warning: 이 API의 contact points, notification policies, notification template groups, mute timings 엔드포인트는 더 이상 사용되지 않으며(deprecated) 향후 릴리스에서 제거될 예정이에요. Grafana App Platform 알림 API를 대신 사용하세요.

Note: Alerting provisioning HTTP API의 엔드포인트는 export 엔드포인트가 반환하는 형식과 다른 JSON 형식을 사용해요. export 엔드포인트는 파일 프로비저닝에 적합한 JSON 형식으로 알림 리소스를 내보내지만, 이 형식으로 HTTP API를 통해 리소스를 업데이트할 수는 없어요.

알림 규칙 (Alert rules)

다음 엔드포인트는 알림 규칙과 녹음 규칙(recording rules)을 모두 관리하는 데 사용할 수 있어요. 녹음 규칙을 만들려면 요청에 condition 필드 대신 record 블록을 포함해요.

새 알림 규칙 요청 예제:

POST /api/v1/provisioning/alert-rules
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIj...ZYbk

{
  "title": "TEST-API_1",
  "ruleGroup": "API",
  "folderUID": "SET_FOLDER_UID",
  "noDataState": "OK",
  "execErrState": "OK",
  "for": "5m",
  "keepFiringFor": "2m",
  "orgId": 1,
  "uid": "",
  "condition": "B",
  "annotations": {
    "summary": "test_api_1"
  },
  "labels": {
    "API": "test1"
  },
  "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"
      }
    }
  ]
}

예제 응답: HTTP/1.1 201 Created와 함께 생성된 규칙의 id, uid, orgID, folderUID, ruleGroup, title, condition, data를 반환해요.

연락처 (Contact points)

모든 연락처 요청 예제 및 응답:

GET /api/v1/provisioning/contact-points
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIj...ZYbk

응답은 uid, name, type(예: email), settings(예: addresses), disableResolveMessage를 포함한 연락처 배열이에요.

수신자 권한 (Receiver permissions)

수신자 권한 엔드포인트는 연결 지점 수신자(receiver)에 대한 접근 제어를 관리해요. 특정 수신자에 대해 사용자·팀·내장 역할에 권한을 지정할 수 있어요.

예: 사용자에게 권한 지정:

POST /api/access-control/receivers/abc123/users/5
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIj...ZYbk

{
  "permission": "Edit"
}

사용 가능한 권한 세트:

• View — 수신자에 대한 읽기 전용 접근. alert.notifications.receivers:read 부여.
• Edit — 수신자 업데이트·테스트 능력. View 액션에 더해 alert.notifications.receivers:write, ...:delete, ...:test:create 부여.
• Admin — 권한 관리와 시크릿 읽기를 포함한 전체 접근. Edit 액션에 더해 alert.notifications.receivers.secrets:read, receivers.permissions:read, receivers.permissions:write, alert.notifications.receivers.protected:write 부여.
• 빈 문자열("") — 권한 제거.

알림 정책 (Notification policies)

음소거 타이밍 (Mute timings)

모든 음소거 타이밍 응답 예제:

GET /api/v1/provisioning/mute-timings
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIj...ZYbk

응답은 name, time_intervals(예: weekdays), version, provenance를 포함한 배열이에요.

Grafana UI에서 리소스 편집

기본적으로 Grafana에서는 API로 프로비저닝된 알림 리소스를 편집할 수 없어요. Grafana UI에서 이 리소스 편집을 활성화하려면 다음 API 요청에 X-Disable-Provenance: true 헤더를 추가해요:

• PUT /api/v1/provisioning/folder/{FolderUID}/rule-groups/{Group}: 이 동작은 규칙 그룹과 그 모든 알림 규칙의 provenance도 설정해요.
• POST /api/v1/provisioning/alert-rules: 새 알림 규칙의 provenance는 그 규칙 그룹에 구성된 provenance 값과 일치해야 해요.
• POST /api/v1/provisioning/contact-points
• POST /api/v1/provisioning/mute-timings
• PUT /api/v1/provisioning/templates/{name}
• PUT /api/v1/provisioning/policies

알림 정책 트리를 기본값으로 재설정하고 Grafana UI에서 편집을 잠금 해제하려면 DELETE /api/v1/provisioning/policies를 사용해요.

데이터 소스 관리형 리소스

Caution: Grafana Cloud에서 사전 프로비저닝된 Loki·Prometheus 데이터 소스 관리형 알림이 더 이상 사용되지 않으며 새 스택에서는 만들 수 없어요. 새 Grafana Cloud 스택은 기본적으로 Grafana 관리형 알림(GMA)을 사용해요. 기존 스택은 영향이 없어요. 이는 Grafana Labs가 관리하는 기본 클라우드 데이터 소스와 Cloud Alertmanager에 적용되며, 직접 Mimir·Loki·Alertmanager 데이터 소스를 추가하면 데이터 소스 관리형 알림을 계속 쓸 수 있어요. Cloud 사용자는 import 도구로 DMA 규칙을 GMA 규칙으로 가져올 수 있어요.

자세한 경로 및 모델

이어지는 문서의 "Paths" 섹션은 위 엔드포인트 각각의 상세한 파라미터·응답 코드·스키마를 제공하며, "Models" 섹션은 AlertQuery, AlertRuleGroup, AlertingFileExport, ContactPointExport, Matcher, MuteTimeInterval, Route, TimeInterval, ProvisionedAlertRule 등 데이터 모델의 정의를 포함해요. 엔드포인트별 요청·응답 스키마는 원문 문서의 각 섹션을 참조하세요.

더 알아보기 (Learn more)

• Grafana Terraform provider
• Provision alerting resources
• Create alert rules
• Grafana Alerting