From b04ebbdd78f9acbc4ec4065f22950a80000c2065 Mon Sep 17 00:00:00 2001 From: Jon Phenow Date: Fri, 9 Oct 2026 19:22:06 +0000 Subject: [PATCH 01/11] Document the storage upgrade MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sprites created before SBD became the default run their disk on the older storage, and moving across is a one-time, customer-initiated upgrade. Nothing in the docs described it. It goes in Sprite Maintenance rather than a page of its own: it is the same shape as the OS upgrade already documented there — an older version that has to be moved forward deliberately — and it needs no new navigation entry for something we expect to delete once the fleet is across. Every command works against shipped code: `sprite exec` to tell which storage a Sprite is on, `sprite file pull -r` for a local copy, and `sprite api` for the upgrade and the rollback. Two details customers cannot discover for themselves are called out, because getting either wrong costs a restart: - `curl -N`, without which the upgrade endpoint's progress stream buffers and a multi-minute upgrade looks like a hung command. - Recording the current version first. Afterwards the version field reports the version that was moved to, and nothing records the one it came from, so the rollback target is unrecoverable if it was not written down. No version numbers are named. A Sprite whose release line has nothing newer published to it is told to contact support rather than given a build that will go stale in the page. Claude-Session: https://claude.ai/code/session_01JvqUYVtkXDQ5m4n5vaH9sr --- sprite-maintenance.mdx | 107 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) diff --git a/sprite-maintenance.mdx b/sprite-maintenance.mdx index 34cc10a..97ec18a 100644 --- a/sprite-maintenance.mdx +++ b/sprite-maintenance.mdx @@ -43,3 +43,110 @@ sudo do-release-upgrade # upgrade installed packages to the new release sudo apt full-upgrade ``` + +--- + +## Storage Upgrades + +Your Sprite's disk can run on a newer storage system than the one it was created with. Newer Sprites already use it. Upgrading is something you ask for — nothing moves your Sprite on its own. + +After upgrading: + +- **Reads and writes get faster.** Recently used data is served from a cache on the host instead of being fetched from object storage each time. +- **Checkpoints get faster.** A checkpoint becomes a marker against your disk rather than a copy of it, so taking one is quick and uses almost no extra space. +- **Restores get faster.** A restore switches your disk back to the checkpoint instead of downloading it, so it finishes in about the time a restart takes. +- **Fewer interruptions.** Short-lived storage problems are much less likely to reach your Sprite. + +You're not obliged to upgrade, and nothing stops working if you don't. The trade-off is updates: new Sprite runtime builds target the newer storage, so a Sprite that stays where it is picks up new versions less and less often. The older storage will eventually be retired. + +### Checking whether a Sprite needs it + +Ask the Sprite directly: + +```bash +sprite exec -- printenv SPRITE_STORAGE_DRIVER +``` + +If that prints `sbd`, you're already on the newer storage and there's nothing to do. Anything else, or nothing at all, means the Sprite hasn't been upgraded yet. + +To check a whole organization at once: + +```bash +sprite list -o my-org | while read -r s; do + printf '%s\t%s\n' "$s" "$(sprite exec -o my-org -s "$s" -- printenv SPRITE_STORAGE_DRIVER 2>/dev/null)" +done +``` + + +Running the upgrade on a Sprite that didn't need it does no harm. With nothing to convert it becomes an ordinary version upgrade: one restart, no copy. So if the answer is ambiguous, run it rather than investigating further. + + +### Before you upgrade + + +**Checkpoints taken before the upgrade won't come with you.** The upgrade copies your Sprite's current disk. Earlier [checkpoints](/concepts/checkpoints) stay behind — they aren't deleted, but they stop appearing in your checkpoint list and can't be restored. + +If something you need exists only inside an old checkpoint, restore it and copy the files out first. Everything on your current disk comes across, so this affects your history, not your working state. + +If your checkpoint history itself matters to you, contact support before upgrading. Bringing it across is possible on request, and it can't be done afterwards. + + +Your Sprite restarts once during the upgrade, and the first start afterwards is slower than usual while your disk is copied. The name, URL, configuration, and files all stay as they are. + +If it would put your mind at ease, copy anything that matters to your own machine first: + +```bash +sprite file pull -r -p -s my-sprite /home/sprite/app ./sprite-backup +``` + +Stop your services first if you can. Files copied while something is writing to them can be captured half-finished. + +Then write down the version your Sprite is on. This is the one thing you can't recover later: once the upgrade is accepted, this field reports the version you moved *to*, and nothing records the one you came from. You need it to go back. + +```bash +sprite api /v1/sprites/my-sprite -- --silent | jq -r .version +``` + +### Running the upgrade + +Take a checkpoint if you want a recent restore point, then: + +```bash +sprite api -s my-sprite /upgrade -- \ + -N -sS -X POST -H 'Content-Type: application/json' \ + -d '{"allow_storage_migration": true}' +``` + +This stays in the foreground for the whole upgrade and prints one line per step, finishing with a line of type `completed` or `failed`. The `-N` matters: without it nothing prints until the end, and a several-minute upgrade looks like a command that has hung. + +The `allow_storage_migration` flag is required, and that's deliberate. Without it, an upgrade that would change your storage is refused. Routine upgrades never move you; only this explicit request does. + + +If the response says `no upgrade is published for this sprite's release lane`, your Sprite is on a release line with nothing newer published to it yet, and nothing has happened. Contact support for the version to use, then add it to the request as `"version": "..."` alongside the flag. + + +When your Sprite comes back, check that your application serves traffic, that your files are where you left them, and that a new checkpoint succeeds. Take that checkpoint once you're satisfied — it becomes your first restore point on the new storage. + +An upgrade that fails leaves your original disk untouched. The copy is written separately and only becomes your active disk at the last step, so a failure part way through can't damage what you had. If your Sprite doesn't come back, or comes back wrong, contact support and say that a storage upgrade failed. Stop writing to the Sprite in the meantime, because anything written after a failed upgrade makes recovery messier. + +### Going back + +The same call, with the version you wrote down and the same flag. The storage check refuses a mismatch in either direction, so going back needs the flag whose name sounds like the opposite: + +```bash +sprite api -s my-sprite /upgrade -- \ + -N -sS -X POST -H 'Content-Type: application/json' \ + -d '{"version": "THE-VERSION-YOU-WROTE-DOWN", "allow_storage_migration": true}' +``` + +You return to your disk as it was at the moment of the upgrade. Anything written after it doesn't come back with you, so the sooner you decide, the less you lose. + + +You can't repeat the upgrade on your own after going back. Asking for it a second time brings back the disk as it was at the first attempt rather than copying your newer work across. Contact support instead of retrying it yourself. + + +### Moving to a new Sprite instead + +There's a second route: create a new Sprite, which already uses the newer storage, and copy your data across. It's more work and you get a new name and URL, but nothing about your existing Sprite changes, your old checkpoints stay reachable on it, and you cut over when you're ready with no deadline. + +Contact support and we'll do the copy with you, including verifying it file by file before you commit to anything. From 69adc6265e2c3c240a63e627678eb16c15679b4a Mon Sep 17 00:00:00 2001 From: Jon Phenow Date: Fri, 9 Oct 2026 20:40:41 +0000 Subject: [PATCH 02/11] Give the new-Sprite route commands instead of a support promise Neither promise was ours to make. "Contact support and we'll do the copy with you, including verifying it file by file" describes a service we do not offer, and "bringing your checkpoint history across is possible on request" describes a mechanism that does not exist. The copy is two commands, so show them. `sprite file pull -r` and `push -r` move the paths you name; `sprite-env services list` is how you find what else needs setting up again, since services, environment variables and configuration do not copy. The checkpoint-history paragraph now points at the new-Sprite route, which genuinely preserves history: the old Sprite is untouched, so its checkpoints stay restorable for as long as it is kept. That replaces an offer with something the reader can act on. Claude-Session: https://claude.ai/code/session_01JvqUYVtkXDQ5m4n5vaH9sr --- sprite-maintenance.mdx | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/sprite-maintenance.mdx b/sprite-maintenance.mdx index 97ec18a..9658f7d 100644 --- a/sprite-maintenance.mdx +++ b/sprite-maintenance.mdx @@ -88,7 +88,7 @@ Running the upgrade on a Sprite that didn't need it does no harm. With nothing t If something you need exists only inside an old checkpoint, restore it and copy the files out first. Everything on your current disk comes across, so this affects your history, not your working state. -If your checkpoint history itself matters to you, contact support before upgrading. Bringing it across is possible on request, and it can't be done afterwards. +If you need to keep your checkpoint history, use the new-Sprite route below instead. Your old Sprite and everything on it stay exactly as they are, so its checkpoints remain restorable for as long as you keep it. Your Sprite restarts once during the upgrade, and the first start afterwards is slower than usual while your disk is copied. The name, URL, configuration, and files all stay as they are. @@ -147,6 +147,23 @@ You can't repeat the upgrade on your own after going back. Asking for it a secon ### Moving to a new Sprite instead -There's a second route: create a new Sprite, which already uses the newer storage, and copy your data across. It's more work and you get a new name and URL, but nothing about your existing Sprite changes, your old checkpoints stay reachable on it, and you cut over when you're ready with no deadline. +There's a second route: create a new Sprite, which already uses the newer storage, and copy your data across. You get a new name and URL, and you recreate your services and configuration by hand. In exchange, nothing about your existing Sprite changes, your old checkpoints stay reachable on it, and you cut over when you're ready with no deadline. -Contact support and we'll do the copy with you, including verifying it file by file before you commit to anything. +Stop your services on the old Sprite first, then copy your data out and back in: + +```bash +sprite create my-new-sprite + +sprite file pull -r -s my-sprite /home/sprite/app . +sprite file push -r -s my-new-sprite ./app /home/sprite/app +``` + +Only the paths you name come across. To see what else you'll need to set up again: + +```bash +sprite exec -s my-sprite -- sprite-env services list +``` + +Recreate each one on the new Sprite with `sprite-env services create`. Environment variables and other configuration don't copy either. + +Test the new Sprite while the old one is still running, then move whatever points at the old URL. Keep the old Sprite until you're satisfied — it's your rollback, and it has no deadline on it. From ca659380d1f881649027a9dd35b70b9c703f8b89 Mon Sep 17 00:00:00 2001 From: Jon Phenow Date: Fri, 9 Oct 2026 20:42:46 +0000 Subject: [PATCH 03/11] Stop mentioning support, and stop claiming checkpoints survive a move MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two things the page should not have said. It named support four times. People reach out when they need to; a doc that routes them there is adding a step, and in two of the four places it was describing work we do not do. Worse, it told readers that moving to a new Sprite preserves their checkpoint history. A new Sprite is a fresh Sprite — it has no checkpoints, and nothing carries them over. What is true is only that an untouched old Sprite still has its own, which is not a migration route and should not be dressed as one. The claim is gone; the warning now says plainly that pre-upgrade checkpoints cannot be restored and that anything needed from one has to be copied out first. The three remaining cases now state the situation and stop: an empty release lane needs an explicit version, a failed upgrade means stop writing to the Sprite, and a repeat upgrade after a rollback does not copy across what was written in between. Claude-Session: https://claude.ai/code/session_01JvqUYVtkXDQ5m4n5vaH9sr --- sprite-maintenance.mdx | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/sprite-maintenance.mdx b/sprite-maintenance.mdx index 9658f7d..2aac4cb 100644 --- a/sprite-maintenance.mdx +++ b/sprite-maintenance.mdx @@ -86,9 +86,7 @@ Running the upgrade on a Sprite that didn't need it does no harm. With nothing t **Checkpoints taken before the upgrade won't come with you.** The upgrade copies your Sprite's current disk. Earlier [checkpoints](/concepts/checkpoints) stay behind — they aren't deleted, but they stop appearing in your checkpoint list and can't be restored. -If something you need exists only inside an old checkpoint, restore it and copy the files out first. Everything on your current disk comes across, so this affects your history, not your working state. - -If you need to keep your checkpoint history, use the new-Sprite route below instead. Your old Sprite and everything on it stay exactly as they are, so its checkpoints remain restorable for as long as you keep it. +If something you need exists only inside an old checkpoint, restore it and copy the files out before you upgrade. Everything on your current disk comes across, so this affects your history, not your working state. Your Sprite restarts once during the upgrade, and the first start afterwards is slower than usual while your disk is copied. The name, URL, configuration, and files all stay as they are. @@ -122,12 +120,12 @@ This stays in the foreground for the whole upgrade and prints one line per step, The `allow_storage_migration` flag is required, and that's deliberate. Without it, an upgrade that would change your storage is refused. Routine upgrades never move you; only this explicit request does. -If the response says `no upgrade is published for this sprite's release lane`, your Sprite is on a release line with nothing newer published to it yet, and nothing has happened. Contact support for the version to use, then add it to the request as `"version": "..."` alongside the flag. +If the response says `no upgrade is published for this sprite's release lane`, your Sprite is on a release line with nothing newer published to it yet, and nothing has happened. Upgrading it needs an explicit version, added to the request as `"version": "..."` alongside the flag. When your Sprite comes back, check that your application serves traffic, that your files are where you left them, and that a new checkpoint succeeds. Take that checkpoint once you're satisfied — it becomes your first restore point on the new storage. -An upgrade that fails leaves your original disk untouched. The copy is written separately and only becomes your active disk at the last step, so a failure part way through can't damage what you had. If your Sprite doesn't come back, or comes back wrong, contact support and say that a storage upgrade failed. Stop writing to the Sprite in the meantime, because anything written after a failed upgrade makes recovery messier. +An upgrade that fails leaves your original disk untouched. The copy is written separately and only becomes your active disk at the last step, so a failure part way through can't damage what you had. If your Sprite doesn't come back, or comes back wrong, stop writing to it — anything written after a failed upgrade makes recovery messier. ### Going back @@ -142,7 +140,7 @@ sprite api -s my-sprite /upgrade -- \ You return to your disk as it was at the moment of the upgrade. Anything written after it doesn't come back with you, so the sooner you decide, the less you lose. -You can't repeat the upgrade on your own after going back. Asking for it a second time brings back the disk as it was at the first attempt rather than copying your newer work across. Contact support instead of retrying it yourself. +Don't repeat the upgrade after going back. Asking for it a second time brings back the disk as it was at the first attempt rather than copying across anything you wrote in between. ### Moving to a new Sprite instead From 275a8cad9589e3c5f4b48b299530e81e177293fc Mon Sep 17 00:00:00 2001 From: Jon Phenow Date: Fri, 9 Oct 2026 20:45:38 +0000 Subject: [PATCH 04/11] Give the rollback warning a way forward "Don't repeat the upgrade after going back" was the whole of it once the support line came out, which leaves someone who has rolled back with no route to the newer storage at all. Moving to a new Sprite is that route, and it is already the next section: a new Sprite converts nothing, so the reused-copy problem cannot arise. The warning now says why the second attempt does not work and where to go instead. Claude-Session: https://claude.ai/code/session_01JvqUYVtkXDQ5m4n5vaH9sr --- sprite-maintenance.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sprite-maintenance.mdx b/sprite-maintenance.mdx index 2aac4cb..6614ccc 100644 --- a/sprite-maintenance.mdx +++ b/sprite-maintenance.mdx @@ -140,7 +140,7 @@ sprite api -s my-sprite /upgrade -- \ You return to your disk as it was at the moment of the upgrade. Anything written after it doesn't come back with you, so the sooner you decide, the less you lose. -Don't repeat the upgrade after going back. Asking for it a second time brings back the disk as it was at the first attempt rather than copying across anything you wrote in between. +Don't repeat the upgrade after going back. The second attempt doesn't copy your disk again — it reuses the copy the first one made, so anything you wrote between the two is left behind. If you still want the newer storage after a rollback, move to a new Sprite instead, as below. ### Moving to a new Sprite instead From 7a7c7bf321d6db4e0360f2148663ddbd52c05b8a Mon Sep 17 00:00:00 2001 From: Jon Phenow Date: Fri, 9 Oct 2026 20:47:10 +0000 Subject: [PATCH 05/11] Say to contact support for the one failure we have to repair Everywhere else the page can tell someone what to do themselves. This case cannot: a Sprite upgraded, rolled back, written to, then upgraded again reuses the copy the first upgrade made, and the work from in between is only reachable by renaming the stale volume aside on the machine. That is internal, so the page should say so rather than leave someone staring at missing files. It states what is true and stops there. Nothing has been deleted, and the in-between work is still on the older storage; it does not promise a recovery or a timeline. Claude-Session: https://claude.ai/code/session_01JvqUYVtkXDQ5m4n5vaH9sr --- sprite-maintenance.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/sprite-maintenance.mdx b/sprite-maintenance.mdx index 6614ccc..aa527d1 100644 --- a/sprite-maintenance.mdx +++ b/sprite-maintenance.mdx @@ -141,6 +141,8 @@ You return to your disk as it was at the moment of the upgrade. Anything written Don't repeat the upgrade after going back. The second attempt doesn't copy your disk again — it reuses the copy the first one made, so anything you wrote between the two is left behind. If you still want the newer storage after a rollback, move to a new Sprite instead, as below. + +If you've already done it and files are missing, stop writing to the Sprite and contact support. Nothing has been deleted — the work from in between is still on the older storage. ### Moving to a new Sprite instead From a9dd814aef510e91a29e1306cd06a9faae90b5b9 Mon Sep 17 00:00:00 2001 From: Jon Phenow Date: Fri, 9 Oct 2026 20:51:23 +0000 Subject: [PATCH 06/11] Lead with the new Sprite, not the in-place upgrade MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Moving to a new Sprite is the option with less to go wrong, so it goes first. No disk conversion runs, the existing Sprite is untouched, its checkpoints stay restorable, and the rollback is to carry on using the Sprite you already have. What it costs is a new name and URL and setting services and configuration up again. Upgrading in place is now second and labelled for what it is: less work, and the one with something to go wrong. Everything specific to it — the checkpoint warning, the local copy, writing down the version, the upgrade itself and going back — sits under it rather than reading as the only route. Checking whether a Sprite needs upgrading stays at the top, since it applies either way, and now ends by naming the two routes. Claude-Session: https://claude.ai/code/session_01JvqUYVtkXDQ5m4n5vaH9sr --- sprite-maintenance.mdx | 66 ++++++++++++++++++++++-------------------- 1 file changed, 34 insertions(+), 32 deletions(-) diff --git a/sprite-maintenance.mdx b/sprite-maintenance.mdx index aa527d1..bda4997 100644 --- a/sprite-maintenance.mdx +++ b/sprite-maintenance.mdx @@ -77,11 +77,36 @@ sprite list -o my-org | while read -r s; do done ``` - -Running the upgrade on a Sprite that didn't need it does no harm. With nothing to convert it becomes an ordinary version upgrade: one restart, no copy. So if the answer is ambiguous, run it rather than investigating further. - +There are two ways across. Moving to a new Sprite is the safer one and the place to start. Upgrading in place is less work, and it's the one with something to go wrong. + +### Moving to a new Sprite + +Create a new Sprite, which already uses the newer storage, and copy your data across. Nothing about your existing Sprite changes, so there's no moment where you're committed to an outcome you haven't seen yet: no disk conversion runs, your old checkpoints stay restorable on the old Sprite, and if you don't like the result you keep using the one you already have. + +The cost is a new name and URL, and setting your services and configuration up again by hand. + +Stop your services on the old Sprite first, then copy your data out and back in: + +```bash +sprite create my-new-sprite + +sprite file pull -r -s my-sprite /home/sprite/app . +sprite file push -r -s my-new-sprite ./app /home/sprite/app +``` + +Only the paths you name come across. To see what else you'll need to set up again: + +```bash +sprite exec -s my-sprite -- sprite-env services list +``` + +Recreate each one on the new Sprite with `sprite-env services create`. Environment variables and other configuration don't copy either. + +Test the new Sprite while the old one is still running, then move whatever points at the old URL. Keep the old Sprite until you're satisfied — it's your rollback, and it has no deadline on it. + +### Upgrading in place -### Before you upgrade +This keeps the Sprite's name, URL and configuration. Your Sprite restarts once, and the first start afterwards is slower than usual while your disk is copied. **Checkpoints taken before the upgrade won't come with you.** The upgrade copies your Sprite's current disk. Earlier [checkpoints](/concepts/checkpoints) stay behind — they aren't deleted, but they stop appearing in your checkpoint list and can't be restored. @@ -89,7 +114,9 @@ Running the upgrade on a Sprite that didn't need it does no harm. With nothing t If something you need exists only inside an old checkpoint, restore it and copy the files out before you upgrade. Everything on your current disk comes across, so this affects your history, not your working state. -Your Sprite restarts once during the upgrade, and the first start afterwards is slower than usual while your disk is copied. The name, URL, configuration, and files all stay as they are. + +Running the upgrade on a Sprite that didn't need it does no harm. With nothing to convert it becomes an ordinary version upgrade: one restart, no copy. So if the check above is ambiguous, run it rather than investigating further. + If it would put your mind at ease, copy anything that matters to your own machine first: @@ -105,9 +132,7 @@ Then write down the version your Sprite is on. This is the one thing you can't r sprite api /v1/sprites/my-sprite -- --silent | jq -r .version ``` -### Running the upgrade - -Take a checkpoint if you want a recent restore point, then: +Take a checkpoint if you want a recent restore point, then run the upgrade: ```bash sprite api -s my-sprite /upgrade -- \ @@ -140,30 +165,7 @@ sprite api -s my-sprite /upgrade -- \ You return to your disk as it was at the moment of the upgrade. Anything written after it doesn't come back with you, so the sooner you decide, the less you lose. -Don't repeat the upgrade after going back. The second attempt doesn't copy your disk again — it reuses the copy the first one made, so anything you wrote between the two is left behind. If you still want the newer storage after a rollback, move to a new Sprite instead, as below. +Don't repeat the upgrade after going back. The second attempt doesn't copy your disk again — it reuses the copy the first one made, so anything you wrote between the two is left behind. If you still want the newer storage after a rollback, create a new Sprite and copy your data across instead. If you've already done it and files are missing, stop writing to the Sprite and contact support. Nothing has been deleted — the work from in between is still on the older storage. - -### Moving to a new Sprite instead - -There's a second route: create a new Sprite, which already uses the newer storage, and copy your data across. You get a new name and URL, and you recreate your services and configuration by hand. In exchange, nothing about your existing Sprite changes, your old checkpoints stay reachable on it, and you cut over when you're ready with no deadline. - -Stop your services on the old Sprite first, then copy your data out and back in: - -```bash -sprite create my-new-sprite - -sprite file pull -r -s my-sprite /home/sprite/app . -sprite file push -r -s my-new-sprite ./app /home/sprite/app -``` - -Only the paths you name come across. To see what else you'll need to set up again: - -```bash -sprite exec -s my-sprite -- sprite-env services list -``` - -Recreate each one on the new Sprite with `sprite-env services create`. Environment variables and other configuration don't copy either. - -Test the new Sprite while the old one is still running, then move whatever points at the old URL. Keep the old Sprite until you're satisfied — it's your rollback, and it has no deadline on it. From 9daea20e7038c402617df506153b56a06c02244b Mon Sep 17 00:00:00 2001 From: Jon Phenow Date: Fri, 9 Oct 2026 20:52:05 +0000 Subject: [PATCH 07/11] Warn that a new Sprite has no labels, so connectors deny it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The new-Sprite route loses more than files and services. Connectors are organization-scoped, so they do not need recreating — but their access policy picks Sprites by name prefix and by label and is deny-by-default, so a Sprite with a new name and no labels matches nothing and cannot reach any connector. That makes labels the load-bearing part rather than an afterthought, and the fix is usually one flag on create, so the warning gives it. Name-prefix policies need the new name to match the prefix, or the policy widened, which is noted rather than solved. Claude-Session: https://claude.ai/code/session_01JvqUYVtkXDQ5m4n5vaH9sr --- sprite-maintenance.mdx | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/sprite-maintenance.mdx b/sprite-maintenance.mdx index bda4997..a49d797 100644 --- a/sprite-maintenance.mdx +++ b/sprite-maintenance.mdx @@ -102,6 +102,18 @@ sprite exec -s my-sprite -- sprite-env services list Recreate each one on the new Sprite with `sprite-env services create`. Environment variables and other configuration don't copy either. + +**Labels don't come with you, and [connector](/concepts/connectors) access usually depends on them.** A connector's access policy picks Sprites by name prefix and by label, and it's deny-by-default — so a new Sprite with a new name and no labels can't reach any of your connectors until it matches a policy. + +Give it the same labels as the old Sprite, either when you create it or afterwards: + +```bash +sprite create my-new-sprite --label github --label production +``` + +If the policy matched on name prefix instead, the new name has to match that prefix too, or you update the policy to include it. + + Test the new Sprite while the old one is still running, then move whatever points at the old URL. Keep the old Sprite until you're satisfied — it's your rollback, and it has no deadline on it. ### Upgrading in place From 769504a2d6a9fef6cec0ea5447b538b99716053f Mon Sep 17 00:00:00 2001 From: Jon Phenow Date: Sat, 10 Oct 2026 01:20:15 +0000 Subject: [PATCH 08/11] Apply Kristin's copy edits MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All 21 suggestions from the review, taken as written. The substantive ones: the intro now says plainly that existing Sprites are not upgraded automatically and the upgrade has to be requested; the two routes are introduced as a recommendation rather than a characterisation of risk; "Going back" is "Rolling back"; and the detection step leads with what the reader is doing rather than with the Sprite being asked. The rest tighten wording throughout — second person, shorter clauses, and the benefit bullets stated as outcomes rather than mechanisms. Claude-Session: https://claude.ai/code/session_01JvqUYVtkXDQ5m4n5vaH9sr --- sprite-maintenance.mdx | 44 ++++++++++++++++++++++-------------------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/sprite-maintenance.mdx b/sprite-maintenance.mdx index a49d797..2ba749b 100644 --- a/sprite-maintenance.mdx +++ b/sprite-maintenance.mdx @@ -48,20 +48,20 @@ sudo apt full-upgrade ## Storage Upgrades -Your Sprite's disk can run on a newer storage system than the one it was created with. Newer Sprites already use it. Upgrading is something you ask for — nothing moves your Sprite on its own. +You can upgrade an existing Sprite with a newer storage system than the one it was created with. New Sprites already use it, but existing Sprites won't be upgraded automatically. You need to request the upgrade. After upgrading: -- **Reads and writes get faster.** Recently used data is served from a cache on the host instead of being fetched from object storage each time. -- **Checkpoints get faster.** A checkpoint becomes a marker against your disk rather than a copy of it, so taking one is quick and uses almost no extra space. -- **Restores get faster.** A restore switches your disk back to the checkpoint instead of downloading it, so it finishes in about the time a restart takes. +- **Reads and writes get faster.** Frequently accessed data is cached on the host instead of fetched from object storage on every request. +- **Checkpoints get faster.** Checkpoints mark a point in your disk's history instead of copying the disk, so they're quick to create and use very little additional space. +- **Restores get faster.** Restoring a checkpoint takes about as long as restarting your Sprite, rather than waiting for a disk download. - **Fewer interruptions.** Short-lived storage problems are much less likely to reach your Sprite. -You're not obliged to upgrade, and nothing stops working if you don't. The trade-off is updates: new Sprite runtime builds target the newer storage, so a Sprite that stays where it is picks up new versions less and less often. The older storage will eventually be retired. +You don't have to upgrade right away. Your Sprite will keep working on the older storage system, but new runtime versions increasingly target the newer one. Eventually, we'll retire the older storage system. ### Checking whether a Sprite needs it -Ask the Sprite directly: +To check which storage system your Sprite uses, run: ```bash sprite exec -- printenv SPRITE_STORAGE_DRIVER @@ -77,13 +77,13 @@ sprite list -o my-org | while read -r s; do done ``` -There are two ways across. Moving to a new Sprite is the safer one and the place to start. Upgrading in place is less work, and it's the one with something to go wrong. +You have two options for moving to the newer storage system. We recommend creating a new Sprite and copying your data over. This leaves your existing Sprite untouched, so you can switch back if something goes wrong. Upgrading in place is simpler, but carries more risk. ### Moving to a new Sprite -Create a new Sprite, which already uses the newer storage, and copy your data across. Nothing about your existing Sprite changes, so there's no moment where you're committed to an outcome you haven't seen yet: no disk conversion runs, your old checkpoints stay restorable on the old Sprite, and if you don't like the result you keep using the one you already have. +Create a new Sprite, which already uses the newer storage system, and copy your data over. Your existing Sprite stays untouched, including its checkpoints. If something goes wrong or you're not happy with the result, you can keep using your original Sprite. -The cost is a new name and URL, and setting your services and configuration up again by hand. +The trade-off is that your new Sprite gets a different name and URL, and you'll need to recreate your services and configuration manually. Stop your services on the old Sprite first, then copy your data out and back in: @@ -100,10 +100,10 @@ Only the paths you name come across. To see what else you'll need to set up agai sprite exec -s my-sprite -- sprite-env services list ``` -Recreate each one on the new Sprite with `sprite-env services create`. Environment variables and other configuration don't copy either. +Recreate each service on the new Sprite using sprite-env services create. You'll also need to copy over your environment variables and any other configuration. -**Labels don't come with you, and [connector](/concepts/connectors) access usually depends on them.** A connector's access policy picks Sprites by name prefix and by label, and it's deny-by-default — so a new Sprite with a new name and no labels can't reach any of your connectors until it matches a policy. +**Your new Sprite might lose access to [connectors](/concepts/connectors)** Connector access policies match Sprites by name prefix or label, and deny access by default. Since your new Sprite has a different name and doesn't inherit labels, check that it matches the policies for any connectors it needs to access. Give it the same labels as the old Sprite, either when you create it or afterwards: @@ -114,7 +114,7 @@ sprite create my-new-sprite --label github --label production If the policy matched on name prefix instead, the new name has to match that prefix too, or you update the policy to include it. -Test the new Sprite while the old one is still running, then move whatever points at the old URL. Keep the old Sprite until you're satisfied — it's your rollback, and it has no deadline on it. +Test the new Sprite while the original is still running. Once you're satisfied, update anything that uses the old Sprite's URL. Keep the original Sprite as a fallback for as long as you need it. ### Upgrading in place @@ -127,10 +127,10 @@ If something you need exists only inside an old checkpoint, restore it and copy -Running the upgrade on a Sprite that didn't need it does no harm. With nothing to convert it becomes an ordinary version upgrade: one restart, no copy. So if the check above is ambiguous, run it rather than investigating further. +If your Sprite already uses the newer storage system, running the upgrade just updates the Sprite's runtime version. There's no data migration, but your Sprite will restart. If you're unsure which storage system your Sprite uses, you can run the upgrade without checking first. -If it would put your mind at ease, copy anything that matters to your own machine first: +For extra peace of mind, you can back up important files to your local machine before upgrading: ```bash sprite file pull -r -p -s my-sprite /home/sprite/app ./sprite-backup @@ -138,7 +138,7 @@ sprite file pull -r -p -s my-sprite /home/sprite/app ./sprite-backup Stop your services first if you can. Files copied while something is writing to them can be captured half-finished. -Then write down the version your Sprite is on. This is the one thing you can't recover later: once the upgrade is accepted, this field reports the version you moved *to*, and nothing records the one you came from. You need it to go back. +Before upgrading, record your Sprite's current version. Once the upgrade is accepted, the version field shows the new version, and the previous one isn't recorded. You'll need the original version number if you want to roll back. ```bash sprite api /v1/sprites/my-sprite -- --silent | jq -r .version @@ -152,7 +152,7 @@ sprite api -s my-sprite /upgrade -- \ -d '{"allow_storage_migration": true}' ``` -This stays in the foreground for the whole upgrade and prints one line per step, finishing with a line of type `completed` or `failed`. The `-N` matters: without it nothing prints until the end, and a several-minute upgrade looks like a command that has hung. +The command runs in the foreground and prints progress as each step completes, ending with a `completed` or `failed` event. The `-N` flag disables output buffering so you can see progress as it happens. Without it, you won't see any output until the upgrade finishes, which can take several minutes. The `allow_storage_migration` flag is required, and that's deliberate. Without it, an upgrade that would change your storage is refused. Routine upgrades never move you; only this explicit request does. @@ -162,11 +162,13 @@ If the response says `no upgrade is published for this sprite's release lane`, y When your Sprite comes back, check that your application serves traffic, that your files are where you left them, and that a new checkpoint succeeds. Take that checkpoint once you're satisfied — it becomes your first restore point on the new storage. -An upgrade that fails leaves your original disk untouched. The copy is written separately and only becomes your active disk at the last step, so a failure part way through can't damage what you had. If your Sprite doesn't come back, or comes back wrong, stop writing to it — anything written after a failed upgrade makes recovery messier. +The upgrade copies your disk separately and switches to the new disk only at the final step. If the upgrade fails before that switch, your original disk remains untouched. -### Going back +If your Sprite doesn't restart successfully or something looks wrong afterward, stop writing to it. Additional writes can complicate recovery. -The same call, with the version you wrote down and the same flag. The storage check refuses a mismatch in either direction, so going back needs the flag whose name sounds like the opposite: +### Rolling back + +To roll back, use the same upgrade command with the version you recorded earlier. You'll also need the same flag to bypass the storage compatibility check, which applies to both upgrades and rollbacks: ```bash sprite api -s my-sprite /upgrade -- \ @@ -177,7 +179,7 @@ sprite api -s my-sprite /upgrade -- \ You return to your disk as it was at the moment of the upgrade. Anything written after it doesn't come back with you, so the sooner you decide, the less you lose. -Don't repeat the upgrade after going back. The second attempt doesn't copy your disk again — it reuses the copy the first one made, so anything you wrote between the two is left behind. If you still want the newer storage after a rollback, create a new Sprite and copy your data across instead. +Don't run the upgrade again after rolling back. A second upgrade reuses the disk copy from the first attempt instead of copying your current disk, so you'll lose any changes made since the rollback. If you still want to move to the newer storage system, create a new Sprite and copy your data over instead. -If you've already done it and files are missing, stop writing to the Sprite and contact support. Nothing has been deleted — the work from in between is still on the older storage. +If you've already run the upgrade again and files are missing, stop writing to the Sprite and contact Support. Your data hasn't been deleted; changes made between the two upgrades are still on the older storage system. From 9e43d2c1e16a01c550842f089b4dbab902507613 Mon Sep 17 00:00:00 2001 From: Jon Phenow Date: Sat, 10 Oct 2026 01:20:25 +0000 Subject: [PATCH 09/11] Restore a period and code formatting lost in the suggestions Two mechanical slips rather than wording choices, so they are separate from the copy edits and can be dropped on their own. The connectors warning lost the period that closes its bold lead-in, which every other callout on the page has. And `sprite-env services create` lost its backticks, leaving a command rendered as prose. Claude-Session: https://claude.ai/code/session_01JvqUYVtkXDQ5m4n5vaH9sr --- sprite-maintenance.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sprite-maintenance.mdx b/sprite-maintenance.mdx index 2ba749b..390c9a7 100644 --- a/sprite-maintenance.mdx +++ b/sprite-maintenance.mdx @@ -100,10 +100,10 @@ Only the paths you name come across. To see what else you'll need to set up agai sprite exec -s my-sprite -- sprite-env services list ``` -Recreate each service on the new Sprite using sprite-env services create. You'll also need to copy over your environment variables and any other configuration. +Recreate each service on the new Sprite using `sprite-env services create`. You'll also need to copy over your environment variables and any other configuration. -**Your new Sprite might lose access to [connectors](/concepts/connectors)** Connector access policies match Sprites by name prefix or label, and deny access by default. Since your new Sprite has a different name and doesn't inherit labels, check that it matches the policies for any connectors it needs to access. +**Your new Sprite might lose access to [connectors](/concepts/connectors).** Connector access policies match Sprites by name prefix or label, and deny access by default. Since your new Sprite has a different name and doesn't inherit labels, check that it matches the policies for any connectors it needs to access. Give it the same labels as the old Sprite, either when you create it or afterwards: From c5d905f8a1a7c84201c53716a89ee63d9d20b6a5 Mon Sep 17 00:00:00 2001 From: Jon Phenow Date: Sat, 10 Oct 2026 02:48:01 +0000 Subject: [PATCH 10/11] List only the Sprites that need upgrading The old snippet piped sprite list into while read, so the loop's stdin was the list itself and sprite exec attached and drained it: the first Sprite consumed every remaining name and only one line of output appeared. A for loop keeps stdin on the terminal, so exec attaches nothing and no redirect is needed. Run the remote side as sh -c 'echo $SPRITE_STORAGE_DRIVER' rather than printenv, which exits 1 when the variable is unset and made sprite exec print "Error: exit status 1" for exactly the Sprites being looked for. Print the Sprites that need the upgrade instead of every Sprite's driver. Claude-Session: https://claude.ai/code/session_01JvqUYVtkXDQ5m4n5vaH9sr --- sprite-maintenance.mdx | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/sprite-maintenance.mdx b/sprite-maintenance.mdx index 390c9a7..6719c4c 100644 --- a/sprite-maintenance.mdx +++ b/sprite-maintenance.mdx @@ -69,14 +69,18 @@ sprite exec -- printenv SPRITE_STORAGE_DRIVER If that prints `sbd`, you're already on the newer storage and there's nothing to do. Anything else, or nothing at all, means the Sprite hasn't been upgraded yet. -To check a whole organization at once: +To list the Sprites in an organization that still need the upgrade: ```bash -sprite list -o my-org | while read -r s; do - printf '%s\t%s\n' "$s" "$(sprite exec -o my-org -s "$s" -- printenv SPRITE_STORAGE_DRIVER 2>/dev/null)" +for s in $(sprite list -o my-org); do + d=$(sprite exec -o my-org -s "$s" -- sh -c 'echo $SPRITE_STORAGE_DRIVER') + [ "$d" = sbd ] || echo "$s" done ``` +Each check starts the Sprite if it isn't already running, so this takes a few seconds per +Sprite. Anything it prints either needs the upgrade or couldn't be reached. + You have two options for moving to the newer storage system. We recommend creating a new Sprite and copying your data over. This leaves your existing Sprite untouched, so you can switch back if something goes wrong. Upgrading in place is simpler, but carries more risk. ### Moving to a new Sprite From 3363495f1488a8aa3d5ba34982165403a501f155 Mon Sep 17 00:00:00 2001 From: Jon Phenow Date: Sat, 10 Oct 2026 02:52:42 +0000 Subject: [PATCH 11/11] Use the same storage check for one Sprite MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit printenv exits 1 when the variable is unset, so the first command in the section greeted a JuiceFS Sprite — the reader it is written for — with "Error: exit status 1" and no value. Match the organization-wide loop. Claude-Session: https://claude.ai/code/session_01JvqUYVtkXDQ5m4n5vaH9sr --- sprite-maintenance.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sprite-maintenance.mdx b/sprite-maintenance.mdx index 6719c4c..3b2f4fe 100644 --- a/sprite-maintenance.mdx +++ b/sprite-maintenance.mdx @@ -64,7 +64,7 @@ You don't have to upgrade right away. Your Sprite will keep working on the older To check which storage system your Sprite uses, run: ```bash -sprite exec -- printenv SPRITE_STORAGE_DRIVER +sprite exec -- sh -c 'echo $SPRITE_STORAGE_DRIVER' ``` If that prints `sbd`, you're already on the newer storage and there's nothing to do. Anything else, or nothing at all, means the Sprite hasn't been upgraded yet.