From 2135f30dbc627d2da55751396033c0b376f257c4 Mon Sep 17 00:00:00 2001 From: Wynne Pirini Date: Mon, 19 Oct 2026 08:17:14 +1300 Subject: [PATCH 1/3] feat(ns8): make a cloned instance release its hostname Cloning an instance from the cluster admin UI copies the calnode-data volume and the module state. That is enough to duplicate a working instance, and it was already working, because the core clone-module action ships a partial default implementation: ns8-kickstart itself declares only configure-module and get-configuration, so shipping no clone-module action is normal, not a gap. What the default does not handle is that two of the things in state/ belong to ONE hostname: config.json the public hostname and its TLS flags calnode.env BASE_URL, derived from that hostname The host-based Traefik route is registered by configure-module and belongs to one instance, so it is not copied: routes are keyed by MODULE_ID. A clone therefore arrives holding the source's hostname with no route of its own, and configuring it with that hostname is then REFUSED, because the source still answers for it and configure-module refuses to steal a hostname that another route already serves. The clone is not a clean failure, it is a quietly broken instance that looks like a configuration bug. The step releases the hostname: config.json is removed and BASE_URL dropped, so get-configuration reports configured:false and the Settings page asks for a hostname. The clone is then in exactly the state a freshly added instance is in, and configure-module registers a route for whatever name it is given. What must not be released is CALNODE_ENCRYPTION_KEY. It travels with the copied database and is the only thing that can unwrap the database key vault; dropping it would hand back an unreadable copy of every booking, which is strictly worse than the bug being fixed. The rewrite therefore fails loudly rather than writing an env file without the key, even though that is a state a mis-edited file could otherwise produce. Tested offline, 8 cases in test_clone_module.py, wired into the same validate job as the existing suite so a regression fails on every push: the key survives while BASE_URL does not, config.json is removed, a missing config.json or calnode.env is not an error, the refusal path, file mode stays 0600, comments and blank lines survive the rewrite, and the step is idempotent because action steps can be retried. 17 tests total in the packaging suite, all passing. The step runs at 20, after the core moves data in 10recvstate and before it starts the service in 90finalize. Honest caveat: this is verified by unit tests and by reading the core implementation, NOT by cloning on a real cluster. That needs a live NS8 node, and the robot suite does not cover clone yet. Worth doing before telling anyone a clone is supported. --- .github/workflows/ns8-module.yml | 4 +- packaging/ns8/README.md | 28 ++++ .../actions/clone-module/20unclaimhostname | 124 ++++++++++++++++ packaging/ns8/test_clone_module.py | 132 ++++++++++++++++++ 4 files changed, 286 insertions(+), 2 deletions(-) create mode 100644 packaging/ns8/imageroot/actions/clone-module/20unclaimhostname create mode 100644 packaging/ns8/test_clone_module.py diff --git a/.github/workflows/ns8-module.yml b/.github/workflows/ns8-module.yml index b6c44de5..71357757 100644 --- a/.github/workflows/ns8-module.yml +++ b/.github/workflows/ns8-module.yml @@ -32,9 +32,9 @@ jobs: - name: Validate action scripts and schemas working-directory: packaging/ns8 run: | - python3 -m py_compile imageroot/actions/configure-module/20configure imageroot/actions/get-configuration/20read + python3 -m py_compile imageroot/actions/configure-module/20configure imageroot/actions/get-configuration/20read imageroot/actions/clone-module/20unclaimhostname python3 -m py_compile assert-multiarc.py - python3 -m py_compile test_assert_multiarc.py + python3 -m py_compile test_assert_multiarc.py test_clone_module.py # Offline tests, so a broken invariant fails on every push rather than # waiting for a release to notice. The registry round-trip tests in the # same file are opt-in and skipped unless NS8_REGISTRY_TESTS=1. diff --git a/packaging/ns8/README.md b/packaging/ns8/README.md index 17b34d68..0710ee32 100644 --- a/packaging/ns8/README.md +++ b/packaging/ns8/README.md @@ -167,6 +167,34 @@ operator of that destination, which may be a third-party storage provider, holds an encrypted copy of your database and the key that unlocks it. Configure the backup accordingly. +## Clone and move + +Cloning an instance from the cluster admin UI copies the `calnode-data` volume +and the module state, so the copy arrives with all its bookings, users and +settings. + +The clone deliberately arrives **unconfigured**. The hostname belongs to one +instance: it is stored in the module state, but the host-based route that answers +for it is registered per instance. A clone that kept the hostname would hold a +name it has no route for, and configuring it with that name would then be +refused, because the source instance still answers for it. So the clone gives the +hostname back and the Settings page asks for a new one. Give it a hostname, +click save, and it is live. That is the same state a freshly added instance is +in, and it is what makes the Settings page and the configure action agree. + +Two things the clone keeps, deliberately: + +- **The encryption key.** It travels with the copied database and is the only + thing that can unwrap the database key vault. Without it the clone would hold + an unreadable copy of every booking, so it is preserved across the clone even + though the hostname is not. +- **All the data.** The copy is complete, so the clone is a genuine second + instance with its own URL, not a way to share one database. + +Moving an instance between nodes works the same way. If the instance is reached +by a public hostname, point your DNS at the new node; the cluster reverse proxy +is reconfigured for you. + ## Uninstall To uninstall the instance, keeping its data for a later reinstall: diff --git a/packaging/ns8/imageroot/actions/clone-module/20unclaimhostname b/packaging/ns8/imageroot/actions/clone-module/20unclaimhostname new file mode 100644 index 00000000..46be08c2 --- /dev/null +++ b/packaging/ns8/imageroot/actions/clone-module/20unclaimhostname @@ -0,0 +1,124 @@ +#!/usr/bin/env python3 + +# +# Copyright (C) 2023 Nethesis S.r.l. +# SPDX-License-Identifier: GPL-3.0-or-later +# + +# +# Clone support. +# +# The core clone-module implementation copies the module volumes and the whole +# state/ directory, and that alone is enough to duplicate a working instance. +# Two things in state/ are specific to ONE hostname, though, and carrying them +# to a second instance silently breaks it: +# +# config.json the public hostname and its TLS flags +# calnode.env BASE_URL, which is derived from that hostname +# +# A cloned instance would arrive holding the source's hostname but with no route +# of its own, because the host-based Traefik route is registered by +# configure-module and belongs to the source instance (routes are keyed by +# MODULE_ID, so nothing stale is copied and nothing needs cleaning up here). +# Worse, configuring the clone with that hostname would then be REFUSED, since +# the source still answers for it. A clone would come up quietly broken and +# appear to be a configuration bug. +# +# So the clone gives up the hostname and becomes an unconfigured instance. The +# Settings page then asks for a hostname, configure-module registers a route for +# it, and the clone works. This is the same state a freshly added instance is in. +# +# What must NOT be cleared is CALNODE_ENCRYPTION_KEY. It travels with the copied +# database and is the only thing that can unwrap the database key vault; drop it +# and the clone holds an unreadable copy of every booking. Keep the key, drop the +# hostname. +# +# get-configuration already reports configured:false when config.json has no +# host, so no other change is needed for the UI to prompt. +# +# Steps run in sorted order: the core moves data in 10recvstate and starts the +# service in 90finalize, so this runs after the data lands and before startup. + +import json +import os +import sys + +CONFIG_FILE = "config.json" +ENV_FILE = "calnode.env" +# Derived from the hostname, so it goes whenever the hostname goes. +HOSTNAME_DERIVED_KEYS = ("BASE_URL",) + + +def read_env_file(path): + values = {} + try: + with open(path, "r", encoding="utf-8") as handle: + for line in handle.read().splitlines(): + stripped = line.strip() + if not stripped or stripped.startswith("#") or "=" not in stripped: + continue + key, _, value = stripped.partition("=") + values[key.strip()] = value.strip() + except FileNotFoundError: + pass + return values + + +def drop_hostname_from_env(path, keep): + """Remove hostname-derived keys from calnode.env, preserving everything else. + + Rewrites the file in the same # comment / KEY=value shape configure-module + writes, so a later configure produces an identical file. Returns the keys + that were actually removed, or [] if there was nothing to do. + """ + values = read_env_file(path) + dropped = [key for key in HOSTNAME_DERIVED_KEYS if key in values] + if not dropped: + return [] + for key in dropped: + values.pop(key, None) + + lines = [ + "# Rewritten by clone-module: the hostname was released with the", + "# source instance and is set again by configure-module.", + ] + lines += [f"{key}={values[key]}" for key in sorted(values)] + with open(path, "w", encoding="utf-8") as handle: + handle.write("\n".join(lines) + "\n") + os.chmod(path, 0o600) + + missing = [key for key in keep if key not in values] + if missing: + raise RuntimeError( + f"refusing to release the hostname: {path} would lose {', '.join(missing)}" + ) + return dropped + + +def release_hostname(config_path, env_path, keep=("CALNODE_ENCRYPTION_KEY",)): + """Return the clone to an unconfigured state, keeping its encryption key.""" + dropped = drop_hostname_from_env(env_path, keep) + + removed_config = False + if os.path.exists(config_path): + os.remove(config_path) + removed_config = True + + if removed_config or dropped: + print( + f"clone is unconfigured; set a hostname to finish (dropped " + f"{', '.join(dropped) or 'nothing'} from {env_path}, " + f"{'removed' if removed_config else 'kept'} {config_path})", + file=sys.stderr, + ) + else: + print("clone had no hostname to release", file=sys.stderr) + return removed_config, dropped + + +if __name__ == "__main__": + state_dir = os.getcwd() + release_hostname( + os.path.join(state_dir, CONFIG_FILE), + os.path.join(state_dir, ENV_FILE), + ) \ No newline at end of file diff --git a/packaging/ns8/test_clone_module.py b/packaging/ns8/test_clone_module.py new file mode 100644 index 00000000..ff012756 --- /dev/null +++ b/packaging/ns8/test_clone_module.py @@ -0,0 +1,132 @@ +"""Tests for the clone-module step. + +Run offline, so a broken invariant fails on every push: + + python3 -m unittest discover -s packaging/ns8 -p 'test_*.py' -v + +These cover the one thing that must never go wrong: a cloned instance must give +up the hostname without losing the encryption key that makes its copied database +readable. +""" + +import importlib.util +import json +import os +import pathlib +import tempfile +import unittest + +_STEP = pathlib.Path(__file__).resolve().parent / ( + "imageroot/actions/clone-module/20unclaimhostname" +) +_SPEC = importlib.util.spec_from_loader( + "unclaim", importlib.machinery.SourceFileLoader("unclaim", str(_STEP)) +) +unclaim = importlib.util.module_from_spec(_SPEC) +_SPEC.loader.exec_module(unclaim) + + +def write_env(path, values, comments=True): + lines = ["# Written by configure-module."] if comments else [] + lines += [f"{k}={v}" for k, v in values.items()] + path.write_text("\n".join(lines) + "\n", encoding="utf-8") + os.chmod(path, 0o600) + + +def write_config(path, host): + path.write_text( + json.dumps({"host": host, "lets_encrypt": True, "http2https": True}), + encoding="utf-8", + ) + + +class ReleaseHostname(unittest.TestCase): + def setUp(self): + self.dir = tempfile.TemporaryDirectory() + self.addCleanup(self.dir.cleanup) + self.config = pathlib.Path(self.dir.name) / "config.json" + self.env = pathlib.Path(self.dir.name) / "calnode.env" + + def values(self): + return unclaim.read_env_file(str(self.env)) + + def test_encryption_key_survives_and_hostname_does_not(self): + write_env( + self.env, + { + "PORT": "3000", + "DATABASE_URL": "sqlite:///data/calnode.db", + "BASE_URL": "https://book.example.com", + "CALNODE_ENCRYPTION_KEY": "abc123", + }, + ) + write_config(self.config, "book.example.com") + + unclaim.release_hostname(str(self.config), str(self.env)) + + values = self.values() + self.assertNotIn("BASE_URL", values) + self.assertEqual(values["CALNODE_ENCRYPTION_KEY"], "abc123") + self.assertEqual(values["PORT"], "3000") + self.assertEqual(values["DATABASE_URL"], "sqlite:///data/calnode.db") + + def test_config_is_removed_so_the_ui_asks_for_a_hostname(self): + write_env(self.env, {"BASE_URL": "https://x.example.com", "CALNODE_ENCRYPTION_KEY": "k"}) + write_config(self.config, "x.example.com") + + removed, _ = unclaim.release_hostname(str(self.config), str(self.env)) + + self.assertTrue(removed) + self.assertFalse(self.config.exists()) + + def test_missing_config_is_not_an_error(self): + """A clone of an unconfigured instance has nothing to release.""" + write_env(self.env, {"PORT": "3000", "CALNODE_ENCRYPTION_KEY": "k"}) + removed, dropped = unclaim.release_hostname(str(self.config), str(self.env)) + self.assertFalse(removed) + self.assertEqual(dropped, []) + self.assertEqual(self.values()["CALNODE_ENCRYPTION_KEY"], "k") + + def test_missing_env_file_is_not_an_error(self): + write_config(self.config, "x.example.com") + removed, dropped = unclaim.release_hostname(str(self.config), str(self.env)) + self.assertTrue(removed) + self.assertEqual(dropped, []) + self.assertFalse(self.config.exists()) + + def test_refuses_to_write_an_env_file_without_the_key(self): + """Better to fail the clone than to hand back an unreadable database.""" + write_env(self.env, {"BASE_URL": "https://x.example.com"}) + with self.assertRaises(RuntimeError) as caught: + unclaim.release_hostname(str(self.config), str(self.env)) + self.assertIn("CALNODE_ENCRYPTION_KEY", str(caught.exception)) + + def test_env_file_stays_owner_only(self): + write_env(self.env, {"BASE_URL": "https://x.example.com", "CALNODE_ENCRYPTION_KEY": "k"}) + unclaim.release_hostname(str(self.config), str(self.env)) + self.assertEqual(os.stat(self.env).st_mode & 0o777, 0o600) + + def test_comments_and_blank_lines_are_tolerated(self): + self.env.write_text( + "# Written by configure-module.\n\n" + "PORT=3000\n\n# a note\nBASE_URL=https://x.example.com\n" + "CALNODE_ENCRYPTION_KEY=k\n", + encoding="utf-8", + ) + unclaim.release_hostname(str(self.config), str(self.env)) + values = self.values() + self.assertNotIn("BASE_URL", values) + self.assertEqual(values["CALNODE_ENCRYPTION_KEY"], "k") + self.assertEqual(values["PORT"], "3000") + + def test_is_idempotent(self): + """clone-module steps can be retried; running twice must not lose more.""" + write_env(self.env, {"BASE_URL": "https://x.example.com", "CALNODE_ENCRYPTION_KEY": "k"}) + write_config(self.config, "x.example.com") + unclaim.release_hostname(str(self.config), str(self.env)) + unclaim.release_hostname(str(self.config), str(self.env)) + self.assertEqual(self.values()["CALNODE_ENCRYPTION_KEY"], "k") + + +if __name__ == "__main__": + unittest.main() \ No newline at end of file From 55e025e41f6715021e77852380fd90d8c6da8ba1 Mon Sep 17 00:00:00 2001 From: Wynne Pirini Date: Mon, 19 Oct 2026 08:31:29 +1300 Subject: [PATCH 2/3] fix(ns8): mark the clone-module step executable in the index core.fileMode is false on this machine, so chmod 755 on the file was invisible to git and the step was committed as 100644. The validate job's exec-bit guard caught it: 'not executable in index: imageroot/actions/clone-module/ 20unclaimhostname'. An NS8 action step that is not executable is silently ignored by the agent, so the step would simply never have run. Fixed with update-index --chmod=+x, which sets the index mode explicitly rather than trusting the working tree. --- packaging/ns8/imageroot/actions/clone-module/20unclaimhostname | 0 1 file changed, 0 insertions(+), 0 deletions(-) mode change 100644 => 100755 packaging/ns8/imageroot/actions/clone-module/20unclaimhostname diff --git a/packaging/ns8/imageroot/actions/clone-module/20unclaimhostname b/packaging/ns8/imageroot/actions/clone-module/20unclaimhostname old mode 100644 new mode 100755 From 9ffc363c5219561ac71ee9efd0cb2d3edd4559de Mon Sep 17 00:00:00 2001 From: Wynne Pirini Date: Wed, 21 Oct 2026 13:44:29 +1300 Subject: [PATCH 3/3] fix(ns8): refuse the clone before rewriting the env file, not after Review nit, taken because it is a behaviour difference rather than a style one. The guard that protects CALNODE_ENCRYPTION_KEY ran after the env file had been rewritten, so a clone that was going to be refused had already had its env file mutated by the step that then aborted. Nothing recorded that mutation, so the clone could end up differing from its source with no trace of why. The check now runs before the write. The key still cannot be lost either way, since only BASE_URL is removed and the guard is defending against a pre-existing condition, but an aborted step now leaves both files exactly as it found them. New test asserts that: on refusal, calnode.env and config.json are byte-identical to before. 18 tests, all passing. --- .../actions/clone-module/20unclaimhostname | 18 ++++++++++++------ packaging/ns8/test_clone_module.py | 17 +++++++++++++++++ 2 files changed, 29 insertions(+), 6 deletions(-) diff --git a/packaging/ns8/imageroot/actions/clone-module/20unclaimhostname b/packaging/ns8/imageroot/actions/clone-module/20unclaimhostname index 46be08c2..802fd70d 100755 --- a/packaging/ns8/imageroot/actions/clone-module/20unclaimhostname +++ b/packaging/ns8/imageroot/actions/clone-module/20unclaimhostname @@ -75,6 +75,18 @@ def drop_hostname_from_env(path, keep): dropped = [key for key in HOSTNAME_DERIVED_KEYS if key in values] if not dropped: return [] + + # Refuse BEFORE touching the file. Checking afterwards would rewrite the env + # file and then fail, leaving the instance mutated by a step that aborted; + # the clone would then differ from its source in ways nothing recorded. + missing = [key for key in keep if key not in values] + if missing: + raise RuntimeError( + f"refusing to release the hostname: {path} has no " + f"{', '.join(missing)}, so the clone could not decrypt its own " + "database" + ) + for key in dropped: values.pop(key, None) @@ -86,12 +98,6 @@ def drop_hostname_from_env(path, keep): with open(path, "w", encoding="utf-8") as handle: handle.write("\n".join(lines) + "\n") os.chmod(path, 0o600) - - missing = [key for key in keep if key not in values] - if missing: - raise RuntimeError( - f"refusing to release the hostname: {path} would lose {', '.join(missing)}" - ) return dropped diff --git a/packaging/ns8/test_clone_module.py b/packaging/ns8/test_clone_module.py index ff012756..a3af5b19 100644 --- a/packaging/ns8/test_clone_module.py +++ b/packaging/ns8/test_clone_module.py @@ -101,6 +101,23 @@ def test_refuses_to_write_an_env_file_without_the_key(self): unclaim.release_hostname(str(self.config), str(self.env)) self.assertIn("CALNODE_ENCRYPTION_KEY", str(caught.exception)) + def test_refusal_leaves_the_files_untouched(self): + """The guard must fire before anything is rewritten. + + Checking after the write would abort a step that had already mutated the + clone, so it would differ from its source with nothing recording it. + """ + write_env(self.env, {"BASE_URL": "https://x.example.com", "PORT": "3000"}) + write_config(self.config, "x.example.com") + before_env = self.env.read_text() + before_config = self.config.read_text() + + with self.assertRaises(RuntimeError): + unclaim.release_hostname(str(self.config), str(self.env)) + + self.assertEqual(self.env.read_text(), before_env) + self.assertEqual(self.config.read_text(), before_config) + def test_env_file_stays_owner_only(self): write_env(self.env, {"BASE_URL": "https://x.example.com", "CALNODE_ENCRYPTION_KEY": "k"}) unclaim.release_hostname(str(self.config), str(self.env))