Terraform으로 저장된 쿼리 관리

Terraform으로 저장된 쿼리 관리 (Manage saved queries using Terraform)

이 문서는 Grafana Terraform provider를 사용해 저장된 쿼리(saved queries, 일명 쿼리 라이브러리)를 코드형으로 관리하는 방법을 안내해요. provider 설정부터 저장된 쿼리 리소스 생성, 기존 쿼리 가져오기까지 다뤄요.

출처: 문서

본문

이 가이드는 저장된 쿼리(saved queries), 일명 쿼리 라이브러리(query library)를 Grafana Terraform provider로 관리하는 방법을 보여줘요. 저장된 쿼리를 코드로 관리하면 쿼리 라이브러리를 버전 관리하고 여러 Grafana 인스턴스에서 일관성을 유지할 수 있어요.

Note 저장된 쿼리는 Grafana Enterprise와 Grafana Cloud에서만 사용할 수 있어요.

시작하기 전에 (Before you begin)

시작하기 전에 다음 항목이 있는지 확인해요:

Grafana provider 구성 (Configure the Grafana provider)

저장된 쿼리를 관리하는 데 필요한 인증으로 Grafana provider를 설정하려면 main.tf 파일을 만들고 다음 내용을 추가해요:

terraform {
  required_providers {
    grafana = {
      source  = "grafana/grafana"
      version = ">= 4.44.0"
    }
  }
}

provider "grafana" {
  url  = "<Grafana-URL>"
  auth = "<Service-account-token>"
}

다음 필드 값을 바꿔주세요:

  • Grafana-URL — Grafana 인스턴스의 URL (예: https://my-stack.grafana.net/)
  • Service-account-token — 생성한 서비스 계정 토큰

저장된 쿼리 리소스 생성 (Create a saved query resource)

<saved-queries.tf> 파일을 만들고 다음 내용을 추가해요:

resource "grafana_apps_queries_query_v1" "example" {
  metadata {
    uid = "example-saved-query"
  }

  spec {
    title       = "Requests per second"
    description = "Prometheus rate of HTTP requests"
    is_visible  = true
    tags        = ["http", "prometheus"]

    targets {
      properties_json = jsonencode({
        refId = "A"
        expr  = "rate(http_requests_total[$__rate_interval])"
        datasource = {
          type = "prometheus"
          uid  = "my-prometheus-uid"
        }
      })
    }
  }
}

데이터 소스 쿼리의 형태는 데이터 소스에 따라 달라지기 때문에, 각 target에 저장되는 쿼리(properties_json), target의 변수 치환(variables_json), 변수의 값 목록(value_list_definition_json)은 원시(raw) JSON 문자열로 전달돼요. 이를 구성하려면 jsonencode()를 사용해요.

spec 블록은 다음 필드를 지원해요:

Field Description
title 저장된 쿼리의 표시 이름. 필수.
description 저장된 쿼리에 대한 자세한 설명.
is_visible 저장된 쿼리가 쿼리 라이브러리에 표시되는지 여부.
is_locked 저장된 쿼리가 잠겨 UI에서 편집할 수 없는지 여부. 보안용이 아니라 UI 표시용이에요.
tags 저장된 쿼리를 필터링하는 데 사용하는 태그.
targets 저장된 쿼리를 구성하는 쿼리 target. 최소 하나의 target이 필요해요.
vars 쿼리 target에 보간(interpolate)할 수 있는 템플릿 변수.

전체 스키마는 grafana_apps_queries_query_v1 리소스 문서를 참고해요.

기존 저장된 쿼리 가져오기 (Import an existing saved query)

기존 저장된 쿼리를 Terraform 관리 하에 두려면 UID를 사용해 가져와요:

terraform import grafana_apps_queries_query_v1.example example-saved-query

요약 (Summary)

이 가이드에서는 Terraform을 사용해 저장된 쿼리를 만들고 가져오는 방법을 배웠어요. 저장된 쿼리에 대해 더 알아보려면 Saved queries를 참고해요.

더 알아보기