diff options
Diffstat (limited to 'nixos/doc/manual')
-rw-r--r-- | nixos/doc/manual/from_md/release-notes/rl-2211.section.xml | 135 | ||||
-rw-r--r-- | nixos/doc/manual/release-notes/rl-2211.section.md | 56 |
2 files changed, 174 insertions, 17 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 a1e01bd92921e..caeeae1aefa86 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 = [ </listitem> <listitem> <para> - The <literal>services.grafana</literal> options were converted - to a + The module <literal>services.grafana</literal> was refactored + to be compliant with <link xlink:href="https://github.com/NixOS/rfcs/blob/master/rfcs/0042-config-option.md">RFC - 0042</link> configuration. - </para> - </listitem> - <listitem> - <para> - The <literal>services.grafana.provision.datasources</literal> - and <literal>services.grafana.provision.dashboards</literal> - options were converted to a - <link xlink:href="https://github.com/NixOS/rfcs/blob/master/rfcs/0042-config-option.md">RFC - 0042</link> configuration. They also now support specifying - the provisioning YAML file with <literal>path</literal> - option. + 0042</link>. To be precise, this means that the following + things have changed: </para> + <itemizedlist> + <listitem> + <para> + The newly introduced option + <xref linkend="opt-services.grafana.settings" /> is an + attribute-set that will be converted into Grafana’s INI + format. This means that the configuration from + <link xlink:href="https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/">Grafana’s + configuration reference</link> can be directly written as + attribute-set in Nix within this option. + </para> + </listitem> + <listitem> + <para> + The option + <literal>services.grafana.extraOptions</literal> has been + removed. This option was an association of environment + variables for Grafana. If you had an expression like + </para> + <programlisting language="bash"> +{ + services.grafana.extraOptions.SECURITY_ADMIN_USER = "foobar"; +} +</programlisting> + <para> + your Grafana instance was running with + <literal>GF_SECURITY_ADMIN_USER=foobar</literal> in its + environment. + </para> + <para> + For the migration, it is recommended to turn it into the + INI format, i.e. to declare + </para> + <programlisting language="bash"> +{ + services.grafana.settings.security.admin_user = "foobar"; +} +</programlisting> + <para> + instead. + </para> + <para> + The keys in + <literal>services.grafana.extraOptions</literal> have the + format + <literal><INI section name>_<Key Name></literal>. + Further details are outlined in the + <link xlink:href="https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#override-configuration-with-environment-variables">configuration + reference</link>. + </para> + <para> + Alternatively you can also set all your values from + <literal>extraOptions</literal> to + <literal>systemd.services.grafana.environment</literal>, + make sure you don’t forget to add the + <literal>GF_</literal> prefix though! + </para> + </listitem> + <listitem> + <para> + Previously, the options + <xref linkend="opt-services.grafana.provision.datasources" /> + and + <xref linkend="opt-services.grafana.provision.dashboards" /> + expected lists of datasources or dashboards for the + <link xlink:href="https://grafana.com/docs/grafana/latest/administration/provisioning/">declarative + provisioning</link>. + </para> + <para> + To declare lists of + </para> + <itemizedlist spacing="compact"> + <listitem> + <para> + <emphasis role="strong">datasources</emphasis>, please + rename your declarations to + <xref linkend="opt-services.grafana.provision.datasources.settings.datasources" />. + </para> + </listitem> + <listitem> + <para> + <emphasis role="strong">dashboards</emphasis>, please + rename your declarations to + <xref linkend="opt-services.grafana.provision.dashboards.settings.providers" />. + </para> + </listitem> + </itemizedlist> + <para> + This change was made to support more features for that: + </para> + <itemizedlist> + <listitem> + <para> + It’s possible to declare the + <literal>apiVersion</literal> of your dashboards and + datasources by + <xref linkend="opt-services.grafana.provision.datasources.settings.apiVersion" /> + (or + <xref linkend="opt-services.grafana.provision.dashboards.settings.apiVersion" />). + </para> + </listitem> + <listitem> + <para> + Instead of declaring datasources and dashboards in + pure Nix, it’s also possible to specify configuration + directories with YAML instead using + <xref linkend="opt-services.grafana.provision.datasources.path" /> + (or + <xref linkend="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. + </para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> </listitem> <listitem> <para> diff --git a/nixos/doc/manual/release-notes/rl-2211.section.md b/nixos/doc/manual/release-notes/rl-2211.section.md index 642009e9f44e4..091377d74a6fb 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 `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. +- 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 + + ```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 `<INI section name>_<Key Name>`. + 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. |