From dd0cbdf40c58e67088fe6a909736ed7eac53139e Mon Sep 17 00:00:00 2001
From: nblock <nblock@users.noreply.github.com>
Date: Fri, 9 May 2025 23:30:39 +0200
Subject: [PATCH] Add migration steps when policy is stored in the database
 (#2581)

Fixes: #2567
---
 CHANGELOG.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 80e08c6e..3d96dc76 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -64,6 +64,29 @@ new policy code passes all of our tests.
     `@` should be appended at the end. For example, if your user is `john`, it
     must be written as `john@` in the policy.
 
+<details>
+
+<summary>Migration notes when the policy is stored in the database.</summary>
+
+This section **only** applies if the policy is stored in the database.
+
+Headscale won't start with an invalid policy and this also means that the policy
+can't be updated with the CLI. One may migrate a policy stored in the database
+following these steps:
+
+* Dump the policy to a file while still running Headscale 0.25:
+  `headscale policy get > policy.json`
+* Create a dummy policy (here: allow all):
+  `echo '{"acls":[{"action":"accept","src":["*"],"dst":["*:*"]}]}' > dummy.json`
+* Load the dummy policy into Headscale 0.25:
+  `headscale policy set --file dummy.json`
+* Edit `policy.json` and migrate to policy V2
+* Update to Headscale 0.26
+* Load the modified policy V2:
+  `headscale policy set --file policy.json`
+
+</details>
+
 **SSH**
 
 The SSH policy has been reworked to be more consistent with the rest of the