Skip to content

Commit 8fbda81

Browse files
post: fstrim the buildkit sticky disk before unmount at commit (#147)
Pruned layers keep their RBD extents allocated on the backing store until the guest discards them. Run a best-effort fstrim on /var/lib/buildkit before unmount, only when the run is still on track to commit (integrity check passed, no early deny, no SIGKILL, no failed steps) and only when the host enabled it: the VM agent returns GetStickyDiskResponse.fstrim_timeout_secs, saved in action state at mount time; 0 means no trim. A positive fstrim_min_extent_bytes becomes `fstrim -m`. Any failure or timeout only logs. Port of #143 (release/v2) to the v1 line; v1 has no DockerJobLifecycle report, so the trim result is logged only. Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
1 parent 668e4bc commit 8fbda81

8 files changed

Lines changed: 239 additions & 32 deletions

File tree

‎dist/index.js‎

Lines changed: 7 additions & 7 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎dist/index.js.map‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@
1515
},
1616
"dependencies": {
1717
"@actions/core": "^1.10.1",
18-
"@buf/blacksmith_vm-agent.bufbuild_es": "2.14.1-20260904133914-c6beb298c70c.3",
19-
"@bufbuild/protobuf": "^2.14.1",
18+
"@buf/blacksmith_vm-agent.bufbuild_es": "2.16.0-20261026163753-b7ed8710bf2b.1",
19+
"@bufbuild/protobuf": "^2.16.0",
2020
"@connectrpc/connect": "^2.1.1",
2121
"@connectrpc/connect-node": "^2.1.1",
2222
"@docker/actions-toolkit": "0.37.1",

‎pnpm-lock.yaml‎

Lines changed: 20 additions & 20 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎src/main.ts‎

Lines changed: 62 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ import {
2727
logBuildkitdLogTail,
2828
logDatabaseHashes,
2929
writeDockerContainerBuildkitdTomlFile,
30+
fstrimFailureOutcome,
3031
} from "./setup_builder";
3132
import {
3233
installBuildKit,
@@ -41,6 +42,38 @@ const DEFAULT_BUILDX_VERSION = "v0.23.0";
4142
const mountPoint = "/var/lib/buildkit";
4243
const execAsync = promisify(exec);
4344

45+
// Best-effort fstrim of the sticky disk before it is unmounted and committed:
46+
// pruned layers keep their RBD extents allocated on the backing store until
47+
// the guest discards them. Bounded by the host-supplied budget; any failure
48+
// (discard not negotiated, missing binary, timeout) only logs. A positive
49+
// minExtentBytes is passed as `fstrim -m`: free extents smaller than that are
50+
// left alone.
51+
async function trimFilesystem(
52+
mountPath: string,
53+
timeoutSecs: number,
54+
minExtentBytes: number,
55+
): Promise<void> {
56+
const start = Date.now();
57+
const minimum = minExtentBytes > 0 ? ` -m ${minExtentBytes}` : "";
58+
try {
59+
const { stdout } = await execAsync(
60+
`timeout ${timeoutSecs} sudo fstrim -v${minimum} -- "${mountPath}"`,
61+
);
62+
core.info(
63+
`fstrim ${mountPath}: ${stdout.trim() || "done"} in ${Date.now() - start}ms`,
64+
);
65+
} catch (error) {
66+
const durationMs = Date.now() - start;
67+
const { code, stderr } = error as { code?: unknown; stderr?: string };
68+
const outcome = fstrimFailureOutcome(code, stderr);
69+
const detail =
70+
outcome === "timeout"
71+
? `timed out after ${timeoutSecs}s`
72+
: stderr?.trim() || (error as Error).message;
73+
core.info(`fstrim ${mountPath}: ${outcome} in ${durationMs}ms: ${detail}`);
74+
}
75+
}
76+
4477
async function getDeviceFromMount(mountPath: string): Promise<string | null> {
4578
try {
4679
const { stdout } = await execAsync(`findmnt -n -o SOURCE "${mountPath}"`);
@@ -514,6 +547,8 @@ async function startBlacksmithBuilder(
514547
// Save state for post action
515548
stateHelper.setExposeId(stickyDiskSetup.exposeId);
516549
stateHelper.setCommitEarlyDenyReason(stickyDiskSetup.commitEarlyDenyReason);
550+
stateHelper.setFstrimTimeoutSecs(stickyDiskSetup.fstrimTimeoutSecs);
551+
stateHelper.setFstrimMinExtentBytes(stickyDiskSetup.fstrimMinExtentBytes);
517552

518553
return { addr: buildkitdAddr, exposeId: stickyDiskSetup.exposeId };
519554
} catch (error) {
@@ -795,6 +830,9 @@ void actionsToolkit.run(
795830
let cleanupError: Error | null = null;
796831
let fsDiskUsageBytes: number | null = null;
797832
let integrityCheckPassed: boolean | null = null;
833+
let earlyFailureCheck: Awaited<
834+
ReturnType<typeof checkPreviousStepFailures>
835+
> | null = null;
798836

799837
try {
800838
// Step 1: Shut down buildkitd if this instance started it.
@@ -827,6 +865,28 @@ void actionsToolkit.run(
827865
// Log database file hashes after integrity check
828866
await logDatabaseHashes("after integrity check");
829867

868+
// Discard freed blocks before unmount so the committed snapshot
869+
// does not keep them allocated. Only when the host enabled the
870+
// trim and this run is still on track to commit; the previous-step
871+
// check is done once here and reused by the commit decision below.
872+
const fstrimTimeoutSecs = stateHelper.getFstrimTimeoutSecs();
873+
if (
874+
fstrimTimeoutSecs > 0 &&
875+
exposeId &&
876+
integrityCheckPassed &&
877+
!stateHelper.getCommitEarlyDenyReason() &&
878+
!stateHelper.getSigkillUsed()
879+
) {
880+
earlyFailureCheck = await checkPreviousStepFailures();
881+
if (!earlyFailureCheck.error && !earlyFailureCheck.hasFailures) {
882+
await trimFilesystem(
883+
mountPoint,
884+
fstrimTimeoutSecs,
885+
stateHelper.getFstrimMinExtentBytes(),
886+
);
887+
}
888+
}
889+
830890
// Get filesystem usage BEFORE unmounting (critical timing)
831891
try {
832892
const { stdout } = await execAsync(
@@ -928,7 +988,8 @@ void actionsToolkit.run(
928988
core.info(
929989
"Checking for previous step failures before committing sticky disk",
930990
);
931-
const failureCheck = await checkPreviousStepFailures();
991+
const failureCheck =
992+
earlyFailureCheck ?? (await checkPreviousStepFailures());
932993

933994
if (failureCheck.error) {
934995
core.warning(

‎src/setup-builder.test.ts‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,49 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
22
import * as core from "@actions/core";
33
import * as fs from "fs";
44
import * as setupBuilder from "./setup_builder";
5+
import { fromBinary } from "@bufbuild/protobuf";
6+
import { GetStickyDiskResponseSchema } from "@buf/blacksmith_vm-agent.bufbuild_es/stickydisk/v1/stickydisk_pb.js";
7+
8+
describe("parseFstrimTimeoutSecs", () => {
9+
it("reads the int64 field as whole seconds, 0 when absent or unusable", () => {
10+
// field 8, varint wire type => tag 0x40; value 5
11+
const response = fromBinary(
12+
GetStickyDiskResponseSchema,
13+
new Uint8Array([0x40, 0x05]),
14+
);
15+
expect(
16+
setupBuilder.parseFstrimTimeoutSecs(response.fstrimTimeoutSecs),
17+
).toBe(5);
18+
expect(
19+
setupBuilder.parseFstrimTimeoutSecs(
20+
fromBinary(GetStickyDiskResponseSchema, new Uint8Array([]))
21+
.fstrimTimeoutSecs,
22+
),
23+
).toBe(0);
24+
expect(setupBuilder.parseFstrimTimeoutSecs(BigInt(5))).toBe(5);
25+
expect(setupBuilder.parseFstrimTimeoutSecs("2.9")).toBe(2);
26+
expect(setupBuilder.parseFstrimTimeoutSecs(-1)).toBe(0);
27+
expect(setupBuilder.parseFstrimTimeoutSecs(undefined)).toBe(0);
28+
});
29+
30+
it("reads fstrim_min_extent_bytes (field 9) as whole bytes, 0 when absent", () => {
31+
// field 9, varint wire type => tag 0x48; value 4194304 (4 MiB)
32+
const response = fromBinary(
33+
GetStickyDiskResponseSchema,
34+
new Uint8Array([0x48, 0x80, 0x80, 0x80, 0x02]),
35+
);
36+
expect(
37+
setupBuilder.parseFstrimMinExtentBytes(response.fstrimMinExtentBytes),
38+
).toBe(4194304);
39+
expect(
40+
setupBuilder.parseFstrimMinExtentBytes(
41+
fromBinary(GetStickyDiskResponseSchema, new Uint8Array([]))
42+
.fstrimMinExtentBytes,
43+
),
44+
).toBe(0);
45+
expect(setupBuilder.parseFstrimMinExtentBytes(-1)).toBe(0);
46+
});
47+
});
548
// import * as reporter from "./reporter";
649

750
// Mock the modules
@@ -308,3 +351,22 @@ describe("setup_builder", () => {
308351
});
309352
});
310353
});
354+
355+
describe("fstrimFailureOutcome", () => {
356+
it("classifies failures", () => {
357+
expect(setupBuilder.fstrimFailureOutcome(124, "")).toBe("timeout");
358+
expect(
359+
setupBuilder.fstrimFailureOutcome(
360+
1,
361+
"fstrim: /var/lib/buildkit: the discard operation is not supported",
362+
),
363+
).toBe("unsupported");
364+
expect(setupBuilder.fstrimFailureOutcome(127, "")).toBe("unsupported");
365+
expect(
366+
setupBuilder.fstrimFailureOutcome(
367+
1,
368+
"fstrim: /x: FITRIM ioctl failed: Input/output error",
369+
),
370+
).toBe("failed");
371+
});
372+
});

‎src/setup_builder.ts‎

Lines changed: 65 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -387,6 +387,51 @@ export async function startBuildkitd(
387387
}
388388
}
389389

390+
/** Why the best-effort pre-unmount fstrim did not complete, as logged by the post step. */
391+
export type FstrimFailureOutcome = "timeout" | "unsupported" | "failed";
392+
393+
/**
394+
* Classifies a failed `timeout <n> sudo fstrim` run: 124 is timeout(1)'s
395+
* exit code; discard not negotiated by the hypervisor (EOPNOTSUPP) or no
396+
* fstrim binary are "unsupported"; anything else is "failed".
397+
*/
398+
export function fstrimFailureOutcome(
399+
code: unknown,
400+
stderr: string | undefined,
401+
): FstrimFailureOutcome {
402+
if (code === 124) return "timeout";
403+
if (code === 127 || code === "ENOENT") return "unsupported";
404+
const msg = (stderr ?? "").toLowerCase();
405+
if (
406+
msg.includes("not supported") ||
407+
msg.includes("command not found") ||
408+
msg.includes("no such file or directory")
409+
) {
410+
return "unsupported";
411+
}
412+
return "failed";
413+
}
414+
415+
/**
416+
* Parse the host's fstrim budget (GetStickyDiskResponse.fstrim_timeout_secs,
417+
* a protobuf int64 that arrives as a bigint) into whole seconds. Anything
418+
* unusable is 0, which disables the trim.
419+
*/
420+
export function parseFstrimTimeoutSecs(value: unknown): number {
421+
const n = typeof value === "bigint" ? Number(value) : Number(value ?? 0);
422+
if (!Number.isFinite(n) || n <= 0) return 0;
423+
return Math.floor(n);
424+
}
425+
426+
/**
427+
* Parse the host's `fstrim --minimum` value
428+
* (GetStickyDiskResponse.fstrim_min_extent_bytes, a bigint or saved-state
429+
* string) into whole bytes. Anything unusable is 0: the fstrim default.
430+
*/
431+
export function parseFstrimMinExtentBytes(value: unknown): number {
432+
return parseFstrimTimeoutSecs(value);
433+
}
434+
390435
export async function getStickyDisk(options?: {
391436
signal?: AbortSignal;
392437
}): Promise<{
@@ -397,6 +442,11 @@ export async function getStickyDisk(options?: {
397442
// Non-empty when the host already knows this job's commit will be denied
398443
// (e.g. branch protection) and its writes to the sticky disk discarded.
399444
commit_early_deny_reason: string;
445+
// Host budget, in whole seconds, for trimming the filesystem before unmount
446+
// at commit; 0 when the host has not enabled the trim.
447+
fstrim_timeout_secs: number;
448+
// Host `fstrim -m` value in bytes; 0 means the fstrim default.
449+
fstrim_min_extent_bytes: number;
400450
}> {
401451
const client = await reporter.createBlacksmithAgentClient();
402452
core.info(`Created Blacksmith agent client`);
@@ -438,6 +488,10 @@ export async function getStickyDisk(options?: {
438488
commit_early_deny_reason: response.commitEarlyDeny
439489
? response.commitEarlyDenyReason || "denied by host policy"
440490
: "",
491+
fstrim_timeout_secs: parseFstrimTimeoutSecs(response.fstrimTimeoutSecs),
492+
fstrim_min_extent_bytes: parseFstrimMinExtentBytes(
493+
response.fstrimMinExtentBytes,
494+
),
441495
};
442496
}
443497

@@ -675,6 +729,8 @@ export async function setupStickyDisk(): Promise<{
675729
device: string;
676730
exposeId: string;
677731
commitEarlyDenyReason: string;
732+
fstrimTimeoutSecs: number;
733+
fstrimMinExtentBytes: number;
678734
}> {
679735
try {
680736
const controller = new AbortController();
@@ -691,6 +747,8 @@ export async function setupStickyDisk(): Promise<{
691747
const cloneName = stickyDiskResponse.clone_name;
692748

693749
const commitEarlyDenyReason = stickyDiskResponse.commit_early_deny_reason;
750+
const fstrimTimeoutSecs = stickyDiskResponse.fstrim_timeout_secs;
751+
const fstrimMinExtentBytes = stickyDiskResponse.fstrim_min_extent_bytes;
694752

695753
core.info(`Sticky disk parent snapshot: ${parentSnapshotName}`);
696754
core.info(`Sticky disk clone name: ${cloneName}`);
@@ -761,7 +819,13 @@ export async function setupStickyDisk(): Promise<{
761819
// Log database file hashes after mount
762820
await logDatabaseHashes("after mount");
763821

764-
return { device, exposeId, commitEarlyDenyReason };
822+
return {
823+
device,
824+
exposeId,
825+
commitEarlyDenyReason,
826+
fstrimTimeoutSecs,
827+
fstrimMinExtentBytes,
828+
};
765829
} catch (error) {
766830
core.warning(`Error in setupStickyDisk: ${(error as Error).message}`);
767831
await reporter.reportBuildPushActionFailure(

0 commit comments

Comments
 (0)