Git Sync 핵심 개념

Git Sync 핵심 개념

이 문서에서는 Git Sync의 핵심 개념을 소개합니다. Grafana 인스턴스, Git 리포지토리, Git Sync 리포지토리 리소스, Git Sync 커넥션 리소스 같은 구성 요소들이 어떻게 연결되는지, 그리고 Git Sync가 어떻게 동작하는지 설명해요.

출처: 문서

본문

참고 Git Sync 기능은 지속적으로 발전하고 있어요. 지원이나 문제 보고는 Grafana에 문의해 이 기능을 개선하는 데 도움을 주세요.

핵심 Git Sync 구성 요소

Git Sync를 사용하기 전에 핵심 Git Sync 구성 요소들이 어떻게 연결되는지 이해하세요:

Grafana 인스턴스

Grafana 인스턴스는 실행 중인 Grafana 서버예요. 여러 인스턴스는 다음을 할 수 있어요:

  • 서로 다른 Repository 구성을 사용해 같은 Git 리포지토리에 연결할 수 있어요.
  • 같은 리포지토리의 서로 다른 브랜치에서 동기화할 수 있어요.
  • 같은 리포지토리 안의 서로 다른 경로에서 동기화할 수 있어요.
  • 서로 다른 리포지토리에서 동기화할 수 있어요.

Git 리포지토리

Git 리포지토리는 Grafana 인스턴스와 동기화하려는 외부 저장소예요. Git 리포지토리를 여러 방식으로 구성할 수 있어요:

  • 단일 브랜치, 여러 경로: 서로 다른 목적에 서로 다른 디렉터리를 사용해요. 예를 들어 dev/, prod/, 또는 team-a/.
  • 여러 브랜치: 서로 다른 환경이나 팀에 서로 다른 브랜치를 사용해요. 예를 들어 main, develop, 또는 team-a.
  • 여러 리포지토리: 서로 다른 팀이나 환경에 별도의 리포지토리를 사용해요.

Git Sync 리포지토리를 위한 유연한 구성

Git Sync 리포지토리는 리포지토리 URL, 브랜치, 경로의 다양한 조합을 지원해요:

  • 서로 다른 Git 리포지토리: 각 환경이나 팀이 자체 리포지토리를 사용할 수 있어요.
    • 인스턴스 A: repository: your-org/grafana-prod.
    • 인스턴스 B: repository: your-org/grafana-dev.
  • 서로 다른 브랜치: 같은 리포지토리 안에서 별도의 브랜치를 사용해요.
    • 인스턴스 A: repository: your-org/grafana-manifests, branch: main.
    • 인스턴스 B: repository: your-org/grafana-manifests, branch: develop.
  • 서로 다른 경로: 같은 리포지토리 안에서 서로 다른 디렉터리 경로를 사용해요.
    • 인스턴스 A: repository: your-org/grafana-manifests, branch: main, path: production/.
    • 인스턴스 B: repository: your-org/grafana-manifests, branch: main, path: development/.
  • 모든 조합: 워크플로 요구 사항에 따라 조합해서 사용해요.

Git Sync 리포지토리 리소스

리포지토리 리소스는 Git Sync를 통해 리포지토리 그룹과 Grafana 인스턴스 간의 연결을 정의하는 Grafana 구성 객체예요.

  • Grafana 인스턴스와 동기화할 Git 리포지토리가 무엇인지.
  • 어떤 브랜치를 사용할지.
  • 어떤 디렉터리 경로를 동기화할지.
  • 동기화 동작과 워크플로.

각 리포지토리 리소스는 Grafana 인스턴스와 Git의 특정 위치 사이에 양방향 동기화를 만들어요.

Git Sync 커넥션 리소스

커넥션은 Grafana와 외부 Git 프로바이더 사이의 인증 설정이에요. Personal Access Token이나 정적 토큰으로 인증하지 않을 때 필요해요. 외부 리포지토리에 대한 접근을 승인하고, Git Sync의 자격 증명을 생성하거나 새로고침하는 데 사용해요. 단일 커넥션은 여러 리포지토리에서 재사용할 수 있어요.

예를 들어 GitHub App으로 인증하는 경우, 커넥션은 앱 설치를 나타내요. Grafana는 이 커넥션을 사용해 GitHub로 인증하고, 접근 토큰을 만들고, 사용자를 대신해 리포지토리 접근을 승인해요.

커넥션 리소스는 다음을 포함해요:

  • 외부 프로바이더 구성: Grafana가 Git 프로바이더(예: GitHub App)와 통신하는 데 사용하는 인증 메커니즘.
  • 프로바이더 승인 또는 설치: Grafana가 프로바이더에 토큰을 요청할 수 있게 해주는 권한 있는 엔터티.
  • 리포지토리 접근 범위: 커넥션(따라서 Grafana)이 Git 프로바이더에서 접근하도록 승인된 리포지토리 집합.

Git Sync는 어떻게 동작하나요?

Git Sync는 양방향이며 리포지토리 리소스를 Grafana 인스턴스와 동기화해요. 프로비저닝된 리소스를 Grafana UI에서 또는 동기화된 GitHub 리포지토리에서 수정할 수 있고, 변경 사항은 두 곳 모두에 반영돼요:

  1. Grafana가 지정된 Git 위치(리포지토리, 브랜치, 경로)를 모니터링해요.
  2. Grafana는 Dashboards에 폴더(보통 리포지토리 이름을 따서)를 만들어요.
  3. Grafana는 이 폴더 안의 Git에 있는 대시보드 JSON 파일로 대시보드를 만들어요.
  4. Grafana는 UI에서 만든 대시보드 변경 사항을 Git에 다시 커밋해요.
  5. Grafana는 Git에서 만든 대시보드 변경 사항을 가져와 UI의 대시보드를 업데이트해요.
  6. 동기화는 정기적인 간격(구성 가능)으로, 또는 웹훅을 사용하면 즉시 발생해요.

프로비저닝된 대시보드는 Dashboards 아래 폴더에 정리되어 있는 것을 찾을 수 있어요.

동기화 대상(Sync targets)

Git Sync로 동기화된 리소스를 Grafana에 두 가지 방식으로 배치할 수 있어요:

  • 폴더 동기화(Folder sync): Grafana가 리포지토리 이름을 따서 폴더를 만들고 모든 동기화된 리소스를 그 안에 배치해요. 리포지토리의 하위 디렉터리는 그 폴더 안의 하위 폴더가 돼요. 이것이 기본 동작이에요.
  • 폴더 없는 동기화(Folderless sync): Grafana가 래퍼 폴더를 만들지 않고 동기화된 리소스를 최상위 수준에 배치해요. 리포지토리 경로 루트의 파일은 최상위 수준 리소스가 되고, 하위 디렉터리는 최상위 수준 폴더가 돼요.

리포지토리 각각의 리소스를 전용 폴더 아래에 함께 그룹화하려면 폴더 동기화를 사용하세요. 프로비저닝된 리소스가 리포지토리 폴더 안에 중첩되지 않고 Dashboards 보기의 맨 위에 나타나길 원한다면 폴더 없는 동기화를 사용하세요.

두 모드는 서로, 그리고 Git Sync로 관리되지 않는 리소스와도 공존할 수 있어요.

다음 예제는 같은 리포지토리를 사용해 각 모드에서 같은 파일이 어떻게 보이는지 보여줘요.

리포지토리 grafana-manifests가 경로 grafana/에서 동기화해요:

your-org/grafana-manifests/
└── grafana/
    ├── cpu-metrics.json
    └── team-platform/
        ├── _folder.json
        └── memory-usage.json

_folder.json 파일은 team-platform 폴더의 안정적인 UID와 표시 이름을 저장해요. 그래서 리포지토리에서 폴더를 이동하거나 이름을 바꿔도 폴더의 정체성과 권한이 유지돼요. 자세한 내용은 The Git Sync folder metadata file을 참고하세요.

인스턴스에는 Git Sync로 관리되지 않는 내용도 있어요: 수동으로 만든 Ops 폴더와 Ad-hoc dashboard.

폴더 동기화를 사용하면, 리포지토리 폴더가 프로비저닝되지 않은 내용과 함께 동기화된 리소스를 감싸요:

Dashboards
├── 📁 grafana-manifests/      ← managed by Git Sync
│   ├── CPU Metrics Dashboard
│   └── 📁 team-platform/
│       └── Memory Usage Dashboard
├── 📁 Ops/                    ← not managed by Git Sync
│   └── Ops dashboard
└── Ad-hoc dashboard           ← not managed by Git Sync

폴더 없는 동기화를 사용하면, 같은 파일이 프로비저닝되지 않은 내용 옆의 최상위 수준에 매핑돼요:

Dashboards
├── CPU Metrics Dashboard      ← managed by Git Sync
├── 📁 team-platform/          ← managed by Git Sync
│   └── Memory Usage Dashboard
├── 📁 Ops/                    ← not managed by Git Sync
│   └── Ops dashboard
└── Ad-hoc dashboard           ← not managed by Git Sync

폴더 없는 동기화는 자체가 프로비저닝한 리소스만 관리해요. 프로비저닝되지 않은 Ops 폴더와 Ad-hoc dashboard는 건드리지 않아요.

여러 폴더 없는 리포지토리

폴더 없는 동기화는 래퍼 폴더를 만들지 않기 때문에, 여러 폴더 없는 리포지토리가 동시에 최상위 수준에 동기화될 수 있어요. 각 리포지토리는 자체가 프로비저닝한 리소스만 관리해요:

Dashboards
├── CPU Metrics Dashboard      ← managed by grafana-manifests
├── 📁 team-platform/          ← managed by grafana-manifests
│   └── Memory Usage Dashboard
├── Billing Overview           ← managed by finance-dashboards
├── 📁 invoices/               ← managed by finance-dashboards
│   └── Monthly Invoices
└── Ad-hoc dashboard           ← not managed by Git Sync

Git Sync 상태

Grafana 인스턴스는 다음 Git Sync 상태 중 하나일 수 있어요:

  • Unprovisioned(미프로비저닝): 인스턴스의 어떤 리소스도 Git Sync로 관리되지 않아요.
  • Partially provisioned(부분 프로비저닝): 일부 리소스가 Git Sync로 제어돼요.
  • Fully provisioned(완전 프로비저닝): 지원되는 모든 리소스 유형이 Git Sync로 관리돼요. 지원되지 않는 리소스는 관리되지 않아요.

예제: 리포지토리, 브랜치, 경로의 관계

다음은 리포지토리, 브랜치, 경로 개념이 어떻게 함께 동작하는지 보여주는 예제예요.

구성:

  • Repository: your-org/grafana-manifests
  • Branch: main
  • Path: team-platform/grafana/

Git(main 브랜치에서):

your-org/grafana-manifests/
├── .git/
├── README.md
├── team-platform/
│   └── grafana/
│       ├── cpu-metrics.json       ← Synced
│       ├── memory-usage.json      ← Synced
│       └── disk-io.json           ← Synced
├── team-data/
│   └── grafana/
│       └── pipeline-stats.json    ← Not synced (different path)
└── other-files.txt                ← Not synced (outside path)

Grafana Dashboards 보기에서:

Dashboards
└── 📁 grafana-manifests/
    ├── CPU Metrics Dashboard
    ├── Memory Usage Dashboard
    └── Disk I/O Dashboard

핵심 요점:

  • Grafana는 지정된 경로(team-platform/grafana/) 안의 파일만 동기화해요.
  • Grafana는 다른 경로나 리포지토리 루트의 파일은 무시해요.
  • Grafana의 폴더 이름은 리포지토리 이름에서 나와요.
  • 대시보드 제목은 파일 이름이 아니라 JSON 파일 내용에서 나와요.

더 알아보기