Add docs, rename grafana-environment to grafana-slack-url

Epiphany: Systemd reads more than a single environment file. This
lets me improve the file naming much.

morph/grid/local/private-keys/README.rst

@@ -19,6 +19,13 @@ grafana-admin.password
 
 This is the initial admin password for the Grafana web admin on the monitoring host.
 
+grafana-slack-url
+-----------------
+
+This file is read by Grafana's systemd service to set an environment variable with a secret Slack WebHook URL to post alerts to.
+The only line in the file should be ``SLACKURL=`` with the secret URL.
+Get a secret URL for your Slack channel at https://www.slack.com/apps/A0F7XDUAZ.
+
 stripe.secret
 -------------
 

morph/lib/customize-monitoring.nix

@@ -32,9 +32,8 @@
   # logins to Grafana.
 , googleOAuthClientID
 
-  # Whether or not to enable slack alerting. Expects a SLACKURL environment
-  # variable with the secret URL. Get the secret URL for your Slack at
-  # https://www.slack.com/apps/A0F7XDUAZ.
+  # Whether to enable alerting via Slack.
+  # When true requires a grafana-slack-url file (see private-keys/README.rst).
 , enableSlackAlert ? false
 
   # A string giving the NixOS state version for the system.
@@ -76,13 +75,13 @@ in {
           action = ["sudo" "systemctl" "restart" "grafana.service"];
         };
       };
-    grafanaEnvironment =
+    grafanaSlackUrl =
       if !enableSlackAlert
-      then {}
+      then { }
       else {
-        "grafana-environment" = {
-          source = "${privateKeyPath}/grafana-environment";
-          destination = "/run/keys/grafana-environment";
+        "grafana-slack-url" = {
+          source = "${privateKeyPath}/grafana-slack-url";
+          destination = "/run/keys/grafana-slack-url";
           owner.user = config.systemd.services.grafana.serviceConfig.User;
           owner.group = config.users.users.grafana.group;
           permissions = "0400";
@@ -94,7 +93,7 @@ in {
       "monitoringvpn-preshared-key".source = "${privateKeyPath}/monitoringvpn/preshared.key";
     };
     in
-      grafanaSSO // grafanaEnvironment // monitoringvpn;
+      grafanaSSO // grafanaSlackUrl // monitoringvpn;
 
   networking.hosts = hostsMap;
 

nixos/modules/monitoring/server/grafana.nix

@@ -66,14 +66,19 @@ in {
     { type = lib.types.bool;
       default = false;
       description = ''
-        Enables the slack alerter. Expects a $SLACKURL environment
-        variable with the secret URL in grafanaEnvironmentFile.
+        Enables the slack alerter. Expects a file that contains
+        the definition of an environment variable named SLACKURL
+        pointing to the secret Slack Web Hook URL in
+        grafanaSlackUrlFile (see below).
       '';
     };
-    grafanaEnvironmentFile = lib.mkOption
+    grafanaSlackUrlFile = lib.mkOption
     { type = lib.types.path;
-      default = /run/keys/grafana-environment;
-      description = "Where to find the Grafana Systemd EnvironmentFile.";
+      default = /run/keys/grafana-slack-url;
+      description = ''
+        Where to find the Grafana Systemd EnvironmentFile that
+        sets the secret SLACKURL environment variable.
+      '';
     };
   };
 
@@ -84,7 +89,7 @@ in {
     # We pass the secret Slack URL using an environment variable.
     systemd.services.grafana.serviceConfig.EnvironmentFile =
       if cfg.enableSlackAlert
-      then [ cfg.grafanaEnvironmentFile ]
+      then [ cfg.grafanaSlackUrlFile ]
       else [ ];
 
     services.grafana = {