{nixos, nixos/tests}/traefik: re-refactor traefik, update tests

doc/build-helpers/fetchers.chapter.md

@@ -1066,3 +1066,75 @@ fetchItchIo {
   upload = "13371354";
 }
 ```
+
+## `fetchTraefikPlugin` {#sec-pkgs-fetchers-fetchtraefikplugin}
+
+This specialised fetcher can build local [Traefik](https://traefik.io) plugins in a format expected by the `experimental.localPlugins` option in a Traefik static configuration file. Built using [extendMkDerivation](https://noogle.dev/f/lib/customisation/extendMkDerivation) based on `fetchzip` {#sec-pkgs-fetchers-fetchzip}, meaning it accepts all parameters that fetchzip does.
+
+::::{.example #ex-fetchers-fetchtraefikplugin}
+# Building a Traefik plugin hosted on `plugins.traefik.io`
+
+The following recipe shows how to use `fetchTraefikPlugin` to fetch the `geoblock` Traefik plugin at version `0.3.3`:
+
+```nix
+{ fetchTraefikPlugin }:
+fetchTraefikPlugin {
+  plugin = "geoblock";
+  owner = "PascalMinder";
+  version = "0.3.3";
+  hash = "sha256-gLhihjsBJEKGzpIwWzu/zmvLJbqnqXsF8ZiJWWKwDIA=";
+}
+```
+
+After building the recipe, the derivation output will set up the appropriate paths expected by Traefik:
+
+```shell
+$ nix-build
+(output removed for clarity)
+/nix/store/m68kmlay1vdjzqjq7144r6ra885fd8l8-geoblock-0.3.3
+
+$ tree /nix/store/m68kmlay1vdjzqjq7144r6ra885fd8l8-geoblock-0.3.3
+/nix/store/m68kmlay1vdjzqjq7144r6ra885fd8l8-geoblock-0.3.3
+└── src
+    └── github.com
+        └── PascalMinder
+            └── geoblock
+                ├── docker
+                │   ├── dev-geoblock
+                │   │   └── docker-compose.yml
+                │   └── traefik-config
+                │       ├── dynamic-configuration.yml
+                │       └── traefik.yml
+                ├── lrucache
+                │   ├── lru.go
+                │   ├── lru_interface.go
+                │   └── lru_test.go
+                ├── LICENSE
+                ├── Makefile
+                ├── geoblock.go
+                ├── geoblock_test.go
+                ├── go.mod
+                └── readme.md
+```
+
+::::
+
+### Parameters {#sec-pkgs-fetchers-fetchtraefikplugin-parameters}
+
+- `plugin`: The plugin name, usually lowercase.
+
+- `owner`: The author of the plugin.
+
+- `version`: The version of the plugin, without the `v` prefix.
+
+- `hash`: The resulting hash of the derivation.
+
+#### Optional parameters {#sec-pkgs-fetchers-fetchtraefikplugin-parameters-optional}
+
+- `provider`: The forge hosting the plugin. This defaults to `github.com`, as most Traefik plugins are hosted on GitHub, but the fetcher will always fetch plugins from `plugins.traefik.io`, regardless of upstream provider.
+
+- `pname`: Defaults to the value of `plugin`.
+
+- `name`: Defaults to `${pname}-${version}`.
+
+- `meta`: Defaults to `{ }`, but can be configured similarly to any other package.

doc/redirects.json

@@ -120,6 +120,9 @@
   "ex-modularServiceCompliance-nixos": [
     "index.html#ex-modularServiceCompliance-nixos"
   ],
+  "ex-fetchers-fetchtraefikplugin": [
+    "index.html#ex-fetchers-fetchtraefikplugin"
+  ],
   "ex-pkgs-replace-vars": [
     "index.html#ex-pkgs-replace-vars",
     "index.html#ex-pkgs-substituteAll",
@@ -786,6 +789,15 @@
   "sec-debug": [
     "index.html#sec-debug"
   ],
+  "sec-pkgs-fetchers-fetchtraefikplugin": [
+    "index.html#sec-pkgs-fetchers-fetchtraefikplugin"
+  ],
+  "sec-pkgs-fetchers-fetchtraefikplugin-parameters": [
+    "index.html#sec-pkgs-fetchers-fetchtraefikplugin-parameters"
+  ],
+  "sec-pkgs-fetchers-fetchtraefikplugin-parameters-optional": [
+    "index.html#sec-pkgs-fetchers-fetchtraefikplugin-parameters-optional"
+  ],
   "sec-prefer-remote-fetch": [
     "index.html#sec-prefer-remote-fetch"
   ],

nixos/doc/manual/redirects.json

@@ -250,6 +250,30 @@
   "sec-nixos-test-vms-vs-containers": [
     "index.html#sec-nixos-test-vms-vs-containers"
   ],
+  "module-services-traefik": [
+    "index.html#module-services-traefik"
+  ],
+  "module-services-traefik-environment": [
+    "index.html#module-services-traefik-environment"
+  ],
+  "module-services-traefik-plugins": [
+    "index.html#module-services-traefik-plugins"
+  ],
+  "module-services-traefik-plugins-custom": [
+    "index.html#module-services-traefik-plugins-custom"
+  ],
+  "module-services-traefik-usage": [
+    "index.html#module-services-traefik-usage"
+  ],
+  "module-services-traefik-usage-routing": [
+    "index.html#module-services-traefik-usage-routing"
+  ],
+  "module-services-traefik-usage-install": [
+    "index.html#module-services-traefik-usage-install"
+  ],
+  "module-services-traefik-migrating-to-26.11": [
+    "index.html#module-services-traefik-migrating-to-26.11"
+  ],
   "sec-override-nixos-test": [
     "index.html#sec-override-nixos-test"
   ],

nixos/doc/manual/release-notes/rl-2611.section.md

@@ -168,6 +168,9 @@
 
 - [firefox-syncserver.database.type](#opt-services.firefox-syncserver.database.type) no longer defaults to `"mysql"`. You must now explicitly choose between `"mysql"` and `"postgresql"`. New deployments should prefer PostgreSQL.
 
++ The Traefik module has been refactored to allow new ways to deploy the install and routing configuration files, as well as nixpkgs packaged plugins. See [Migrating traefik for pre 26.11 configurations](#module-services-traefik-migrating-to-26.11).
++
+>>>>>>> conflict 1 of 1 ends
 ## Other Notable Changes {#sec-release-26.11-notable-changes}
 
 <!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. -->

nixos/modules/services/networking/pangolin.nix

@@ -225,13 +225,10 @@ in
           isSystemUser = true;
         };
       };
-      groups.fossorial = {
-        members = [
-          "pangolin"
-          "gerbil"
-          "traefik"
-        ];
-      };
+      groups.fossorial.members = [
+        "pangolin"
+        "gerbil"
+      ];
     };
     # order is as follows
     # "pangolin.service"
@@ -241,21 +238,18 @@ in
     # make tunnels declarative by calling API
     ###
     systemd = {
-      tmpfiles.settings."10-fossorial-paths" = {
-        "${cfg.dataDir}".d = {
-          user = "pangolin";
-          group = "fossorial";
-          mode = "0770";
-        };
-        "${cfg.dataDir}/config".d = {
-          user = "pangolin";
-          group = "fossorial";
-          mode = "0770";
-        };
-        "${cfg.dataDir}/config/letsencrypt".d = {
-          user = "traefik";
-          group = "fossorial";
-          mode = "0700";
+      tmpfiles.settings = {
+        "10-fossorial-paths" = {
+          "${cfg.dataDir}".d = {
+            user = "pangolin";
+            group = "fossorial";
+            mode = "0770";
+          };
+          "${cfg.dataDir}/config".d = {
+            user = "pangolin";
+            group = "fossorial";
+            mode = "0770";
+          };
         };
       };
       services = {
@@ -265,9 +259,11 @@ in
           requires = [ "network.target" ];
           after = [ "network.target" ];
 
+          # need to do the symlinks here because of strict
+          # systemd tmpfiles unsafe path transitions
           preStart = ''
-            mkdir -p ${cfg.dataDir}/config
-            cp -f ${cfgFile} ${cfg.dataDir}/config/config.yml
+            ln -sf  ${cfgFile} ${cfg.dataDir}/config/config.yml
+            ln -sft ${cfg.dataDir}/config/ ${config.services.traefik.dataDir}
           '';
 
           serviceConfig = {
@@ -455,18 +451,12 @@ in
 
     services.traefik = {
       enable = true;
-      group = "fossorial";
-      dataDir = "${cfg.dataDir}/config/traefik";
-      staticConfigOptions = {
+      localPlugins = [ pkgs.fosrl-badger ];
+      install.settings = {
         providers.http = {
           endpoint = "http://localhost:${toString finalSettings.server.internal_port}/api/v1/traefik-config";
           pollInterval = "5s";
         };
-        # TODO to change this once #437073 is merged.
-        experimental.plugins.badger = {
-          moduleName = "github.com/fosrl/badger";
-          version = "v1.2.0";
-        };
         certificatesResolvers.letsencrypt.acme =
           (
             if finalSettings.domains.domain1.prefer_wildcard_cert then
@@ -483,7 +473,7 @@ in
           # common
           {
             email = cfg.letsEncryptEmail;
-            storage = "${cfg.dataDir}/config/letsencrypt/acme.json";
+            storage = "acme.json";
             caServer = "https://acme-v02.api.letsencrypt.org/directory";
           };
         entryPoints = {
@@ -495,7 +485,7 @@ in
           };
         };
       };
-      dynamicConfigOptions = {
+      routing.files."pangolin".settings = {
         http = {
           middlewares.redirect-to-https.redirectScheme.scheme = "https";
           routers = {

nixos/modules/services/web-servers/traefik.md

@@ -0,0 +1,119 @@
+# Traefik {#module-services-traefik}
+
+[Traefik][upstream-1] is an open-source, cloud-native reverse proxy that
+can be configured in NixOS using the {option}`services.traefik` option set.
+
+## Basic Usage {#module-services-traefik-usage}
+
+A key feature of Traefik is that the reverse proxy configuration is split into
+two: a **install configuration** that requires Traefik to be restarted in order
+to update it, and a **routing configuration** that can change without a need to
+restart the server. The [upstream documentation][upstream-2] has a detailed
+overview on the difference between both configuration types.
+
+### install Configuration {#module-services-traefik-usage-install}
+
+The install configuration is controlled by the {option}`services.traefik.install`
+option set.
+
+- The {option}`services.traefik.install.file` option allows you to pass a path to
+  a file containing a Traefik configuration.
+
+- The {option}`services.traefik.install.settings` option instead allows you to
+  declare the Traefik configuration directly in the NixOS configuration, using
+  the usual Nix syntax.
+
+### routing Configuration {#module-services-traefik-usage-routing}
+
+The routing configuration has a similar option set to the install configuration,
+but it also has the {option}`services.traefik.routing.dir` option, which allows
+you to define a directory containing several Traefik routing configuration files.
+
+## Plugins {#module-services-traefik-plugins}
+
+When using the structured `settings` configuration options, the Traefik module
+supports [plugins][upstream-3]. Plugins in Traefik are an additional routing
+configuration source and can programatically set up routes and proxies.
+
+The {option}`services.traefik.plugins` option takes in a list of derivations
+that contain Traefik plugins. Some plugins are available in the package set, and
+can be called directly from `pkgs`. The example below sets up `geoblock`, a
+Traefik plugin that blocks connections from a given list of countries based on
+the client's IP address, to block all connections not coming from the Netherlands.
+
+```nix
+{
+  services.traefik = {
+    plugins = with pkgs; [ geoblock ];
+    install.settings.entryPoints.websecure.http.middlewares = "my-geoblock";
+    routing.settings.http.middlewares.my-geoblock.plugin.geoblock.countries = [ "NL" ];
+  };
+}
+```
+
+### Custom Plugins {#module-services-traefik-plugins-custom}
+
+Plugins that are not currently packaged in Nixpkgs can also be added to the
+{option}`services.traefik.plugins` option after being built with the
+`fetchTraefikPlugin` builder. See the [Nixpkgs manual section on
+`fetchTraefikPlugin`][fetcher] for more information on the available options.
+
+```nix
+{
+  services.traefik.plugins = [
+    (pkgs.fetchTraefikPlugin {
+      plugin = "example";
+      owner = "example-author";
+      version = "1.0.0";
+      hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
+    })
+  ];
+}
+```
+
+For plugins not found in `plugins.traefik.io`, simply use the
+[`lib.fileset.toSource` library function][fileset] to build a derivation from a path to a
+local plugin. The module will generate a warning mentioning that the local plugin
+may be misconfigured, but it can be safely ignored, or removed by updating the
+derivation to include the `_isTraefikPlugin` attribute.
+
+```nix
+{
+  services.traefik.plugins = [
+    (
+      (lib.fileset.toSource {
+        root = ./my-plugin;
+        fileset = ./my-plugin;
+      })
+      # Supress Traefik module warning.
+      # Don't forget to ensure that ./my-plugin has an appropriate
+      # directory structure as expected by Traefik.
+      // {
+        _isTraefikPlugin = true;
+      }
+    )
+  ];
+}
+```
+
+## Environment Files {#module-services-traefik-environment}
+
+Although the Traefik module offers the {option}`services.traefik.environmentFiles`
+option to set up environment files for the running server, *it is not recommended
+to use them as install configuration sources*. The environment files are intended
+to provision secrets for ACME/Let's Encrypt and other certificate setups.
+
+See the [upstream documentation][upstream-4] for more information on passing
+ACME secrets for setting up DNS-01 challenges.
+
+
+[fetcher]: https://nixos.org/manual/nixpkgs/stable/#sec-pkgs-fetchers-fetchtraefikplugin
+[fileset]: https://nixos.org/manual/nixpkgs/stable/#function-library-lib.fileset.toSource
+[upstream-1]: https://traefik.io
+[upstream-2]: https://doc.traefik.io/traefik/getting-started/configuration-overview
+[upstream-3]: https://plugins.traefik.io/plugins
+[upstream-4]: https://doc.traefik.io/traefik/https/acme/#providers
+
+## Migrating to 26.11 {#module-services-traefik-migrating-to-26.11}
+
+The Traefik module now features new ways to deploy the routing and install configuration files. Move your existing declarative install and routing configurations to `services.traefik.install.settings` and `services.traefik.routing.files."my-application".settings` respectively. The `services.traefik.routing.settings` option is available for a simpler migration without needing to define a filename like `my-application`, but this option will be removed in NixOS 27.05. The option to use `EnvSubst` to substitute environment variables has been removed, as using environment variables to store secrets is already supported by the {option}`services.traefik.environmentFiles`.