시작하기 전에

시작하기 전에

이 문서에서는 Git Sync를 설정하기 전에 준비해야 할 사전 요구 사항과 환경 구성을 안내합니다. 필요한 항목, 기능 토글, Git 프로바이더 활성화, 네트워크 연결, SSH 보호, 권한 설정, GitHub App 생성 방법을 설명해요.

출처: 문서

본문

Git Sync를 설정하기 전에 다음이 준비되어 있는지 확인하세요:

• Grafana 인스턴스(Cloud, OSS 또는 Enterprise)
• Grafana 조직의 관리 권한
• Git provider
• 웹훅 또는 이미지 렌더링을 사용한다면, 외부 접근이 가능한 공개 인스턴스
• 선택 사항: PR과 함께 이미지 미리보기를 저장하기 위한 Image Renderer 서비스

필요한 기능 토글 활성화하기

provisioning 기능 토글은 Grafana Cloud에서 기본적으로 활성화되어 있고, Grafana v13부터 OSS와 Enterprise에서도 기본적으로 활성화되어 있어요. 수동 구성이 필요하지 않아요.

기능 토글에 대한 자세한 내용은 Configure feature toggles를 참고하세요.

Git 프로바이더 활성화하기

Grafana Enterprise v12.4.0을 사용하면서 pure Git, GitLab 또는 Bitbucket으로 Git Sync를 설정하려 하거나, Grafana OSS v12.4.0을 사용하면서 pure Git으로 Git Sync를 설정하려 한다면, 구성 파일에 추가하세요:

1. grafana.ini 또는 custom.ini 중 하나인 Grafana 구성 파일을 여세요.
2. 사용 가능한 프로바이더를 추가하세요:

[provisioning]
repository_types = "git|github|bitbucket|gitlab|local"

3. 파일 변경 사항을 저장하고 Grafana를 다시 시작하세요.

네트워크 연결과 IP 허용 목록

Git Sync는 Grafana 인스턴스와 Git 서버 사이의 네트워크 연결을 요구해요. 트래픽 패턴을 이해하면 방화벽 규칙과 허용 목록을 올바르게 구성하는 데 도움이 돼요.

트래픽 유형

Git Sync는 두 가지 유형의 네트워크 트래픽을 사용해요:

• 동기화 작업(pull 및 push): Grafana에서 Git 서버로
  • Hosted Grafana IP 주소에서 나가는 이그레스(egress) 트래픽
  • Git 서버가 이 IP 주소에서 들어오는 인바운드 트래픽을 허용해야 해요
  • Git 서버의 허용 목록에 추가할 IP 주소 목록은 Hosted Grafana source IPs를 참고하세요
• 웹훅(즉시 동기화): Git 서버에서 Grafana 스택으로
  • 스택의 공개 엔드포인트로 들어오는 인바운드 트래픽
  • Git 서버가 *.grafana.net에 도달할 수 있어야 해요
  • 웹훅을 사용하는 경우에만 필요해요

AWS PrivateLink와 Private Data Source Connect

Git Sync는 AWS PrivateLink나 Private Data Source Connect(PDC)를 통해 라우팅하지 않아요. 대신 Git Sync는 PrivateLink와 PDC와 독립적인 Hosted Grafana IP의 일반 공개 경로를 사용해요. AWS PrivateLink와 PDC는 데이터 소스 쿼리 트래픽(Grafana에서 프라이빗 데이터베이스나 데이터 소스로)을 위한 별도의 터널을 제공해요.

데이터 소스에 AWS PrivateLink나 PDC를 사용해도 Git Sync는 여전히 사용할 수 있어요. 두 기능은 서로 간섭하지도, 서로 의존하지도 않아요.

내부 또는 프라이빗 Git 서버 허용하기

참고 이 설정은 Grafana v13.0.4와 Grafana v13.1.1 이상에서 사용할 수 있어요. 자체 관리형 Grafana(OSS와 Enterprise)에만 적용되며, Grafana Cloud에서는 구성할 수 없어요.

github.com, gitlab.com, bitbucket.org 같은 공개 Git 서버는 공개 주소로 확인되며 항상 허용되지만, 기본적으로 Git Sync는 루프백(loopback), 프라이빗(RFC 1918), 링크-로컬(link-local) 또는 미지정 주소로 확인되는 호스트를 가진 리포지토리 URL을 거부해요. 이는 서버 측 요청 위조(SSRF)로부터 Grafana 인스턴스를 보호해요.

내부 주소로만 접근 가능한 자체 호스팅 GitHub Enterprise, GitLab, Bitbucket 인스턴스 같은 프라이빗 네트워크의 Git 서버에 Git Sync를 연결한다면, 그 호스트를 allowed_git_urls 허용 목록에 추가하세요:

1. grafana.ini 또는 custom.ini 중 하나인 Grafana 구성 파일을 여세요.
2. 각 내부 Git 호스트를 쉼표로 구분된 목록으로 allowed_git_urls에 추가하세요:

[provisioning]
allowed_git_urls = git.internal.example.com, ghe.example.com:8443

3. 파일 변경 사항을 저장하고 Grafana를 다시 시작하세요.

각 항목은 호스트 이름, host:port, 전체 URL(호스트만 사용됨), 리터럴 IP 주소 또는 CIDR 범위가 될 수 있어요. 가능하면 특정 호스트나 좁은 범위를 사용하세요. 10.0.0.0/8 같은 넓은 CIDR은 SSRF 보호가 차단하는 전체 프라이빗 범위를 다시 노출시키기 때문이에요.

신뢰하는 호스트만 추가하세요. 허용 목록에 등록된 호스트는 모든 동기화, 가져오기, 푸시에서 구성된 Git 토큰을 받기 때문이에요.

리소스 및 역할 권한

기본적으로 Git Sync로 프로비저닝된 폴더에는 다음 역할이 있어요:

• Admin = Admin
• Editor = Editor
• Viewer = Viewer

Git Sync에서 권한을 설정하는 방법에 대한 자세한 내용은 Git Sync permissions를 참고하세요. 권한을 수정하려면 Manage folder permissions를 참고하세요.

Grafana 역할에 대한 자세한 내용은 Roles and permissions를 참고하세요.

GitHub App 만들기

GitHub App은 GitHub 기능을 확장하는 도구예요. 세밀한 권한과 단기 토큰을 사용해 어떤 리포지토리에 접근하는지 더 잘 제어할 수 있어요. 자세한 내용은 GitHub Apps 공식 문서에서 확인하세요.

새로 만든 GitHub App으로 인증하기로 선택했다면 다음 매개변수가 필요해요:

• GitHub App ID
• GitHub App Private Key
• GitHub App Installation ID

GitHub App을 만드는 방법은 여러 가지가 있어요. 아래 지침은 참고용일 뿐이며, 자세한 내용은 항상 공식 GitHub 문서를 참고하세요.

GitHub App을 만들려면 다음 단계를 따르세요:

1. https://github.com/settings/apps로 이동해 New Github App을 클릭하거나, https://github.com/settings/apps/new로 직접 이동하세요.
2. 다음 필드를 채우세요:
   • Name: 고유해야 함
   • Homepage URL: 예를 들어 Grafana Cloud 인스턴스 URL
3. Webhook 섹션까지 아래로 스크롤해 Active 상자의 체크를 해제하세요.
4. Permissions 섹션에서 Repository permissions로 이동해 다음 매개변수를 설정하세요:
   • Administration: 읽기 전용 권한(구성된 브랜치에 직접 푸시할 수 있을 때 브랜치 보호 규칙 검증을 활성화하며, 향후 다른 리포지토리 설정을 확인하고 설정 과정을 더 매끄럽게 하는 데 사용될 수 있음)
   • Contents: 읽기 및 쓰기 권한
   • Metadata: 읽기 전용 권한
   • Pull requests: 읽기 및 쓰기 권한
   • Webhooks: 읽기 및 쓰기 권한
5. 마지막으로 Where can this GitHub App be installed? 아래에서 Only on this account를 선택하세요.
6. 프로세스를 완료하려면 Create Github App을 클릭하세요.

앱 페이지에서:

1. About 섹션에서 AppID를 복사하세요.
2. 배너에서 Generate private key를 선택하거나 Private Keys 섹션까지 아래로 스크롤해 키를 생성하세요.
3. 프라이빗 키가 포함된 PEM 파일이 컴퓨터로 다운로드돼요.

마지막으로 앱을 설치하세요:

1. 앱 페이지 왼쪽 상단에서 Install App을 클릭하세요.
2. 어느 사용자에게 설치할지 선택하면 리포지토리 선택 화면으로 리다이렉트돼요.
3. 앱을 설치할 리포지토리를 선택하세요.
4. Install을 클릭하세요.
5. 설치 페이지에서 페이지 URL https://github.com/settings/installations/installationID에서 installationID 를 복사하세요.

이제 Set up Git Sync로 진행할 수 있어요!

다음 단계

Git Sync가 어떻게 동작하는지 더 자세히 알아보려면 다음을 참고하세요:

• Git Sync key concepts
• Git Sync supported resources
• Git Sync usage and performance limitations

더 알아보기

• 원문 문서