Git Sync 권한 및 접근 제어

Git Sync가 올바르게 작동하려면 두 계층에서 권한을 구성해야 해요:

이 문서에서 설명하는 저장소 관리 및 리소스 접근을 위한 Grafana 수준 권한.
저장소를 보호하기 위한 Git 프로바이더 수준 권한. 자세한 내용은 Git Sync 저장소 보호를 참고하세요.

출처: 문서

본문

Grafana 역할 기반 권한

Git Sync는 세 가지 수준을 가진 Grafana 표준 역할 기반 권한 모델과 통합돼요:

조직 수준: Admin, Editor, Viewer 역할의 기본 권한. 자세한 내용은 역할 및 권한을 참고하세요.
폴더 수준: 폴더 안의 모든 대시보드에도 적용돼요. 자세한 내용은 폴더 권한을 참고하세요.
대시보드 수준: 자세한 내용은 대시보드 권한을 참고하세요.

참고

대시보드 수준 권한은 폴더 수준 권한보다 우선하며, 폴더 수준 권한은 조직 수준 역할보다 우선해요.

Git Sync에는 다음 사항이 적용돼요:

권한은 동기화되지 않아요: 폴더 및 대시보드 권한은 Grafana에서만 관리되며 Git으로 동기화되지 않아요. 저장소를 사용하는 각 Grafana 인스턴스에서 권한을 별도로 구성해야 해요.
대시보드 변경: 적절한 대시보드 또는 폴더 권한을 가진 사용자가 대시보드 콘텐츠를 수정하면 해당 변경 사항이 Git에 자동으로 동기화되거나, 브랜치 보호가 활성화된 경우 pull request가 생성돼요.
폴더 구조: 폴더 생성, 이름 변경, 삭제는 Git에 동기화돼요.

Git Sync에서 조직 수준 권한 사용

조직 수준 권한을 적용하면 사용자는 Git Sync로 다음을 수행할 수 있어요.

Admin 사용자

Grafana OSS/Enterprise인 경우 Git Sync 저장소와 연결을 설정하고 관리하려면 Admin 역할이 필요해요. Grafana Cloud에서는 이에 해당하는 역할이 조직 수준의 Grafana Cloud Admin 또는 Admin이에요.

Admin으로 다음을 할 수 있어요:

새 Git Sync 저장소 및 연결 구성
저장소 설정 업데이트(URL, 브랜치, 경로, 동기화 간격, 웹훅 구성)
저장소 연결 삭제
인증 자격 증명 및 Git 프로바이더 연결 관리
동기화 작업을 수동으로 트리거(Git에서 pull)
동기화 상태, 로그, 통계 보기
Administration > General > Provisioning의 프로비저닝 관리 UI 접근

Editor 사용자

Editor 역할을 가진 사용자는 프로비저닝된 대시보드와 폴더를 다룰 수 있어요. 구체적인 기능은 할당된 폴더 수준 및 대시보드 수준 권한에 따라 달라져요.

조직 수준 기능:

pull request에서 대시보드 미리 보기 링크 보기
jobs API를 통해 대시보드 및 폴더 변경 사항을 Git에 푸시하고 pull request 열기

참고

수동 동기화(Git에서 pull)와 고아(orphan) 리소스 정리는 Admin만 트리거할 수 있어요. Editor는 자신의 변경 사항을 푸시할 수 있지만 필요할 때 Git에서 pull할 수는 없어요. 자세한 내용은 작업(Job) 및 필요한 권한을 참고하세요.

리소스 접근은 폴더/대시보드 권한에 따라 달라져요:

Folder Editor 또는 Admin: 폴더 안의 대시보드를 생성·편집·삭제하고, 하위 폴더를 만들 수 있으며, 변경 사항이 Git에 동기화돼요.
Folder Viewer: 해당 폴더 안의 대시보드만 볼 수 있어요.
Dashboard Editor 또는 Admin: 특정 대시보드를 편집할 수 있으며, 변경 사항이 Git에 동기화돼요(폴더 편집 권한이 없어도).
Dashboard Viewer: 특정 대시보드만 볼 수 있어요.

Editor는 프로비저닝 관리 UI나 저장소 구성에 접근할 필요가 없어요. 자세한 내용은 폴더 및 대시보드 권한 구성과 세분화된 접근 제어(RBAC) 구성을 참고하세요.

Viewer 사용자

Viewer 역할을 가진 사용자는 프로비저닝된 리소스를 볼 수 있어요. 특정 대시보드와 폴더에 대한 접근은 할당된 권한에 따라 달라져요.

조직 수준 기능:

provisioning.settings:read 권한을 통해 Git Sync 설정 읽기
pull request에서 대시보드 미리 보기 링크 보기

리소스 접근은 폴더 및 대시보드 권한에 따라 달라져요:

Folder Viewer: 해당 폴더 안의 모든 대시보드와 하위 폴더를 볼 수 있어요.
Dashboard Viewer: 폴더 접근 권한이 없어도 특정 대시보드를 볼 수 있어요.
대시보드를 편집하거나 Git Sync 저장소를 관리할 수 없어요.

폴더 및 대시보드 권한 구성

폴더 수준 역할 권한은 프로비저닝된 리소스를 누가 보기·편집·삭제할 수 있는지 결정해요.

이러한 역할은 사용자가 Git Sync 파일 엔드포인트를 통해 프로비저닝된 리소스와 상호작용할 때 확인되는 Grafana 권한(dashboards:read, dashboards:write, folders:create 등)을 부여해요. 프로비저닝된 폴더 안의 대시보드는 폴더의 권한을 상속해요.

Git Sync가 프로비저닝된 폴더를 만들 때 다음 기본 권한을 할당해요:

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

폴더 수준 Viewer 사용자:

대시보드와 폴더를 볼 수 있어요.
리소스를 생성·편집·삭제할 수 없어요.

폴더 수준 Editor 사용자:

모든 Viewer 권한을 가져요.
대시보드를 생성·편집·삭제해요.
하위 폴더를 만들어요.
Editor가 대시보드 변경 사항을 저장하면 Git Sync가 변경 사항을 Git에 자동으로 커밋하거나, 브랜치 보호가 활성화된 경우 pull request를 생성해요.

폴더 수준 Admin 사용자:

모든 Editor 권한을 가져요.
폴더 설정을 업데이트하고, 폴더 이름을 바꾸고, 삭제해요.
폴더 권한을 수정해요.
폴더와 모든 내용에 대한 전체 제어권을 가져요.

폴더 수준 권한 수정

Grafana의 폴더 권한은 Git 저장소의 경로가 아니라 폴더의 UID에 연결돼요. Git Sync는 이 UID를 폴더의 _folder.json 메타데이터 파일(metadata.name 필드)에 저장해요. 메타데이터 파일 스키마와 존재 이유에 대해서는 Git Sync 폴더 메타데이터 파일을 참고하세요.

권한이 폴더 UID를 참조하므로 다음 사항을 기억하세요:

먼저 폴더를 생성하세요. 권한을 할당하려면 폴더가 Grafana에 존재하고 안정적인 UID가 있는 _folder.json 파일이 있어야 해요. Git Sync가 폴더를 만들고 동기화하게 한 다음, 결과 UID를 참조하는 권한을 적용하세요. 아직 동기화되지 않은 폴더에 권한을 설정하려고 하면 붙일 UID가 없어요.
권한은 Git으로 동기화되지 않아요. Grafana 인스턴스별로 설정하세요. 동일한 저장소를 동기화하는 모든 인스턴스는 ( _folder.json의) 동일한 폴더 UID를 공유하므로 각 인스턴스에 동일한 권한 정의를 적용할 수 있어요.

참고

권한을 안전하게 수정하려면 각 프로비저닝된 폴더에 폴더 UID가 포함된 _folder.json 메타데이터 파일이 있어야 해요. 이 파일이 없으면 폴더의 UID가 저장소 경로에서 파생되므로, 폴더가 Git 저장소의 다른 경로로 이동하면 폴더 권한이 손실될 수 있어요.

Grafana UI에서 생성된 폴더는 메타데이터 파일이 자동으로 추가돼요. 폴더에 메타데이터 파일이 없으면 UI에 추가 방법을 안내하는 경고가 표시돼요. 자세한 내용은 Git Sync 폴더 메타데이터 파일을 참고하세요.

폴더 권한을 수동으로 또는 코드로 설정할 수 있어요. 두 경우 모두 Git Sync가 폴더를 만든 후에만 적용하세요.

권한을 수동으로 설정

Grafana UI: 폴더로 이동해 Folder actions > Manage permissions를 선택하세요. 역할, 팀, 사용자에 대한 권한을 추가하거나 편집하세요.
HTTP API: 폴더/대시보드 권한 API를 사용하세요. _folder.json 파일에 저장된 UID로 폴더를 참조하세요.
RBAC (Enterprise/Cloud): 세분화된 권한 관리를 위해 역할 기반 접근 제어를 사용하세요.

Terraform으로 권한 설정

Grafana Terraform 프로바이더로 폴더 권한을 코드로 관리할 수 있어요. 폴더는 Terraform이 아니라 Git Sync가 만들기 때문에, 각 폴더를 _folder.json 파일(metadata.name 값)의 UID로 참조하세요. 폴더 UID가 이미 존재하도록 Git Sync가 폴더를 동기화한 후에만 권한을 적용하세요.

grafana_folder_permission_item을 사용해 단일 권한 항목을 관리하세요. 이는 추가(additive) 방식이라 선언한 항목만 관리하고 다른 권한은 그대로 둬요:

# UID는 폴더의 _folder.json 메타데이터 파일("metadata.name")에서 가져옵니다.
locals {
  team_platform_folder_uid = "team-platform-abc123"
}

resource "grafana_folder_permission_item" "team_platform_editor" {
  folder_uid = local.team_platform_folder_uid
  team       = grafana_team.platform.id # an existing team
  permission = "Edit"
}

resource "grafana_folder_permission_item" "team_platform_viewer" {
  folder_uid = local.team_platform_folder_uid
  role       = "Viewer"
  permission = "View"
}

또는 grafana_folder_permission을 사용해 폴더에 대한 전체 권한 집합을 단일 리소스로 선언할 수 있어요. 이 리소스는 권위(authoritative)가 있어서 구성에 나열되지 않은 권한은 구성을 적용할 때 제거돼요.

참고

이 폴더들을 grafana_folder 리소스로 관리하지 마세요. Git Sync가 소유하고 있기 때문이에요. UID를 하드코딩하지 않으려면 저장소의 _folder.json 파일에서 읽거나 grafana_folder 데이터 소스로 조회하세요.

세분화된 접근 제어(RBAC) 구성

RBAC가 활성화된 Grafana Enterprise 또는 Grafana Cloud 사용자라면 Git Sync에서 Git Sync 작업을 더 세밀하게 제어할 수 있는 세분화된 권한을 제공해요. Git Sync 권한을 다양한 방식으로 결합하는 사용자 지정 역할을 만들 수 있어요. 사용자 지정 역할 생성 및 관리 지침은 역할 기반 접근 제어 문서를 참고하세요.

기본 역할이 RBAC 권한에 매핑되는 방식

각 기본 역할이 받는 권한을 이해하면 사용자 지정 역할을 만들거나 사용자에게 정확히 어떤 권한이 있는지 이해하는 데 도움이 돼요. 아래 표는 각 역할에 기본적으로 부여되는 Git Sync 권한을 보여줘요.

참고

provisioning.settings:read 권한은 모든 역할(Viewer 이상)에 부여되며 Git Sync 시스템 설정 보기를 허용해요. 이는 UI가 제대로 표시되는 데 필요해요. 이 권한으로 설정을 수정하거나 저장소를 관리할 수는 없어요.

Admin 역할

Admin 역할을 가진 사용자는 Git Sync 인프라에 대한 전체 접근 권한을 받아요:

권한 범주	구체적 권한	허용되는 작업
Repositories	provisioning.repositories:create provisioning.repositories:read provisioning.repositories:write provisioning.repositories:delete	새 저장소 생성 저장소 구성 보기 저장소 설정 업데이트(브랜치, 경로, 간격) 저장소 삭제
Connections	provisioning.connections:create provisioning.connections:read provisioning.connections:write provisioning.connections:delete	Git 프로바이더 연결 생성 연결 세부 정보 보기 연결 설정 업데이트 연결 삭제
Jobs	provisioning.jobs:create provisioning.jobs:read provisioning.jobs:write provisioning.jobs:delete	수동 동기화 트리거 동기화 작업 보기 동기화 작업 설정 수정 동기화 작업 취소/삭제
History & Monitoring	provisioning.historicjobs:read provisioning.stats:read	동기화 작업 기록 보기 Git Sync 통계 및 메트릭 보기
Settings	provisioning.settings:read	Git Sync 시스템 설정 보기

Editor 역할

Editor 역할을 가진 사용자는 동기화 작업은 관리할 수 있지만 인프라 구성은 관리할 수 없어요:

권한 범주	구체적 권한	허용되는 작업
Jobs	provisioning.jobs:create provisioning.jobs:read provisioning.jobs:write provisioning.jobs:delete	변경 사항 푸시 및 pull request 열기 동기화 작업 보기 동기화 작업 설정 수정 동기화 작업 취소/삭제
Read-Only Access	provisioning.repositories:read provisioning.settings:read	저장소 구성 보기 Git Sync 설정 보기

참고

provisioning.jobs:create는 Editor가 관련 dashboards:* 및 folders:* 권한을 조건으로 자신의 변경 사항을 푸시하는 작업을 만들 수 있게 해요. 그러나 provisioning.repositories:write 권한이 필요한 Git에서의 수동 pull 또는 고아 리소스 정리 같은 관리자 전용 작업은 허용하지 않아요. 자세한 내용은 작업 및 필요한 권한을 참고하세요.

Editor는 폴더/대시보드 할당에 따라 리소스에 접근할 수 있어요:

Folder Editor 또는 Dashboard Editor가 할당된 폴더/대시보드에서 dashboards:create, dashboards:read, dashboards:write, dashboards:delete

Folder Editor가 할당된 폴더에서 folders:create, folders:read, folders:write, folders:delete

Viewer 역할

Viewer 역할을 가진 사용자는 Git Sync에 대한 읽기 전용 접근 권한을 가져요:

권한 범주	구체적 권한	허용되는 작업
Read-Only Access	provisioning.repositories:read provisioning.settings:read	저장소 구성 보기 Git Sync 설정 보기(UI에 필요)

Viewer는 폴더/대시보드 할당에 따라 리소스에 접근할 수 있어요:

Folder Viewer 또는 Dashboard Viewer가 할당된 폴더/대시보드에서 dashboards:read
Folder Viewer가 할당된 폴더에서 folders:read

대시보드 및 폴더에 대한 RBAC

프로비저닝된 대시보드와 폴더는 Grafana 표준 권한 모델을 사용해요. 프로비저닝된 리소스를 수정하려면 대시보드와 폴더에 대한 권한이 필요해요.

Git Sync에는 다음 사항이 적용돼요:

프로비저닝된 리소스를 다루려면 표준 dashboards:* 및 folders:* 권한이 필요해요.
Editor와 Viewer는 Git Sync 구성을 보려면 provisioning.settings:read 및 provisioning.repositories:read가 필요해요.
대시보드를 편집하는 데 저장소 쓰기/삭제 또는 연결 권한은 필요하지 않아요.
대시보드 수준 권한은 폴더 수준 권한보다 우선해요.
적절한 권한을 가진 사용자가 만든 변경 사항은 Git에 자동으로 동기화돼요.

작업(Job) 및 필요한 권한

Git Sync 작업은 jobs로 실행돼요. 어떤 작업이든 만들려면 provisioning.jobs:create 권한이 필요해요. 게다가 일부 작업 동작은 관리자로 제한되며 provisioning.repositories:write 권한이 필요해요. 이로 인해 Editor가 provisioning.jobs:create를 보유하더라도 저장소 전체 작업을 트리거하지 못하게 막아요.

작업 동작	필요한 권한	실행 가능한 사용자
변경 사항 푸시 / pull request 열기	provisioning.jobs:create + 관련 dashboards:* / folders:* 권한	수정할 수 있는 리소스에 대해 Editor 및 Admin
리소스 마이그레이션	provisioning.jobs:create + 영향받는 리소스 유형에 대한 읽기/쓰기	필요한 리소스 권한이 있는 Editor 및 Admin
수동 동기화(Git에서 pull)	provisioning.repositories:write	Admin만
고아 리소스 해제/삭제	provisioning.repositories:write	Admin만

저장소 하위 리소스 접근

저장소 API는 여러 하위 리소스를 노출해요. 아래 표는 각각이 어떤 권한으로 제어되는지 보여줘요.

refs 하위 리소스는 저장소의 브랜치와 커밋을 나열하며, 두 가지 서로 다른 흐름이 정당하게 이를 필요로 해요:

Editor가 변경 사항 푸시: Editor가 변경 사항을 저장하거나 push-job 흐름을 통해 pull request를 열 때 Grafana는 브랜치 목록이 필요해요. 이는 provisioning.jobs:create로 승인돼요.
Admin이 저장소 구성: Admin 또는 저장소 소유자가 저장소를 설정·편집하고 대상 브랜치를 선택할 때 Grafana는 Repository 리소스 정보를 업데이트해요. 이는 provisioning.repositories:write로 승인돼요.

repositories 리소스에는 Editor 계층이 없으므로(repositories:read는 Viewer 이상에 부여되고, write, create, delete는 관리자 전용), refs는 이 두 검사 중 하나를 허용하며 뷰어는 둘 다 충족하지 못해요.

하위 리소스	용도	필요한 권한	접근 가능한 사용자
files	프로비저닝된 리소스 파일 읽기 및 쓰기	인증된 접근 후 표준 dashboards:* / folders:* 검사	모든 인증된 사용자
refs	저장소 브랜치 및 커밋 나열	provisioning.repositories:write 또는 provisioning.jobs:create	Admin 및 Editor
resources, history, status	저장소 관리 및 검사 뷰	provisioning.repositories:write	Admin만

참고

관리 및 검사 뷰(resources, history, status)는 repositories:read가 아니라 provisioning.repositories:write로 제어돼요. repositories 리소스에는 관리자 전용 읽기 작업이 없기 때문이에요. 결과적으로 저장소를 관리할 수 있는 사용자만 관리 뷰를 검사할 수 있어요. Viewer와 Editor는 이러한 뷰에 접근할 수 없어요.

Git 저장소 보호 구성

Grafana 권한을 구성한 후에는 변경 사항을 쓰기 위해 Git 프로바이더에 적절한 권한을 설정하세요. 저장소 보호 설정은 쓰기 접근, 브랜치 보호 규칙, 코드 검토 요구 사항을 제어해요.

저장소 쓰기 접근 및 브랜치 보호 구성에 대한 자세한 내용은 Git Sync 저장소 보호를 참고하세요.

권한 문제 해결

대시보드 저장 시 "Permission denied"

원인: 사용자가 프로비저닝된 폴더에 대한 Editor 또는 Admin 권한이 없음.

해결 방법:

Grafana에서 사용자의 폴더 수준 권한을 확인하세요.
Folder settings > Permissions로 이동하세요.
사용자 또는 해당 팀에 Editor 또는 Admin 역할을 부여하세요.

Git Sync가 "403 Forbidden" 또는 "Unauthorized"로 실패

원인: Git 프로바이더 인증 자격 증명에 필요한 저장소 권한이 없음.

해결 방법:

인증 자격 증명(GitHub App, Personal Access Token)이 저장소에 대한 읽기 및 쓰기 권한이 있는지 확인하세요.
GitHub App 또는 OAuth 앱을 사용하는 경우 대상 저장소에 설치되고 승인되었는지 확인하세요.
자격 증명에 pull request 생성 권한이 있는지 확인하세요(브랜치 보호가 활성화된 경우).
인증 자격 증명이 만료되지 않았는지 확인하세요.
만료되었거나 취소된 토큰의 경우 새 자격 증명을 생성하고 Git Sync 연결 구성을 업데이트하세요.

대시보드 변경 사항이 pull request를 만들지 않고 직접 커밋됨

원인: Git 프로바이더에서 브랜치 보호가 구성되지 않음.

해결 방법: Git 프로바이더에서 브랜치 보호 규칙을 활성화해 pull request 워크플로를 적용하거나 Grafana 저장소 설정에서 활성화하세요. 브랜치 보호 구성 지침은 Git 프로바이더 문서를 참고하세요.

대시보드 변경 사항이 검토 없이 직접 커밋됨

원인: Git 프로바이더에서 브랜치 보호가 구성되지 않음.

해결 방법:

Git 프로바이더의 대상 브랜치에서 브랜치 보호를 활성화하세요.
병합 전에 pull request를 요구하도록 브랜치를 구성하세요.
보호 규칙의 브랜치 이름이 Grafana에 구성된 브랜치와 일치하는지 확인하세요.

예상될 때 pull request가 생성되지 않음

원인: 브랜치 보호가 활성화되지 않았거나 인증 자격 증명에 pull request 생성 권한이 없음.

해결 방법:

올바른 브랜치에서 브랜치 보호가 활성화되었는지 확인하세요.
자격 증명에 pull request 생성 권한이 있는지 확인하세요.
Git Sync 설정의 브랜치 이름이 보호된 브랜치와 정확히 일치하는지 확인하세요.

Git Sync 권한 및 접근 제어