Set up file provisioning

Local file provisioning is an experimental feature introduced in Grafana v12 for open source and Enterprise editions, but it's not available in Grafana Cloud. Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided.

Use local file provisioning to include in your Grafana instance resources (such as folders and dashboard JSON files) that are stored in a local file system.

This page explains how to set up local file provisioning.

The local path mount is referred to as a repository.

Using the local path lets you also use it with a tool like fuse, allowing you to mount S3 buckets as local paths. You can also use tools like restic to automatically back up your dashboards to your preferred backup storage solution.

To set up file sync with local with local files, you need to:

Configure permitted paths in Grafana configuration file (first time set up).
Set the local path.
Choose what content to sync with Grafana.

New file provisioning capabilities

Local file provisioning using Administration > Provisioning will eventually replace the traditional methods Grafana has used for referencing local file systems for dashboard files.

{{< admonition type="note" >}} For production systems, use the folderFromFilesStructure capability instead of Administration > Provisioning to include dashboards from a local file system in your Grafana instance. Refer to Provision Grafana for more information. {{< /admonition >}}

Limitations

A provisioned dashboard can't be deleted from within Grafana UI. The dashboard has to be deleted at the local file system and those changes synced to Grafana.
Changes from the local file system are one way: you can't save changes from the Grafana UI to GitHub.

Before you begin

To set up file provisioning, you need:

Administration rights in your Grafana organization.
A local directory where your dashboards will be stored.
- If you want to use a GitHub repository, refer to Set up Git Sync.
To update the permitted_provisioning_paths section of custom.ini.

Configure permitted paths

The provisioning feature toggle is enabled by default in Grafana Cloud and, starting in Grafana v13, for OSS and Enterprise as well. No manual configuration of the feature toggle is required.

The local setting must be a relative path and its relative path must be configured in the permitted_provisioned_paths configuration option. The configuration option is relative to your working directory, i.e. where you are running Grafana from; this is usually /usr/share/grafana or similar.

Local file paths can point to any directory that is permitted by the configuration. The default paths is devenv/dev-dashboards and conf/provisioning in your grafana installation directory.

The path must behave as a standard file directory on the system of choice. Any subdirectories are automatically included.

The values that you enter for the permitted_provisioning_paths become the base paths for those entered when you enter a local path in the Connect to local storage wizard.

Open your Grafana configuration file, either grafana.ini or custom.ini. For file location based on operating system, refer to Configuration file location.
Locate or add a [paths] section. To add more than one location, use the pipe character (|) to separate the paths. The list should not include empty paths or trailing pipes. Add these values:
ini
```
[paths]
; This is devenv/dev-dashboards and conf/provisioning by default.
permitted_provisioning_paths = grafana/ | /etc/grafana/provisioning/
```
Save the changes to the file and start Grafana.

Set up file-based provisioning

To use file-based provisioning, you need the file path to the grafana folder where your dashboards are stored in the repository.

To start setting up file-based provisioning:

Log in to your Grafana server with an account that has the Grafana Admin flag set.
Select Administration in the left-side menu and then Provisioning.
Select Configure file provisioning.

Connect to local storage

The local path can point to any directory that is permitted by the configuration. Refer to Configure permitted paths for information.

The starting path is always your working grafana directory. The prefix that must be entered is determined by the locations configured in permitted_provisioning_paths. The default paths are devenv/dev-dashboards and conf/provisioning in your grafana installation directory. The value you enter in the Grafana UI must begin with any of the configured values. For example, conf/provisioning/test is valid, but conf/test is not.

Enter the Local path, for example grafana/. This must begin with any of the configured permitted_provisioned_paths.
Select Choose what to synchronize.

The set up process verifies the path and provides an error message if a problem occurs.

Choose what to synchronize

Synchronization limitations

Full instance sync is not available in Grafana Cloud and is experimental and unsupported in Grafana OSS/Enterprise.

To have access to full instance sync you must explicitly enable the option.

The following applies:

You won't be able to create new alerts or library panels after setup is completed.
If you opted for full instance sync and want to use alerts and library panels, you'll have to delete the provisioned repository and connect again with folder sync.

Set up synchronization

You can sync external resources into a new folder without affecting the rest of your instance.

To set up synchronization:

Select which resources you want to sync.
Enter a Display name for the repository connection. Resources stored in this connection appear under the chosen display name in the Grafana UI.
Click Synchronize to continue.
You can repeat this process for up to 10 connections.

Optionally, you can export any unmanaged resources into the provisioned folder. See how in Synchronize with external storage.

Synchronize with external storage

In this step you proceed to synchronize the resources selected in the previous step. Optionally, you can check the Migrate existing resources box to migrate your unmanaged dashboards to the provisioned folder.

Select Begin synchronization to start the process. After this one time step, all future updates are automatically saved to the local file path and provisioned back to the instance.

Note that during the initial synchronization, your dashboards will be temporarily unavailable. No data or configurations will be lost. How long the process takes depends upon the number of resources involved.

Choose additional settings

If you wish, you can make any files synchronized as as Read only so no changes can be made to the resources through Grafana. Any resources made outside of Grafana and saved to the local repository will be reflected in Grafana.

Select Finish.

Verify your dashboards in Grafana

To verify that your dashboards are available at the location that you specified, click Dashboards. The name of the dashboard is listed in the Name column.