How to configure the Grafana database

Grafana stores its state (dashboards, users, and settings) in a database. In COS you can either:

  • Use SQLite (single Grafana unit only), or

  • Integrate Grafana with an external PostgreSQL database, which is required to scale Grafana to more than one unit for high availability.

Which path is used is controlled by the postgresql_offer_url and grafana.units inputs of the Terraform module:

  • When postgresql_offer_url is set, Grafana is integrated with the external PostgreSQL service over the postgresql_client interface, at any scale.

  • When postgresql_offer_url is null (the default), Grafana uses SQLite. In this case Grafana must run as a single unit.

Important

Grafana defaults to 3 units in COS and 1 unit in COS Lite.

Running more than one Grafana unit requires a shared external database. Therefore, whenever grafana.units is greater than 1, you must also set postgresql_offer_url. If you don’t, applying the module fails validation on a terraform plan.

Configure an external database

To back Grafana with an external PostgreSQL database, supply the postgresql_offer_url input with the Juju offer URL of a PostgreSQL service that provides the postgresql_client integration (for example, admin/postgresql.database). Set grafana.units to the desired number of Grafana units for high availability.

module "cos" {
  # Use the right source value depending on whether you are using cos or cos-lite
  source = "git::https://github.com/canonical/observability-stack//terraform/cos?ref=main"

  # ... other inputs ...

  # Number of Grafana units. Scaling above 1 requires an external database,
  # so 'postgresql_offer_url' must be set when 'units' is greater than 1.
  grafana = {
    units = 3
  }

  # A Juju offer URL of a PostgreSQL service providing the 'postgresql_client'
  # integration. Set to 'null' to fall back to the default per-unit Juju storage.
  postgresql_offer_url = "admin/postgresql.database"
}

The postgresql_offer_url input determines whether Grafana is integrated with the external database. When it is set, COS creates a cross-model integration between Grafana and the PostgreSQL service, regardless of the Grafana unit count. You can therefore use an external database even when running a single Grafana unit.

Ensure that you have provided any required variables (update the ... other inputs ... placeholder) for the respective COS module before applying the configuration, by running terraform apply.

Configure SQLite

If you do not supply postgresql_offer_url, Grafana falls back to SQLite. This is only supported with a single Grafana unit, so set grafana.units to 1:

module "cos" {
  grafana = { units = 1 }
  postgresql_offer_url = null
}

For details on sizing and customizing the underlying storage, see How to customize storage options and the Storage best practices reference.