Skip to content

Commit d434ecb

Browse files
committed
Migrate legacy deployment assets to scoped R2.
1 parent 206ae25 commit d434ecb

18 files changed

Lines changed: 2626 additions & 506 deletions

File tree

‎docs/guide/platform/administration/operations.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,30 @@ Following waits for the final logs before stopping, including diagnostics writte
5151

5252
## Checking the Platform
5353

54+
### Migrating older deployment assets
55+
56+
After upgrading the platform, inspect every page of its asset inventory:
57+
58+
```sh
59+
void platform system asset-migrations --page 1 --limit 100
60+
void platform deployment migrate-assets <deployment-id> --plan
61+
void platform deployment migrate-assets <deployment-id> --yes
62+
```
63+
64+
Migrate every deployment with a nonzero `needsMigration` count, including retained
65+
rollback targets and stored Worker bundles. Investigate entries marked `invalid`
66+
before continuing. The command verifies each copied asset, preserves originals,
67+
and applies successive batches. If interrupted, inspect the result and resume
68+
with the last successful `nextCursor` using `--cursor`; restarting without a
69+
cursor also verifies and reuses completed copies.
70+
71+
Run the inventory again across all pages when finished. Existing applications
72+
continue serving during this migration, and the provider asset mirror remains.
73+
Legacy reads remain available while older platform runtimes and cached manifests
74+
can still reference original assets.
75+
76+
### Health checks
77+
5478
Use the overview to see recent activity, or run a health check to test the platform's services and database:
5579

5680
```sh

‎docs/reference/cli.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -660,10 +660,17 @@ Find a deployment, inspect its manifest, or request cancellation:
660660
void platform deployment list [--project <id-or-slug>] [--status <status>] [--search <text>] [--page <n>] [--limit <n>]
661661
void platform deployment show <id>
662662
void platform deployment cancel <id>
663+
void platform deployment migrate-assets <id> [--cursor <cursor>] [--plan|--yes]
663664
```
664665

665666
Cancellation applies while a deployment is pending, uploading, migrating, or prerendering, and can be requested again while it is canceling. A deployment that has begun switching traffic, is compensating for a failure, or has finished cannot be canceled through this command.
666667

668+
`migrate-assets` copies legacy assets to scoped R2 storage, verifies their contents, and updates each batch only after all its assets are verified. Original assets remain in place, and application traffic stays on the same deployment. Upgrade the platform runtime before using this command. Migrate both active deployments and retained rollback deployments before removing support for older asset storage.
669+
670+
Use `--plan` to preview the first batch. Applying authorizes all remaining batches for that deployment; the CLI previews each batch and prints its result, including `nextCursor`. With `--json`, results are JSON Lines. If a later batch fails or the command is interrupted, resume with the cursor from the last successful result. An ambiguous request is never retried automatically; inspect the deployment before resuming. A completed migration reports `complete: true` and `nextCursor: null`.
671+
672+
Use [`void platform system asset-migrations`](#operator-system) to find deployments requiring migration. Inspect every inventory page, migrate each deployment with `needsMigration` greater than zero, then inspect every page again. Include retained rollback deployments and stored bundles. Investigate rows marked `invalid` before considering migration complete. Keep the older asset readers until the full inventory is valid and no protected deployment needs migration.
673+
667674
Read its runtime logs with:
668675

669676
```sh
@@ -791,13 +798,16 @@ Inspect activity, check service health, or review administrative changes:
791798
void platform system overview
792799
void platform system health
793800
void platform system cli-versions
801+
void platform system asset-migrations [--page <n>] [--limit <n>]
794802
void platform system events [--page <n>] [--limit <n>]
795803
void platform system backfill-queue-tokens
796804
void platform system sandbox-drain [--cursor <opaque-cursor>]
797805
```
798806

799807
`overview` shows platform totals and recent activity. `health` checks the configured services and database, and exits with a nonzero status if a check fails. `cli-versions` reports the CLI versions used by deployments.
800808

809+
`asset-migrations` inventories active deployments, retained rollback deployments, and deployments with stored bundles. It reports their asset counts, `needsMigration`, and an `invalid` flag for unreadable metadata. Read all pages using the response's pagination fields. Migrate each deployment with `needsMigration` greater than zero through [`deployment migrate-assets`](#operator-deployments), then rerun the full inventory. Migration keeps the original assets; removing those assets or their older readers requires separate verification.
810+
801811
`events` shows the administrator, target, and outcome of changes. A pending event means the outcome has not been recorded. Previews and session login/logout do not create these events. `backfill-queue-tokens` repairs older queue entries that are missing authentication tokens and supports `--plan` before applying the repair.
802812

803813
Use `sandbox-drain` when an upgrade from the legacy tenant-owned Sandbox runtime asks you to finish cleanup. Preview with `--plan`; pass the returned `nextCursor` as `--cursor` to inspect later pages. Apply with `--yes` and rerun until it reports `complete: true`, then rerun the interrupted upgrade. Application traffic stays paused during cleanup, while administrator login remains available. The completed upgrade enables the current managed Sandbox controller automatically.

‎packages/void/skills/void/SKILL.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,8 @@ For Void platform project access, use `void project team`: invite only an email
7979

8080
For a self-hosted platform's project Zero Trust policy, installation administrators use `void platform zero-trust`; pass the Access management token only through `--token-stdin`. Project owners and project administrators use `void project zero-trust status|protect|public|reconcile`; these commands do not apply to direct Cloudflare deployments. When a deploy or rollback is refused because protection is not settled, check `void project zero-trust status`; an owner or project administrator can run `void project zero-trust reconcile` before retrying.
8181

82+
For older platform asset storage, administrators inspect every page with `void platform system asset-migrations`, preview each affected deployment with `void platform deployment migrate-assets <id> --plan`, and apply with `--yes`. Include retained rollback targets and stored Worker bundles; investigate `invalid` inventory rows. Migration verifies copies, preserves originals, and supports `--cursor` from the last successful batch. Keep legacy reads until the full inventory and serving checks are complete.
83+
8284
Use Void commands for every user-facing workflow. Never ask the user to install, authenticate, or run Wrangler directly. Say Cloudflare or Void instead, except when naming literal `wrangler.jsonc` / `wrangler.json` files or `WRANGLER_*` environment variables the user must inspect.
8385

8486
`void auth login|status|logout` follows the saved deploy destination or asks the user to choose; `void account` explicitly manages a Void platform account. If updating Void stops recognizing an older login, run `void account login` again; preserve the saved platform and project links.

‎packages/void/src/cli/operator-args.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -214,6 +214,15 @@ export const operatorCommands: Array<OperatorCommand> = [
214214
positional: ['id'],
215215
method: 'POST',
216216
},
217+
{
218+
group: 'deployment',
219+
action: 'migrate-assets',
220+
description: 'Copy and verify legacy deployment assets in scoped R2 storage',
221+
path: '/deployments/:id/migrate-assets',
222+
positional: ['id'],
223+
values: { cursor: 'Resume from the last successful asset migration cursor' },
224+
method: 'POST',
225+
},
217226
{
218227
group: 'deployment',
219228
action: 'logs',
@@ -327,6 +336,13 @@ export const operatorCommands: Array<OperatorCommand> = [
327336
description: 'Inspect CLI version adoption and deployment statistics',
328337
path: '/system/cli-versions',
329338
},
339+
{
340+
group: 'system',
341+
action: 'asset-migrations',
342+
description: 'Inventory legacy assets in active and retained deployments',
343+
path: '/system/asset-migrations',
344+
values: { page: 'One-based page number', limit: 'Maximum 100 records per page' },
345+
},
330346
{
331347
group: 'system',
332348
action: 'events',

‎packages/void/src/cli/operator-cmd.ts‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -483,6 +483,86 @@ export async function followOperatorLogs(
483483
}
484484
}
485485

486+
async function migrateDeploymentAssets(
487+
client: OperatorClient,
488+
origin: string,
489+
args: OperatorArgs,
490+
): Promise<void> {
491+
const target = decodeURIComponent(
492+
args.path.slice('/deployments/'.length, -'/migrate-assets'.length),
493+
);
494+
const seenCursors = new Set<string>();
495+
let body = { ...args.body };
496+
if (typeof body.cursor === 'string') {
497+
seenCursors.add(body.cursor);
498+
}
499+
let authorized = false;
500+
while (true) {
501+
const preview = await client.request(args.path, {
502+
method: 'POST',
503+
body: { ...body, dryRun: true },
504+
timeoutMs: args.timeoutMs,
505+
});
506+
if (
507+
preview.dryRun !== true ||
508+
preview.action !== 'deployment.migrate-assets' ||
509+
preview.target !== target ||
510+
typeof preview.expected !== 'string' ||
511+
!preview.expected.trim()
512+
) {
513+
throw new OperatorClientError(
514+
'The server did not return a valid asset migration preview. No asset batch was requested.',
515+
'invalid_preview',
516+
);
517+
}
518+
if (
519+
!(await confirmOperatorMutation(
520+
origin,
521+
{
522+
...preview,
523+
scope:
524+
'Copy and verify all remaining asset batches for this deployment; keep original assets.',
525+
},
526+
authorized ? { ...args, yes: true } : args,
527+
))
528+
) {
529+
return;
530+
}
531+
authorized = true;
532+
// Each batch is pinned to its own preview. Failed or ambiguous writes are never retried.
533+
const result = await client.request(args.path, {
534+
method: 'POST',
535+
body: { ...body, expected: preview.expected },
536+
timeoutMs: args.timeoutMs,
537+
});
538+
const nextCursor = result.nextCursor;
539+
if (
540+
result.dryRun !== false ||
541+
result.action !== 'deployment.migrate-assets' ||
542+
result.target !== target ||
543+
typeof result.complete !== 'boolean' ||
544+
(result.complete
545+
? nextCursor !== null
546+
: typeof nextCursor !== 'string' || !nextCursor.trim() || seenCursors.has(nextCursor))
547+
) {
548+
throw new OperatorClientError(
549+
'The server returned an invalid asset migration continuation. Inspect the deployment before resuming; no batch was retried.',
550+
'invalid_response',
551+
undefined,
552+
{ target, lastSuccessfulCursor: body.cursor ?? null, result },
553+
);
554+
}
555+
// Preserve each successful continuation in stdout if a later batch fails or is interrupted.
556+
output(result, args.json);
557+
if (result.complete) {
558+
return;
559+
}
560+
const cursor = nextCursor as string;
561+
seenCursors.add(cursor);
562+
body = { ...args.body, cursor };
563+
}
564+
}
565+
486566
export async function runOperatorCommand(args: OperatorArgs): Promise<void> {
487567
if (!args.action) {
488568
const { printHelpPage } = await import('./help.ts');
@@ -502,6 +582,9 @@ export async function runOperatorCommand(args: OperatorArgs): Promise<void> {
502582
'confirmation_required',
503583
);
504584
}
585+
if (args.group === 'deployment' && args.action === 'migrate-assets') {
586+
return migrateDeploymentAssets(client, origin, args);
587+
}
505588
// Read once for preview and apply; the server excludes the token from audit output.
506589
if (
507590
args.tokenStdin &&
@@ -553,6 +636,20 @@ export async function runOperatorCommand(args: OperatorArgs): Promise<void> {
553636
const result = await client.request(args.path, { query: args.query });
554637
if (args.action === 'logs' && args.group !== 'email') {
555638
outputLogs(result, args.json);
639+
} else if (
640+
args.group === 'system' &&
641+
args.action === 'asset-migrations' &&
642+
!args.json &&
643+
Array.isArray(result.deployments)
644+
) {
645+
// Keep every migration count and protection flag visible without table truncation.
646+
console.log(
647+
[
648+
...humanLines({ pagination: result.pagination }),
649+
'deployments:',
650+
...eventLines(result.deployments, ' '),
651+
].join('\n'),
652+
);
556653
} else {
557654
output(result, args.json);
558655
}

0 commit comments

Comments
 (0)