Merge pull request 'docs/guides: facts vars migration guide' (#3598) from kenji/clan-core:ke-docs-vars-facts-migration into main

Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/3598

docs/mkdocs.yml

@@ -55,6 +55,7 @@ nav:
       - Backup & Restore: getting-started/backups.md
       - Vars Backend: manual/vars-backend.md
       - Facts Backend: manual/secrets.md
+      - Facts Vars Migration: manual/migration-facts-vars.md
       - Autoincludes: manual/adding-machines.md
       - Inventory:
           - Inventory: manual/inventory.md

docs/site/manual/migration-facts-vars.md

@@ -0,0 +1,127 @@
+# Migrate modules from `facts` to `vars`.
+
+For a high level overview about `vars` see our [blog post](https://clan.lol/blog/vars/).
+
+This guide will help you migrate your modules that still use our [`facts`](../manual/secrets.md) backend
+to the [`vars`](../manual/vars-backend.md) backend.
+
+The `vars` [module](../reference/clan-core/vars.md) and the clan [command](../reference/cli/vars.md) work in tandem, they should ideally be kept in sync.
+
+## Keep Existing Values
+
+In order to keep existing values and move them from `facts` to `vars`
+we will need to set the corresponding option in the vars module:
+
+```
+migrateFact = "fact-name"
+```
+
+This will now check on `vars` generation if there is an existing `fact` with the
+name already present and if that is the case will migrate it to `vars`.
+
+Let us look at the mapping a little closer.
+Suppose we have the following fact: `facts.services.vaultwarden.secret.admin`.
+This would read as follows: The `vaultwarden` `fact` service has the `admin` secret.
+In order to migrate this fact we would need to have the following `vars` configuration:
+
+```nix
+vars.generators.vaultwarden = {
+    migrateFact = "vaultwarden";
+    files.admin = {};
+};
+```
+
+And this would read as follows: The vaultwarden `vars` module generates the admin file.
+
+
+## Prompts
+
+Because prompts can be a necessity for certain systems `vars` have a shorthand for defining them.
+A prompt is a request for user input. Let us look how user input used to be handled in facts:
+
+```nix
+facts.services.forgejo-api = {
+    secret.token = {};
+    generator.prompt = "Please insert your forgejo api token";
+    generator.script = "cp $prompt_value > $secret/token";
+};
+```
+To have analogous functionality in `vars`:
+```nix
+vars.generators.forgejo-api = {
+    prompts.token = {
+        description = "Please insert your forgejo api token"
+        persist = true;
+    };
+};
+```
+This does not only simplify prompting, it also now allows us to define multiple prompts in one generator.
+A more analogous way to the `fact` method is available, in case the module author needs more flexibility with the prompt input:
+
+```nix
+vars.generators.forgejo-api = {
+    files.token = {};
+    prompts.token.description = "Please insert your forgejo api token";
+    script = "cp $prompts/<name> $out/<name>";
+};
+```
+
+## Migration of a complete module
+
+Let us look closer at how we would migrate an existing generator for syncthing.
+This is the `fact` module of syncthing:
+
+```nix
+facts.services.syncthing = {
+  secret.key = {};
+  secret.cert = {};
+  public.id = {};
+
+  generator.path = [
+    pkgs.coreutils
+    pkgs.gnugrep
+    pkgs.syncthing
+  ];
+
+  generator.script = ''
+    syncthing generate --config "$out"
+    mv "$out"/key.pem "$secret"/key
+    mv "$out"/cert.pem "$secret"/cert
+    cat "$out"/config.xml | grep -oP '(?<=<device id=")[^"]+' | uniq > "$public"/id
+  '';
+};
+```
+
+
+This would be the corresponding `vars` module, which also will migrate existing facts.
+```nix
+vars.generators.syncthing = {
+  migrateFact = "syncthing";
+
+  files.key = {};
+  files.cert = {};
+  files.id.secret = false;
+
+  runtimeInputs = [
+    pkgs.coreutils
+    pkgs.gnugrep
+    pkgs.syncthing
+  ];
+
+  script = ''
+    syncthing generate --config "$out"
+    mv "$out"/key.pem "$out"/key
+    mv "$out"/cert.pem "$out"/cert
+    cat "$out"/config.xml | grep -oP '(?<=<device id=")[^"]+' | uniq > "$out"/id
+  '';
+};
+```
+Most of the usage patterns stay the same, but `vars` have a more ergonomic interface.
+There are not two different ways to define files anymore (public/secret).
+Not files are defined under the files attribute and are secret by default. 
+
+
+## Happy Migration
+
+We hope this gives you a clear path to start and finish your migration from `facts` to `vars`.
+Please do not hesitate reaching out if something is still unclear - either through [matrix](https://matrix.to/#/#clan:clan.lol) or through our git [forge](https://git.clan.lol/clan/clan-core).