@intentius/chant-lexicon-fly 0.124.67 → 0.124.68

package/src/components/fly-release.test.ts

@@ -491,3 +491,234 @@ describe("fly-release with a scheduled Machine (#4696)", () => {
     expect(s.fake.calls.some((c) => c.startsWith("POST"))).toBe(false);
   });
 });
+
+/**
+ * #4719: two serving Machines behind Flycast with Fly checks, as Arugula's
+ * platform runs. The release rolls them one at a time on their checks,
+ * verifies both, and on a failure puts back each one it changed.
+ */
+describe("fly-release over serving Machines with Fly checks (#4719)", () => {
+  const CHECKED = { services: [{ internal_port: 8080, protocol: "tcp", checks: [{ type: "http", port: 8080, path: "/platform.json", method: "GET" }] }] };
+  const machine = (name: string, extra: Record<string, unknown> = CHECKED) => ({
+    endpoint: "/v1/apps/shop/machines",
+    method: "POST",
+    body: { name, config: { image: "shop:declared", metadata: { "managed-by": "chant" }, ...extra } },
+  });
+  const writePlan = (plan: Record<string, unknown>) => writeFileSync(planPath, JSON.stringify(plan));
+  const CHECK = "servicecheck-00-http-8080";
+  const FAST = { intervalMs: 1, timeoutMs: 50 };
+
+  /**
+   * A fake whose Machines report one check: critical for the first few reads
+   * of each new instance, then passing, unless `healthy` says the Machine
+   * cannot pass at all. `events` holds each Machine create and update and
+   * the first passing read of each instance, in order.
+   */
+  function checkedFake(healthy: (m: { name: string; config: Record<string, unknown> }) => boolean = () => true, opts: { exec?: () => void } = {}) {
+    const events: string[] = [];
+    const reads = new Map<string, number>();
+    const fake = createMachinesFake({
+      exec: () => {
+        opts.exec?.();
+        return { exit_code: 0 };
+      },
+      checks: (_app, m) => {
+        if (!declares(m.config)) return undefined;
+        if (!healthy(m)) return [{ name: CHECK, status: "critical", output: "503 Service Unavailable" }];
+        const n = (reads.get(m.instance_id) ?? 0) + 1;
+        reads.set(m.instance_id, n);
+        if (n < 3) return [{ name: CHECK, status: "critical", output: "503 Service Unavailable" }];
+        if (n === 3) events.push(`passing ${m.name}`);
+        return [{ name: CHECK, status: "passing" }];
+      },
+    });
+    const http = fake.http;
+    fake.http = async (method, url, body, headers, signal) => {
+      const path = new URL(url).pathname.split("/");
+      // POST /v1/apps/<app>/machines/<id>: an update of that Machine.
+      if (method === "POST" && path.length === 6 && path[4] === "machines") {
+        const m = [...fake.machines.values()].flat().find((x) => x.id === path[5]);
+        events.push(`update ${m?.name}`);
+      }
+      // POST /v1/apps/<app>/machines: a new Machine.
+      if (method === "POST" && path.length === 5 && path[4] === "machines") events.push(`create ${(body as { name?: string }).name}`);
+      return http(method, url, body, headers, signal);
+    };
+    return { fake, events };
+  }
+  const declares = (config: Record<string, unknown>) => Array.isArray(config.services) && config.services.length > 0;
+
+  test("rolls the Machines one at a time: the second is updated only once the first passes its checks", async () => {
+    writePlan({ shop: PLAN.shop, web: machine("web"), web2: machine("web2") });
+    const { fake, events } = checkedFake();
+    const s = setup(fake);
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { machine: "web", image: "shop:1", images: { web2: "shop:1" }, checks: FAST }));
+    events.length = 0;
+
+    await s.release.run(CTX, input("sha256:bbbbbbbbbbbb", { machine: "web", image: "shop:2", images: { web2: "shop:2" }, checks: FAST }));
+    expect(events).toEqual(["update web", "passing web", "update web2", "passing web2"]);
+    expect(s.fake.machine("shop", "web")!.config.image).toBe("shop:2");
+    expect(s.fake.machine("shop", "web2")!.config.image).toBe("shop:2");
+  });
+
+  test("a Machine whose checks never pass times out, restores every Machine it updated in reverse order, and names the Machine and check", async () => {
+    writePlan({ shop: PLAN.shop, web: machine("web"), web2: machine("web2") });
+    // web2 cannot pass on the new image.
+    const { fake, events } = checkedFake((m) => !(m.name === "web2" && m.config.image === "shop:2"));
+    const s = setup(fake);
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { machine: "web", image: "shop:1", images: { web2: "shop:1" }, checks: FAST }));
+    const web = structuredClone(fake.machine("shop", "web")!.config);
+    const web2 = structuredClone(fake.machine("shop", "web2")!.config);
+    events.length = 0;
+    s.lines.length = 0;
+
+    await expect(
+      s.release.run(CTX, input("sha256:bbbbbbbbbbbb", { machine: "web", image: "shop:2", images: { web2: "shop:2" }, checks: FAST })),
+    ).rejects.toThrow(/^machine shop\/web2 \(m[0-9a-f]+\) did not pass its Fly checks within 50ms: check servicecheck-00-http-8080 is critical \(503 Service Unavailable\)$/);
+    expect(fake.machine("shop", "web")!.config).toEqual(web);
+    expect(fake.machine("shop", "web2")!.config).toEqual(web2);
+    // Last updated, first restored; each restore waits for its Machine's checks.
+    expect(events).toEqual(["update web", "passing web", "update web2", "update web2", "passing web2", "update web", "passing web"]);
+    expect(s.lines.filter((l) => l.includes("restore"))).toEqual([
+      "fly-release: restored shop/web2 to its previous config",
+      "fly-release: restored shop/web to sha256:aaaaaaaaaaaa",
+    ]);
+    expect(await s.configs.read({ app: "shop", machine: "web", digest: "sha256:bbbbbbbbbbbb" })).toBeUndefined();
+  });
+
+  test("a serving Machine whose checks never pass is restored before the next Machine is touched", async () => {
+    writePlan({ shop: PLAN.shop, web: machine("web"), web2: machine("web2") });
+    const { fake, events } = checkedFake((m) => !(m.name === "web" && m.config.image === "shop:2"));
+    const s = setup(fake);
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { machine: "web", image: "shop:1", images: { web2: "shop:1" }, checks: FAST }));
+    events.length = 0;
+    await expect(
+      s.release.run(CTX, input("sha256:bbbbbbbbbbbb", { machine: "web", image: "shop:2", images: { web2: "shop:2" }, checks: FAST })),
+    ).rejects.toThrow(/machine shop\/web .* check servicecheck-00-http-8080 is critical/);
+    expect(events).toEqual(["update web", "update web", "passing web"]);
+    expect(fake.machine("shop", "web")!.config.image).toBe("shop:1");
+    expect(fake.machine("shop", "web2")!.config.image).toBe("shop:1");
+  });
+
+  test("a check still passing from before the update does not count: the roll waits for one reported since", async () => {
+    writePlan({ shop: PLAN.shop, web: machine("web"), web2: machine("web2") });
+    const events: string[] = [];
+    const reads = new Map<string, number>();
+    // The first reads of each new instance carry the old instance's passing
+    // status, stamped before the update; then a fresh one arrives.
+    const fake = createMachinesFake({
+      checks: (_app, m) => {
+        const n = (reads.get(m.instance_id) ?? 0) + 1;
+        reads.set(m.instance_id, n);
+        if (n <= 3) return [{ name: CHECK, status: "passing", updated_at: "2000-01-01T00:00:00.000Z" }];
+        if (n === 4) events.push(`fresh ${m.name}`);
+        return [{ name: CHECK, status: "passing", updated_at: m.updated_at }];
+      },
+    });
+    const http = fake.http;
+    fake.http = async (method, url, body, headers, signal) => {
+      const path = new URL(url).pathname.split("/");
+      if (method === "POST" && path.length === 6 && path[4] === "machines") {
+        events.push(`update ${[...fake.machines.values()].flat().find((x) => x.id === path[5])?.name}`);
+      }
+      return http(method, url, body, headers, signal);
+    };
+    const s = setup(fake);
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { machine: "web", image: "shop:1", images: { web2: "shop:1" }, checks: FAST }));
+    events.length = 0;
+    await s.release.run(CTX, input("sha256:bbbbbbbbbbbb", { machine: "web", image: "shop:2", images: { web2: "shop:2" }, checks: FAST }));
+    expect(events).toEqual(["update web", "fresh web", "update web2", "fresh web2"]);
+
+    // A check that never reports again times out, saying so.
+    const stuck = createMachinesFake({ checks: () => [{ name: CHECK, status: "passing", updated_at: "2000-01-01T00:00:00.000Z" }] });
+    const t = setup(stuck);
+    await expect(t.release.run(CTX, input("sha256:aaaaaaaaaaaa", { machine: "web", image: "shop:1", images: { web2: "shop:1" }, checks: FAST }))).rejects.toThrow(
+      /machine shop\/web .* did not pass its Fly checks within 50ms: check servicecheck-00-http-8080 has not reported since the update at .* \(last at 2000-01-01T00:00:00.000Z\)/,
+    );
+  });
+
+  test("without checks, the release waits for started only, as before #4719, even with checks failing", async () => {
+    writePlan({ shop: PLAN.shop, web: machine("web"), web2: machine("web2") });
+    const { fake, events } = checkedFake(() => false);
+    const s = setup(fake);
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { machine: "web", image: "shop:1", images: { web2: "shop:1" } }));
+    events.length = 0;
+    const out = await s.release.run(CTX, input("sha256:bbbbbbbbbbbb", { machine: "web", image: "shop:2", images: { web2: "shop:2" } }));
+    expect(out.digest).toBe("sha256:bbbbbbbbbbbb");
+    expect(events).toEqual(["update web", "update web2"]);
+  });
+
+  test("without checks, an apply that fails partway restores the Machines it had already updated", async () => {
+    writePlan({ shop: PLAN.shop, web: machine("web", {}), web2: machine("web2", {}) });
+    // web2 never starts on the new image.
+    const fake = createMachinesFake({ settle: (m) => (m.name === "web2" && m.config.image === "shop:2" ? "failed" : "started") });
+    const s = setup(fake);
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { machine: "web", image: "shop:1", images: { web2: "shop:1" } }));
+    s.lines.length = 0;
+    await expect(
+      s.release.run(CTX, input("sha256:bbbbbbbbbbbb", { machine: "web", image: "shop:2", images: { web2: "shop:2" }, wait: { intervalMs: 0, deadlineMs: 50 } })),
+    ).rejects.toThrow(/machine shop\/m[0-9a-f]+ did not reach started within the deadline/);
+    expect(fake.machine("shop", "web")!.config.image).toBe("shop:1");
+    expect(fake.machine("shop", "web2")!.config.image).toBe("shop:1");
+    expect(s.lines.filter((l) => l.includes("restore"))).toEqual([
+      "fly-release: restored shop/web to sha256:aaaaaaaaaaaa",
+      "fly-release: restored shop/web2 to its previous config",
+    ]);
+  });
+
+  test("checks: true rolls with the defaults", { timeout: 20_000 }, async () => {
+    writePlan({ shop: PLAN.shop, web: machine("web"), web2: machine("web2") });
+    const { fake, events } = checkedFake();
+    const s = setup(fake);
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { machine: "web", image: "shop:1", images: { web2: "shop:1" }, checks: true }));
+    expect(events).toEqual(["create web", "passing web", "create web2", "passing web2"]);
+  });
+
+  test("a Machine with no checks configured is done once started, as before", async () => {
+    writePlan({ shop: PLAN.shop, web: machine("web", {}), web2: machine("web2", {}) });
+    const { fake, events } = checkedFake();
+    const s = setup(fake);
+    // A zero timeout: a Machine that had to wait for a check would fail at once.
+    const zero = { intervalMs: 1, timeoutMs: 0 };
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { machine: "web", image: "shop:1", images: { web2: "shop:1" }, checks: zero }));
+    const out = await s.release.run(CTX, input("sha256:bbbbbbbbbbbb", { machine: "web", image: "shop:2", images: { web2: "shop:2" }, checks: zero }));
+    expect(out.digest).toBe("sha256:bbbbbbbbbbbb");
+    expect(events).toEqual(["create web", "create web2", "update web", "update web2"]);
+    expect(s.fake.machine("shop", "web2")!.config.image).toBe("shop:2");
+  });
+
+  test("verify covers every Machine the release updated: one whose checks fail after the roll fails the release, and both are restored", async () => {
+    writePlan({ shop: PLAN.shop, web: machine("web"), web2: machine("web2") });
+    // The migration takes web2's database away: its checks fail from then on.
+    let broken = false;
+    const { fake } = checkedFake((m) => !(broken && m.name === "web2" && m.config.image === "shop:2"), { exec: () => void (broken = true) });
+    const s = setup(fake);
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { machine: "web", image: "shop:1", images: { web2: "shop:1" }, checks: FAST }));
+    s.lines.length = 0;
+
+    await expect(
+      s.release.run(
+        CTX,
+        input("sha256:bbbbbbbbbbbb", { machine: "web", image: "shop:2", images: { web2: "shop:2" }, checks: FAST, migrations: [{ name: "1.sql", command: "migrate" }] }),
+      ),
+    ).rejects.toThrow(/machine shop\/web2 .* check servicecheck-00-http-8080 is critical/);
+    expect(fake.machine("shop", "web")!.config.image).toBe("shop:1");
+    expect(fake.machine("shop", "web2")!.config.image).toBe("shop:1");
+    expect(s.lines.filter((l) => l.includes("restore"))).toEqual([
+      "fly-release: restored shop/web2 to its previous config",
+      "fly-release: restored shop/web to sha256:aaaaaaaaaaaa",
+    ]);
+  });
+
+  test("verify reads the serving Machine's checks too", async () => {
+    writePlan({ shop: PLAN.shop, web: machine("web") });
+    let broken = false;
+    const { fake } = checkedFake((m) => !(broken && m.config.image === "shop:2"), { exec: () => void (broken = true) });
+    const s = setup(fake);
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { image: "shop:1", checks: FAST }));
+    await expect(
+      s.release.run(CTX, input("sha256:bbbbbbbbbbbb", { image: "shop:2", checks: FAST, migrations: [{ name: "1.sql", command: "migrate" }] })),
+    ).rejects.toThrow(/verify shop\/web: machine shop\/web \(m[0-9a-f]+\): check servicecheck-00-http-8080 is critical/);
+    expect(fake.machine("shop", "web")!.config.image).toBe("shop:1");
+  });
+});

package/src/components/fly-release.ts

@@ -29,8 +29,19 @@
  * 3. verify: the Machine is started with this release, and its health
  *    endpoint answers when a URL is given;
  * 4. on a failure after the Machine changed, restore: the config it replaced
- *    goes back (or, on a first release, the Machine is stopped), and the step
- *    fails.
+ *    goes back (or, on a first release, the Machine is stopped), and so does
+ *    the old config of each other Machine the release updated, and the step
+ *    fails. A failure partway through the apply restores the Machines it had
+ *    already updated the same way.
+ *
+ * Given `checks` (#4719), the apply rolls the plan's Machines one at a time on
+ * their Fly checks: each Machine it starts must pass its checks
+ * (`checks[].status` on the Machine, reported since its update) before the
+ * next is updated, within `checks.timeoutMs` (default five minutes). A Machine
+ * with no checks is done once started. Verify then also needs every Machine
+ * the release started to pass its checks, and a failure restores the Machines
+ * the release changed last changed first, each restore waiting for its
+ * Machine's checks. Without `checks`, only `started` is waited for.
  *
  * A scheduled Machine (`config.schedule`, #4696) is released without being
  * started, whether it is the one that serves or another Machine in the plan:
@@ -57,6 +68,7 @@ import type { Capability, DeployContext } from "@intentius/chant/components/capa
 import type { ReceiptStore, EffectReceiptRef } from "@intentius/chant/op/receipt-store";
 import {
   findMachine,
+  flyMachineChecks,
   flyMachineExec,
   flyMachineRelease,
   flyMachineRestart,
@@ -65,9 +77,12 @@ import {
   flyMachineVerify,
   readMachineRelease,
   releaseTarget,
+  MachineReleaseError,
   type FlyMachineReleaseResult,
+  type MachineChecksOpts,
   type MachineFile,
   type MachineRelease,
+  type ReleasedMachine,
 } from "../op/activities/machine-release";
 import { defaultFlyHttp, machineSchedule, parsePlan, resolveEndpoint, skipsLaunch, type FlyHttp, type WaitOpts } from "../op/activities/fly-apply";
 import type { MachineConfigStore } from "../release-store";
@@ -174,6 +189,14 @@ export interface FlyReleaseInput {
   /** Migrations, in order. */
   migrations?: FlyMigration[];
   verify?: FlyVerify;
+  /**
+   * Roll the Machines one at a time on their Fly checks (#4719): each Machine
+   * the release starts must pass its checks before the next is updated, and
+   * verify reads every one's checks. `true` takes the defaults: five minutes
+   * per Machine, polled every second. A Machine with no checks configured is
+   * done once started. Without it, only `started` is waited for.
+   */
+  checks?: MachineChecksOpts | true;
   /** flaps endpoint override. Default: `FLY_FLAPS_BASE_URL`, else real Fly. */
   endpoint?: string;
   wait?: WaitOpts;
@@ -297,15 +320,33 @@ export function createFlyReleaseCapability(deps: FlyReleaseDeps = {}): Capabilit
   const log = deps.log ?? ((line: string) => console.error(line));
   const httpFor = () => deps.http ?? defaultFlyHttp();
 
-  /** On a failed release, put the plan's other Machines it updated back on their old configs. */
-  async function restoreOthers(released: FlyMachineReleaseResult, input: FlyReleaseInput, http: FlyHttp): Promise<void> {
-    for (const other of released.others) {
-      if (other.action !== "updated" || !other.previous) continue;
+  /**
+   * On a failed release, put each Machine it changed back. The serving
+   * Machine gets its old config, or is stopped when it served nothing before;
+   * another Machine it updated gets its old config.
+   *
+   * Without `checks` this is the order and the calls fly-release made before
+   * #4719: the serving Machine first, then the others in plan order. With
+   * `checks`, the last Machine changed goes back first, and each restore
+   * waits for its Machine's checks before the next.
+   */
+  async function restoreApplied(applied: ReleasedMachine[], input: FlyReleaseInput, http: FlyHttp, rolling: MachineChecksOpts | undefined, servingWas?: string | null): Promise<void> {
+    const order = rolling ? [...applied].reverse() : [...applied.filter((m) => m.serving), ...applied.filter((m) => !m.serving)];
+    for (const m of order) {
+      if (m.serving ? rolling && m.action === "noop" : m.action !== "updated" || !m.previous) continue;
+      const where = { app: m.app, machine: m.name, endpoint: input.endpoint, wait: input.wait };
       try {
-        await flyMachineRestore({ app: other.app, machine: other.name, config: other.previous, endpoint: input.endpoint, wait: input.wait }, undefined, http);
-        log(`fly-release: restored ${other.app}/${other.name} to its previous config`);
+        if (m.previous) {
+          await flyMachineRestore({ ...where, config: m.previous, ...(rolling ? { checks: rolling } : {}) }, undefined, http);
+          const was = m.serving ? (servingWas === undefined ? readMachineRelease(m.previous.metadata)?.digest : (servingWas ?? undefined)) : undefined;
+          log(`fly-release: restored ${m.app}/${m.name} to ${was ?? "its previous config"}`);
+        } else {
+          await flyMachineStop(where, undefined, http);
+          log(`fly-release: nothing had been released on ${m.app}/${m.name}; stopped it`);
+        }
       } catch (restoreErr) {
-        log(`fly-release: restore of ${other.app}/${other.name} failed: ${restoreErr instanceof Error ? restoreErr.message : String(restoreErr)}`);
+        const why = restoreErr instanceof Error ? restoreErr.message : String(restoreErr);
+        log(m.serving && !rolling ? `fly-release: restore failed: ${why}` : `fly-release: restore of ${m.app}/${m.name} failed: ${why}`);
       }
     }
   }
@@ -359,21 +400,31 @@ export function createFlyReleaseCapability(deps: FlyReleaseDeps = {}): Capabilit
         ...(input.env ?? {}),
       };
 
-      const released = await flyMachineRelease(
-        {
-          plan,
-          machine: input.machine,
-          release: { digest: input.digest, gitSha, ...(input.release ? { release: input.release } : {}) },
-          image: input.image,
-          ...(input.images ? { images: input.images } : {}),
-          env,
-          ...(source ? { files: source.files, cmd: source.cmd } : {}),
-          endpoint: input.endpoint,
-          wait: input.wait,
-        },
-        undefined,
-        http,
-      );
+      const rolling: MachineChecksOpts | undefined = input.checks === true ? {} : input.checks;
+      let released: FlyMachineReleaseResult;
+      try {
+        released = await flyMachineRelease(
+          {
+            plan,
+            machine: input.machine,
+            release: { digest: input.digest, gitSha, ...(input.release ? { release: input.release } : {}) },
+            image: input.image,
+            ...(input.images ? { images: input.images } : {}),
+            env,
+            ...(source ? { files: source.files, cmd: source.cmd } : {}),
+            endpoint: input.endpoint,
+            wait: input.wait,
+            ...(rolling ? { checks: rolling } : {}),
+          },
+          undefined,
+          http,
+        );
+      } catch (err) {
+        // A Machine failed to settle or to pass its checks partway through the
+        // roll: put back every Machine changed so far, then fail.
+        if (err instanceof MachineReleaseError) await restoreApplied(err.applied, input, http, rolling);
+        throw err;
+      }
       const where = { app: released.app, machine: released.machine.name, endpoint: input.endpoint };
       log(`fly-release: ${released.app}/${released.machine.name} ${released.action}, serving ${input.digest}${released.unlaunched ? ", stopped until its schedule starts it" : ""}`);
       for (const other of released.others) {
@@ -411,22 +462,38 @@ export function createFlyReleaseCapability(deps: FlyReleaseDeps = {}): Capabilit
           }
           if (migrations.some((m) => m.fired)) await flyMachineRestart({ ...where, wait: input.wait }, undefined, http);
         }
-        await flyMachineVerify({ ...where, digest: input.digest, ...(input.verify ?? {}) }, undefined, http, deps.fetch);
-      } catch (err) {
-        // Restore: the Machine changed, so put back what it served (or stop it
-        // when it served nothing), then fail the step.
-        try {
-          if (released.previous) {
-            await flyMachineRestore({ ...where, config: released.previous.config, wait: input.wait }, undefined, http);
-            log(`fly-release: restored ${released.app}/${released.machine.name} to ${previousRelease?.digest ?? "its previous config"}`);
-          } else {
-            await flyMachineStop({ ...where, wait: input.wait }, undefined, http);
-            log(`fly-release: nothing had been released on ${released.app}/${released.machine.name}; stopped it`);
-          }
-        } catch (restoreErr) {
-          log(`fly-release: restore failed: ${restoreErr instanceof Error ? restoreErr.message : String(restoreErr)}`);
+        const serving = released.applied.find((m) => m.serving);
+        await flyMachineVerify(
+          {
+            ...where,
+            digest: input.digest,
+            ...(input.verify ?? {}),
+            ...(rolling ? { checks: true, ...(serving?.updatedAt ? { checksSince: serving.updatedAt } : {}) } : {}),
+          },
+          undefined,
+          http,
+          deps.fetch,
+        );
+        // With checks, every other Machine the release started serves too: started, with its checks passing.
+        for (const m of rolling ? released.applied : []) {
+          if (m.serving || m.action === "noop" || m.unlaunched) continue;
+          await flyMachineChecks(
+            {
+              app: m.app,
+              machine: m.name,
+              endpoint: input.endpoint,
+              timeoutMs: input.verify?.timeoutMs ?? 120_000,
+              intervalMs: input.verify?.intervalMs,
+              ...(m.updatedAt ? { since: m.updatedAt } : {}),
+            },
+            undefined,
+            http,
+          );
         }
-        await restoreOthers(released, input, http);
+      } catch (err) {
+        // Restore: the Machines changed, so put back what each served (or stop
+        // the serving one when it served nothing), then fail the step.
+        await restoreApplied(released.applied, input, http, rolling, previousRelease?.digest ?? null);
         throw err;
       }
 

package/src/describe-resources.test.ts

@@ -240,6 +240,33 @@ describe("flyPlan: declared-vs-live change set (create/noop/delete/adopt)", () =
     expect(changeSet.entries.find((e) => e.name === "web")?.action).toBe("update");
   });
 
+  test("a mount named in the plan and mounted by id on the live Machine is a noop; another volume is an update (#4717)", async () => {
+    const planWith = (volume: string) =>
+      JSON.stringify({
+        app: { endpoint: "/v1/apps", method: "POST", body: { app_name: APP } },
+        web: {
+          endpoint: `/v1/apps/${APP}/machines`,
+          method: "POST",
+          body: { name: "web", config: { image: "nginx:1", mounts: [{ volume, path: "/data" }], metadata: { ...OWNED_META } } },
+        },
+      });
+    const ents = entities([
+      ["app", "Fly::Machines::App"],
+      ["web", "Fly::Machines::Machine"],
+    ]);
+    const live = liveMachine("web", "nginx:1");
+    (live.config as Record<string, unknown>).mounts = [{ volume: "vol_r68lmz2doox9myd4", name: "data", path: "/data" }];
+    const actionFor = async (volume: string) =>
+      (
+        await flyPlan(
+          { environment: "prod", buildOutput: planWith(volume), entityNames: [...ents.keys()], entities: ents, endpoint: ENDPOINT },
+          fakeHttp([live]),
+        )
+      ).changeSet.entries.find((e) => e.name === "web")?.action;
+    expect(await actionFor("data")).toBe("noop");
+    expect(await actionFor("logs")).toBe("update");
+  });
+
   test("an unreadable plan makes every declared entity unobserved, not a create (#1089)", async () => {
     const { changeSet } = await flyPlan(
       { environment: "prod", buildOutput: "not json", entityNames: [...ENTS.keys()], entities: ENTS, endpoint: ENDPOINT },

package/src/describe-resources.ts

@@ -52,6 +52,8 @@ import {
   resolveApp,
   isChantOwned,
   configEqual,
+  alignMountsWithLive,
+  volumeAliases,
   listMachines,
   listVolumes,
   listIps,
@@ -501,8 +503,11 @@ export async function flyPlan(
 
   // Declared config per entity, for the machine update/noop refinement.
   const declaredConfig = new Map<string, unknown>();
+  let aliases = new Map<string, string>();
   try {
-    for (const [entityName, req] of Object.entries(parsePlan(options.buildOutput))) {
+    const plan = parsePlan(options.buildOutput);
+    aliases = volumeAliases(plan);
+    for (const [entityName, req] of Object.entries(plan)) {
       if (isMachineRequest(req)) declaredConfig.set(entityName, req.body.config);
     }
   } catch {
@@ -514,7 +519,9 @@ export async function flyPlan(
     const declaredCfg = declaredConfig.get(entry.name);
     if (declaredCfg === undefined) continue; // not a declared machine
     const liveCfg = (observedNow[entry.name]?.attributes as { config?: unknown } | undefined)?.config;
-    if (!configEqual(declaredCfg, liveCfg)) {
+    // A declared mount names its volume; the live one has the id flyApply
+    // looked up, and the name beside it (#4717).
+    if (!configEqual(alignMountsWithLive(declaredCfg, liveCfg, aliases), liveCfg)) {
       entry.action = "update";
     }
   }

package/src/lint/audit-catalog.ts

@@ -43,7 +43,7 @@ export const flyAuditCatalog: Record<string, RuleMeta> = {
     "merge-worthy",
     "correctness",
     "Machine mount references an undeclared volume",
-    "Declare the Volume in the same stack, or point the mount at one that is.",
+    "Declare the Volume in the same stack, point the mount at one that is, or mount an existing volume by its id (vol_...).",
   ),
   FLY012: rule(
     "FLY012",

package/src/lint/post-synth/fly011-mount-references-declared-volume.test.ts

@@ -79,6 +79,37 @@ describe("FLY011: mount references a declared volume", () => {
     expect(diags).toHaveLength(0);
   });
 
+  test("passes a mount given a volume id, with no Volume declared (#4717)", () => {
+    const diags = fly011.check(
+      ctx(
+        ["app", new App({ name: "my-app" })],
+        [
+          "web",
+          new Machine({
+            config: new MachineConfig({
+              image: "nginx",
+              mounts: [new MachineMount({ volume: "vol_r68lmz2doox9myd4", name: "control_data", path: "/data" })],
+            }),
+          }),
+        ],
+      ),
+    );
+    expect(diags).toHaveLength(0);
+  });
+
+  test("a name that only starts like an id is still a name", () => {
+    const diags = fly011.check(
+      ctx([
+        "web",
+        new Machine({
+          config: new MachineConfig({ image: "nginx", mounts: [new MachineMount({ volume: "vol_", path: "/data" })] }),
+        }),
+      ]),
+    );
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("vol_...");
+  });
+
   test("does not flag a machine without mounts", () => {
     const diags = fly011.check(
       ctx(["web", new Machine({ config: new MachineConfig({ image: "nginx" }) })]),

package/src/lint/post-synth/fly011-mount-references-declared-volume.ts

@@ -6,17 +6,22 @@
  * apply time, so catch it at synth. This is a whole-stack check: it reads all
  * entities in the build (`ctx.entities`), so the mount and the Volume can be
  * declared in different files.
+ *
+ * A mount given a volume id (`vol_...`) names a volume that already exists on
+ * Fly, which the stack need not declare, so it passes (#4717). `flyApply`
+ * sends it as it is, and looks a name up to send its id.
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
 import { readProps, entityTypeOf } from "./fly-helpers";
+import { isVolumeId } from "../../volume-id";
 
 const MACHINE_ENTITY_TYPE = "Fly::Machines::Machine";
 const VOLUME_ENTITY_TYPE = "Fly::Machines::Volume";
 
 export const fly011: PostSynthCheck = {
   id: "FLY011",
-  description: "A machine mount's volume must resolve to a Volume declared in the stack",
+  description: "A machine mount's volume must resolve to a Volume declared in the stack, or be a volume id (vol_...)",
 
   check(ctx: PostSynthContext): PostSynthDiagnostic[] {
     const diagnostics: PostSynthDiagnostic[] = [];
@@ -44,11 +49,13 @@ export const fly011: PostSynthCheck = {
         // reference to a Volume that exists in the stack by construction, so it
         // never dangles — skip it to avoid false positives.
         if (typeof volume !== "string" || volume.length === 0) continue;
+        // A volume id names a volume that exists outside the stack.
+        if (isVolumeId(volume)) continue;
         if (!declaredVolumes.has(volume)) {
           diagnostics.push({
             checkId: "FLY011",
             severity: "error",
-            message: `Machine "${machineName}" mounts volume "${volume}", which is not declared as a Volume in the stack.`,
+            message: `Machine "${machineName}" mounts volume "${volume}", which is not declared as a Volume in the stack. Declare the Volume, or mount an existing volume by its id (vol_...).`,
             entity: machineName,
             lexicon: "fly",
           });