CI/CD로 대시보드 프로비저닝 자동화
CI/CD로 대시보드 프로비저닝 자동화 (Automate dashboard provisioning with CI/CD)
Grafana 대시보드를 수동으로 관리하는 것은 비효율적이고 오류가 발생하기 쉬울 수 있어요. Grafana Foundation SDK로 강력한 타입의 코드를 사용해 대시보드를 정의하고, 버전 관리 시스템에 커밋하고, GitHub Actions로 자동 배포할 수 있어요.
출처: 문서
본문
Grafana 대시보드를 수동으로 관리하는 것은 비효율적이고 오류가 발생하기 쉬울 수 있어요. Grafana Foundation SDK로 강력한 타입의 코드를 사용해 대시보드를 정의하고, 버전 관리 시스템에 커밋하고, GitHub Actions로 자동 배포할 수 있어요.
왜 자동화하나요? (Why automate?)
Grafana 대시보드 배포를 자동화하면 수동 대시보드 생성과 업데이트가 필요 없어져 환경 간에 대시보드가 일관되게 유지되는 것을 보장해요.
대시보드를 코드로 방어하고 GitHub Actions 같은 CI/CD로 관리하면 완전한 버전 관리의 이점을 얻어 시간 경과에 따른 변경 사항을 추적하고 필요시 롤백하기 쉬워요. 또한 워크플로가 대시보드를 생성할지 업데이트할지 결정하기 전에 대시보드가 존재하는지 지능적으로 확인하므로 중복도 방지해요.
이 완전 자동화된 CI/CD 파이프라인으로 JSON 파일을 Grafana에 수동으로 업로드하는 대신 대시보드 개선에 집중할 수 있어요.
전체 예제 소스 코드는 Introduction to the Foundation SDK GitHub 저장소에서 찾을 수 있어요.
개요 (Overview)
이 가이드는 다음 방법을 보여줘요:
- Grafana 대시보드를 코드로 생성하고 Kubernetes 스타일 배포용으로 포맷해요
- GitHub Actions를 사용해 대시보드를 배포, 검증, 업데이트해요
끝나면 대시보드를 코드로 프로비저닝할 수 있고, 대시보드에 대한 모든 변경이 수동 개입 없이 Grafana 인스턴스에 자동으로 생성되거나 업데이트돼요.
1. 대시보드 JSON 생성 (1. Generate the dashboard JSON)
대시보드를 배포하기 전에 Grafana Foundation SDK를 사용해 코드로 정의해요.
Grafana는 Kubernetes 리소스 호환 API를 노출하므로 대시보드 JSON을 적절한 형식으로 출력하려면 코드를 몇 가지 변경해야 해요.
이 스크립트는:
- Grafana 대시보드 JSON 파일을 생성해요
- Kubernetes 스타일 API 형식(
apiVersion,kind,metadata,spec)으로 감싸요 - 배포용
dashboard.json으로 저장해요
Go
typescript
Go
package main
import (
"encoding/json"
"log"
"os"
"github.com/grafana/grafana-foundation-sdk/go/cog"
"github.com/grafana/grafana-foundation-sdk/go/common"
"github.com/grafana/grafana-foundation-sdk/go/dashboard"
)
type DashboardWrapper struct {
APIVersion string `json:"apiVersion"`
Kind string `json:"kind"`
Metadata Metadata `json:"metadata"`
Spec dashboard.Dashboard `json:"spec"`
}
type Metadata struct {
Name string `json:"name"`
}
func main() {
builder := dashboard.NewDashboardBuilder("My Dashboard").
Uid("my-dashboard").
Tags([]string{"generated", "foundation-sdk", "go"}).
Refresh("5m").
Time("now-1h", "now").
Timezone(common.TimeZoneBrowser).
WithRow(dashboard.NewRowBuilder("Overview"))
dashboard, err := builder.Build()
if err != nil {
log.Fatalf("failed to build dashboard: %v", err)
}
dashboardWrapper := DashboardWrapper{
APIVersion: "dashboard.grafana.app/v1",
Kind: "Dashboard",
Metadata: Metadata{
Name: *dashboard.Uid,
},
Spec: dashboard,
}
dashboardJson, err := json.MarshalIndent(dashboardWrapper, "", " ")
if err != nil {
log.Fatalf("failed to marshal dashboard: %v", err)
}
err = os.WriteFile("dashboard.json", dashboardJson, 0644)
if err != nil {
log.Fatalf("failed to write dashboard to file: %v", err)
}
log.Printf("Dashboard JSON:\n%s", dashboardJson)
}
typescript
import { DashboardBuilder, RowBuilder } from '@grafana/grafana-foundation-sdk/dashboard';
import * as fs from 'fs';
// Generate the dashboard JSON
const dashboard = new DashboardBuilder('My Dashboard')
.uid('my-dashboard')
.tags(['generated', 'foundation-sdk', 'typescript'])
.refresh('5m')
.time({ from: 'now-1h', to: 'now' })
.timezone('browser')
.withRow(new RowBuilder('Overview'))
.build();
// Convert to Kubernetes-style format
const dashboardWrapper = {
apiVersion: "dashboard.grafana.app/v1",
kind: "Dashboard",
metadata: {
name: dashboard.uid!
},
spec: dashboard
};
// Save the formatted JSON to a file
const dashboardJSON = JSON.stringify(dashboardWrapper, null, 2);
fs.writeFileSync('dashboard.json', dashboardJSON, 'utf8');
console.log(`Dashboard JSON:\n${}`);
2. GitHub Actions로 배포 자동화 (2. Automate deployment with GitHub Actions)
다음으로 Foundation SDK와 gcx CLI 도구를 사용해 Grafana 대시보드 배포를 자동화하도록 GitHub Actions를 설정해요:
dashboard.json에서 대시보드 이름을 추출해요- Grafana 인스턴스에 대시보드가 이미 존재하는지 확인해요
- 있으면 업데이트하고, 없으면 생성해요
Note 다음 GitHub Action 구성은 Go 기반 대시보드 생성기를 사용한다고 가정해요. Foundation SDK가 지원하는 다른 언어 중 하나를 사용한다면 Generate Dashboard JSON 단계를 그에 맞게 수정해요.
.github/workflows/deploy-dashboard.yml 배포 워크플로는 다음과 같아요:
YAML
name: Deploy Grafana Dashboard
on:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Set up Go
uses: actions/setup-go@v5
with:
go-version: 1.24.6
- name: Verify Go version
run: go version
- name: Download and Extract gcx
run: |
curl -L -o gcx-x86_64.tar.gz "https://github.com/grafana/gcx/releases/download/${{ vars.GCX_VERSION }}/gcx_Linux_x86_64.tar.gz"
tar -xzf gcx-x86_64.tar.gz
chmod +x gcx
sudo mv gcx /usr/local/bin/gcx
- name: Generate Dashboard JSON
working-directory: ./github-actions-example
run: go run main.go
- name: Deploy Dashboard with gcx
env:
GRAFANA_SERVER: ${{ vars.GRAFANA_SERVER }}
GRAFANA_STACK_ID: ${{ vars.GRAFANA_STACK_ID }}
GRAFANA_TOKEN: ${{ secrets.GRAFANA_TOKEN }}
run: |
if [ -f dashboard.json ]; then
echo "dashboard.json exists, deploying dashboard."
gcx resources push dashboards --path ./dashboard.json
else
echo "dashboard.json does not exist."
exit 1
fi
working-directory: ./github-actions-example
1. Checkout과 Go 설정 (1. Checkout and set up Go)
Go를 설정하려면:
- 저장소를 체크아웃해 프로젝트 코드에 접근해요.
actions/setup-go액션으로 Go 1.24.6을 설치해요.- Go가 제대로 설치되었는지 확인해요.
2. gcx 다운로드와 설치 (2. Download and install gcx)
다음으로 vars.GCX_VERSION에 정의된 버전을 사용해 GitHub에서 gcx CLI를 다운로드해요. tarball을 풀고 실행 가능하게 만든 뒤 시스템 PATH의 위치로 이동해요.
3. 대시보드 JSON 생성 (3. Generate the dashboard JSON)
다음으로 ./github-actions-example 디렉터리에서 대시보드 생성기(main.go)를 실행해 Grafana 대시보드 정의가 담긴 dashboard.json 파일을 만들어요.
4. gcx로 대시보드 배포 (4. Deploy the dashboard with gcx)
dashboard.json이 이미 존재하면 다음을 사용해 Grafana 인스턴스에 배포돼요:
Bash
gcx resources push dashboards --path ./dashboard.json
이 명령어는 다음 환경 변수를 사용해 Grafana에 인증해요:
GRAFANA_SERVER: Grafana 인스턴스 URLGRAFANA_STACK_ID: Grafana 스택 IDGRAFANA_TOKEN: 충분한 권한이 있는 Grafana 서비스 계정 토큰
사용된 GitHub 변수와 시크릿 (GitHub variables and secrets used)
이 변수들이 Settings > Security > Secrets and variables > Actions 아래 저장소에 구성되어 있는지 확인해요:
vars.GCX_VERSION: 설치할gcx버전vars.GRAFANA_SERVER: Grafana 인스턴스의 URLvars.GRAFANA_STACK_ID: Grafana의 스택 IDsecrets.GRAFANA_TOKEN: Grafana API 토큰
이 액션은 main에 대한 모든 푸시가 최신 대시보드 정의를 재생성하고 Grafana에 배포하도록 보장해요.