Grafana 서버 CLI로 Grafana 관리
Grafana 서버 CLI로 Grafana 관리 (Administer Grafana with the Grafana server CLI)
Grafana 서버 CLI는 Grafana 서버에 번들로 포함된 작은 실행 파일로, 이 CLI로 Grafana 인스턴스를 관리할 수 있어요. plugins와 admin 명령, 그리고 전역 옵션을 제공해요.
출처: 문서
본문
Grafana 서버 CLI(grafana server CLI)라는 Grafana 서버에 번들로 포함된 작은 실행 파일로 Grafana 인스턴스를 관리할 수 있어요.
Grafana 서버 CLI에는 plugins와 admin 명령, 그리고 전역 옵션(global options)이 있어요. 이들을 나열하려면 다음을 실행해요:
grafana cli -h
자세한 내용은 계속 읽어보세요.
Grafana 서버 CLI 실행 (Run the Grafana server CLI)
Grafana 서버 CLI는 Grafana 서버가 실행 중인 같은 머신에서 실행할 수 있어요.
CLI를 실행하는 방법은 다음과 같아요:
- Grafana 바이너리의 경로를
PATH환경 변수에 추가해요. - 현재 디렉터리가
bin디렉터리라면./grafana cli를 실행해요. - 그 외에는 바이너리의 전체 경로를 지정해요. 예를 들어 Linux의
/usr/share/grafana/bin/grafana, Windows의C:\Program Files\GrafanaLabs\grafana\bin\grafana.exe예요.
Grafana 서버 CLI 명령의 일반 문법은:
grafana cli [global options] command [command options] [arguments...]
Note
플러그인 설치·제거 같은 일부 명령은 Linux에서
sudo가 필요해요. Windows라면 관리자 권한으로 Windows PowerShell을 실행하세요.
전역 옵션 (Global options)
Grafana 서버 CLI는 특정 Grafana 기본 설정을 일시적으로 오버라이드할 수 있게 해줘요. --help와 --version을 제외한 대부분의 전역 옵션은 개발자만 사용해요.
각 전역 옵션은 사용된 명령에만 적용돼요. 예를 들어 --pluginsDir value는 Grafana가 플러그인을 저장하는 위치를 영구적으로 변경하지 않아요. 옵션을 적용한 명령에만 변경을 적용해요.
Grafana 서버 CLI 도움말 표시 (Display Grafana server CLI help)
--help 또는 -h는 기본 경로와 Docker 구성 정보를 포함한 도움말을 표시해요.
예시:
grafana cli -h
Grafana 서버 CLI 버전 표시 (Display Grafana server CLI version)
--version 또는 -v는 현재 실행 중인 Grafana 서버 CLI의 버전을 출력해요.
예시:
grafana cli -v
기본 플러그인 디렉터리 오버라이드 (Override default plugin directory)
--pluginsDir value는 로컬 Grafana 인스턴스가 플러그인을 저장하는 경로를 오버라이드해요. 기본 디렉터리("/var/lib/grafana/plugins") [$GF_PLUGIN_DIR] 외 다른 곳에 플러그인을 설치·업데이트·제거하려면 이 옵션을 사용해요.
예시:
grafana cli --pluginsDir "/var/lib/grafana/devplugins" plugins install <plugin-id>
기본 플러그인 저장소 URL 오버라이드 (Override default plugin repo URL)
--repo value를 사용하면 기본 Grafana 저장소가 아닌 다른 저장소에서 플러그인을 다운로드해 설치하거나 업데이트할 수 있어요.
예시:
grafana cli --repo "https://example.com/plugins" plugins install <plugin-id>
기본 플러그인 .zip URL 오버라이드 (Override default plugin .zip URL)
--pluginUrl value는 기본 Grafana 소스에서 다운로드하는 대신 로컬 URL에서 플러그인이 포함된 .zip 파일을 다운로드할 수 있게 해줘요.
예시:
grafana cli --pluginUrl https://company.com/grafana/plugins/<plugin-id>-<plugin-version>.zip plugins install <plugin-id>
전송 계층 보안 오버라이드 (Override Transport Layer Security)
Warning: TLS를 끄는 것은 상당한 보안 위험이에요. 이 옵션 사용을 권장하지 않아요.
--insecure는 전송 계층 보안(TLS) 검증을 끌 수 있게 해줘요. 기본이 아닌 소스에서 플러그인을 다운로드할 때 이 옵션을 사용하고 싶을 수 있어요.
예시:
grafana cli --insecure --pluginUrl https://company.com/grafana/plugins/<plugin-id>-<plugin-version>.zip plugins install <plugin-id>
디버그 로깅 활성화 (Enable debug logging)
--debug 또는 -d는 디버그 로깅을 활성화해요. 디버그 출력은 터미널에 반환·표시돼요.
예시:
grafana cli --debug plugins install <plugin-id>
구성 설정 오버라이드 (Override a configuration setting)
--configOverrides는 환경 변수 오버라이드처럼 작동하는 명령줄 인자예요.
예를 들어 로깅을 다른 파일로 리다이렉트하거나(예: Grafana Cloud에서 플러그인 설치를 기록), 데이터베이스 위치 같은 중요한 구성 값이 기본이 아닐 때 관리자 비밀번호를 리셋하는 데 사용할 수 있어요.
예시:
grafana cli --configOverrides cfg:default.paths.log=/dev/null plugins install <plugin-id>
홈패스 값 오버라이드 (Override homepath value)
Grafana 설치/홈 경로를 설정해요. 기본값은 작업 디렉터리예요. CLI 사용 시 Grafana 설치 디렉터리에 있다면 사용할 필요가 없어요.
예시:
grafana cli --homepath "/usr/share/grafana" admin reset-admin-password <new password>
구성 파일 오버라이드 (Override config file)
--config value는 Grafana가 구성 파일을 기대하는 기본 위치를 오버라이드해요. Grafana 구성과 기본 구성 파일 위치에 대한 자세한 내용은 Configuration을 참고해요.
예시:
grafana cli --config "/etc/configuration/" admin reset-admin-password mynewpassword
플러그인 명령 (Plugins commands)
Grafana CLI를 사용하면 Grafana 플러그인을 설치·업그레이드·관리할 수 있어요. 플러그인 설치에 대한 자세한 내용은 plugins page를 참고해요.
나열된 모든 명령은 Grafana 기본 저장소와 디렉터리에 적용돼요. Global Options로 기본값을 오버라이드할 수 있어요.
사용 가능한 플러그인 나열 (List available plugins)
grafana cli plugins list-remote
플러그인의 최신 버전 설치 (Install the latest version of a plugin)
grafana cli plugins install <plugin-id>
플러그인의 특정 버전 설치 (Install a specific version of a plugin)
grafana cli plugins install <plugin-id> <version>
설치된 플러그인 나열 (List installed plugins)
grafana cli plugins ls
설치된 모든 플러그인 업데이트 (Update all installed plugins)
grafana cli plugins update-all
하나의 플러그인 업데이트 (Update one plugin)
grafana cli plugins update <plugin-id>
하나의 플러그인 제거 (Remove one plugin)
grafana cli plugins remove <plugin-id>
관리 명령 (Admin commands)
Admin 명령은 Grafana 4.1 이상에서만 사용할 수 있어요.
모든 관리 명령 표시 (Show all admin commands)
grafana cli admin
관리자 비밀번호 리셋 (Reset admin password)
grafana cli admin reset-admin-password <new password>는 CLI를 사용해 admin 사용자의 비밀번호를 리셋해요. 관리자 비밀번호를 잃어버렸을 때 필요할 수 있어요. 기본적으로 이 명령은 admin 사용자의 기본 ID인 1을 사용해요. admin 사용자의 ID를 알고 있다면 --user-id 플래그로 사용자 ID를 지정할 수 있어요. --user-id 플래그가 지정되지 않고 명령이 admin 사용자를 찾지 못하면, 현재 admin 사용자의 사용자 이름과 ID 목록을 반환해요. 이 목록에서 admin 사용자의 ID를 확인하고 --user-id 플래그로 다시 명령을 실행할 수 있어요.
homepath와 구성 파일 경로를 설정하는 두 플래그가 사용되면 명령이 다음 오류를 반환해요:
Could not find config defaults, make sure homepath command line parameter is set or working directory is homepath
이를 해결하려면 --homepath 전역 옵션으로 이 명령의 Grafana 기본 homepath를 지정해요:
grafana cli --homepath "/usr/share/grafana" admin reset-admin-password <new password>
관리자 비밀번호를 잃어버리지 않았다면, User Preferences 또는 Server Admin > User 탭에서 사용자 비밀번호를 변경하는 것을 권장해요.
스크립트에서 비밀번호를 설정해야 한다면 Grafana User API를 사용할 수 있어요.
관리자 비밀번호 리셋 (Reset admin password)
Homebrew로 Grafana를 설치했다면 다음 명령으로 관리자 비밀번호를 리셋할 수 있어요:
/opt/homebrew/opt/grafana/bin/grafana cli --config /opt/homebrew/etc/grafana/grafana.ini --homepath /opt/homebrew/opt/grafana/share/grafana --configOverrides cfg:default.paths.data=/opt/homebrew/var/lib/grafana admin reset-admin-password <new password>
Grafana Operator로 배포하고 외부 데이터베이스를 사용하는 경우 관리자 비밀번호 리셋
Grafana Operator로 Grafana를 배포하고 Grafana가 외부 PostgreSQL 또는 MySQL 데이터베이스를 사용하도록 구성했다면, 명령에 homepath와 구성 파일을 모두 지정해요:
grafana cli --homepath /usr/share/grafana --config /etc/grafana/grafana.ini admin reset-admin-password <new password>
이렇게 하지 않으면 CLI는:
- Grafana homepath 밖의 디렉터리에 있으므로 데이터베이스 연결 정보를 볼 수 없어요
/var/lib/grafana에 기본 SQLite 데이터베이스를 구성해 외부 데이터베이스가 아닌 그 비밀번호를 리셋해요
데이터 마이그레이션 및 비밀번호 암호화 (Migrate data and encrypt passwords)
data-migration은 데이터베이스의 데이터를 마이그레이션하거나 정리하는 스크립트를 실행해요.
encrypt-datasource-passwords는 비밀번호를 안전하지 않은 필드에서 secure_json_data 필드로 마이그레이션해요. 오류가 없으면 ok를 반환해요. 여러 번 실행해도 안전해요.
예시:
grafana cli admin data-migration encrypt-datasource-passwords