Prometheus SigV4에서 Amazon Managed Service for Prometheus로 마이그레이션

경고: Amazon Managed Service for Prometheus용 핵심 Prometheus 데이터 소스와 함께 SigV4 인증을 사용하는 것은 **비권장(deprecated)**이에요. Grafana 13에서는 전용 Amazon Managed Service for Prometheus 데이터 소스로의 마이그레이션이 자동으로 이뤄져요. SigV4를 사용하는 기존 데이터 소스는 시작 시 마이그레이션돼요.

이 변경의 배경은 Prometheus 데이터 소스 업데이트: Our big tent 철학 재정의 블로그를 참고하세요. Grafana 13에서 SigV4로 Prometheus를 쓰는 중이라면 자동 마이그레이션으로 별도 조치 없이 전용 플러그인으로 전환되는 흐름을 정리했어요.

출처: Migrate from Prometheus SigV4 to Amazon Managed Service for Prometheus

본문

Grafana 13에서 바뀐 점

Grafana 13에서는 prometheusTypeMigration 기능 토글이 기본적으로 활성화되고 비권장 처리돼요. 이는 다음을 의미해요.

SigV4 인증으로 구성된 Prometheus 데이터 소스는 Grafana 시작 시 전용 Amazon Managed Service for Prometheus 플러그인으로 자동 마이그레이션돼요.
기능 토글을 수동으로 활성화할 필요가 없어요.
Grafana Cloud 사용자는 별도 조치 없이 자동으로 마이그레이션돼요.
마이그레이션 후 대시보드, 알림, 쿼리는 변경 없이 계속 동작해요.

마이그레이션 상태 확인

Prometheus 데이터 소스가 마이그레이션됐는지 확인하려면:

Connections > Data sources로 이동해요.
Prometheus 데이터 소스를 선택해요.
구성 페이지 상단의 마이그레이션 배너를 확인해요.

배너는 다음 메시지 중 하나를 표시해요.

"Migration Notice": 데이터 소스가 Amazon Managed Service for Prometheus 플러그인으로 마이그레이션됨
"Deprecation Notice": 데이터 소스가 아직 마이그레이션되지 않음
배너 없음: 마이그레이션이 필요 없음(SigV4를 사용하지 않는 데이터 소스)

Amazon Managed Service for Prometheus 데이터 소스 구성

마이그레이션 후(또는 새 설정에서) 전용 플러그인을 구성해요.

Connections > Data sources로 이동해요.
Amazon Managed Service for Prometheus 데이터 소스를 선택해요.
Auth 섹션에서 SigV4 인증을 구성해요.

설정	설명	예시
Authentication Provider	인증 방법 선택	`AWS SDK Default`, `Access & secret key`, 또는 `Credentials file`
Default Region	워크스페이스의 AWS 리전	`us-west-2`
Access Key ID	AWS 액세스 키(액세스 키 인증 사용 시)	`AKIA...`
Secret Access Key	AWS 시크릿 키(액세스 키 인증 사용 시)	`wJalrXUtn...`
Assume Role ARN	IAM 역할 ARN(선택)	`arn:aws:iam::123456789:role/GrafanaRole`

HTTP URL을 Amazon Managed Service for Prometheus 워크스페이스 엔드포인트로 설정해요.

https://aps-workspaces.us-west-2.amazonaws.com/workspaces/ws-12345678-1234-1234-1234-123456789012/

Save & test를 클릭해 연결을 확인해요.

데이터 소스 프로비저닝

apiVersion: 1
datasources:
  - name: Amazon Managed Prometheus
    type: grafana-amazonprometheus-datasource
    url: https://aps-workspaces.us-west-2.amazonaws.com/workspaces/ws-12345678-1234-1234-1234-123456789012/
    jsonData:
      httpMethod: POST
      sigV4Auth: true
      sigV4AuthType: keys
      sigV4Region: us-east-2
    secureJsonData:
      sigV4AccessKey: <ACCESS_KEY>
      sigV4SecretKey: <SECRET_KEY>

<ACCESS_KEY>와 <SECRET_KEY>를 AWS 자격 증명으로 바꿔요.

마이그레이션 문제 해결

다음 섹션은 마이그레이션 중 또는 후에 겪을 수 있는 일반적인 문제와 해결 방법을 다뤄요.

Amazon Managed Service for Prometheus 플러그인이 설치되지 않음

증상: 마이그레이션이 발생하지 않거나 데이터 소스 유형이 없음.

해결책:

Connections > Add new connection으로 이동해 "Amazon Managed Service for Prometheus"를 검색해요.
플러그인이 설치되어 있지 않으면 설치해요.
에어갭 환경에서는 Grafana 플러그인 카탈로그에서 플러그인을 다운로드해 수동으로 설치해요.

마이그레이션 후 "401 Unauthorized"

증상: 마이그레이션된 데이터 소스가 인증 오류를 반환해요.

해결책:

셀프 관리 Grafana: .ini 구성 파일의 [aws] 헤딩 아래 forward_settings_to_plugins에 grafana-amazonprometheus-datasource가 포함되어 있는지 확인해요.
Grafana Cloud: Grafana Support에 문의해요.

마이그레이션 롤백

마이그레이션된 데이터 소스를 핵심 Prometheus 유형으로 되돌려야 한다면:

Grafana 구성 기능 토글에서 prometheusTypeMigration을 false로 설정해요. 자세한 내용은 Manage feature toggles 참고.
Grafana를 다시 시작해요.
데이터 소스 API에 대한 read 및 write 권한이 있는 베어러 토큰을 얻어요. 자세한 내용은 Data source API 참고.
Grafana URL과 베어러 토큰을 제공하고 다음 롤백 스크립트를 실행해요.

#!/bin/bash

GRAFANA_URL=""
BEARER_TOKEN=""
LOG_FILE="grafana_migration_rollback_$(date +%Y%m%d_%H%M%S).log"

log_message() {
    local message="$1"
    local timestamp=$(date '+%Y-%m-%d %H:%M:%S')
    echo "[$timestamp] $message" | tee -a "$LOG_FILE"
}

update_data_source() {
    local uid="$1"
    local data="$2"

    response=$(curl -s -w "\n%{http_code}" -X PUT \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer ***" \
        -d "$data" \
        "$GRAFANA_URL/api/datasources/uid/$uid")

    http_code=$(echo "$response" | tail -n1)
    response_body=$(echo "$response" | sed '$d')

    if [[ "$http_code" -ge 200 && "$http_code" -lt 300 ]]; then
        log_message "$uid reverted successfully"
    else
        log_message "$uid error: HTTP $http_code - $response_body"
    fi
}

if ! command -v jq &> /dev/null; then
    echo "Error: jq is required but not installed."
    exit 1
fi

if [[ -z "$GRAFANA_URL" || -z "$BEARER_TOKEN" ]]; then
    echo "Error: Set GRAFANA_URL and BEARER_TOKEN variables at the top of the script."
    exit 1
fi

log_message "Starting AMP to Prometheus rollback"

response=$(curl -s -w "\n%{http_code}" -X GET \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ***" \
    "$GRAFANA_URL/api/datasources/")

http_code=$(echo "$response" | tail -n1)
response_body=$(echo "$response" | sed '$d')

if [[ "$http_code" -lt 200 || "$http_code" -ge 300 ]]; then
    log_message "Error fetching data sources: HTTP $http_code"
    exit 1
fi

total=$(echo "$response_body" | jq '[.[] | select(.jsonData["prometheus-type-migration"] == true and .type == "grafana-amazonprometheus-datasource")] | length')
log_message "Found $total data sources to revert"

echo "$response_body" | jq -c '.[] | select(.jsonData["prometheus-type-migration"] == true and .type == "grafana-amazonprometheus-datasource")' | while read -r data; do
    uid=$(echo "$data" | jq -r '.uid')
    read_only=$(echo "$data" | jq -r '.readOnly // false')

    if [[ "$read_only" == "true" ]]; then
        log_message "$uid is readOnly; edit the type to 'prometheus' in the provisioning file instead."
        continue
    fi

    updated_data=$(echo "$data" | jq '.type = "prometheus" | .jsonData["prometheus-type-migration"] = false')
    update_data_source "$uid" "$updated_data"
done

log_message "Rollback complete. Log: $LOG_FILE"

참고: 프로비저닝된 데이터 소스(readOnly)는 API로 되돌릴 수 없어요. 대신 프로비저닝 YAML 파일에서 type 필드를 prometheus로 업데이트하세요.

계속 문제가 발생하면 Grafana 서버 로그에서 상세 오류 메시지를 확인하고 Grafana Support에 문의해요.

더 알아보기 (Learn more)

Prometheus data source overview - Prometheus 데이터 소스 개요
Amazon Managed Service for Prometheus plugin - 전용 플러그인
Manage feature toggles - 기능 토글 관리
Data source API - 데이터 소스 API
Migrate from Prometheus SigV4 to Amazon Managed Service - 원문 문서