Integrate a datasource with Grafana

Grafana offers native integration with a number of datasources. If you are charming an application that is a supported grafana datasource, you can integrate with the grafana-k8s charm to automatically provision the datasource in grafana.

For an example of charms that already do that, see loki and prometheus.

Add an integration endpoint to metadata.yaml

Datasource spec is communicated over relation data, where the Grafana charm is the requirer and the datasource server is the provider. For consistency accross the ecosystem, it is encouraged to name the relation grafana-source.

Edit your charm’s metadata.yaml to add, under provides, the following:

provides:
    # any other providers your charm supports
    grafana-source:
        interface: grafana_source

Fetch the grafana_source charm library

The Grafana charm will provision a datasource per grafana_source relation, which is managed by the grafana_source library.

charmcraft fetch-lib charms.grafana_k8s.v0.grafana_source

The library offers a GrafanaSourceProvider object, which provides sensible defaults and a simple API that you can use to configure the datasource.

Use GrafanaSourceProvider

If you are adding a prometheus datasource:

from charms.grafana_k8s.v0.grafana_source import GrafanaSourceProvider

class FooCharm:
    def __init__(self, *args):
        super().__init__(*args, **kwargs)
        ...
        self.grafana_source_provider = GrafanaSourceProvider(
            self, source_type="prometheus"
        )
        ...

This will ensure that each unit of Foo is added as a datasource in the Grafana configuration once a relation is established.

Configure GrafanaSourceProvider

Certain datasources require additional configuration. That can be passed to GrafanaSourceProvider as constructor arguments.

• source_port: the port at which the datasource server is listening. Defaults to 9090.
• source_url: fully resolvable url at which the datasource server can be reached (useful for example if you are sitting behind an ingress). If provided, source_port will be ignored. If not provided, the library will use the fqdn. Should be reachable from the grafana pod.
• relation_name: name of the binding. Defaults to grafana-source.
• refresh_event: event or list of events on which the library will refresh the source url. Useful if the charm’s address is changed as a consequence of a restart (pod churn on k8s).