파일 프로비저닝 설정

파일 프로비저닝 설정 (Set up file provisioning)

이 문서는 로컬 파일 시스템에 저장한 리소스를 Grafana 인스턴스에 포함시키는 로컬 파일 프로비저닝(local file provisioning)을 설정하는 방법을 안내해요. 허용 경로 구성부터 동기화할 내용 선택, 동기화 실행까지 단계별로 다뤄요.

출처: 문서

본문

Note 온프레미스 파일 프로비저닝은 오픈 소스 및 Enterprise 에디션의 Grafana v12 이상에서 사용할 수 있어요. Grafana Cloud에서는 사용할 수 없어요. 이 새로운 파일 프로비저닝 기능은 대시보드에만 사용할 수 있고, 당분간 기존 프로비저닝(classic provisioning)을 대체하지는 않아요. 구성 파일을 사용한 기존 프로비저닝은 Provision Grafana을 참고해요.

로컬 파일 프로비저닝을 사용하면 로컬 파일 시스템에 저장한 리소스를 Grafana 인스턴스에 포함시킬 수 있어요. 로컬 경로 마운트를 repository라고 해요.

로컬 경로를 사용하면 fuse 같은 도구와 함께 쓸 수도 있어요. 이를 통해 S3 버킷을 로컬 경로로 마운트할 수 있어요. 또한 restic 같은 도구를 사용해 대시보드를 원하는 백업 저장소로 자동 백업할 수도 있어요.

로컬 파일과 파일 동기화를 설정하려면 다음 단계를 거쳐요:

Grafana 구성 파일에서 허용 경로(permitted paths)를 구성해요 (최초 설정 시).
로컬 경로를 설정해요.
Grafana와 동기화할 콘텐츠를 선택해요.

새로운 파일 프로비저닝 기능 (New file provisioning capabilities)

Administration > Provisioning을 사용한 로컬 파일 프로비저닝은 결국 Grafana가 대시보드 파일용 로컬 파일 시스템을 참조하던 기존 방식을 대체하게 돼요.

Note 프로덕션 시스템에서는 로컬 파일 시스템의 대시보드를 Grafana 인스턴스에 포함시키려면 Administration > Provisioning 대신 folderFromFilesStructure 기능을 사용해요. 자세한 내용은 Provision Grafana를 참고해요.

시작하기 전에 (Before you begin)

파일 프로비저닝을 설정하려면 다음이 필요해요:

Grafana 조직의 관리 권한.
대시보드를 저장할 로컬 디렉터리. GitHub 저장소를 사용하려면 Set up Git Sync을 참고해요.
custom.ini의 permitted_provisioning_paths 섹션 업데이트.
로컬 파일 프로비저닝의 제한 사항 이해. 자세한 내용은 동작 방식(How it works)을 참고해요.

허용 경로 구성 (Configure permitted paths)

provisioning 기능 토글은 Grafana Cloud에서 기본적으로 활성화되며, Grafana v13부터 OSS와 Enterprise에서도 기본 활성화돼요. 기능 토글을 수동으로 구성할 필요는 없어요.

로컬 설정은 상대 경로여야 하며, 그 상대 경로는 permitted_provisioned_paths 구성 옵션에 구성해야 해요. 이 구성 옵션은 작업 디렉터리(즉 Grafana를 실행하는 위치, 보통 /usr/share/grafana 등)를 기준으로 해요.

로컬 파일 경로는 구성에서 허용하는 모든 디렉터리를 가리킬 수 있어요. 기본 경로는 grafana 설치 디렉터리의 devenv/dev-dashboards와 conf/provisioning이에요.

경로는 대상 시스템의 표준 파일 디렉터리처럼 동작해야 해요. 모든 하위 디렉터리는 자동으로 포함돼요.

permitted_provisioning_paths에 입력한 값은 Connect to local storage 마법사에서 로컬 경로를 입력할 때의 기본 경로가 돼요.

grafana.ini 또는 custom.ini 중 Grafana 구성 파일을 열어요. 운영 체제별 파일 위치는 Configuration file location을 참고해요.
[paths] 섹션을 찾거나 추가해요. 두 개 이상의 위치를 추가하려면 파이프 문자(|)로 경로를 구분해요. 목록에 빈 경로나 끝에 붙는 파이프는 포함하지 않아요. 다음 값을 추가해요:

[paths]
; This is devenv/dev-dashboards and conf/provisioning by default.
permitted_provisioning_paths = grafana/ | /etc/grafana/provisioning/

파일의 변경 사항을 저장하고 Grafana를 시작해요.

파일 기반 프로비저닝 설정 (Set up file-based provisioning)

파일 기반 프로비저닝을 사용하려면 저장소에서 대시보드가 저장된 grafana 폴더의 파일 경로가 필요해요.

파일 기반 프로비저닝 설정을 시작하려면:

Grafana Admin 플래그가 설정된 계정으로 Grafana 서버에 로그인해요.
왼쪽 메뉴에서 Administration을 선택한 다음 Provisioning을 선택해요.
Configure file provisioning을 선택해요.

로컬 저장소에 연결 (Connect to local storage)

로컬 경로는 구성에서 허용하는 모든 디렉터리를 가리킬 수 있어요. 자세한 내용은 허용 경로 구성을 참고해요. 시작 경로는 항상 작업 grafana 디렉터리예요.

입력해야 하는 접두사는 permitted_provisioning_paths에 구성된 위치에 따라 결정돼요. 기본 경로는 grafana 설치 디렉터리의 devenv/dev-dashboards와 conf/provisioning이에요.

Grafana UI에 입력하는 값은 구성된 값 중 하나로 시작해야 해요. 예를 들어 conf/provisioning/test는 유효하지만 conf/test는 유효하지 않아요.

Local path를 입력해요 (예: grafana/). 이 값은 구성된 permitted_provisioned_paths 중 하나로 시작해야 해요.
Choose what to synchronize를 선택해요.

설정 과정이 경로를 검증하고 문제가 있으면 오류 메시지를 제공해요.

동기화할 내용 선택 (Choose what to synchronize)

동기화 제한 사항 (Synchronization limitations)

전체 인스턴스 동기화(full instance sync)에 접근하려면 해당 옵션을 명시적으로 활성화해야 해요. 다음 사항이 적용돼요:

설정 완료 후에는 새 알림이나 라이브러리 패널을 만들 수 없어요.
전체 인스턴스 동기화를 선택하고 알림과 라이브러리 패널을 사용하려면 프로비저닝된 저장소를 삭제하고 폴더 동기화로 다시 연결해야 해요.

동기화 설정 (Set up synchronization)

인스턴스의 나머지 부분에 영향을 주지 않고 외부 리소스를 새 폴더로 동기화할 수 있어요. 동기화를 설정하려면:

동기화할 리소스를 선택해요.
저장소 연결의 Display name을 입력해요. 이 연결에 저장된 리소스는 Grafana UI에서 선택한 표시 이름 아래에 나타나요.
계속하려면 Synchronize를 클릭해요.
최대 10개 연결까지 이 과정을 반복할 수 있어요.

Note 선택적으로 관리되지 않는 리소스(unmanaged resources)를 provisioned 폴더로 내보낼 수 있어요. 방법은 외부 저장소와 동기화를 참고해요.

외부 저장소와 동기화 (Synchronize with external storage)

이 단계에서는 이전 단계에서 선택한 리소스를 동기화해요. 선택적으로 Migrate existing resources 상자를 선택해 관리되지 않는 대시보드를 provisioned 폴더로 마이그레이션할 수 있어요.

Begin synchronization을 선택해 과정을 시작해요. 이 일회성 단계 이후에는 모든 향후 업데이트가 자동으로 로컬 파일 경로에 저장되고 인스턴스로 다시 프로비저닝돼요.

초기 동기화 동안에는 대시보드가 일시적으로 사용 불가 상태가 될 수 있어요. 데이터나 구성이 손실되지는 않아요. 과정에 걸리는 시간은 관련된 리소스 수에 따라 달라져요.

추가 설정 선택 (Choose additional settings)

원하면 동기화된 파일을 Read only(읽기 전용)로 만들어 Grafana를 통해 리소스를 변경할 수 없게 할 수 있어요. Grafana 외부에서 만들어 로컬 저장소에 저장된 리소스는 Grafana에 반영돼요.

Finish를 선택해요.

Grafana에서 대시보드 확인 (Verify your dashboards in Grafana)

대시보드가 지정한 위치에서 사용 가능한지 확인하려면 Dashboards를 클릭해요. 대시보드 이름은 Name 열에 나열돼요.

더 알아보기

원문 문서