grafanactl CLI 설치 및 설정

주의

grafanactl은 사용 중단(deprecated)될 예정이며, 지금까지의 모든 학습과 경험을 새롭게 개선된 CLI 도구인 gcx로 옮기고 있어요. GitHub의 grafanactl 저장소는 2026년 6월 1일에 보관(archive)될 거예요.

grafanactl에서 gcx로 마이그레이션하려면 grafanactl을 gcx로 검색·바꾸기 하세요. grafanactl resources serve의 경우에는 gcx dev serve를 대신 사용하세요.

grafanactl 명령줄 도구를 사용하면 Grafana REST API를 통해 터미널에서 인증하고, 여러 환경을 관리하고, 관리 작업을 수행할 수 있어요. Grafana OSS, Enterprise, Cloud에서 모두 사용할 수 있어요.

출처: 문서

본문

Grafana CLI grafanactl 설치

다음 지원되는 방법 중 하나로 프로젝트를 설치할 수 있어요.

1. 사전 빌드된 바이너리 다운로드

Releases 페이지에서 플랫폼에 맞는 최신 바이너리를 다운로드하세요.

사전 빌드된 바이너리는 다양한 운영 체제와 아키텍처에 제공돼요. 최신 릴리스 페이지를 방문해 Assets 섹션으로 스크롤하세요.

바이너리를 설치하려면 아래 지침을 따르세요:

원하는 운영 체제와 아키텍처의 아카이브를 다운로드
아카이브 추출
실행 파일을 원하는 디렉터리로 이동
이 디렉터리가 PATH 환경 변수에 포함되어 있는지 확인
파일에 실행 권한이 있는지 확인

2. 소스에서 빌드

grafanactl을 소스에서 빌드하려면 다음이 필요해요:

git 설치
go v1.24(또는 그 이상) 설치

go install github.com/grafana/grafanactl/cmd/grafanactl@latest

grafanactl 구성

grafanactl은 환경 변수 또는 구성 파일의 두 가지 방식으로 구성할 수 있어요.

환경 변수는 CI 환경에 적합하며 단일 컨텍스트(context)를 지원해요. 지원되는 환경 변수의 전체 목록은 참조 문서에서 확인할 수 있어요.
구성 파일은 여러 컨텍스트를 관리할 수 있어 서로 다른 Grafana 인스턴스 간 전환을 더 쉽게 만들어요.

참고

구성 항목은 설정 방식에 따라 달라질 수 있어요. 예를 들어 자체 관리형 Grafana에서는 org-id를 사용하지만 Grafana Cloud에서는 stack-id를 사용하세요.

환경 변수로 Grafana CLI 구성

Grafana CLI는 REST API를 통해 Grafana와 통신하며, 여기에는 인증 자격 증명이 필요해요.

최소한 Grafana 인스턴스의 URL과 조직 ID를 설정하세요:

GRAFANA_SERVER='http://localhost:3000' GRAFANA_ORG_ID='1' grafanactl config check

인증 방식에 따라 다음도 설정해야 할 수 있어요:

Grafana 서비스 계정의 토큰 (권장)
기본 인증을 위한 사용자 이름과 비밀번호

구성을 영구화하려면 컨텍스트를 만드는 것을 고려하세요.

구성 컨텍스트 사용

컨텍스트를 사용하면 여러 Grafana 인스턴스 간에 쉽게 전환할 수 있어요.

기본적으로 CLI는 default라는 이름의 컨텍스트를 사용해요. 구성하려면 다음을 사용하세요:

grafanactl config set contexts.default.grafana.server http://localhost:3000
grafanactl config set contexts.default.grafana.org-id 1

서비스 계정 토큰으로 인증:

grafanactl config set contexts.default.grafana.token service-account-token

또는 기본 인증 사용:

grafanactl config set contexts.default.grafana.user admin
grafanactl config set contexts.default.grafana.password admin

같은 방식으로 추가 컨텍스트를 정의할 수 있어요:

grafanactl config set contexts.staging.grafana.server https://staging.grafana.example
grafanactl config set contexts.staging.grafana.org-id 1

참고

이 예시에서 default와 staging은 컨텍스트의 이름이에요.

구성 파일로 Grafana CLI 구성

Grafana CLI는 구성을 YAML 파일에 저장해요. CLI는 다음 순서로 구성 파일 위치를 결정해요:

--config 플래그가 제공되면 지정된 파일을 사용해요.
$XDG_CONFIG_HOME이 설정된 경우: $XDG_CONFIG_HOME/grafanactl/config.yaml
$HOME이 설정된 경우: $HOME/.config/grafanactl/config.yaml
$XDG_CONFIG_DIRS가 설정된 경우: $XDG_CONFIG_DIRS/grafanactl/config.yaml

참고

grafanactl config check를 사용하면 현재 사용 중인 구성 파일을 표시할 수 있어요.

유용한 명령

현재 구성을 확인:

grafanactl config check

참고

이 명령은 구성 문제를 해결하는 데 유용해요.

사용 가능한 모든 컨텍스트 나열:

grafanactl config list-contexts

특정 컨텍스트로 전환:

grafanactl config use-context staging

전체 구성 보기:

grafanactl config view

grafanactl CLI 설치 및 설정