From 252785fd9cce3474c6167d98b57e64509b1da37e Mon Sep 17 00:00:00 2001 From: Maximilian Bosch Date: Wed, 2 Nov 2022 12:31:26 +0100 Subject: [PATCH] nixos/doc: improve release-notes for services.grafana --- .../from_md/release-notes/rl-2211.section.xml | 135 ++++++++++++++++-- .../manual/release-notes/rl-2211.section.md | 54 ++++++- 2 files changed, 173 insertions(+), 16 deletions(-) diff --git a/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml b/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml index a1e01bd92921..caeeae1aefa8 100644 --- a/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml +++ b/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml @@ -1189,22 +1189,129 @@ services.github-runner.serviceOverrides.SupplementaryGroups = [ - The services.grafana options were converted - to a + The module services.grafana was refactored + to be compliant with RFC - 0042 configuration. - - - - - The services.grafana.provision.datasources - and services.grafana.provision.dashboards - options were converted to a - RFC - 0042 configuration. They also now support specifying - the provisioning YAML file with path - option. + 0042. To be precise, this means that the following + things have changed: + + + + The newly introduced option + is an + attribute-set that will be converted into Grafana’s INI + format. This means that the configuration from + Grafana’s + configuration reference can be directly written as + attribute-set in Nix within this option. + + + + + The option + services.grafana.extraOptions has been + removed. This option was an association of environment + variables for Grafana. If you had an expression like + + +{ + services.grafana.extraOptions.SECURITY_ADMIN_USER = "foobar"; +} + + + your Grafana instance was running with + GF_SECURITY_ADMIN_USER=foobar in its + environment. + + + For the migration, it is recommended to turn it into the + INI format, i.e. to declare + + +{ + services.grafana.settings.security.admin_user = "foobar"; +} + + + instead. + + + The keys in + services.grafana.extraOptions have the + format + <INI section name>_<Key Name>. + Further details are outlined in the + configuration + reference. + + + Alternatively you can also set all your values from + extraOptions to + systemd.services.grafana.environment, + make sure you don’t forget to add the + GF_ prefix though! + + + + + Previously, the options + + and + + expected lists of datasources or dashboards for the + declarative + provisioning. + + + To declare lists of + + + + + datasources, please + rename your declarations to + . + + + + + dashboards, please + rename your declarations to + . + + + + + This change was made to support more features for that: + + + + + It’s possible to declare the + apiVersion of your dashboards and + datasources by + + (or + ). + + + + + Instead of declaring datasources and dashboards in + pure Nix, it’s also possible to specify configuration + directories with YAML instead using + + (or + . + This is useful when having provisioning files from + non-NixOS Grafana instances that you also want to + deploy to NixOS. + + + + + diff --git a/nixos/doc/manual/release-notes/rl-2211.section.md b/nixos/doc/manual/release-notes/rl-2211.section.md index 642009e9f44e..091377d74a6f 100644 --- a/nixos/doc/manual/release-notes/rl-2211.section.md +++ b/nixos/doc/manual/release-notes/rl-2211.section.md @@ -372,9 +372,59 @@ Available as [services.patroni](options.html#opt-services.patroni.enable). - The `services.matrix-synapse` systemd unit has been hardened. -- The `services.grafana` options were converted to a [RFC 0042](https://github.com/NixOS/rfcs/blob/master/rfcs/0042-config-option.md) configuration. +- The module `services.grafana` was refactored to be compliant with [RFC 0042](https://github.com/NixOS/rfcs/blob/master/rfcs/0042-config-option.md). To be precise, this means that the following things have changed: + - The newly introduced option [](#opt-services.grafana.settings) is an attribute-set that + will be converted into Grafana's INI format. This means that the configuration from + [Grafana's configuration reference](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/) + can be directly written as attribute-set in Nix within this option. + - The option `services.grafana.extraOptions` has been removed. This option was an association + of environment variables for Grafana. If you had an expression like -- The `services.grafana.provision.datasources` and `services.grafana.provision.dashboards` options were converted to a [RFC 0042](https://github.com/NixOS/rfcs/blob/master/rfcs/0042-config-option.md) configuration. They also now support specifying the provisioning YAML file with `path` option. + ```nix + { + services.grafana.extraOptions.SECURITY_ADMIN_USER = "foobar"; + } + ``` + + your Grafana instance was running with `GF_SECURITY_ADMIN_USER=foobar` in its environment. + + For the migration, it is recommended to turn it into the INI format, i.e. + to declare + + ```nix + { + services.grafana.settings.security.admin_user = "foobar"; + } + ``` + + instead. + + The keys in `services.grafana.extraOptions` have the format `_`. + Further details are outlined in the [configuration reference](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#override-configuration-with-environment-variables). + + Alternatively you can also set all your values from `extraOptions` to + `systemd.services.grafana.environment`, make sure you don't forget to add + the `GF_` prefix though! + - Previously, the options [](#opt-services.grafana.provision.datasources) and + [](#opt-services.grafana.provision.dashboards) expected lists of datasources + or dashboards for the [declarative provisioning](https://grafana.com/docs/grafana/latest/administration/provisioning/). + + To declare lists of + - **datasources**, please rename your declarations to [](#opt-services.grafana.provision.datasources.settings.datasources). + - **dashboards**, please rename your declarations to [](#opt-services.grafana.provision.dashboards.settings.providers). + + This change was made to support more features for that: + + - It's possible to declare the `apiVersion` of your dashboards and datasources + by [](#opt-services.grafana.provision.datasources.settings.apiVersion) (or + [](#opt-services.grafana.provision.dashboards.settings.apiVersion)). + + - Instead of declaring datasources and dashboards in pure Nix, it's also possible + to specify configuration directories with YAML instead using + [](#opt-services.grafana.provision.datasources.path) (or + [](#opt-services.grafana.provision.dashboards.path). This is useful when having + provisioning files from non-NixOS Grafana instances that you also want to + deploy to NixOS. - The `services.grafana.provision.alerting` option was added. It includes suboptions for every alerting-related objects (with the exception of `notifiers`), which means it's now possible to configure modern Grafana alerting declaratively.