From 3f5aab0a99c78865e77b73fc4296b3e7b728aecb Mon Sep 17 00:00:00 2001
From: Yaroslav Bolyukin <iam@lach.pw>
Date: Tue, 21 May 2024 22:49:24 +0000
Subject: [PATCH] doc: migration to updated fleet.nix format


---
--- /dev/null
+++ b/MIGRATION.adoc
@@ -0,0 +1,50 @@
+== fleet.nix <unset> => 0.1.0
+
+Add version field::
+Set it to 0.1.0; This field specifies which version of fleet do you use for cluster management, breaking changes will also break this value to make sure you read MIGRATION.adoc.
+
+Move every secret part::
+Before it was only public and private, now it can be any number of parts.
+
+In your fleet.nix file, look at every record like this:
+[source,nix]
+----
+gitlab-initial-root = {
+	createdAt = "2024-03-01T15:54:32.983358495Z";
+	public = "example";
+	secret = "vp%d6wO#0#D2.../dgCA+v4Gf:YG";
+};
+----
+
+And modify it as following:
+[source,nix]
+----
+gitlab-initial-root = {
+	createdAt = "2024-03-01T15:54:32.983358495Z";
+	public.raw = "<PLAINTEXT>example";
+	secret.raw = ''
+		<ENCRYPTED><Z85-ENCODED>
+		vp%d6wO#0#D2.../dgCA+v4Gf:YG
+	'';
+};
+----
+
+Thus moving all the data under the `raw` attr, and then prefixing it with `<PLAINTEXT>` for `public`, and `<ENCRYPTED><Z85-ENCODED>\n` for `private`.
+The reason for this change is that public parts are not always plaintext, and sometimes there are more than two parts.
+Of course, it is also possible to process all of this data on demand (I.e doing reencoding of secret in service `PreStart=`), but I decided to provide better user exprience out of the box.
+
+Default encoding was also changed from `Z85` to `base64`, because `Z85` was chosen a long time ago for different reasons, and no need to keep it further.
+This conversion will be done by fleet by itself.
+
+Update references to secrets in fleet/nixos configurations::
+Instead of `config.secrets.secret-name.secretPath` use `config.secrets.secret-name.secret.path`, 
+instead of `config.secrets.secret-name.stableSecretPath` use `config.secrets.secret-name.secret.stablePath`, 
+instead of `config.secrets.secret-name.public` use `config.secrets.secret-name.public.data` (note that this attribute will also work for parts other than named `public`, but it will throw an error
+if target secret part is encrypted or not `<PLAINTEXT>`-based.
+
+Do not expect used directory structure to be stable, it will be reworked a bit later, for now always directly reference secrets by attribute paths.
+
+Update scripts using fleet::
+`fleet secrets` subcommand no longer has `--plaintext` arguments where it used to have them, due to non-plaintext mode basically unusable.
+
+`fleet secrets read-public` is now can be replaced with `fleet secrets read ... public` (So, reading `public` part of secret).

-- 
gitstuff