grafanactl로 리소스 관리

주의

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

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

config 및 resources 옵션을 사용해 Grafana 리소스를 한 환경에서 다른 환경으로 마이그레이션할 수 있어요(예: 개발 환경에서 프로덕션 환경으로). config 옵션은 구성 컨텍스트를 정의할 수 있게 해요. resources를 pull, push, serve와 함께 사용하면 정의된 리소스를 한 인스턴스에서 끌어오고(pull) 해당 리소스를 다른 인스턴스로 푸시(push)할 수 있어요. serve는 푸시 전에 변경 사항을 로컬에서 미리 볼 수 있게 해요.

참고

현재 serve 명령은 대시보드에서만 작동해요.

참고

리소스는 기본적으로 ./resources 디렉터리에서 풀·푸시돼요. -p, --path 플래그로 디스크의 사용자 지정 경로를 지정해 구성할 수 있어요.

출처: 문서

본문

환경 간 리소스 마이그레이션

다음 단계를 사용해 환경 간 리소스를 마이그레이션하세요:

개발 인스턴스의 Grafana UI를 사용해 대시보드 및 기타 리소스를 변경하세요.
해당 리소스를 개발 환경에서 로컬 머신으로 끌어오세요:

grafanactl config use-context YOUR_CONTEXT
grafanactl resources pull --path ./resources/ -o yaml

(선택 사항) 푸시 전에 리소스를 로컬에서 미리 보세요:

grafanactl config use-context YOUR_CONTEXT
grafanactl resources serve ./resources/

프로덕션 인스턴스로 전환하고 리소스를 푸시하세요:

grafanactl config use-context YOUR_CONTEXT
grafanactl resources push -p ./resources/

Grafana 리소스 백업

이 워크플로는 한 인스턴스의 모든 Grafana 리소스를 백업하고 나중에 복원하는 데 도움이 돼요. 구성 복제 또는 재해 복구를 수행하는 데 유용해요.

grafanactl을 사용해 대상 환경에서 모든 리소스를 끌어오세요:

grafanactl config use-context YOUR_CONTEXT
grafanactl resources pull --path ./resources/ -o yaml

내보낸 리소스를 버전 관리 또는 클라우드 스토리지에 저장하세요.

Grafana 리소스 복원

(선택 사항) 백업을 로컬에서 미리 보세요:

grafanactl config use-context YOUR_CONTEXT
grafanactl resources serve ./resources/

나중에 리소스를 복원하거나 다른 인스턴스에서 복원하려면 저장된 리소스를 푸시하세요:

grafanactl config use-context YOUR_CONTEXT
grafanactl resources push -p ./resources/

대시보드를 코드로 관리

이 워크플로를 통해 대시보드를 코드로 정의하고 관리하면서 Git 같은 버전 관리 시스템에 저장할 수 있어요. 변경 기록을 유지하고, 대시보드 설계에서 협업하고, 환경 간 일관성을 보장하려는 팀에 유용해요.

대시보드 생성 스크립트를 사용하세요(예: Foundation SDK 사용). 예제 구현은 Grafana as code hands-on lab 저장소에서 찾을 수 있어요.
대시보드 생성기의 출력을 로컬에서 서빙하고 미리 보세요:

grafanactl config use-context YOUR_CONTEXT
grafanactl resources serve --script 'go run scripts/generate-dashboard.go' --watch './scripts'

출력이 올바르게 보이면 대시보드 매니페스트 파일을 생성하세요:

go run scripts/generate-dashboard.go --generate-resource-manifests --output './resources'

생성된 리소스를 Grafana 인스턴스에 푸시하세요:

grafanactl config use-context YOUR_CONTEXT
grafanactl resources push -p ./resources/

터미널에서 리소스 탐색 및 수정

이 섹션에서는 Grafana CLI를 사용해 터미널에서 직접 Grafana 리소스와 상호작용하는 방법을 설명해요. 이러한 명령을 사용하면 Grafana UI 없이 리소스를 탐색·검사·업데이트·삭제할 수 있어요. 이 접근 방식은 리소스를 더 효율적으로 관리하거나 Grafana 작업을 자동화된 워크플로에 통합하려는 고급 사용자에게 유용해요.

잘못된 데이터 소스를 사용하는 대시보드 찾기 및 삭제

이 워크플로를 사용해 잘못되었거나 오래된 데이터 소스를 참조하는 대시보드를 식별하고, 필요하면 제거하세요.

적절한 환경으로 컨텍스트를 설정하세요:

grafanactl config use-context YOUR_CONTEXT

특정 데이터 소스를 사용하는 대시보드 찾기:

grafanactl resources get dashboards -ojson | jq '.items | map({ uid: .metadata.name, datasources: .spec.panels | map(.datasource.uid)  })'
[
   {
      "uid": "important-production-dashboard",
      "datasources": [
         "mimir-prod"
      ]
   },
   {
      "uid": "test-dashboard-from-dev",
      "datasources": [
         "mimir-prod",
         "mimir-dev"
      ]
   },
   {
      "uid": "test-dashboard-from-stg",
      "datasources": [
         "mimir-prod",
         "mimir-stg",
         "mimir-dev"
      ]
   }
]

이 명령은 대시보드 UID와 해당 패널에서 사용되는 데이터 소스 UID를 나열해요. 그런 다음 잘못되었거나 예상치 못한 데이터 소스를 사용하는 대시보드를 식별할 수 있어요.

식별된 대시보드를 직접 삭제하세요:

grafanactl resources delete dashboards/test-dashboard-from-stg,test-dashboard-from-dev
✔ 2 resources deleted, 0 errors

이전 API 버전을 사용하는 대시보드 찾기 및 사용 중단 표시

이 워크플로를 사용해 사용 중단된 API 버전을 사용하는 대시보드를 찾고 그에 따라 표시하세요.

적절한 환경으로 컨텍스트를 설정하세요:

grafanactl config use-context YOUR_CONTEXT

사용 가능한 모든 리소스 유형과 버전을 나열하세요:

grafanactl resources list

이 명령은 버전, 유형, 수량을 포함한 리소스 목록을 반환해요:

GROUP                               VERSION   KIND
folder.grafana.app                  v1        folder
dashboard.grafana.app               v1        dashboard
dashboard.grafana.app               v1        librarypanel
dashboard.grafana.app               v2        dashboard
dashboard.grafana.app               v2        librarypanel
playlist.grafana.app                v1        playlist

여전히 사용 중단된 API 버전을 사용하는 대시보드를 찾으세요:

grafanactl resources get dashboards.v1.dashboard.grafana.app

이 명령은 리소스 유형, 리소스 이름, 연결된 네임스페이스를 표시하는 테이블을 반환해요:

KIND         NAME                                   NAMESPACE
dashboards   really-old-dashboard                   default

각 대시보드를 편집해 deprecated 태그를 추가하세요:

grafanactl resources edit dashboards.v1.dashboard.grafana.app/really-old-dashboard -p '{"spec":{"tags":["deprecated"]}}'

팁

grafanactl --help 명령으로 도움말을 볼 수 있어요.

grafanactl로 리소스 관리