풀 리퀘스트에서 즉시 풀링과 대시보드 프리뷰 설정
풀 리퀘스트에서 즉시 풀링과 대시보드 프리뷰 설정 (Set up instantaneous pulling and dashboard previews in Pull Requests)
이 문서는 Git Sync를 확장하는 방법을 안내해요. 풀 리퀘스트 알림을 활성화하고 대시보드 변경 사항의 이미지 프리뷰를 제공하는 웹훅 설정과 이미지 렌더링 구성 방법을 다뤄요.
출처: 문서
본문
설정 후, 풀 리퀘스트 알림과 대시보드 변경 사항의 이미지 프리뷰를 활성화해 Git Sync를 선택적으로 확장할 수 있어요.
| Capability | Benefit | Requires |
|---|---|---|
| 풀 리퀘스트에 변경 사항을 요약하는 표 | GitHub에 변경 사항을 다시 저장하는 편리한 방법 | 웹훅 구성됨 |
| PR에 대시보드 프리뷰 이미지 | Grafana 외부의 풀 리퀘스트에 대시보드 변경 사항 스냅샷 | 이미지 렌더러와 웹훅 구성됨 |
실시간 알림 및 풀 리퀘스트 통합용 웹훅 설정 (Set up webhooks for real-time notification and pull request integration)
실시간 알림(또는 자동 풀링)은 Grafana Cloud에서 기본적으로 활성화·구성돼요. Grafana OSS/Enterprise에서 Git Sync는 웹훅을 사용해 GitHub 퍼블릭 저장소의 실시간 업데이트를 활성화하거나 풀 리퀘스트 통합을 활성화해요. 웹훅이 없으면 폴링 간격은 구성 중에 설정되며 기본값은 60초예요. 웹훅은 원하는 서비스나 도구로 설정할 수 있어요: Cloudflare 관리 도메인의 Cloudflare Tunnels, 포트 포워딩과 DNS 옵션, 또는 ngrok 같은 도구.
웹훅을 설정하려면:
- Grafana 인스턴스를 공개 인터넷에 노출해요. 포트 포워딩과 DNS,
ngrok, 또는 원하는 다른 방법을 사용해요. GitHub 액세스 토큰에 설정된 권한이 이 통신에 대한 인증을 제공해요. - 공개 URL을 확보한 후 Grafana 구성 파일에 추가해요:
[server]
root_url = https://<PUBLIC_DOMAIN>
- *
<PUBLIC_DOMAIN>*을 공개 도메인으로 바꿔요.
구성된 웹훅을 확인하려면 Administration > General > Provisioning으로 가서 GitHub 저장소의 View 링크를 클릭해요.
웹훅 제한 (Webhook limits)
Git Sync는 각 저장소 연결에 대해 자체 웹훅을 등록해요. 따라서 여러 Grafana 인스턴스가 같은 저장소를 동기화하면 각 연결이 이 총계에 추가돼요. Git provider는 각 저장소에 설정할 수 있는 웹훅 수를 제한하므로, 제한을 초과하면 Git provider가 새 웹훅을 거부해요.
예를 들어 GitHub에서는 다음과 같은 오류가 발생할 수 있어요:
GitHub API error (HTTP 422: Validation Failed: The "pull_request" event cannot have more than 20 hooks; The "push" event cannot have more than 20 hooks)
이 제한에 도달하면 다음 중 하나를 할 수 있어요:
- 저장소의 Settings > Webhooks 페이지에서 사용하지 않거나 중복된 웹훅을 제거해요.
- 실시간 동기화가 필요 없는 연결에 대해 웹훅 통합을 비활성화해 해당 인스턴스가 대신 간격으로 폴링하도록 해요. 웹훅 통합을 비활성화하려면 웹훅 옵션(Webhook options)을 참고해요.
provider별 웹훅 제한 (Webhook limitations per provider)
다음 제한이 적용돼요:
- GitHub는 각 저장소를 이벤트 유형(
push,pull_request등)당 20개 웹훅으로 제한해요. 자세한 내용은 공식 GitHub webhooks documentation을 참고해요. - GitLab은 각 프로젝트에 100개, 각 그룹에 50개의 웹훅을 기본으로 적용해요(하위 그룹 웹훅은 상위 그룹 제한에 포함되지 않음). 자세한 내용은 GitLab settings을 참고해요.
- BitBucket은 저장소당 50개 웹훅으로 제한해요. 자세한 내용은 BitBucket webhook documentation을 참고해요.
공개적으로 접근 가능한 URL 설정 (Set a publicly-reachable URL)
[server] root_url을 내부 주소로 지정해야 한다면(예: Grafana가 Kubernetes 클러스터의 프라이빗 인그레스 뒤에서 실행되는 경우), 대신 [provisioning] public_root_url로 공개적으로 접근 가능한 URL을 설정해요. 이 URL은 Git provider에 웹훅 콜백을 등록하는 데 사용되며, Git provider 서버가 공개 인터넷에서 가져오는 풀 리퀘스트 주석에 포함된 스크린샷 이미지의 기준 URL로도 사용돼요.
[server]
root_url = http://internal.cluster.local
[provisioning]
public_root_url = https://<PUBLIC_DOMAIN>
저장소별 spec.webhook.baseUrl 필드는 웹훅 등록에 여전히 public_root_url을 재정의하고, 스크린샷 URL은 항상 public_root_url(설정하지 않으면 root_url)을 사용해요.
필요한 경로만 노출 (Expose necessary paths only)
보안 설정이 Grafana 인스턴스를 공개적으로 노출하는 것을 허용하지 않는다면, Git provider의 IP 주소를 허용 목록에 추가하거나 필요한 경로만 노출할 수 있어요. Grafana와 Git 서버 사이의 트래픽에 대한 정보는 네트워크 연결 및 IP 허용 목록(Network connectivity and IP allowlisting)을 참고해요.
RegExp에서 노출해야 하는 필수 경로는 /apis/provisioning\.grafana\.app/v0(alpha1)?/namespaces/[^/]+/repositories/[^/]+/(webhook|render/.*)$예요.
대시보드 프리뷰용 이미지 렌더링 설정 (Set up image rendering for dashboard previews)
Caution Grafana OSS와 Grafana Enterprise에서만 사용할 수 있어요.
풀 리퀘스트에서 대시보드 업데이트의 시각적 프리뷰를 추가하려면 Grafana 인스턴스에 Grafana Image Renderer를 설치해요. 자세한 내용과 설치 방법은 Image Renderer 서비스를 참고해요. 이미지 렌더링에는 웹훅이 필요해요.
다음 단계 (Next steps)
Git Sync 사용에 대해 더 배우려면 다음 문서를 참고해요: