README.md

# BRIAN Dashboard Manager

## Overview

This module is used to provision Organizations and Dashboards in Grafana for BRIAN.
It implements a Flask-based webservice used only to trigger the provisioning process.

The dashboards are generated from a list of interfaces obtained from Inventory Provider.

Jinja templates are populated with data from these interfaces to render Dashboard JSON definitions sent to the Grafana API.

Grafana API-related code lives in the `grafana` package.

The `brian_dashboard_manager/grafana/provision.py` file is responsible for the entire provisioning lifecycle.

Grafana API endpoints have wrapper functions in one file for relevant parts of the API, e.g. `brian_dashboard_manager/grafana/dashboard.py` for the dashboard API functions.

Another example is `brian_dashboard_manager/grafana/organization.py` for the organization API functions.

Some of the provisioned dashboards are not generated but are just static JSON files. These are put in the `brian_dashboard_manager/dashboards` directory. The same can be done for JSON datasource definitions in the `datasources` directory.

The `brian_dashboard_manager/templating` package contains the code and Jinja templates used to render dashboard JSON. Most dashboards reuse the same templates, with the exception of NREN-specific dashboards, which has its own template.

Of note is the `templating/helpers.py` file, which has all of the predicates and helper functions used to group interfaces together and generate the necessary data for the dashboard templates.
The `templating/render.py` has functions for rendering of the various Jinja templates from the given data.

## Configuration

This app allows specification of a few
example configuration parameters. These
parameters should stored in a file formatted
similarly to `config.json.example`, and the name
of this file should be stored in the environment
variable `CONFIG_FILENAME` when running the service.

## Running this module

This module has been tested in the following execution environments:

- As an embedded Flask application.
  For example, the application could be launched as follows:

```bash
$ export FLASK_APP=/path/to/brian_dashboard_manager/app.py
$ export CONFIG_FILENAME=/path/to/config.json
$ flask run
```

- As a `gunicorn` wsgi service.
  - Details of `gunicorn` configuration can be found in the brian_dashboard_manager Puppet repository.

## Protocol Specification

The following resources can be requested from the webservice.

### resources
Any non-empty responses are JSON formatted messages.

## /update

This resource is used to trigger the provisioning to Grafana.
It responds to the request immediately after starting the provisioning process.

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    }
  }
}
```