Documentation Grafana documentation Administration Provision Grafana

Provision Grafana

Grafana has an active provisioning system that uses configuration files. This makes GitOps more natural since data sources and dashboards can be defined using files that can be version controlled.

Configuration file

Refer to Configuration for more information on what you can configure in grafana.ini.

Configuration file locations

• Default configuration from $WORKING_DIR/conf/defaults.ini
• Custom configuration from $WORKING_DIR/conf/custom.ini
• The custom configuration file path can be overridden using the --config parameter

Environment variables

You can use environment variable interpolation in all three provisioning configuration types. The allowed syntax is either $ENV_VAR_NAME or ${ENV_VAR_NAME}, and it can be used only for values, not for keys or larger parts of the configurations. It’s not available in the dashboard’s definition files, just the dashboard provisioning configuration.

Example:

yaml Copy

datasources:
  - name: Graphite
    url: http://localhost:$PORT
    user: $USER
    secureJsonData:
      password: $PASSWORD

You can use $$ if you have a literal $ in your value and want to avoid interpolation.

Configuration management tools

Currently, we don’t provide any scripts or manifests for configuring Grafana. Rather than spending time learning and creating scripts or manifests for each tool, we think our time is better spent making Grafana easier to provision. Therefore, we heavily rely on the expertise of the community.

Data sources

You can manage data sources in Grafana by adding YAML configuration files in the provisioning/datasources directory. Each configuration file can contain a list of datasources to add or update during startup. If the data source already exists, Grafana reconfigures it to match the provisioned configuration file.

The configuration file can also list data sources to automatically delete, called deleteDatasources. Grafana deletes the data sources listed in deleteDatasources before adding or updating those in the datasources list.

You can configure Grafana to automatically delete provisioned data sources when they’re removed from the provisioning file. To do so, add prune: true to the root of your provisioning file. With this configuration, Grafana also removes the provisioned data sources if you remove the provisioning file entirely.

Running multiple Grafana instances

If you run multiple instances of Grafana, add a version number to each data source in the configuration and increase it when you update the configuration. Grafana updates only data sources with the same or lower version number than specified in the configuration. This prevents old configurations from overwriting newer ones if you have different versions of the datasource.yaml file that don’t define version numbers, and then restart instances at the same time.

Example data source configuration file

This example provisions a Graphite data source:

yaml Copy

# Configuration file version
apiVersion: 1

# List of data sources to delete from the database.
deleteDatasources:
  - name: Graphite
    orgId: 1

# Mark provisioned data sources for deletion if they are no longer in a provisioning file.
# It takes no effect if data sources are already listed in the deleteDatasources section.
prune: true

# List of data sources to insert/update depending on what's
# available in the database.
datasources:
  # <string, required> Sets the name you use to refer to
  # the data source in panels and queries.
  - name: Graphite
    # <string, required> Sets the data source type.
    type: graphite
    # <string, required> Sets the access mode, either
    # proxy or direct (Server or Browser in the UI).
    # Some data sources are incompatible with any setting
    # but proxy (Server).
    access: proxy
    # <int> Sets the organization id. Defaults to orgId 1.
    orgId: 1
    # <string> Sets a custom UID to reference this
    # data source in other parts of the configuration.
    # If not specified, Grafana generates one.
    uid: my_unique_uid
    # <string> Sets the data source's URL, including the
    # port.
    url: http://localhost:8080
    # <string> Sets the database user, if necessary.
    user:
    # <string> Sets the database name, if necessary.
    database:
    # <bool> Enables basic authorization.
    basicAuth:
    # <string> Sets the basic authorization username.
    basicAuthUser:
    # <bool> Enables credential headers.
    withCredentials:
    # <bool> Toggles whether the data source is pre-selected
    # for new panels. You can set only one default
    # data source per organization.
    isDefault:
    # <map> Fields to convert to JSON and store in jsonData.
    jsonData:
      # <string> Defines the Graphite service's version.
      graphiteVersion: '1.1'
      # <bool> Enables TLS authentication using a client
      # certificate configured in secureJsonData.
      tlsAuth: true
      # <bool> Enables TLS authentication using a CA
      # certificate.
      tlsAuthWithCACert: true
    # <map> Fields to encrypt before storing in jsonData.
    secureJsonData:
      # <string> Defines the CA cert, client cert, and
      # client key for encrypted authentication.
      tlsCACert: '...'
      tlsClientCert: '...'
      tlsClientKey: '...'
      # <string> Sets the database password, if necessary.
      password:
      # <string> Sets the basic authorization password.
      basicAuthPassword:
    # <int> Sets the version. Used to compare versions when
    # updating. Ignored when creating a new data source.
    version: 1
    # <bool> Allows users to edit data sources from the
    # Grafana UI.
    editable: false

For provisioning examples of specific data sources, refer to that data source’s documentation.

JSON data

Not all data sources have the same configuration settings. Only the most common fields are included in examples. To provision the rest of a data source’s settings, include them as a JSON blob in the jsonData field.

Common settings in the built-in core data sources include:

For examples of specific data sources’ JSON data, refer to that data source’s documentation.

Secure JSON Data

Secure JSON data is a map of settings that are encrypted with a secret key from the Grafana configuration. The encryption hides content from the users of the application. This should be used for storing the TLS Cert and password that Grafana appends to the request on the server side. All of these settings are optional.

Custom HTTP headers for data sources

Data sources managed with provisioning can be configured to add HTTP headers to all requests. Configure the header name in the jsonData field and the header value in secureJsonData.

yaml Copy

apiVersion: 1

datasources:
  - name: Graphite
    jsonData:
      httpHeaderName1: 'HeaderName'
      httpHeaderName2: 'Authorization'
    secureJsonData:
      httpHeaderValue1: 'HeaderValue'
      httpHeaderValue2: 'Bearer XXXXXXXXX'

Plugins

You can manage plugin applications in Grafana by adding one or more YAML configuration files in the provisioning/plugins directory. Each configuration file can contain a list of apps that update during start up. Grafana updates each app to match the configuration file.

Example plugin configuration file

yaml Copy

apiVersion: 1

apps:
  # <string> the type of app, plugin identifier. Required
  - type: raintank-worldping-app
    # <int> Org ID. Default to 1, unless org_name is specified
    org_id: 1
    # <string> Org name. Overrides org_id unless org_id not specified
    org_name: Main Org.
    # <bool> disable the app. Default to false.
    disabled: false
    # <map> fields that will be converted to json and stored in jsonData. Custom per app.
    jsonData:
      # key/value pairs of string to object
      key: value
    # <map> fields that will be converted to json, encrypted and stored in secureJsonData. Custom per app.
    secureJsonData:
      # key/value pairs of string to string
      key: value

Dashboards

You can manage dashboards in Grafana by adding one or more YAML configuration files in the provisioning/dashboards directory. Each configuration file can contain a list of dashboards providers that load dashboards into Grafana from the local filesystem.

The dashboard provider configuration file looks somewhat like this:

yaml Copy

apiVersion: 1

providers:
  # <string> an unique provider name. Required
  - name: 'a unique provider name'
    # <int> Org id. Default to 1
    orgId: 1
    # <string> name of the dashboard folder.
    folder: ''
    # <string> folder UID. will be automatically generated if not specified
    folderUid: ''
    # <string> provider type. Default to 'file'
    type: file
    # <bool> disable dashboard deletion
    disableDeletion: false
    # <int> how often Grafana will scan for changed dashboards
    updateIntervalSeconds: 10
    # <bool> allow updating provisioned dashboards from the UI
    allowUiUpdates: false
    options:
      # <string, required> path to dashboard files on disk. Required when using the 'file' type
      path: /var/lib/grafana/dashboards
      # <bool> use folder names from filesystem to create folders in Grafana
      foldersFromFilesStructure: true

When Grafana starts, it updates and inserts all dashboards available in the configured path. Then later on, Grafana polls that path every updateIntervalSeconds, looks for updated JSON files, and updates and inserts those into the database.

Note: Dashboards are provisioned to the root level if the folder option is missing or empty.

Making changes to a provisioned dashboard

While you can change a provisioned dashboard in the Grafana UI, those changes can’t be saved back to the provisioning source. If allowUiUpdates is set to true and you make changes to a provisioned dashboard, you can Save the dashboard, then changes persist to the Grafana database.

If allowUiUpdates is configured to false, you are not able to make changes to a provisioned dashboard. When you click Save, Grafana brings up a Cannot save provisioned dashboard dialog. The screenshot below illustrates this behavior.

Grafana offers options to export the JSON definition of a dashboard. Either Copy JSON to Clipboard or Save JSON to file can help you synchronize your dashboard changes back to the provisioning source.

Reusable dashboard URLs

If the dashboard in the JSON file contains an UID, Grafana forces insert/update on that UID. This allows you to migrate dashboards between Grafana instances and provisioning Grafana from configuration without breaking the URLs given because the new dashboard URL uses the UID as identifier. When Grafana starts, it updates and inserts all dashboards available in the configured folders. If you modify the file, then the dashboard is also updated. By default, Grafana deletes dashboards in the database if the file is removed. You can disable this behavior using the disableDeletion setting.

Provision folders structure from filesystem to Grafana

If you already store your dashboards using folders in a git repo or on a filesystem, and also you want to have the same folder names in the Grafana menu, you can use foldersFromFilesStructure option.

For example, to replicate these dashboards structure from the filesystem to Grafana,

Copy

/etc/dashboards
├── /server
│   ├── /common_dashboard.json
│   └── /network_dashboard.json
└── /application
    ├── /requests_dashboard.json
    └── /resources_dashboard.json

You need to specify just this short provision configuration file.

yaml Copy

apiVersion: 1

providers:
  - name: dashboards
    type: file
    updateIntervalSeconds: 30
    options:
      path: /etc/dashboards
      foldersFromFilesStructure: true

In this example, server and application become new folders in the Grafana menu.

Alerting

For information on provisioning Grafana Alerting, refer to Provision Grafana Alerting resources.

Supported settings

The following sections detail the supported settings and secure settings for each alert notification type. Secure settings are stored encrypted in the database and you add them to secure_settings in the YAML file instead of settings.

Alert notification pushover

Alert notification discord

Alert notification slack

Alert notification victorops

Alert notification kafka

Alert notification LINE

Alert notification MQTT

TLS config

Alert notification pagerduty

Alert notification sensu

Alert notification sensugo

Alert notification prometheus-alertmanager

Alert notification teams

Alert notification dingding

Alert notification email

Alert notification hipchat

Alert notification opsgenie

Alert notification telegram

Alert notification threema

Alert notification webhook

Alert notification googlechat

Alert notification Cisco Webex Teams

Grafana Enterprise

Grafana Enterprise supports:

• Provisioning role-based access control with Grafana
• Provisioning role-based access control with Terraform