Terraform으로 사용자 지정 모델 규칙(custom model rules) 만들기

Terraform으로 사용자 지정 모델 규칙(custom model rules) 만들기

Knowledge Graph의 사용자 지정 모델 규칙을 사용하면 Prometheus 쿼리를 기반으로 엔티티가 어떻게 발견되고 모델링되는지 정의할 수 있어요. 이러한 규칙을 통해 사용자 지정 엔티티 유형을 만들고, 그 관계를 정의하고, 추가 데이터로 어떻게 강화(enrich)할지 지정할 수 있어요.

Knowledge Graph UI에서 엔티티와 관계를 관리하는 방법에 대한 자세한 내용은 엔티티 및 관계 관리 문서를 참고하세요.

출처: 문서

본문

기본 사용자 지정 모델 규칙

custom-model-rules.tf라는 파일을 만들고 다음 내용을 추가하세요:

# Basic custom model rule for services
resource "grafana_asserts_custom_model_rules" "basic_service" {
  provider = grafana.asserts

  name = "basic-service-model"

  rules {
    entity {
      type = "Service"
      name = "service"

      defined_by {
        query = "up{job!=''}"
        label_values = {
          service = "job"
        }
        literals = {
          _source = "up_query"
        }
      }
    }
  }
}

범위와 조회가 있는 고급 서비스 모델

환경 범위 지정과 관계 매핑으로 서비스 엔티티를 정의하세요:

# Advanced service model with environment scoping
resource "grafana_asserts_custom_model_rules" "advanced_service" {
  provider = grafana.asserts

  name = "advanced-service-model"

  rules {
    entity {
      type = "Service"
      name = "workload | service | job"

      scope = {
        namespace = "namespace"
        env       = "asserts_env"
        site      = "asserts_site"
      }

      lookup = {
        workload  = "workload | deployment | statefulset | daemonset | replicaset"
        service   = "service"
        job       = "job"
        proxy_job = "job"
      }

      defined_by {
        query = "up{job!='', asserts_env!=''}"
        label_values = {
          service     = "service"
          job         = "job"
          workload    = "workload"
          namespace   = "namespace"
        }
        literals = {
          _source = "up_with_workload"
        }
      }

      defined_by {
        query    = "up{job='maintenance'}"
        disabled = true
      }
    }
  }
}

다중 엔티티 모델 구성

단일 구성에서 여러 엔티티 유형을 정의하세요:

# Multiple entity types in a single model
resource "grafana_asserts_custom_model_rules" "multi_entity" {
  provider = grafana.asserts

  name = "kubernetes-entities"

  rules {
    # Service entity
    entity {
      type = "Service"
      name = "service"

      scope = {
        namespace = "namespace"
        cluster   = "cluster"
      }

      defined_by {
        query = "up{service!=''}"
        label_values = {
          service   = "service"
          namespace = "namespace"
          cluster   = "cluster"
        }
      }
    }

    # Pod entity
    entity {
      type = "Pod"
      name = "Pod"

      scope = {
        namespace = "namespace"
        cluster   = "cluster"
      }

      lookup = {
        service   = "service"
        workload  = "workload"
      }

      defined_by {
        query = "kube_pod_info{pod!=''}"
        label_values = {
          Pod       = "pod"
          namespace = "namespace"
          cluster   = "cluster"
          service   = "service"
        }
        literals = {
          _entity_type = "Pod"
        }
      }
    }

    # Namespace entity
    entity {
      type = "Namespace"
      name = "namespace"

      scope = {
        cluster = "cluster"
      }

      defined_by {
        query = "kube_namespace_status_phase{namespace!=''}"
        label_values = {
          namespace = "namespace"
          cluster   = "cluster"
        }
      }
    }
  }
}

강화(enrichment)가 있는 복잡한 엔티티

여러 데이터 소스와 강화로 서비스 엔티티를 만드세요:

# Service entity with enrichment from multiple sources
resource "grafana_asserts_custom_model_rules" "enriched_service" {
  provider = grafana.asserts

  name = "enriched-service-model"

  rules {
    entity {
      type = "Service"
      name = "service"

      enriched_by = [
        "prometheus_metrics",
        "kubernetes_metadata",
        "application_logs"
      ]

      scope = {
        environment = "asserts_env"
        region      = "asserts_site"
        team        = "team"
      }

      lookup = {
        deployment = "workload"
        Pod        = "pod"
        container  = "container"
      }

      # Primary definition from service up metrics
      defined_by {
        query = "up{service!='', asserts_env!=''}"
        label_values = {
          service     = "service"
          environment = "asserts_env"
          region      = "asserts_site"
          team        = "team"
        }
        literals = {
          _primary_source = "service_up"
        }
      }

      # Secondary definition from application metrics
      defined_by {
        query = "http_requests_total{service!=''}"
        label_values = {
          service     = "service"
          environment = "environment"
          version     = "version"
        }
        literals = {
          _secondary_source = "http_metrics"
        }
      }

      # Disabled definition for testing
      defined_by {
        query    = "test_metric{service!=''}"
        disabled = true
      }
    }
  }
}

데이터베이스 및 인프라스트럭처 엔티티

데이터베이스와 인프라스트럭처 엔티티 모델을 정의하세요:

# Database and infrastructure entity models
resource "grafana_asserts_custom_model_rules" "infrastructure" {
  provider = grafana.asserts

  name = "infrastructure-entities"

  rules {
    # Database entity
    entity {
      type = "Database"
      name = "database_instance"

      scope = {
        environment = "env"
        region      = "region"
      }

      lookup = {
        host     = "instance"
        port     = "port"
        db_name  = "database"
      }

      defined_by {
        query = "mysql_up{instance!=''}"
        label_values = {
          database_instance = "instance"
          database         = "database"
          env             = "environment"
          region          = "region"
        }
        literals = {
          _db_type = "mysql"
        }
        metric_value = "1"
      }

      defined_by {
        query = "postgres_up{instance!=''}"
        label_values = {
          database_instance = "instance"
          database         = "datname"
          env             = "environment"
        }
        literals = {
          _db_type = "postgresql"
        }
      }
    }

    # Load balancer entity
    entity {
      type = "LoadBalancer"
      name = "lb_instance"

      scope = {
        environment = "env"
      }

      defined_by {
        query = "haproxy_up{proxy!=''}"
        label_values = {
          lb_instance = "instance"
          proxy      = "proxy"
          env        = "environment"
        }
        literals = {
          _lb_type = "haproxy"
        }
      }
    }
  }
}

리소스 참조

grafana_asserts_custom_model_rules

Grafana API를 통해 Knowledge Graph 사용자 지정 모델 규칙을 관리해요. 이 리소스를 사용하면 고급 매핑과 강화 기능을 가진 Prometheus 쿼리 기반의 사용자 지정 엔티티 모델을 정의할 수 있어요.

인자(Arguments)

Rules 블록

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

Entity 블록

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

defined_by 블록

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

참고

defined_by 쿼리에 disabled = true가 설정되면 매칭에 query 필드만 사용돼요. 블록의 다른 모든 필드는 무시돼요.

모범 사례

Terraform으로 사용자 지정 모델 규칙을 만들 때 다음 모범 사례를 고려하세요.

엔티티 모델

• 실제 인프라스트럭처와 애플리케이션 아키텍처를 반영하도록 엔티티 모델을 설계하세요.
• 목적과 범위를 나타내는 설명적인 이름을 사용자 지정 모델 규칙에 사용하세요.
• 기본 엔티티 정의로 시작하고 필요에 따라 점차 복잡성을 추가하세요.
• scope 매개변수로 명확한 엔티티 범위를 정의해 환경, 지역, 팀별로 엔티티를 구성하세요.

쿼리 설계 및 성능

• 모니터링 시스템에 과부하를 주지 않는 효율적인 Prometheus 쿼리를 작성하세요.
• 모델 규칙에 사용하기 전에 Prometheus 쿼리를 독립적으로 테스트하세요.
• 가능하면 특정 라벨 필터를 사용해 쿼리 범위를 줄이세요.
• 엔티티 정의의 카디널리티(cardinality) 영향을 고려하세요.
• 디버깅 중 문제가 있는 쿼리를 일시적으로 비활성화하려면 disabled 플래그를 사용하세요.

관계 및 강화

• lookup 매핑을 사용해 서로 다른 엔티티 유형 간 관계를 설정하세요.
• 엔티티 강화를 위한 추가 데이터 소스를 지정하려면 enriched_by를 활용하세요.
• 명확하고 설명적인 이름을 사용해 Prometheus 라벨을 엔티티 속성에 매핑하세요.
• 엔티티 식별에 도움이 되는 정적 메타데이터를 추가하려면 의미 있는 literals를 사용하세요.

라벨 및 속성 관리

• 인프라 전체에 일관된 라벨링 규칙을 정립하세요.
• 메트릭에서 동적 속성을 추출하려면 label_values를 사용하세요.
• 사용자 지정 리터럴의 의미와 예상 값을 문서화하세요.
• 관계 발견이 올바르게 되도록 서로 다른 엔티티 정의에서 라벨 이름이 일치하는지 확인하세요.

검증

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

• 사용자 지정 모델 규칙이 Knowledge Graph 인스턴스에 적용되었는지.
• 정의한 쿼리에 따라 엔티티가 발견되고 있는지.
• 엔티티 관계와 강화가 예상대로 작동하는지.
• 엔티티 그래프가 올바른 엔티티 유형과 연결을 표시하는지.
• 쿼리가 과도한 부하를 일으키지 않고 잘 수행되는지.

관련 문서

• Knowledge Graph에서 엔티티 및 관계 관리
• Knowledge Graph용 Terraform 시작하기
• Knowledge Graph 기초

더 알아보기 (Learn more)

• Knowledge Graph용 Terraform
• Knowledge Graph 기초