nixos/doc: improve release-notes for services.grafana
This commit is contained in:
Maximilian Bosch
parent
957e368f3d
commit
252785fd9c
2 changed files with 173 additions and 16 deletions
|
|
@ -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.
|
||||
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 <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.
|
||||
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>
|
||||
|
|
|
|||
|
|
@ -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 `<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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue