데이터 소스 관리 알림 규칙을 Grafana 관리 규칙으로 가져오기

데이터 소스 관리 알림 규칙을 Grafana 관리 규칙으로 가져오기 (Import data source-managed rules to Grafana-managed rules)

Mimir, Loki, Prometheus 같은 데이터 소스의 기존 알림 규칙을 Grafana 관리 알림 규칙으로 변환할 수 있어요. 이렇게 하면 Grafana Alerting으로 규칙을 운영·관리할 수 있습니다. 가져오기는 안전한 작업으로, 원본 데이터 소스 관리 규칙은 원래 위치에 그대로 유지돼요. 두 가지 방법을 알려드릴게요.

출처: 문서

본문

가져오기 방법 두 가지:

• Grafana Alerting UI로 연결된 데이터 소스 또는 Prometheus 규칙 YAML 파일에서 가져오기
• 커맨드라인 도구(mimirtool, cortextool)로 YAML 파일에서 가져오기

모든 규칙을 마이그레이션하기 전에 가져오기 과정을 테스트·검증하는 것이 모범 사례입니다.

동작 방식

가져오기를 사용하면 데이터 소스 관리 규칙이 다른 폴더로 Grafana 관리 규칙으로 복사되고, 원본 규칙은 원래 위치에 그대로 유지됩니다. 변환 중 다음 설정이 적용돼요.

• 고유 UID: 새 규칙에 고유 UID 할당. 자동 생성을 원하지 않으면 __grafana_alert_rule_uid__ 라벨로 지정 가능
• 쿼리 오프셋: 각 규칙에 쿼리 오프셋 적용. 예: 1m 오프셋은 쿼리 시간 범위를 To: now-1m으로 조정. 규칙 그룹의 query_offset 값에서 가져오며, 비어 있으면 기본 1m인 rule_query_offset 설정 사용
• 규칙 쿼리 변환: 알림 규칙에 prometheus_math·threshold 표현식을 추가해 Prometheus no data 동작 보존(쿼리가 데이터 없으면 규칙을 Normal 상태로 유지)
• Missing series evaluations to resolve: Prometheus의 알림 제거 동작을 재현하도록 설정을 1로 설정
• 규칙 그룹 라벨: 규칙 그룹 레벨 라벨을 그룹 내 각 가져온 규칙에 라벨로 추가
• 순차 평가: 가져온 규칙은 각 그룹 안에서 순차 평가되어 Prometheus 동작을 반영(순서가 강제되지 않는 네이티브 Grafana 관리 규칙과 다름). 평가 전략 참고
• 기능 호환성: 규칙 그룹 limit 옵션과 규칙 템플릿의 query 함수는 Grafana 관리 규칙에서 현재 지원하지 않아요. limit 옵션이 있으면 가져오기 실패, 템플릿의 query는 규칙과 함께 가져옵니다.

참고: __grafana_origin 라벨이 있는 규칙은 가져오기에 포함되지 않아요. Kubernetes Monitoring, Synthetic Monitoring, Grafana 플러그인 같은 앱이 만든 규칙들입니다.

Grafana Alerting으로 규칙 가져오기

다음 소스에서 가져올 수 있어요: ruler API가 활성화된 연결된 Mimir·Loki 데이터 소스, Prometheus YAML 규칙 파일. 이 방식으로 가져온 규칙은 UI에서 편집 가능해요.

시작 전 RBAC 권한: Alerting: Rules Writer, Set provisioning status. Datasources: Reader. Folders: Creator(선택, 새 폴더 생성 시에만).

단계:

1. Alerting > Alert rules 이동
2. Data source-managed 규칙 섹션에서 Import to Grafana-managed rules 클릭
3. Import source 선택: Existing data source-managed rules(ruler API 활성화 Mimir/Loki) 또는 Prometheus YAML file(업로드)
4. Data source 드롭다운에서 가져온 규칙이 쿼리할 데이터 소스 선택
5. (선택) 대상 폴더 선택 또는 새 폴더 지정. 기존 폴더를 선택하면 기존 규칙이 있는 폴더는 피하세요(덮어써질 수 있음)
6. (선택) Namespace/Group 선택해 가져올 규칙 결정
7. (선택) Pause imported alerting rules(일시 중지 시 평가 중지, 알림 인스턴스 생성 안 함)
8. (선택) Pause imported recording rules
9. (선택) Recording rules의 Target data source에서 레코딩 규칙이 메트릭을 쓸 데이터 소스 선택(기본은 Data source 선택 값)
10. Import 클릭 → 미리보기 확인, 대상 폴더에 같은 이름의 폴더가 있으면 경고 표시 → Yes, import 클릭

커맨드라인 도구로 규칙 가져오기

mimirtool(Mimir/Prometheus 규칙), cortextool(Loki 규칙)을 사용해요. 두 도구 모두 규칙 그룹 가져오기용 rules 명령을 제공합니다. rules load는 파일에서 규칙 그룹을 가져오고, rules sync는 기존 Grafana 관리 규칙과의 차이만 적용해 자동화 워크플로에 유용해요. 기본적으로 API/CLI로 가져온 규칙은 Provisioned 상태로 UI에서 편집할 수 없어요. 편집하려면 X-Disable-Provenance 헤더를 활성화하세요.

시작 전: mimirtool 또는 cortextool(0.11.3 이상) 설치. 서비스 계정과 다음 권한 필요: Alerting Rules Reader, Rules Writer, Set provisioning status; Datasources Reader; Folders Creator, Reader, Writer.

mimirtool

MIMIR_ADDRESS=<GRAFANA_BASE_URL>/api/convert/ \
MIMIR_AUTH_TOKEN=<SERVICE_ACCOUNT_TOKEN> \
MIMIR_TENANT_ID=1 \
mimirtool rules load rule_file.yaml \
  --extra-headers "X-Grafana-Alerting-Datasource-UID=<DATASOURCE_UID_QUERY_TARGET>"

주의: <GRAFANA_BASE_URL>/api/convert/ 엔드포인트 사용 시 mimirtool은 Mimir가 아닌 Grafana와 상호작용하고, MIMIR_TENANT_ID는 항상 1이어야 해요. X-Grafana-Alerting-Datasource-UID 헤더가 가져온 규칙이 쿼리할 데이터 소스를 구성합니다.

rules sync 명령도 있습니다.

MIMIR_ADDRESS=<GRAFANA_BASE_URL>/api/convert/ \
MIMIR_AUTH_TOKEN=<SERVICE_ACCOUNT_TOKEN> \
MIMIR_TENANT_ID=1 \
mimirtool rules sync rule_file.yaml \
  --extra-headers "X-Grafana-Alerting-Datasource-UID=<DATASOURCE_UID_QUERY_TARGET>" \
  --concurrency 1

--concurrency는 기본값 8이 API 오류를 일으킬 수 있으므로 1로 설정해야 해요. 이 sync 명령은 파일의 규칙을 기존 Grafana 관리 규칙과 비교해 차이만 적용합니다(생성·업데이트·삭제).

## Sync Summary: 0 Groups Created, 1 Groups Updated, 0 Groups Deleted

cortextool

Loki 알림 규칙용(--backend=loki 플래그):

CORTEX_ADDRESS=<GRAFANA_BASE_URL>/api/convert/ \
CORTEX_AUTH_TOKEN=<SERVICE_ACCOUNT_TOKEN> \
CORTEX_TENANT_ID=1 \
cortextool rules load loki_rules.yaml \
  --extra-headers "X-Grafana-Alerting-Datasource-UID=<LOKI_DATASOURCE_UID_QUERY_TARGET>" \
  --backend=loki

선택적 헤더

• X-Disable-Provenance: true 설정 시 가져온 규칙이 provisioned로 표시되지 않고 UI에서 편집 가능해지며 /api/convert 엔드포인트의 GET·DELETE에서 제외. rules sync 사용 시 활성화하지 마세요(GET/DELETE에 의존함).
• X-Grafana-Alerting-Alert-Rules-Paused: true면 알림 규칙을 일시 중지 상태로 가져옴
• X-Grafana-Alerting-Recording-Rules-Paused: 레코딩 규칙 일시 중지
• X-Grafana-Alerting-Datasource-UID: 알림 규칙 쿼리에 사용할 데이터 소스 UID. 미지정 시 unified_alerting.prometheus_conversion.default_datasource_uid의 기본값 사용. 둘 다 없으면 요청 실패
• X-Grafana-Alerting-Target-Datasource-UID: 레코딩 규칙 대상 데이터 소스 UID. 미지정 시 Datasource-UID 값 사용
• X-Grafana-Alerting-Folder-UID: 가져온 규칙의 대상 폴더 UID
• X-Grafana-Alerting-Notification-Settings: 컨택트 포인트 설정용 JSON 인코딩 AlertRuleNotificationSettings

AlertRuleNotificationSettings 객체

호환 엔드포인트

"namespace"는 Grafana의 폴더 제목에 해당해요. POST 엔드포인트는 YAML·JSON 모두 허용(미지정 시 YAML).

GET/DELETE는 provisioned·가져온 규칙에만 동작하며, GET은 Accept 헤더에 따라 JSON(application/json) 또는 YAML(application/yaml) 반환.

여러 규칙 그룹 생성·업데이트 예시 요청 본문:

namespace1:
  - name: MyGroupName1
    rules:
      - alert: MyAlertName1
        expr: up == 0
        labels:
          severity: warning
namespace2:
  - name: MyGroupName2
    rules:
      - alert: MyAlertName2
        expr: rate(http_requests_total[5m]) > 0.1
        labels:
          severity: critical

더 알아보기 (Learn more)

• Mimirtool 문서
• Mimir HTTP Rule API
• cortex-tools
• 알림 규칙 평가 전략