diff options
author | Maximilian Bosch <maximilian@mbosch.me> | 2022-11-20 20:53:25 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-11-20 20:53:25 +0100 |
commit | 853d0a3f2b85eef8916dc634f7233067f1ad90b3 (patch) | |
tree | 36e3ebd25df600c12e97edebfb1b520d971b2261 /nixos/doc/manual/from_md/release-notes/rl-2211.section.xml | |
parent | bd3a8c7b9eb738a223d702a7580e372a33ac1071 (diff) | |
parent | 4a73fad5155245e66323d422a373e3377da747aa (diff) |
Merge pull request #199150 from Ma27/grafana-fixup
nixos/grafana: documentation/warning improvements after #191768
Diffstat (limited to 'nixos/doc/manual/from_md/release-notes/rl-2211.section.xml')
-rw-r--r-- | nixos/doc/manual/from_md/release-notes/rl-2211.section.xml | 152 |
1 files changed, 138 insertions, 14 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 c56cfb10538bb..8e97e58f81a61 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 @@ -1206,22 +1206,146 @@ 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 + files (or 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> + <para> + <emphasis role="strong">Note:</emphasis> secrets from + these files will be leaked into the store unless you + use a + <link xlink:href="https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#file-provider"><emphasis role="strong">file</emphasis>-provider + or env-var</link> for secrets! + </para> + </listitem> + <listitem> + <para> + <xref linkend="opt-services.grafana.provision.notifiers" /> + is not affected by this change because this feature is + deprecated by Grafana and will probably removed in + Grafana 10. It’s recommended to use + <literal>services.grafana.provision.alerting.contactPoints</literal> + instead. + </para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> </listitem> <listitem> <para> |