# grafana-dashboard-manager
![CodeQL](https://github.com/Beam-Connectivity/grafana-dashboard-manager/actions/workflows/codeql-analysis.yml/badge.svg)
[![PyPI version](https://badge.fury.io/py/grafana_dashboard_manager.svg)](https://badge.fury.io/py/grafana_dashboard_manager)
A simple CLI utility for importing and exporting dashboards as JSON using the Grafana HTTP API.
This can be used for:
- Backing up your dashboards that already exist within your Grafana instance, e.g. if you are migrating from the internal SQLite database to MySQL.
- Updating dashboard files for your Infrastructure-as-Code for use with [Grafana dashboard provisioning](https://grafana.com/docs/grafana/latest/administration/provisioning/#dashboards).
- Making tweaks to dashboard JSON files directly and updating Grafana with one command.
## Features
- Mirrors the folder structure between a local set of dashboards and Grafana, creating folders where necessary.
- Ensures links to dashboards folders in a `dashlist` Panel are consistent with the Folder UIDs - useful for deploying one set of dashboards across multiple Grafana instances, for instance across environments.
## Usage
> For detailed command help, see the full help text with the `--help` option.
### Credentials
It is important to note that the **admin** login username and password are required, and its selected organization must be correct, if you are accessing the API using `--username` and `--password`. Alternatively, a provided API Key must have **admin** permissions if you are accessing the API using `--token`.
### Docker
A Dockerfile is provided. To build and run:
```sh
docker build -t grafana-dashboard-manager:latest .
docker run grafana-dashboard-manager --help
```
### From PyPI
Install via _[pip](https://pypi.org/project/pip/)_:
```sh
pip install grafana-dashboard-manager
```
### From source
Install dependencies and run with _[Poetry](https://python-poetry.org/)_
```sh
cd /path/to/grafana-dashboard-manager
poetry install
poetry run python ./grafana_dashboard_manager --help
```
## Workflow
The intended workflow is:
1. Download dashboards and to a local directory or version control system for backup and change control.
1. Replicate across multiple Grafana installs or restore a previous install by uploading the saved dashboards.
## Usage Examples
These examples use `docker run` commands, but the commands are the same regardless of run method.
Download dashboards using the Grafana admin user:
```sh
docker run grafana-dashboard-manager \
download \
--scheme https \
--host my.grafana.example.com \
--username $USERNAME --password $PASSWORD \
--destination /path/to/dashboards/
```
Download dashboards using a Grafana admin API Key:
```sh
docker run grafana-dashboard-manager \
download \
--scheme https \
--host my.grafana.example.com \
--token $API_KEY \
--destination /path/to/dashboards/
```
Upload dashboards using the Grafana admin user, to a local instance for testing
```sh
docker run grafana-dashboard-manager \
upload \
--scheme http \
--port 3000 \
--host localhost \
--username $USERNAME --password $PASSWORD \
--source /path/to/dashboards/
```
Upload dashboards using a Grafana admin key without any user prompts:
```sh
docker run grafana-dashboard-manager \
upload \
--scheme http \
--port 3000 \
--host localhost \
--token $API_KEY \
--source /path/to/dashboards/
```
## Notes
- The scheme is `https` and port is 443 by default. If your Grafana is not hosted with https on 443, the scheme and port needs to be specified using the `--scheme` and `--port` options respectively.
- If you use self signed certs on the Grafana server or otherwise don't want to validate an HTTPS connection, use `--skip-verify` although this is not recommended.
- The `version` of the dashboard is removed of the json files in order to allow overwriting and creation of dashboards as new.
- URL encoding of strings is handled by httpx and so characters such as `/` in folder names is supported.
- When uploading, setting the home dashboard from the `home.json` file can be disabled with the option `--skip-home`.
## Limitations
- Does not support the experimental nested folders in Grafana. Only one level of folders is supported.
- Does not support multi-organization deployments.
Raw data
{
"_id": null,
"home_page": "https://www.beamconnectivity.com",
"name": "grafana_dashboard_manager",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "grafana, dashboard, json",
"author": "Vince Chan",
"author_email": "vince@beamconnectivity.com",
"download_url": "https://files.pythonhosted.org/packages/a8/1f/f389e156803662b2b42e2bf23fdb39b8356e6da388237cde19badb45a5ae/grafana_dashboard_manager-0.2.8.85601276621.tar.gz",
"platform": null,
"description": "# grafana-dashboard-manager\n\n![CodeQL](https://github.com/Beam-Connectivity/grafana-dashboard-manager/actions/workflows/codeql-analysis.yml/badge.svg)\n[![PyPI version](https://badge.fury.io/py/grafana_dashboard_manager.svg)](https://badge.fury.io/py/grafana_dashboard_manager)\n\nA simple CLI utility for importing and exporting dashboards as JSON using the Grafana HTTP API.\n\nThis can be used for:\n\n- Backing up your dashboards that already exist within your Grafana instance, e.g. if you are migrating from the internal SQLite database to MySQL.\n- Updating dashboard files for your Infrastructure-as-Code for use with [Grafana dashboard provisioning](https://grafana.com/docs/grafana/latest/administration/provisioning/#dashboards).\n- Making tweaks to dashboard JSON files directly and updating Grafana with one command.\n\n## Features\n\n- Mirrors the folder structure between a local set of dashboards and Grafana, creating folders where necessary.\n- Ensures links to dashboards folders in a `dashlist` Panel are consistent with the Folder UIDs - useful for deploying one set of dashboards across multiple Grafana instances, for instance across environments.\n\n## Usage\n\n> For detailed command help, see the full help text with the `--help` option.\n\n### Credentials\n\nIt is important to note that the **admin** login username and password are required, and its selected organization must be correct, if you are accessing the API using `--username` and `--password`. Alternatively, a provided API Key must have **admin** permissions if you are accessing the API using `--token`.\n\n### Docker\n\nA Dockerfile is provided. To build and run:\n\n```sh\ndocker build -t grafana-dashboard-manager:latest .\ndocker run grafana-dashboard-manager --help\n```\n\n### From PyPI\n\nInstall via _[pip](https://pypi.org/project/pip/)_:\n\n```sh\npip install grafana-dashboard-manager\n```\n\n### From source\n\nInstall dependencies and run with _[Poetry](https://python-poetry.org/)_\n\n```sh\ncd /path/to/grafana-dashboard-manager\npoetry install\npoetry run python ./grafana_dashboard_manager --help\n```\n\n## Workflow\n\nThe intended workflow is:\n\n1. Download dashboards and to a local directory or version control system for backup and change control.\n1. Replicate across multiple Grafana installs or restore a previous install by uploading the saved dashboards.\n\n## Usage Examples\n\nThese examples use `docker run` commands, but the commands are the same regardless of run method.\n\nDownload dashboards using the Grafana admin user:\n\n```sh\ndocker run grafana-dashboard-manager \\\n download \\\n --scheme https \\\n --host my.grafana.example.com \\\n --username $USERNAME --password $PASSWORD \\\n --destination /path/to/dashboards/\n```\n\nDownload dashboards using a Grafana admin API Key:\n\n```sh\ndocker run grafana-dashboard-manager \\\n download \\\n --scheme https \\\n --host my.grafana.example.com \\\n --token $API_KEY \\\n --destination /path/to/dashboards/\n```\n\nUpload dashboards using the Grafana admin user, to a local instance for testing\n\n```sh\ndocker run grafana-dashboard-manager \\\n upload \\\n --scheme http \\\n --port 3000 \\\n --host localhost \\\n --username $USERNAME --password $PASSWORD \\\n --source /path/to/dashboards/\n```\n\nUpload dashboards using a Grafana admin key without any user prompts:\n\n```sh\ndocker run grafana-dashboard-manager \\\n upload \\\n --scheme http \\\n --port 3000 \\\n --host localhost \\\n --token $API_KEY \\\n --source /path/to/dashboards/\n```\n\n## \u00a0Notes\n\n- The scheme is `https` and port is 443 by default. If your Grafana is not hosted with https on 443, the scheme and port needs to be specified using the `--scheme` and `--port` options respectively.\n- If you use self signed certs on the Grafana server or otherwise don't want to validate an HTTPS connection, use `--skip-verify` although this is not recommended.\n- The `version` of the dashboard is removed of the json files in order to allow overwriting and creation of dashboards as new.\n- URL encoding of strings is handled by httpx and so characters such as `/` in folder names is supported.\n- When uploading, setting the home dashboard from the `home.json` file can be disabled with the option `--skip-home`.\n\n## Limitations\n\n- Does not support the experimental nested folders in Grafana. Only one level of folders is supported.\n- Does not support multi-organization deployments.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A cli utility that uses Grafana's HTTP API to easily save and restore dashboards.",
"version": "0.2.8.85601276621",
"project_urls": {
"Homepage": "https://www.beamconnectivity.com",
"Repository": "https://github.com/Beam-Connectivity/grafana-dashboard-manager"
},
"split_keywords": [
"grafana",
" dashboard",
" json"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "35e74f236ca5eff3dcdc11a2ac05590908a5e8f7f964552d12116bc95744b656",
"md5": "04294f3379a13de0c574decd99e19a56",
"sha256": "16bf3d03d60a3cefc06011a38b094d238a078fd8d302dbad15592c0d51959072"
},
"downloads": -1,
"filename": "grafana_dashboard_manager-0.2.8.85601276621-py3-none-any.whl",
"has_sig": false,
"md5_digest": "04294f3379a13de0c574decd99e19a56",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 22557,
"upload_time": "2024-04-04T19:18:42",
"upload_time_iso_8601": "2024-04-04T19:18:42.486915Z",
"url": "https://files.pythonhosted.org/packages/35/e7/4f236ca5eff3dcdc11a2ac05590908a5e8f7f964552d12116bc95744b656/grafana_dashboard_manager-0.2.8.85601276621-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a81ff389e156803662b2b42e2bf23fdb39b8356e6da388237cde19badb45a5ae",
"md5": "731af29820a59a44b26cff7de52db700",
"sha256": "01d15d0a39476c2717c18fa210c9ea60781a8c90b2a810ed848945e9f19a6345"
},
"downloads": -1,
"filename": "grafana_dashboard_manager-0.2.8.85601276621.tar.gz",
"has_sig": false,
"md5_digest": "731af29820a59a44b26cff7de52db700",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 15243,
"upload_time": "2024-04-04T19:18:44",
"upload_time_iso_8601": "2024-04-04T19:18:44.065590Z",
"url": "https://files.pythonhosted.org/packages/a8/1f/f389e156803662b2b42e2bf23fdb39b8356e6da388237cde19badb45a5ae/grafana_dashboard_manager-0.2.8.85601276621.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-04 19:18:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Beam-Connectivity",
"github_project": "grafana-dashboard-manager",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "grafana_dashboard_manager"
}