사용 및 성능 제한

사용 및 성능 제한 (Usage and performance limitations)

Note Git Sync 기능은 계속 진화하고 있어요. Grafana에 문의하여 지원을 받거나 겪은 문제를 보고해 이 기능 개선에 도움을 주세요.

출처: 문서

본문

Note Git Sync 기능은 계속 진화하고 있어요. Grafana에 문의하여 지원을 받거나 겪은 문제를 보고해 이 기능 개선에 도움을 주세요.

성능 고려 사항 (Performance considerations)

Git Sync가 활성화되면 데이터베이스 로드가 증가할 수 있으며, 특히 Grafana 인스턴스에 폴더와 중첩 폴더가 많다면 더해요. 성능 영향을 프로덕션 환경이 아닌 곳에서 평가해요.

사용 등급과 한도 (Usage tiers and limits)

다음 Git Sync 등급별 한도가 적용돼요:

테이블 펼치기

Tier	Cloud - Free	Cloud - Other	On-prem OSS	On-prem Enterprise
Amount of repositories	1	10	10 (default)	10 (default)
Amount of synced resources per repository	20	1,000	No limit	No limit

Note Grafana Cloud에서 등급 한도는 구성에서 변경할 수 없어요. 더 높은 연결 한도가 필요하면 지원팀에 문의하거나, 팀이나 마이크로서비스별 단일 연결 대신 용량별 샤딩을 사용해요. 자체 관리 Grafana(OSS 또는 Enterprise)에서 표의 저장소 수 10은 기본값이지 하드 상한이 아니에요. Grafana 구성 파일의 [provisioning] max_repositories로 올리거나 제거할 수 있어요. 온프레미스 저장소당 리소스는 기본적으로 무제한으로 유지되고(max_resources_per_repository = 0), 원하면 상한을 설정할 수 있어요. 자세한 내용은 사용 한도 수정을 참고해요.

권장 한도 (Recommended limits)

Grafana Cloud에서 저장소 연결 한도는 스택당 한도예요. 자체 관리 Grafana에서 유효 한도는 max_repositories(기본 10)로 설정한 값이에요.

현재 저장소 연결당 1,000개가 넘는 리소스를 동기화하지 마세요. 이는 임의의 상한이 아니에요. 연결당 약 1,000개 리소스를 넘어가면 동기화 워크플로가 Grafana 자체에 눈에 띄는 부하를 가해 동기화가 느려지고 데이터베이스 로드가 증가할 수 있어요.

이 두 한도는 초기 수치예요. Git Sync가 성숙해지면 이 한도는 몇 자릿수로 올라갈 거예요. 목표는 Git Sync가 스택당 약 100개 Repository 연결과 장기적으로 약 1,000개까지 지원하고, 연결당 동기화할 수 있는 리소스 수도 비슷하게 늘리는 거예요.

이 한도가 Git Sync 사용에 영향을 주고 있다면 연락해 상황을 설명해요. 아이디어나 제안도 공유할 수 있어요.

사용 및 저장 한도에 대한 자세한 내용은 Dashboard and folder limits를 참고해요.

사용 한도 수정 (Modify your usage limits)

사용 한도를 변경하기 전에 특정 사용 사례를 연구해요. 저장소 구조를 신중히 설계하고, 몇 개의 저장소와 몇 개의 리소스를 지원할 수 있을지 결정해요. 예를 들어 저장소당 1,000개가 넘는 리소스를 설정하면 시스템 성능에 영향을 줄 수 있어요.

많은 경우 저장소당 1,000개 리소스 이상 확장에서 설명한 대로 단일 저장소를 여러 연결로 나누는 것이 한도를 올리는 것보다 더 나은 옵션이에요.

Grafana Cloud

Grafana Cloud에서 한도는 등급별로 적용되며 구성에서 편집할 수 없어요. 10개 연결 한도는 요청 시 약간 늘릴 수 있지만, 등급 한도를 변경하지 않고 더 많은 리소스를 동기화하는 권장 방법은 단일 저장소를 여러 연결로 나누는 것이에요.

한도 증가는 자동으로 부여되지 않아요. 요청하면 지원팀이 현재 한도가 충분하지 않은 이유를 이해하기 위해 사용 사례를 설명해 달라고 하고, 증가가 스택 성능에 필요하고 안전한지 평가해요.

Grafana OSS/Enterprise

Grafana 온프레미스(OSS 또는 Enterprise)에서 표의 10개 저장소 값은 기본값일 뿐 하드 상한이 아니에요. 저장소당 리소스는 기본적으로 무제한으로 유지돼요. 1,000개 리소스/연결 수치는 성능 권장 사항이지 온프레미스 기본 상한이 아니에요.

온프레미스 사용자라면 아래 설명된 대로 구성 설정을 통해 한도를 직접 변경할 수 있어요.

한도를 커스터마이징하려면 다음 구성 설정 중 하나를 사용해요:

동기화할 수 있는 저장소 수를 설정하려면 max_repositories를 사용해요. 기본값은 10이에요. 무제한 저장소에는 0으로 설정해요. 자세한 내용은 Configure Grafana 섹션의 max_repositories를 참고해요.
동기화할 저장소당 리소스 수를 설정하려면 max_resources_per_repository를 사용해요. 기본값은 0(무제한)이에요. 자세한 내용은 Configure Grafana 섹션의 max_resources_per_repository를 참고해요.

저장소당 1,000개 리소스 이상 확장 (Scale beyond 1,000 resources per repository)

단일 저장소에 1,000개가 넘는 리소스가 있다면 저장소당 한도를 올릴 필요가 없어요. 대신 같은 저장소를 여러 번 연결하고, 각 연결이 저장소의 다른 폴더(경로)를 가리키게 해요. 각 연결은 자체 리소스 부분집합을 동기화하고 1,000개 리소스 권장 사항에 독립적으로 집계돼요.

스택이 최대 10개 Repository 연결을 허용하므로, 각 연결을 권장 범위 내로 유지하면서 단일 저장소에서 약 10,000개 리소스를 동기화할 수 있어요.

단일 저장소를 여러 연결로 나눌 때는 각 연결에 folderless sync를 사용해요. 폴더 동기화(기본값)에서는 모든 연결이 저장소 이름을 딴 자체 래퍼 폴더를 만들므로, 저장소를 나누면 폴더 계층이 바뀌고 리소스를 한 단계 더 깊게 중첩하게 돼요. Folderless sync는 각 연결의 리소스를 최상위에 배치하므로, 분할이 Grafana에서 대시보드와 폴더가 정리되는 방식에 영향을 주지 않아요.

더 많은 것이 필요하면 10개 연결 한도를 Cloud 스택의 경우 요청 시 약간 늘릴 수 있어요. 사용 사례에 대해 논의하려면 지원팀에 문의해요.

Grafana Cloud에서 이렇게 많은 리소스를 동기화하면 스택의 최대 대시보드 수를 초과할 수도 있어요. 그렇다면 그 한도도 늘려야 해요. Dashboard and folder limits를 참고해 대시보드 한도를 검토하고 조정해요.

팀이 아닌 용량별 샤딩 (Shard by capacity, not by team)

팀이나 테넌트가 많을 때 각 팀이 자신의 연결에 매핑되도록 팀별 연결 하나를 만드는 것이 유혹적이에요. 이는 피해요. 연결을 빠르게 소비하고 팀이 늘어날 때 확장되지 않으며, Grafana Cloud에서 단일 스택에 필요할 수백 개 연결을 부여할 수 없어요.

대신 용량별로 샤딩해요. 저장소 하나를 만들고 팀을 각각 약 1,000개 리소스를 담는 소수의 샤드 폴더로 그룹화한 뒤 각 샤드 폴더를 개별적으로 연결해요. 예를 들어 190개 팀과 900개 리소스가 있는 고객은 오늘 단일 샤드에 편안히 들어맞아요:

your-org/grafana-manifests/
├── shard-1/        ← ~900 resources today, connected now
│   ├── team-a/
│   ├── team-b/
│   └── ...
├── shard-2/        ← empty for now, add a connection when shard-1 approaches 1,000
├── shard-3/        ← add later as you keep growing
└── shard-4/        ← ...up to 10 shards / connections per stack

리소스 수가 늘어나면 shard-2, shard-3, 이후 샤드를 추가하고 각각 연결해요. 부하를 균형 있게 맞추기 위해 언제든지 샤드 사이에서 팀을 이동할 수 있으므로 실제로 필요한 연결에 대해서만 비용을 지불하고 저장소를 재구성하지 않고도 10개 연결 한도까지 성장할 수 있어요.

하드웨어 샤딩이 설정에 실용적이지 않다면 연결당 리소스 한도를 적당히 올리는 것을 시도해요. 예를 들어 1,000에서 1,200 - 1,500 범위로요. 이는 약간의 여유를 위한 작은 조정이지 자릿수 증가가 아니에요. 그래도 Grafana에 대한 성능 영향 때문에 연결당 1,500개 리소스를 넘지 마세요. 훨씬 더 큰 규모에서는 샤딩이 여전히 권장 접근 방식이에요.

여러 조직에 걸친 Git Sync (Git Sync across multiple organizations)

Git Sync는 자체 관리 Grafana 인스턴스의 여러 조직에서 작동해요. 각 조직에서 Git Sync를 독립적으로 설정할 수 있고, 한 조직에서 동기화하는 것이 다른 조직에 영향을 주지 않아요. 별도 조직에서 단일 Grafana 인스턴스를 공유하는 팀은 각자 Git에서 자체 프로비저닝을 관리할 수 있어요.

이 기능은 Grafana 13.0.4부터 사용할 수 있으며, Grafana 13.1.1부터 지원돼요.

호환 Git 제공자 (Compatible Git providers)

Git Sync는 Pure Git 저장소 유형을 통해 모든 Git 제공자에서 사용할 수 있으며, GitHub, GitLab, Bitbucket에 대한 특정 향상된 통합이 있어요.

테이블 펼치기

Provider	Available in	Authentication
Pure Git	Cloud, OSS, Enterprise	Personal Access Token
GitHub	Cloud, OSS, Enterprise	Personal Access Token or GitHub App
GitHub Enterprise (Server and Cloud)	Cloud, Enterprise	Personal Access Token or GitHub App
GitLab	Cloud, Enterprise	Personal Access Token
Bitbucket	Cloud, Enterprise	API token with scopes

Pure Git, GitLab, Bitbucket은 Grafana v12.4.x 이상에서만 지원됨을 참고해요. 설정하려면 Enable Git providers를 참고해요.

Git에 대해 더 배우려면 공식 Git 문서의 Getting Started - About Version Control 단락(Pro Git book)을 참고해요.

Pure Git 저장소 유형 (The Pure Git repository type)

Pure Git 저장소 유형은 제공자별 논리 없이 Smart HTTP protocol v2(HTTPS 위의 Git)를 사용해요. Pure Git은 핵심 Git Sync 워크플로를 제공해요. 저장소가 진실의 원천이고, UI에서 대시보드를 편집할 수 있으며, Grafana가 동기화 상태를 유지해요.

Note Pure Git은 Smart HTTP protocol v2만 지원해요. 이전 프로토콜 버전(v1, v0)과 SSH 전송은 지원되지 않아요. Git 서버가 HTTPS에서 프로토콜 v2를 지원하는지 확인해요. Azure DevOps 같은 일부 제공자는 v1만 사용하므로 Git Sync와 호환되지 않아요.

하지만 Pure Git은 webhook 기반 즉시 동기화, 자동 PR 댓글, 소스 파일로의 딥 링크 같은 제공자 API가 필요한 기능은 포함하지 않아요.

향상된 통합: GitHub, GitHub Enterprise, GitLab, Bitbucket (Enhanced integrations: GitHub, GitHub Enterprise, GitLab, Bitbucket)

Git 제공자가 GitHub, GitHub Enterprise(Server and Cloud), GitLab, Bitbucket이라면 향상된 통합을 사용해요. 향상된 통합은 사용 중인 플랫폼을 이해해 네이티브처럼 느껴지는 워크플로를 허용해요: 대시보드 미리보기가 있는 자동 풀 리퀘스트 댓글, 즉시 webhook 기반 동기화, 또는 Grafana에서 제공자 UI의 소스 파일로 직접 탐색.

GitHub 향상된 통합이 오늘날 가장 기능이 완전한 경험이에요. Grafana OSS, Enterprise, Cloud에서 사용할 수 있고, 더 풍부한 풀 리퀘스트 워크플로, Grafana와 GitHub 사이의 더 깊은 연결, 검토 프로세스로의 더 긴밀한 통합을 활성화해요.

GitLab과 Bitbucket 통합은 Grafana Enterprise와 Grafana Cloud에서만 사용할 수 있어요. 현재는 덜 개발되었지만 풀 리퀘스트 워크플로, 연결, 동기화 동작에서 계속 개선될 것으로 기대해요.

리소스 지원과 호환성 (Resource support and compatibility)

Git Sync는 대시보드와 폴더만 지원해요. 알림, 데이터 소스, 패널, 기타 리소스는 아직 지원되지 않아요.

Grafana Cloud 사용자라면 Grafana 로드맵 포털에서 향후 개선 사항을 확인할 수 있어요.

리소스 호환성 (Resource compatibility)

Grafana OSS 또는 Grafana Enterprise에서 Git Sync를 사용한다면 일부 지원되는 리소스가 호환되지 않는 데이터 형식일 수 있어요. 이런 일이 발생하면 동기화가 차단돼요. 호환성 문제는 곧 출시될 마이그레이션 도구로 해결될 거예요.

리소스는 다음과 같을 수 있어요:

테이블 펼치기

Is the resource?	Compatible	Incompatible
Supported	The resource can be managed with Git Sync.	The resource is supported but has compatibility issues. It cannot be managed with Git Sync.
Unsupported	The resource is not supported and cannot be managed with Git Sync.	Not applicable.

중첩 폴더 (Nested folders)

Git Sync는 저장소 내 최대 4개 중첩 폴더를 지원해요.

알려진 한계 (Known limitations)

Git Sync로 마이그레이션 (Migration to Git Sync)

전체 인스턴스 동기화는 실험적이에요.

리소스를 Git Sync로 마이그레이션할 때 여전히 리소스를 생성, 편집, 삭제할 수 있지만 변경 사항이 내보내지지 않을 수 있어요. 이 프로세스의 기간은 관련된 리소스 수에 따라 달라져요.

기존 리소스 사용 (Use existing resources)

기존 리소스를 프로비저닝된 Git Sync 리소스로 추가하려면 Import dashboards 도구를 사용하거나, UI에서 저장하거나, JSON 파일로 저장해 동기화된 저장소에 커밋하거나, gcx를 사용할 수 있어요. 자세한 내용은 Export non-provisioned resources from Grafana를 참고해요. 기존 대시보드를 마이그레이션할 때 폴더 구조가 프로비저닝된 저장소에 복제돼요.

Caution Grafana에 같은 UID를 가진 비관리 리소스가 존재하는 동안 Git Sync는 리소스의 소유권을 가져올 수 없으므로, 프로비저닝된 리소스로의 전환을 보장하려면 원래 리소스를 수동으로 제거해야 할 수 있어요. 리소스 삭제는 특정 운영상의 주의 사항을 수반하므로 How to delete existing resources in Grafana를 참고해요.

리소스 복원 (Restore resources)

UI에서 리소스를 복원하는 것은 현재 불가능해요. 대안으로 GitHub 저장소에서 직접 PR을 올려 대시보드를 복원할 수 있으며, 그러면 Grafana에서 업데이트돼요.

사용 및 성능 제한