Terraform으로 Knowledge Graph 스택 구성

Terraform으로 Knowledge Graph 스택 구성 (Configure the Knowledge Graph stack using Terraform)

Knowledge Graph 스택 리소스는 Grafana Cloud 스택의 전체 온보딩 흐름을 관리해요. API 토큰을 프로비저닝하고, 사용 가능한 메트릭을 기반으로 데이터 세트를 구성하며, 스택을 활성화해요.

기본적으로 데이터 세트는 감지된 메트릭을 기반으로 자동 구성돼요. 메트릭이 비표준 레이블 이름을 사용하는 경우처럼 데이터 세트를 수동 구성하려면 dataset 블록을 사용해요.

출처: 문서

본문

시작하기 전에 (Before you begin)

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

Get started에 표시된 Grafana Cloud 계정
머신에 설치된 Terraform
Knowledge Graph용 Terraform 시작하기에 표시된 대로 구성된 Grafana Terraform 제공자
다음 범위가 있는 Cloud Access Policy: stacks:read, metrics:read, metrics:write

데이터 세트 유형 (Dataset types)

다음 데이터 세트 유형을 사용할 수 있어요:

kubernetes: Kubernetes 메트릭. 스택에서 Kubernetes Monitoring이 활성화되어 있어야 해요.
otel: Application Observability 메트릭. 스택에서 Application Observability이 활성화되어 있어야 해요.
prometheus: 표준 Prometheus 메트릭.
aws: Amazon Web Services 메트릭.

필요한 토큰 만들기 (Create the required tokens)

Knowledge Graph 스택을 구성하기 전에 리소스가 요구하는 Cloud Access Policy와 Grafana Service Account 토큰을 만들어요.

knowledge-graph-stack.tf라는 파일을 만들고 다음을 추가해요:

terraform

# Create a Cloud Access Policy with required scopes
resource "grafana_cloud_access_policy" "knowledge_graph" {
  name         = "knowledge-graph-stack-policy"
  display_name = "Knowledge Graph Stack Policy"

  scopes = [
    "stacks:read",
    "metrics:read",
    "metrics:write",
  ]

  realm {
    type       = "stack"
    identifier = var.stack_id
  }
}

# Create a token from the Cloud Access Policy
resource "grafana_cloud_access_policy_token" "knowledge_graph" {
  name             = "knowledge-graph-stack-token"
  access_policy_id = grafana_cloud_access_policy.knowledge_graph.policy_id
}

# Create a Grafana Service Account for dashboards and Grafana Managed Alerts
resource "grafana_cloud_stack_service_account" "knowledge_graph" {
  stack_slug  = var.stack_slug
  name        = "knowledge-graph-managed-alerts-sa"
  role        = "Admin"
  is_disabled = false
}

resource "grafana_cloud_stack_service_account_token" "knowledge_graph" {
  stack_slug         = var.stack_slug
  service_account_id = grafana_cloud_stack_service_account.knowledge_graph.id
  name               = "knowledge-graph-managed-alerts-token"
}

variable "stack_id" {
  description = "The Grafana Cloud stack ID"
  type        = string
}

variable "stack_slug" {
  description = "The Grafana Cloud stack slug"
  type        = string
}

다음 값을 바꿔요:

*<STACK_ID>*를 Grafana Cloud 스택 ID로
*<STACK_SLUG>*를 Grafana Cloud 스택 slug로

자동 감지 데이터 세트가 있는 기본 스택 구성 (Basic stack configuration with auto-detected datasets)

가장 간단한 구성은 토큰을 프로비저닝하고 사용 가능한 메트릭을 기반으로 데이터 세트를 자동 감지해요. 메트릭이 표준 레이블 이름을 사용할 때 권장되는 접근 방식이에요.

knowledge-graph-stack.tf에 다음을 추가해요:

terraform

resource "grafana_asserts_stack" "main" {
  cloud_access_policy_token = grafana_cloud_access_policy_token.knowledge_graph.token
  grafana_token             = grafana_cloud_stack_service_account_token.knowledge_graph.key
}

이 구성을 적용하면 리소스가:

Grafana Cloud, Mimir, assertion detector용 API 토큰을 프로비저닝해요
스택의 메트릭을 기반으로 사용 가능한 데이터 세트를 자동 감지해요
감지된 데이터 세트로 스택을 활성화해요

데이터 세트 수동 구성 (Configure the dataset manually)

메트릭이 비표준 레이블 이름(예: 커스텀 환경 레이블)을 사용할 때 수동 구성을 사용해요. 각 dataset 블록은 하나의 데이터 세트 유형을 구성해요.

terraform

resource "grafana_asserts_stack" "manual" {
  cloud_access_policy_token = grafana_cloud_access_policy_token.knowledge_graph.token
  grafana_token             = grafana_cloud_stack_service_account_token.knowledge_graph.key

  dataset {
    type = "kubernetes"

    filter_group {
      env_label  = "deployment_environment"
      site_label = "cluster"

      env_label_values  = ["production", "staging"]
      site_label_values = ["us-east-1", "eu-west-1"]
    }
  }
}

Note 하나 이상의 dataset 블록을 지정하면 자동 감지가 건너뛰어져요. 구성하려는 모든 데이터 세트를 정의해야 해요.

필터가 있는 여러 데이터 세트 구성 (Configure multiple datasets with filters)

커스텀 레이블 매핑과 메트릭 필터로 여러 데이터 세트 유형을 구성해요:

terraform

resource "grafana_asserts_stack" "multi_dataset" {
  cloud_access_policy_token = grafana_cloud_access_policy_token.knowledge_graph.token
  grafana_token             = grafana_cloud_stack_service_account_token.knowledge_graph.key

  dataset {
    type = "kubernetes"

    filter_group {
      env_label  = "deployment_environment"
      site_label = "cluster"

      env_label_values  = ["production", "staging"]
      site_label_values = ["us-east-1", "eu-west-1"]
    }
  }

  dataset {
    type = "prometheus"

    filter_group {
      env_label = "environment"
      env_name  = "prod"

      filter {
        name     = "region"
        operator = "=~"
        values   = ["us-.*", "eu-.*"]
      }
    }
  }
}

리소스 참조 (Resource reference)

`grafana_asserts_stack`

Grafana API를 통해 Knowledge Graph 스택 구성을 관리해요. 이 리소스는 토큰 프로비저닝, 데이터 세트 구성, 스택 활성화를 포함한 전체 온보딩 흐름을 처리해요.

인자 (Arguments)

테이블 펼치기

Name	Type	Required	Description
`cloud_access_policy_token`	`string`	Yes	다음 범위가 있는 Grafana Cloud Access Policy 토큰: `stacks:read`, `metrics:read`, `metrics:write`. Grafana Cloud API 접근, Mimir 인증, assertion detector 웹훅 인증에 사용돼요. 민감함.
`grafana_token`	`string`	No	대시보드와 Grafana Managed Alerts 설치용 Grafana Service Account 토큰. `grafana_cloud_stack_service_account_token`으로 만들기. 민감함.
`dataset`	`list(object)`	No	수동 데이터 세트 구성. 지정하면 자동 감지가 건너뛰어져요. 자세한 내용은 dataset block을 참고해요.

속성 (Attributes)

테이블 펼치기

Name	Type	Description
`enabled`	`bool`	스택이 현재 활성화되어 있는지 여부.
`status`	`string`	스택의 현재 온보딩 상태.
`version`	`int`	구성 버전 번호.

Dataset 블록 (Dataset block)

각 dataset 블록은 다음을 지원해요:

테이블 펼치기

Name	Type	Required	Description
`type`	`string`	Yes	데이터 세트 유형: `kubernetes`, `otel`, `prometheus`, 또는 `aws`.
`disabled_vendors`	`list(string)`	No	이 데이터 세트에 대해 비활성화할 공급업체 목록.
`filter_group`	`list(object)`	No	커스텀 레이블 매핑용 필터 그룹. 자세한 내용은 filter group block을 참고해요.

Filter group 블록 (Filter group block)

각 filter_group 블록은 다음을 지원해요:

테이블 펼치기

Name	Type	Required	Description
`env_label`	`string`	No	환경에 사용되는 메트릭 레이블 이름(예: `env`, `environment`, `deployment_environment`).
`env_name`	`string`	No	환경의 친근한 이름.
`site_label`	`string`	No	사이트나 클러스터에 사용되는 메트릭 레이블 이름.
`env_label_values`	`list(string)`	No	일치시킬 환경 레이블의 특정 값.
`site_label_values`	`list(string)`	No	일치시킬 사이트 레이블의 특정 값.
`filter`	`list(object)`	No	추가 메트릭 필터. 자세한 내용은 filter block을 참고해요.

Filter 블록 (Filter block)

각 filter 블록은 다음을 지원해요:

테이블 펼치기

Name	Type	Required	Description
`name`	`string`	Yes	필터링할 레이블 이름.
`operator`	`string`	Yes	필터 연산자: `=`, `!=`, `=~`, 또는 `!~`.
`values`	`list(string)`	Yes	일치시킬 값.

예 (Example)

terraform

resource "grafana_asserts_stack" "example" {
  cloud_access_policy_token = grafana_cloud_access_policy_token.knowledge_graph.token
  grafana_token             = grafana_cloud_stack_service_account_token.knowledge_graph.key

  dataset {
    type = "kubernetes"

    filter_group {
      env_label         = "deployment_environment"
      site_label        = "cluster"
      env_label_values  = ["production"]
      site_label_values = ["us-east-1"]
    }
  }
}

모범 사례 (Best practices)

Terraform으로 Knowledge Graph 스택을 구성할 때 다음 모범 사례를 고려해요.

토큰 관리 (Token management)

필요한 범위만 있는 Knowledge Graph 스택 전용 Cloud Access Policy를 만들어요
단일 관리자 토큰을 공유하는 대신 다른 목적에 별도의 Service Accounts를 사용해요
토큰을 정기적으로 회전하고 Terraform의 민감 변수 처리를 사용해 로그에 토큰이 노출되지 않게 해요
토큰을 시크릿 관리 시스템에 저장하고 Terraform 변수로 참조해요

데이터 세트 구성 (Dataset configuration)

자동 감지된 데이터 세트로 시작하고 필요할 때만 수동 구성으로 전환해요
수동 구성 사용 시 모니터링하려는 모든 데이터 세트를 정의해요
모니터링 범위를 제한하려면 구체적인 env_label_values와 site_label_values를 사용해요
먼저 비프로덕션 스택에서 데이터 세트 구성을 테스트해요

필터 그룹 (Filter groups)

메트릭이 비표준 레이블 이름을 사용할 때 필터 그룹을 사용해요
env_label과 site_label 값을 Prometheus 메트릭의 실제 레이블 이름과 일치시켜요
지역이나 환경 전반의 유연한 값 매칭을 위해 필터에서 정규식 연산자(=~, !~)를 사용해요
예측 가능한 동작을 위해 데이터 세트 전반에서 필터 구성을 일관되게 유지해요

검증 (Validation)

Terraform 구성을 적용한 후 다음을 확인해요:

enabled 출력 속성을 확인해 스택 상태가 활성화로 표시되는지
status 속성이 성공적인 온보딩을 나타내는지
Knowledge Graph UI에서 데이터 세트가 올바르게 구성되었는지
grafana_token이 제공되면 대시보드와 알림 규칙이 설치되었는지

Terraform 출력으로 스택 상태를 검사할 수 있어요:

terraform

output "stack_enabled" {
  value       = grafana_asserts_stack.main.enabled
  description = "Whether the Knowledge Graph stack is enabled"
}

output "stack_status" {
  value       = grafana_asserts_stack.main.status
  description = "Current onboarding status of the stack"
}

output "stack_version" {
  value       = grafana_asserts_stack.main.version
  description = "Configuration version number"
}

Terraform으로 Knowledge Graph 스택 구성