대시보드 설정

Sophonz 인프라의 Grafana 데이터소스와 대시보드를 프로비저닝하는 방법을 설명합니다.

Sophonz는 파일 기반 프로비저닝을 사용해 Grafana 데이터소스와 대시보드를 자동으로 등록합니다. v2에서는 Grafana Provisioning 서비스가 Sophonz 서비스·네임스페이스 메타를 기반으로 대시보드를 동적으로 생성하고 동기화합니다. 이 페이지에서는 관련 설정 파일의 구조와 커스터마이징 방법을 설명합니다.

디렉터리 구조

Grafana 프로비저닝 파일은 다음 위치에 마운트됩니다.

/etc/grafana/provisioning/
├── dashboards/
│   ├── dashboards.yml                      # 프로비저닝 정책
│   ├── sophonz-service.json                # Web 대시보드
│   ├── sophonz-service-ios.json            # iOS 대시보드
│   └── sophonz-service-test-payload.json   # 페이로드 검증 대시보드
└── datasources/
    └── datasources.yml                     # 데이터소스 정의

대시보드 프로비저닝 설정

dashboards.yml은 Grafana가 JSON 파일을 읽는 방식을 정의합니다.

configs/grafana/provisioning/dashboards/dashboards.yml

apiVersion: 1
 
providers:
  - name: 'default'
    type: file
    updateIntervalSeconds: 10
    options:
      path: /etc/grafana/provisioning/dashboards
      foldersFromFilesStructure: true

updateIntervalSeconds: 10 — 10초마다 디렉터리를 스캔해 신규·변경 대시보드를 자동으로 반영합니다.
foldersFromFilesStructure: true — 하위 디렉터리 이름을 Grafana 폴더로 사용합니다.

새 대시보드 추가

대시보드 JSON 파일을 프로비저닝 디렉터리에 복사하면 Grafana가 자동으로 임포트합니다.

cp my-dashboard.json /etc/grafana/provisioning/dashboards/

Kubernetes 환경에서는 shared-dashboards 볼륨을 통해 Sophonz 앱이 JSON 파일을 직접 기록하면 Grafana가 이를 감지합니다.

NOTE — 프로비저닝된 대시보드 수정

파일 프로비저닝으로 등록된 대시보드는 Grafana UI에서 저장 시 경고가 표시됩니다. 영구 수정이 필요하면 JSON 파일 자체를 업데이트하세요.

데이터소스 설정

datasources.yml은 Grafana가 시작 시 자동으로 로드하는 데이터소스를 정의합니다. ClickHouse FQDN 등 동적 값은 Terraform templatefile() 또는 동등한 배포 도구로 치환됩니다. 실제 설정 파일의 ${clickhouse_fqdn} 같은 플레이스홀더는 배포 시 클러스터 내부 서비스 주소로 대체됩니다.

configs/grafana/provisioning/datasources/datasources.yml

apiVersion: 1
 
datasources:
  # ClickHouse (공식 플러그인) — 기본 데이터소스
  - name: ClickHouse
    type: grafana-clickhouse-datasource
    uid: clickhouse
    access: proxy
    url: http://clickhouse.your-cluster.svc.cluster.local:8123
    database: sophonz
    user: default
    isDefault: true
    jsonData:
      defaultDatabase: sophonz
      protocol: http
      host: clickhouse.your-cluster.svc.cluster.local
      port: 8123
      logs:
        defaultDatabase: sophonz
        defaultTable: sophonz_logs
        otelEnabled: true
        otelVersion: "latest"
      traces:
        defaultDatabase: sophonz
        defaultTable: sophonz_traces
        otelEnabled: true
        otelVersion: "latest"
 
  # ClickHouse (Altinity 플러그인) — 보조 데이터소스
  - name: ClickHouse-Altinity
    type: vertamedia-clickhouse-datasource
    uid: clickhouse-altinity
    access: proxy
    url: http://clickhouse.your-cluster.svc.cluster.local:8123
    database: sophonz
    user: default
    jsonData:
      defaultDatabase: sophonz
      usePOST: false
      addCorsHeader: true
 
  # Prometheus
  - name: Prometheus
    type: prometheus
    uid: prometheus
    access: proxy
    url: http://prometheus.your-cluster.svc.cluster.local:9090
    jsonData:
      httpMethod: POST
      timeInterval: "15s"
 
  # PostgreSQL
  - name: PostgreSQL
    type: postgres
    uid: postgres
    access: proxy
    url: postgresql.your-cluster.svc.cluster.local:5432
    database: sophonz
    user: sophonz
    jsonData:
      sslmode: disable
      postgresVersion: 1500
      timescaledb: false
    secureJsonData:
      password: your-db-password

CAUTION — secureJsonData 관리

secureJsonData.password 같은 민감한 값은 Kubernetes Secret 또는 Vault를 통해 주입하세요. 설정 파일에 평문으로 기록하지 마세요.

Grafana 플러그인 설치

ClickHouse 데이터소스는 서드파티 플러그인이 필요합니다. GF_INSTALL_PLUGINS 환경 변수로 설정합니다.

env:
  - name: GF_INSTALL_PLUGINS
    value: "grafana-clickhouse-datasource,vertamedia-clickhouse-datasource"

Kubernetes Deployment에서는 컨테이너 env 섹션에 위 값을 추가합니다. Grafana 11.2.0 이미지를 사용하는 경우 두 플러그인 모두 자동으로 다운로드 및 활성화됩니다.

OAuth2 인증 설정 (Keycloak)

Grafana는 Keycloak Generic OAuth를 통해 SSO를 제공합니다. 환경 변수로 구성합니다.

env:
  - name: GF_AUTH_GENERIC_OAUTH_ENABLED
    value: "true"
  - name: GF_AUTH_GENERIC_OAUTH_NAME
    value: "Keycloak"
  - name: GF_AUTH_GENERIC_OAUTH_CLIENT_ID
    value: "grafana"
  - name: GF_AUTH_GENERIC_OAUTH_SCOPES
    value: "openid email profile"
  - name: GF_AUTH_GENERIC_OAUTH_AUTH_URL
    value: "https://auth.example.com/realms/sophonz/protocol/openid-connect/auth"
  - name: GF_AUTH_GENERIC_OAUTH_TOKEN_URL
    value: "https://auth.example.com/realms/sophonz/protocol/openid-connect/token"
  - name: GF_AUTH_GENERIC_OAUTH_API_URL
    value: "https://auth.example.com/realms/sophonz/protocol/openid-connect/userinfo"
  - name: GF_AUTH_GENERIC_OAUTH_ALLOW_SIGN_UP
    value: "true"

GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET은 Kubernetes Secret으로 분리해 관리하세요.

Kubernetes ConfigMap으로 대시보드 배포

Terraform을 사용하지 않는 환경에서는 kubectl로 ConfigMap을 직접 생성할 수 있습니다.

# 대시보드 프로비저닝 정책 ConfigMap
kubectl create configmap grafana-dashboards \
  --from-file=dashboards.yml \
  -n observability
 
# 대시보드 JSON 파일 ConfigMap
kubectl create configmap grafana-dashboard-files \
  --from-file=sophonz-service.json \
  --from-file=sophonz-service-ios.json \
  --from-file=sophonz-service-test-payload.json \
  -n observability
 
# 데이터소스 ConfigMap
kubectl create configmap grafana-datasources \
  --from-file=datasources.yml \
  -n observability

Grafana Pod의 volumeMounts에서 이 ConfigMap들을 /etc/grafana/provisioning/ 하위 경로에 마운트합니다.

volumeMounts:
  - name: grafana-datasources
    mountPath: /etc/grafana/provisioning/datasources
  - name: shared-dashboards
    mountPath: /etc/grafana/provisioning/dashboards

동적 대시보드 공유 볼륨

Sophonz 앱은 shared-dashboards 볼륨을 통해 런타임에 대시보드 JSON을 생성하고 Grafana에 전달할 수 있습니다.

sophonz-app:/app/provisioned-dashboard  ←→  shared-dashboards  ←→  grafana:/etc/grafana/provisioning/dashboards

앱이 /app/provisioned-dashboard에 JSON 파일을 기록하면 Grafana가 10초 이내에 자동으로 감지하고 임포트합니다.

v2: Grafana Provisioning 서비스

NOTE — v2 계획

아래 내용은 v2 로드맵에 해당합니다. 현재는 정적 파일 프로비저닝만 운영 중입니다.

v2에서는 Grafana Provisioning 마이크로서비스가 정적 JSON 파일을 대체합니다. 이 서비스는 다음을 담당합니다.

자동 동기화 — Sophonz Management 서비스의 서비스·네임스페이스 메타를 읽어 Grafana 데이터소스·폴더·대시보드를 자동으로 생성·갱신합니다 (POST /provision/sync).
템플릿 대시보드 — 서비스 상세, RUM 요약, 에러 트렌드 등 표준 템플릿을 제공하며, 신규 서비스 등록 시 자동으로 대시보드를 생성합니다.
임베드 URL 발급 — Sophonz Dashboard에 Grafana 패널을 삽입하기 위한 서명된 URL을 발급합니다 (POST /dashboards/embed-url).
변경 감지 재프로비저닝 — GitOps 패턴과 유사하게, 서비스 메타 변경 시 자동으로 대시보드를 재동기화합니다.

온프레미스 환경에서는 고객사 자체 Grafana 인스턴스와 연동하여 동일한 프로비저닝 흐름을 적용할 수 있습니다.