Export and import Grafana dashboards using the Grafana HTTP API and grafana-client.
- Export dashboards into JSON format.
- Import dashboards into Grafana, both in native JSON format, or
emitted by dashboard builders, supporting dashboard-as-code workflows.
- Supported builders are Grafonnet, grafana-dashboard, grafanalib, and any other executable program which emits Grafana Dashboard JSON on STDOUT.
- The import action preserves the version history of dashboards.
- Watchdog: For a maximum of authoring and editing efficiency, the watchdog monitors the input dashboard for changes on disk, and re-uploads it to the Grafana API, when changed.
- Remove dashboards.
pip install --upgrade 'grafana-import[builder] @ git+https://github.com/grafana-toolbox/grafana-import.git'
Currently, there is no up-to-date version on PyPI, so we recommend to
install directly from the repository. The command outlined above describes
a full installation of grafana-import
, including support for dashboard
builders, aka. dashboard-as-code.
You can use grafana-import
in ad hoc mode without a configuration file.
In order to do some orientation flights, start a Grafana instance using Podman or Docker.
docker run --rm -it --name=grafana --publish=3000:3000 \
--env='GF_SECURITY_ADMIN_PASSWORD=admin' grafana/grafana:latest
If you don't have any Grafana dashboard representations at hand, you can
acquire some from the examples
directory within the grafana-import
repository, like this.
wget https://github.com/grafana-toolbox/grafana-snippets/raw/main/dashboard/native-play-influxdb.json
wget https://github.com/grafana-toolbox/grafana-snippets/raw/main/dashboard/gd-prometheus.py
Define Grafana endpoint.
export GRAFANA_URL=http://admin:admin@localhost:3000
Import a dashboard from a JSON file.
grafana-import import -i native-play-influxdb.json
Import a dashboard emitted by a dashboard builder, overwriting it when a dashboard with the same name already exists in the same folder.
grafana-import import --overwrite -i gd-prometheus.py
Watch the input dashboard for changes on disk, and re-upload it, when changed.
grafana-import import --overwrite --reload -i gd-prometheus.py
Export the dashboard titled my-first-dashboard
to the default export directory.
grafana-import export --pretty -d "my-first-dashboard"
Delete the dashboard titled my-first-dashboard
from folder Applications
.
grafana-import remove -f Applications -d "my-first-dashboard"
You can also use grafana-import
with a configuration file. In this way, you
can manage and use different Grafana connection profiles, and also use presets
for application-wide configuration settings.
The configuration is stored in a YAML file. In order to use it optimally, build a directory structure like this:
grafana-import/
- conf/grafana-import.yml
Path to your main configuration file.
- exports/
Path where exported dashboards will be stored.
- imports/
Path where dashboards are imported from.
Then, enter into your directory, and type in your commands.
The configuration file uses two sections, general
, and grafana
.
Configure program directories.
- debug: enable verbose (debug) trace (for dev only...)
- export_suffix: when exporting a dashboard, append that suffix to the file name. The suffix can contain plain text and pattern that is translated with strftime command.
- export_path: where to store the exported dashboards.
- import_path: where to load the dashboards before to import then into grafana server.
Grafana authentication settings. You can define multiple Grafana access
configuration sections using different settings for api_key
or Grafana
server URL.
- label: A label to refer this Grafana server, e.g.
default
- protocol, host, port: use to build the access url
- verify_ssl: to check ssl certificate or not
- token: APIKEY with admin right from Grafana to access the REST API.
- search_api_limit: the maximum element to retrieve on search over API.
Example:
---
general:
debug: false
import_folder: test_import
grafana:
default:
protocol: http
host: localhost
port: 3000
token: "____APIKEY____"
search_api_limit: 5000
verify_ssl: true
In order to connect to Grafana, you can use either vanilla credentials
(username/password), or an authentication token. Because grafana-import
uses grafana-client
, the same features for defining authentication
settings can be used. See also grafana-client authentication variants.
Vanilla credentials can be embedded into the Grafana URL, to be supplied
using the --grafana_url
command line argument, or the GRAFANA_URL
environment variable. For specifying a Grafana authentication token without
using a configuration file, use the GRAFANA_TOKEN
environment variable.
grafana-import provides support for dashboard-as-code builders.
To get inspired what you can do, by reading more examples, please also visit grafonnet examples, grafana-dashboard examples, and grafanalib examples.
Grafonnet is a Jsonnet library for generating Grafana dashboards.
The library is generated from JSON Schemas generated by Grok. In turn, these schemas are generated directly from the Grafana repository, in order to ensure Grafonnet is always synchronized with the development of Grafana without much friction.
Install Jsonnet, and its jsonnet-bundler package manager.
brew install go-jsonnet jsonnet-bundler
Install Grafonnet into a Jsonnet project.
git clone https://github.com/grafana-toolbox/grafana-snippets
cd grafana-snippets/dashboard/grafonnet-simple
jb install github.com/grafana/grafonnet/gen/grafonnet-latest@main
Render dashboard defined in Grafonnet/Jsonnet.
grafana-import import --overwrite -i /path/to/faro.jsonnet
Render dashboard defined using grafana-dashboard.
grafana-import import --overwrite -i /path/to/gd-dashboard.py
Render dashboard defined using grafanalib.
grafana-import import --overwrite -i /path/to/gl-dashboard.py
grafana-import --help
usage: grafana-import [-h] [-a] [-b BASE_PATH] [-c CONFIG_FILE]
[-d DASHBOARD_NAME] [-g GRAFANA_LABEL]
[-f GRAFANA_FOLDER] [-i DASHBOARD_FILE] [-o] [-p] [-v]
[-V]
[ACTION]
play with grafana dashboards json files.
positional arguments:
ACTION action to perform. Is one of 'export', 'import'
(default), or 'remove'.
export: lookup for dashboard name in Grafana and dump
it to local file.
import: import a local dashboard file (previously
exported) to Grafana.
remove: lookup for dashboard name in Grafana and remove
it from Grafana server.
optional arguments:
-h, --help show this help message and exit
-a, --allow_new if a dashboard with same name exists in an another
folder, allow to create a new dashboard with same name
it that folder.
-b BASE_PATH, --base_path BASE_PATH
set base directory to find default files.
-c CONFIG_FILE, --config_file CONFIG_FILE
path to config files.
-d DASHBOARD_NAME, --dashboard_name DASHBOARD_NAME
name of dashboard to export.
-u GRAFANA_URL, --grafana_url GRAFANA_URL
Grafana URL to connect to.
-g GRAFANA_LABEL, --grafana_label GRAFANA_LABEL
label in the config file that represents the grafana to
connect to.
-f GRAFANA_FOLDER, --grafana_folder GRAFANA_FOLDER
the folder name where to import into Grafana.
-i DASHBOARD_FILE, --dashboard_file DASHBOARD_FILE
path to the dashboard file to import into Grafana.
-o, --overwrite if a dashboard with same name exists in folder,
overwrite it with this new one.
-r, --reload Watch the input dashboard for changes on disk, and
re-upload it, when changed.
-p, --pretty use JSON indentation when exporting or extraction of
dashboards.
-v, --verbose verbose mode; display log message to stdout.
-V, --version display program version and exit.
- https://grafana.com/blog/2020/02/26/how-to-configure-grafana-as-code/
- https://grafana.com/blog/2022/12/06/a-complete-guide-to-managing-grafana-as-code-tools-tips-and-tricks/
- https://grafana.github.io/grizzly/ https://grafana.github.io/grizzly/what-is-grizzly/
- https://docs.ansible.com/ansible/latest/collections/grafana/grafana/dashboard_module.html#ansible-collections-grafana-grafana-dashboard-module
- https://blog.kevingomez.fr/2023/03/07/three-years-of-grafana-dashboards-as-code/
- https://github.com/K-Phoen/grabana
- https://github.com/K-Phoen/dark
- https://github.com/grafana/scenes
Contributions are welcome, and they are greatly appreciated. You can contribute in many ways, and credit will always be given.
For learning more how to contribute, see the contribution guidelines and learn how to set up a development sandbox.