Git Sync에서 프로비저닝된 저장소 다루기

참고

Git Sync 기능은 계속 진화하고 있어요. 이 기능을 개선하는 데 도움이 되도록 Grafana에 지원을 요청하거나 문제를 신고해 주세요.

리소스를 동기화한 후 Git Sync는 리소스, 상태(health), 풀(pull) 상태, 웹훅, 동기화 작업, 리소스, 파일에 대한 요약을 제공하는 대시보드를 생성해요. 이 대시보드에 접근하려면 다음 단계를 따르세요:

Grafana Admin 플래그가 설정된 계정으로 Grafana 서버에 로그인하세요.
왼쪽 메뉴에서 Administration > General > Provisioning을 선택해 Git Sync 구성 화면에 접근하세요.
Repositories 탭으로 이동해 작업할 저장소를 찾으세요. 동기화의 현재 상태를 보거나, 풀을 실행하거나, 설정을 업데이트할 수 있어요.

프로비저닝된 파일을 다루는 방법에 대한 자세한 내용은 프로비저닝된 대시보드 다루기 문서를 참고하세요.

출처: 문서

본문

동기화된 저장소의 현재 상태 보기

View 섹션을 사용해 동기화의 현재 상태에 대한 자세한 정보를 보고 가능한 문제를 해결하세요:

Overview 탭에는 저장소와 Grafana 간 연결 상태, 웹훅 같은 구성 옵션, Git 프로세스에 대한 정보가 포함돼요.
Resources 탭에는 연결의 프로비저닝된 리소스가 나열돼요.

동기화 문제 해결

참고

문제 해결을 진행하기 전에 사용 및 성능 알려진 제한 사항을 이해하세요.

동기화 문제와 상태 업데이트를 모니터링하려면 View 상태 페이지를 확인하세요. 상태 페이지에는 다음 이벤트가 표시돼요:

Sync started: 동기화 프로세스가 시작됨.
Sync completed: 동기화 프로세스가 성공적으로 완료됨.
Sync failed: 동기화 프로세스가 실패함. 문제 해결을 위해 오류 세부 정보를 참고하세요.
Sync issues: 동기화 프로세스에서 문제가 발생함.

대시보드 동기화 오류

저장소 URL: 대시보드가 동기화되지 않으면 저장소 URL이 올바르고 Grafana 인스턴스에서 접근 가능한지 확인하세요.
저장소 브랜치: 구성된 저장소 브랜치가 존재하고 올바르게 참조되는지 확인하세요.
충돌: 동기화를 방해할 수 있는 저장소의 충돌을 확인하세요.

대시보드 가져오기 오류

가져오기 전에 대시보드 파일의 JSON 형식을 검증하세요.
가져오기가 실패하면 Grafana 로그에서 오류 메시지를 확인하고 그에 따라 문제를 해결하세요.

변경 사항 동기화

프로비저닝된 저장소와 Grafana 인스턴스 간 리소스를 동기화하려면 동기화하려는 저장소 아래의 Pull을 클릭하세요. 동기화 프로세스가 실행되고 완료돼요.

Grafana는 동일한 uid를 가진 기존 대시보드를 덮어써요.

설정 업데이트 또는 삭제

설정을 완료한 후 저장소 구성을 업데이트하거나 삭제하려면:

Grafana Admin 플래그가 설정된 계정으로 Grafana 서버에 로그인하세요.
Administration > General > Provisioning을 선택하세요.
Repositories 탭으로 이동해 수정할 저장소를 찾으세요.
Settings를 선택해 Configure repository 화면에 접근하세요:
- 구성을 수정하려면 설정 중 하나를 업데이트하고 Save를 선택하세요.
- 저장소를 삭제하려면 Delete를 클릭하세요. 동기화된 리소스를 유지하거나 삭제할 수 있어요.

참고

변경 사항이 화면에 반영되는 데 몇 분이 걸릴 수 있어요. 반영되지 않으면 UI를 수동으로 새로 고치세요.

폴더 권한 관리

기본적으로 사용자는 Git Sync로 프로비저닝된 폴더에서 자신의 역할을 유지해요.

Grafana 역할	폴더 권한
Admin	Admin
Editor	Editor
Viewer	Viewer

Git Sync에서 권한을 이해하고 설정하려면 Git Sync 권한 문서를 참고하세요.

폴더 권한 수정

참고

권한을 수정하려면 각 프로비저닝된 폴더에 _folder.json 메타데이터 파일이 포함되어 있어야 해요. 이 파일은 폴더에 안정적인 UID를 부여해요. 이 파일이 없으면 Git 저장소에서 해당 폴더를 이동하거나 이름을 바꿀 때 폴더의 권한이 손실돼요. 이 파일과 파일이 존재하는 이유에 대한 자세한 내용은 Git Sync 폴더 메타데이터 파일을 참고하세요.

폴더 권한은 저장소 경로가 아니라 폴더의 UID(_folder.json에 저장됨)에 연결돼요. 따라서 Git Sync가 폴더를 만든 후에만 권한을 설정할 수 있어요. 폴더 권한을 추가하거나 수정하려면:

UI에서 오른쪽 상단의 Folder actions > Manage permissions를 선택하세요.
API를 사용하려면 대시보드 권한 API를 참고하세요.
코드로 Terraform을 사용하려면 _folder.json의 폴더 UID를 사용하세요. 수동 및 Terraform 예시는 폴더 수준 권한 수정을 참고하세요.

Git Sync 폴더 메타데이터 파일

동기화된 저장소의 각 프로비저닝된 폴더에는 그 루트에 _folder.json 메타데이터 파일이 포함돼요. 이 파일은 폴더의 매니페스트 역할을 해요. 저장소 레이아웃이 변경되어도 유지되는 폴더의 안정적인 UID와 표시 이름을 저장해요.

이 파일이 존재하는 이유는 디렉터리 경로가 안정적인 식별자가 아니기 때문이에요. _folder.json이 없으면 Grafana는 저장소의 디렉터리 경로 해시에서 폴더 UID를 파생해요. Git에서 해당 디렉터리를 이동하거나 이름을 바꾸면 해시가 변경되어 Grafana는 이를 다른 폴더로 취급해요. 사용자 지정 폴더 권한, 북마크, API 참조 등 이전 UID에 연결된 모든 것이 손실돼요. _folder.json을 사용하면 UID가 디렉터리와 함께 이동하므로 권한이나 참조를 깨지 않고 저장소를 재구성할 수 있어요.

이 파일은 또한 폴더의 표시 이름을 디렉터리 이름과 분리해요. 디렉터리는 파일 시스템에 친숙한 이름(예: team-platform)을 유지하고, spec.title 필드는 Grafana UI에 표시되는 이름(예: Team Platform)을 담아요.

Grafana가 이 파일을 관리해요:

Grafana UI에서 프로비저닝된 폴더를 만들면 Git Sync는 _folder.json 파일을 폴더와 함께 커밋해요.
Grafana에서 폴더 이름을 바꾸면 Git Sync는 파일의 spec.title 필드를 업데이트해요.
폴더에 파일이 없으면(예: Git에서 직접 디렉터리를 만든 경우) Grafana는 해시 기반 UID로 대체하고 누락된 메타데이터를 추가하는 방법에 대한 지침과 함께 UI에 경고를 표시해요.

이 파일의 형식은 다음과 같아요:

{
  "apiVersion": "",
  "kind": "Folder",
  "metadata": {
    "name": ""
  },
  "spec": {
    "title": ""
  }
}

여기서:

apiVersion은 폴더 API의 버전이에요. 예: folder.grafana.app/v1.
metadata.name은 Grafana가 권한, 북마크, API 참조에 사용하는 안정적인 폴더 UID예요. 이 값을 불변(immutable)으로 취급하세요. Grafana는 폴더 UID 변경을 거부하며, Git에서 직접 변경하면 디렉터리와 기존 Grafana 폴더 간 연결이 끊어져 메타데이터 파일이 없는 것과 같은 결과가 발생해요.
spec.title은 Grafana UI에 표시되는 표시 이름이에요. 이 필드는 선택 사항이에요. 설정하지 않으면 Grafana는 대신 디렉터리 이름을 사용해요.

Git Sync에서 프로비저닝된 저장소 다루기