Grafana에서 비프로비저닝 리소스 추가하기

Grafana에서 비프로비저닝 리소스 추가하기

참고: Git Sync 기능은 계속 진화하고 있어요. 지원을 받거나 발견한 문제를 보고해 이 기능 개선에 도움을 주려면 Grafana에 문의하세요.

기존의 비프로비저닝 리소스로 하고 싶은 일은 두 가지가 있고, 동작 방식이 서로 달라요:

  • 개별 대시보드 체리픽(Cherry-pick): 선택한 대시보드의 복사본을 프로비저닝된 폴더에 추가해요. Grafana가 새 UID를 가진 새 대시보드를 만들고, 원본은 그대로 두며 기존 링크도 계속 원본을 가리켜요. 가장 간단한 옵션이고 아무것도 삭제할 필요 없어요.
  • 기존 대시보드 마이그레이션: UID를 유지한 채 기존 대시보드를 Git Sync 아래로 옮겨서 기존 링크와 참조가 계속 동작하게 해요. 이 옵션은 리소스를 그 자리에서 채택하고 원본 리소스를 삭제해야 하므로 각별한 주의가 필요해요.

참고: Git Sync는 대시보드와 폴더만 관리해요. 알림(Alerts), 데이터 소스, 라이브러리 패널은 아직 지원되지 않아요. 마이그레이션할 때 이 점을 유의하세요. 자세한 내용은 시작하기 전에를 참고하세요.

출처: 문서

본문

개별 대시보드 체리픽하기

이 방법들로 대시보드 하나 이상의 복사본을 프로비저닝된 폴더에 추가할 수 있어요. 각 복사본은 새 UID로 만들어져서 원본 대시보드는 정확히 그대로 남고 아무것도 삭제할 필요 없어요. 기존 링크는 복사본이 아니라 원본 대시보드를 계속 가리켜요.

  • Import dashboards로 대시보드 추가하기
  • Grafana UI에서 기존 대시보드 복사하기

Import dashboards로 대시보드 추가하기

Grafana UI 또는 HTTP API로 대시보드를 Git Sync 프로비저닝 폴더에 직접 가져올 수 있어요.

Git Sync UI에서 Import dashboard 도구에 접근하려면:

  • 연결의 Dashboards 탭으로 가요.
  • 오른쪽 위에서 New를 클릭해요.
  • Import dashboard를 선택하면 마법사로 리다이렉트돼요.
  • 대시보드 JSON을 업로드하거나 붙여넣어요.
  • 브랜치와 저장소 폴더를 포함한 관련 필드를 채우고 Import를 눌러요.
  • 풀 리퀘스트를 열고 평소 워크플로우를 따르고 병합해요. 가져온 대시보드가 나타나기까지 몇 분 걸릴 수 있어요.

다음을 유의하세요:

  • 일반 대시보드 JSON을 가져오면 새 UID를 가진 새 대시보드가 만들어져요. 원본 UID를 보존하려면(마이그레이션용) 마법사에서 UID를 제공하거나 이미 metadata.name을 설정한 리소스 파일을 가져오세요. 기존 대시보드 마이그레이션하기 참고.
  • UID는 조직별로 전역 고유해요. UID를 공유하는 대시보드가 있는 두 저장소는 충돌해요.
  • 두 대시보드는 저장소에서 서로 다른 경로에 있으면 같은 제목을 공유할 수 있어요. 대상 경로에 같은 이름의 파일이 이미 있으면 아무것도 덮어쓰기 전에 가져오기가 중단돼요.

자세한 내용은 Data Visualization 문서의 Import dashboards를 참고하세요.

참고: 변경 사항이 화면에 반영되기까지 몇 분 걸릴 수 있어요. 반영되지 않으면 UI를 수동으로 새로고침하세요.

Grafana UI에서 기존 대시보드 복사하기

Grafana UI에서 직접 대시보드 복사본을 프로비저닝 폴더에 저장할 수도 있어요. 새 UID를 가진 새 대시보드를 만들고 원본은 그대로 둬요.

이렇게 하려면:

  • 대시보드가 Editable 모드인지 확인해요.
  • 오른쪽 위에서 Save 또는 Save as를 선택해요.
  • 메뉴에서:
    • Target folder: 대시보드를 저장할 Grafana UI의 프로비저닝 폴더를 선택해요.
    • Branch: 작업할 프로비저닝 저장소의 브랜치 이름을 입력하거나 새 브랜치를 만들어요. main에 직접 커밋하는 것은 지원되지 않아요.
    • Folder: 동기화 저장소의 폴더가 있으면 입력해요.
  • 나머지 필드를 알맞게 채워요.
  • Save를 클릭해요.
  • 동기화된 GitHub 저장소에서 동기화할 대시보드가 든 브랜치를 병합해요.

기존 대시보드를 Git Sync로 마이그레이션하기

마이그레이션 옵션은 UID를 유지한 채 기존 대시보드를 Git Sync 아래로 옮겨서 기존 링크, 참조, 북마크가 계속 동작하게 해요. UID가 보존되므로 Git Sync는 리소스를 그 자리에서 채택하고, Git Sync가 UID를 인계받으려면 원본 리소스를 삭제해야 해요.

마이그레이션은 다음 단계를 따라 진행돼요:

  • 시작하기 전에: 인스턴스를 백업하고 Git Sync가 무엇을 관리하는지 이해해요.
  • 1단계: 저장소로 리소스 내보내기: UID를 보존한 채 내보내고 커밋해요.
  • 2단계: 원본 대시보드 삭제하기: Git Sync가 UID별로 각 대시보드를 채택하려면 필요해요.
  • 3단계: 마이그레이션 검증하기: 넘어가기 전에 리소스가 동기화됐는지 확인해요.

시작하기 전에

Git Sync는 대시보드와 폴더만 관리해요. 알림, 데이터 소스, 라이브러리 패널, 기타 리소스는 아직 지원되지 않아서 Git Sync가 다시 만들지 않아요. 마이그레이션은 리소스 삭제를 수반하므로 시작 전에 신중히 계획하세요.

Git Sync는 기존 저장소와 동기화할 때 자기만의 폴더를 만들어요. 저장소의 폴더 경로에서 각 폴더의 UID를 파생시키므로, 만드는 폴더는 같은 이름을 공유하더라도 기존 폴더와 무관한 새 폴더예요. 그 결과:

  • 안쪽 대시보드를 마이그레이션하려고 원본 폴더를 삭제할 필요 없어요.
  • 알림이나 라이브러리 패널이 든 폴더는 삭제하지 마세요. Git Sync는 그런 것을 관리하지 않고, 폴더를 삭제하면 영구 삭제돼요.

주의: 폴더를 삭제하면 그 안의 모든 것(알림 규칙, 라이브러리 패널 같은 지원되지 않는 리소스 포함)이 삭제돼요. Git Sync는 대시보드와 폴더는 다시 만들지만 알림이나 라이브러리 패널은 다시 만들지 않아요. 저장소 구조에 맞추려고 폴더를 삭제하거나 다시 만들면 그 안의 알림 규칙과 라이브러리 패널이 영구 삭제되고 복원되지 않아요.

폴더 동기화나 폴더 없는 동기화에서는 마이그레이션 중인 개별 대시보드만 삭제하고 절대 폴더는 삭제하지 마세요. 전체 인스턴스 마이그레이션은 정리 동작이 달라 관리되지 않는 폴더를 삭제할 수 있으니, 전체 인스턴스 마이그레이션 안내를 따르세요.

안전하게 마이그레이션하려면 다음을 유의하세요:

  • 먼저 인스턴스를 백업해요. 아무것도 삭제하기 전에 대시보드, 폴더, 알림 규칙, 라이브러리 패널을 내보내거나 스냅샷해요. 삭제된 리소스는 Grafana UI에서 복원할 수 없어요.
  • 폴더별로 마이그레이션해요. 단일 폴더로 시작해 전체 마이그레이션을 완료하고, 다음 폴더로 가기 전에 결과를 검증해요. 그러면 문제가 생겨도 영향이 제한되고 프로세스에 익숙해질 수 있어요.
  • 원본 폴더를 유지하고 따로 구분해 두세요. 마이그레이션 후에는 원본 폴더(알림·라이브러리 패널을 담는)가 같은 이름의 새 Git Sync 폴더와 나란히 있게 돼요. 혼란을 피하려면 원본 폴더 이름을 바꾸거나 단일 최상위 Alerts & Library Panels 폴더 아래로 옮기세요. 그러면 지원되지 않는 리소스가 온전히, 프로비저닝된 대시보드와 명확히 분리된 채 유지돼요. 대신 원본 폴더로 가는 링크가 계속 동작해야 한다면 원본 폴더 링크 보존하기를 참고하세요.

1단계: 저장소로 리소스 내보내기

마이그레이션할 대시보드를 각 파일이 대시보드의 원본 UID(metadata.name)를 유지하도록 내보낸 다음, 파일을 Git 저장소에 커밋해요. 다음 중 하나를 쓸 수 있어요.

  • Grafana CLI로 내보내기
  • JSON 리소스 파일로 내보내기
Grafana CLI로 내보내기

터미널이나 에이전틱 코딩 도구에서 CLI gcx로 기존 대시보드를 내보낼 수 있어요. gcx로 Grafana에서 동기화할 리소스를 다운로드한 다음, 그 파일을 프로비저닝된 Git 저장소에 커밋하고 푸시할 수 있어요. 그러면 Git Sync가 커밋을 감지하고 Grafana와 동기화해요.

참고: 자세한 내용은 gcx 문서를 참고하세요.

gcx로 대시보드를 내보내려면:

  • Defining contexts에 문서화된 대로 gcx 컨텍스트가 인스턴스를 가리키도록 설정해요.
  • 동기화할 리소스를 인스턴스에서 로컬 저장소로 가져와요:
gcx resources pull dashboards --path
  • 리소스를 Git 저장소에 커밋하고 푸시해요:
git add 
git commit -m "Add dashboards from Grafana"
git push

여기서: .: Git Sync와 동기화된 저장소의 경로, .: 내보낼 대시보드가 있는 경로. 대시보드 경로는 저장소 아래에 있어야 해요.

리소스를 커밋한 뒤 2단계로 진행해요.

JSON 리소스 파일로 내보내기

대시보드를 JSON 리소스 파일로 내보내려면:

  • 대시보드를 JSON으로 내보내요.
  • Grafana App Platform이 요구하는 CRD(Custom Resource Definition) 형식으로 변환해요.
  • 변환된 파일을 Git 저장소에 커밋해요.

파일을 커밋한 뒤 2단계로 진행해요.

대시보드를 JSON 파일로 내보내려면 다음 CRD 구조를 따라야 해요:

{
  'apiVersion': 'dashboard.grafana.app/v1',
  'kind': 'Dashboard',
  'metadata': { 'name': 'dcf2lve9akj8xsd' },
  'spec': { /* Original dashboard JSON goes here */ },
}

구조는 다음을 포함해요:

  • apiVersion: API 버전을 지정해요. classic과 v2 JSON 모델이 모두 지원돼요. 자세한 내용은 Dashboard JSON model 참고.
  • kind: 리소스 타입을 식별해요. 예: dashboard.
  • metadata: 대시보드 식별자 이름을 담아요. Git Sync가 채택할 수 있도록 원본 대시보드 UID와 일치해야 해요. 식별자는 대시보드 URL이나 내보낸 JSON에서 찾을 수 있어요.
  • spec: 원본 대시보드 JSON을 감싸요.

2단계: 원본 대시보드 삭제하기

내보낸 파일이 원본 UID를 유지하므로, Grafana에 같은 UID(metadata.name)의 관리되지 않는 대시보드가 여전히 있으면 Git Sync는 그 대시보드를 채택하지 않아요. 마이그레이션 중인 각 원본 대시보드를 삭제해서 Git Sync가 UID를 인계받게 해요.

주의: 마이그레이션 중인 개별 대시보드만 삭제하세요. Git Sync는 경로 파생 UID를 가진 자기 폴더를 만들므로 폴더는 삭제할 필요 없어요. 알림 규칙이나 라이브러리 패널이 든 폴더는 삭제하거나 다시 만들지 마세요. 그 리소스는 영구 삭제되고 Git Sync는 다시 만들지 않으니까요. 원본 폴더를 유지하고 구분하는 방법은 시작하기 전에 참고.

대시보드를 삭제할 때 다음을 유의하세요:

  • 삭제된 리소스는 UI에서 복원할 수 없어요.
  • 대시보드 버전 이력은 이어지지 않아요.
  • 커스텀 폴더 권한을 다시 적용해야 해요. 자세한 내용은 Git Sync 권한 및 접근 제어 참고.

3단계: 마이그레이션 검증하기

  • 새 pull을 트리거해 동기화를 완료해요. 대시보드는 원본 UID를 가진 프로비저닝 리소스로 다시 만들어져서 기존 링크가 계속 동작해요.
  • 각 대시보드가 프로비저닝 폴더에 나타나고 올바르게 열리는지 확인해요. 변경 사항이 나타나기까지 몇 분 걸릴 수 있고, 안 나타나면 UI를 수동으로 새로고침해요.
  • 원본 폴더의 알림 규칙과 라이브러리 패널이 여전히 존재하고 동작하는지 확인해요.

한 폴더를 검증한 뒤에는 마이그레이션이 완료될 때까지 다음 폴더에 대해 이 과정을 반복해요.

원본 폴더 링크 보존하기

기본적으로 Git Sync는 동기화된 각 폴더에 저장소의 경로에서 파생된 새 UID를 부여해요. 즉 원본 폴더를 가리키는 링크와 URL은 새 프로비저닝 폴더가 아니라 원본 폴더를 계속 가리켜요.

기존 폴더 링크와 URL이 프로비저닝 폴더를 가리키게 만들고 싶다면 폴더 메타데이터 파일로 폴더의 UID를 고정해서 Git Sync가 원본 폴더의 UID를 재사용하게 할 수 있어요.

참고: 폴더 메타데이터는 기본 활성화된 provisioningFolderMetadata 기능을 필요로 해요. 관리자가 비활성화했다면 metadata.name은 무시되고 폴더는 항상 경로 파생 UID를 받아요.

원본 폴더의 UID를 재사용하려면 저장소의 해당 폴더 디렉토리에 _folder.json 파일을 추가해요:

{
  "apiVersion": "folder.grafana.app/v1beta1",
  "kind": "Folder",
  "metadata": { "name": "" },
  "spec": { "title": "" }
}

여기서 해당 원본 폴더의 UID예요. 폴더 URL에서 찾을 수 있어요.

이 옵션은 원본 폴더의 UID를 재사용하므로 동기화된 폴더가 기존의 관리되지 않는 폴더와 충돌하고, Git Sync는 아직 관리되지 않는 폴더에 속한 UID를 인계받을 수 없어서 충돌과 함께 동기화가 실패해요. 지원되지 않는 리소스를 잃지 않으려면 동기화 전에 폴더마다 다음 단계를 완료하세요:

  • 새 폴더를 만들고 원본 폴더에서 모든 알림 규칙, 라이브러리 패널, 기타 지원되지 않는 리소스를 그 안으로 옮겨요.
  • 원본 폴더를 삭제해요. 대시보드는 1단계에서 저장소로 이미 내보냈어야 해요.
  • 새 프로비저닝 폴더에 커스텀 권한을 다시 적용해요. 폴더 권한은 이어지지 않아요. Git Sync 권한 및 접근 제어 참고.

주의: 폴더를 삭제하기 전에 알림 규칙과 라이브러리 패널을 폴더 밖으로 옮기세요. 폴더를 삭제하면 그 안의 모든 것이 삭제되고 Git Sync는 알림이나 라이브러리 패널을 다시 만들지 않아요.

Git 관리 대시보드 작업하기

대시보드를 Git에 저장하면 자동으로 동기화되고, 다른 프로비저닝 리소스와 똑같이 작업할 수 있어요. 자세한 내용은 프로비저닝된 대시보드 작업하기를 참고하세요.

더 알아보기 (Learn more)