Grafana Provisioned Dashboards: How To Update Them

Updating dashboards managed via code can feel frustrating when changes don't show up immediately in the user interface. When you use file-based or API-based provisioning, you don't edit panels directly in the browser; instead, you update your source files and force Grafana to reload them.

You can update Grafana provisioned dashboards by modifying your source JSON files in your configuration directory and reloading the provisioning system via the HTTP API, restarting the service, or configuring the built-in polling interval. Grafana locks provisioned dashboards to prevent manual UI edits, meaning any permanent changes must originate from your source control repository.

Let's dive into how dashboard provisioning works, the exact steps to apply updates without downtime, and how to avoid common pitfalls that trap engineers.

Understanding Grafana Provisioning

Provisioning allows you to manage Grafana data sources, plugins, alerting rules, and dashboards through configuration files and JSON templates rather than manual clicks in the web UI. This approach fits naturally into GitOps workflows, where your monitoring setup lives alongside your application code.

When Grafana starts up, it reads YAML configuration files that point to folders containing dashboard JSON files. Grafana then reads these JSON files and creates or updates the dashboards in its internal database.

Because these dashboards are managed externally, the Grafana UI disables the save and edit buttons for panels by default. If you try to modify a provisioned dashboard directly in the browser, your changes will vanish the next time Grafana restarts or reloads its provisioning config. Therefore, all updates must happen in your source files.

Step-by-Step: Updating File-Based Dashboards

When your dashboards are stored on disk as JSON files, updating them requires a specific workflow to push changes into the running server.

Step 1: Locate Your Source JSON Files

Find the directory where your dashboard JSON files live on your server or in your container image. This path is defined in your provisioning YAML configuration file, usually located at /etc/grafana/provisioning/dashboards/.

Open your provisioning configuration file to check the path:

apiVersion: 1

providers:
  - name: 'default'
    orgId: 1
    folder: 'Services'
    type: file
    disableDeletion: false
    editable: false
    options:
      path: /var/lib/grafana/dashboards

Step 2: Modify the JSON or Export from UI

You have two choices for updating the content. You can edit the JSON file directly in your code editor, or you can import a modified version from a temporary Grafana instance.

If you choose to edit in the UI for testing, you can export the updated JSON via Dashboard Settings > JSON Model. Copy that JSON and replace the contents of your source file in your repository. Ensure you remove the id field from the root of the JSON object before saving it back to disk. Leaving a hardcoded id can cause conflicts if multiple dashboards share the same identifier.

Step 3: Apply Changes Without Restarting

Restarting the entire Grafana service in production causes brief connection drops and unnecessary overhead. Instead, use Grafana's HTTP API to trigger a reload of the dashboard provisioning system.

Send a POST request to the admin reload endpoint using curl:

curl -X POST -u admin:admin_password http://localhost:3000/api/admin/provisioning/dashboards/reload

If successful, Grafana responds with a confirmation message, and your updated dashboards appear in the UI within a few seconds.

Automating Updates with Git and CI/CD

In modern environments, you shouldn't manually SSH into servers to update JSON files. Instead, tie your dashboards to a CI/CD pipeline using official tools like Grafana Labs.

When developers push changes to a Git repository containing your infrastructure-as-code manifests, your CI pipeline should deploy the updated JSON files to your Kubernetes ConfigMaps, Docker volumes, or virtual machines.

For Kubernetes deployments using Helm, your dashboards typically live in ConfigMaps. Updating them involves modifying your Helm values file, bumping the chart version, and running a upgrade command:

helm upgrade monitoring-stack grafana/grafana -f values.yaml

Kubernetes automatically mounts the updated ConfigMap into the Grafana pod. Because Grafana monitors its file paths, or because you can trigger the provisioning reload API via a post-install hook, the dashboards update seamlessly.

Common Mistakes to Avoid

Even experienced engineers run into roadblocks when managing provisioned assets. Watch out for these frequent missteps:

• Forgetting to remove the dashboard ID: Leaving an explicit "id": 123 field in your JSON file can cause Grafana to throw duplicate key errors or overwrite unrelated dashboards if another dashboard already uses that ID. Set the id field to null in your source files.
• Editing dashboards directly in the UI: Relying on the web interface to tweak a panel color or query will leave you with a rude awakening after the next server reboot. Always update the source code.
• Ignoring folder permissions and UIDs: If you change a dashboard's uid, Grafana treats it as an entirely new dashboard rather than an update to an existing one. Keep stable UIDs across versions.
• Misconfigured file paths: Ensure the user running the Grafana process has read permissions for the target dashboard directories. Permission denied errors will silently fail to load dashboards during startup.

Frequently Asked Questions

Why are my dashboard edit buttons disabled in Grafana?

Provisioned dashboards are locked by design to enforce code-based management. To edit them, you must update the source JSON file on disk or in your repository rather than clicking through the web interface.

How do I force Grafana to reload dashboards without restarting?

You can trigger an immediate reload of all provisioned dashboards by sending a POST request to Grafana's admin API endpoint at /api/admin/provisioning/dashboards/reload using an account with administrator privileges.

Can I use environment variables inside my dashboard JSON files?

Grafana does not natively parse environment variables inside dashboard JSON files. If you need dynamic values like data source names or server hosts, you can use provisioning file templating or pre-process your JSON files with a build script or CI pipeline tool before deploying them.

What happens if I change a dashboard UID in my source file?

Grafana uses the dashboard uid as its primary unique identifier. Changing the UID causes Grafana to create a brand-new dashboard instead of updating the existing one, leaving the old dashboard orphaned in your workspace. Keep UIDs consistent when making edits.