Add API for "full" container snapshots by gpanders · Pull Request #6430 · cloudflare/workerd

gpanders · 2026-03-26T16:40:28Z

This is part 2 of the containers snapshot API, following up from #6376 which implemented snapshotDirectory() to create a "directory snapshot". This PR implements snapshotContainer() to create a "full container" snapshot.

Conceptually, a "directory snapshot" can be thought of as an (immutable) Docker volume which can be mounted (restored) to other containers. More than one directory snapshot can be restored to a container.

A "full container snapshot" can be thought of as creating a new Docker image based on the current state of the container (this is how it is even implemented in local dev, using the Docker commit API). Only one full container snapshot can be restored into a new container, which effectively replaces the image of the container.

Directory snapshots can be restored alongside a full container snapshot.

cc @IRCody @spahl

ask-bonk

I'm Bonk, and I've done a quick review of your PR.

This PR adds snapshotContainer() API and local dev Docker implementation for full container snapshots, alongside renaming the existing directory snapshot fields for clarity.

[MEDIUM] No stale container snapshot image cleanup: warnAboutStaleSnapshotVolumes handles stale Docker volumes for directory snapshots, but there's no equivalent mechanism for stale workerd-container-snap-* images. Over time in local dev, these could accumulate. Not blocking, but worth tracking.
[LOW] Missing KJ_LOG in snapshotContainer: snapshotDirectory logs KJ_LOG(INFO, "created snapshot volume", ...) on success, but snapshotContainer has no corresponding log entry. Minor consistency/debugging gap.

This review was generated by an AI assistant and may contain inaccuracies.

src/workerd/server/container-client.c++

ask-bonk · 2026-03-26T16:44:18Z

I'm Bonk, and I've done a quick review of your PR.

This PR adds snapshotContainer() API and local dev Docker implementation for full container snapshots, alongside renaming the existing directory snapshot fields for clarity.

Summary of findings posted to PR #6430:

[MEDIUM] No stale container snapshot image cleanup — There's a warnAboutStaleSnapshotVolumes mechanism for directory snapshot volumes, but no equivalent for workerd-container-snap-* Docker images that could accumulate over time in local dev.
[LOW] Missing KJ_LOG in snapshotContainer — snapshotDirectory logs on success for observability, but snapshotContainer doesn't. Posted a suggestion comment with the fix.
[LOW] User-facing error message — When restoring a container snapshot with a non-existent ID, the error from inspectImage ("Failed to inspect Docker image") is less clear than the directory snapshot equivalent. Posted an inline comment.

Things that looked good:

Cap'n Proto schema changes are wire-compatible (ordinals preserved, struct renames don't affect wire format, new fields/methods are additive)
The KJ_DEFER cleanup logic in snapshotContainer is correct — it protects the window between commitContainer and the end of the function
parseSnapshotId using UUID::fromString is a good tightening vs. the old ad-hoc hex validation
The validateSnapshotSize refactor eliminates duplication
Test coverage is thorough — round-trip, named, memory unsupported, non-existent ID, directory overlay, exclude mounts, relayer, and cross-DO scenarios
TypeScript types are correctly generated with proper experimental gating

github run

codecov-commenter · 2026-03-26T17:13:30Z

Codecov Report

❌ Patch coverage is 0% with 131 lines in your changes missing coverage. Please review.
✅ Project coverage is 70.89%. Comparing base (9a696e4) to head (4b14c9d).
⚠️ Report is 41 commits behind head on main.

Files with missing lines	Patch %	Lines
src/workerd/server/container-client.c++	0.00%	90 Missing ⚠️
src/workerd/api/container.c++	0.00%	41 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6430      +/-   ##
==========================================
+ Coverage   70.70%   70.89%   +0.19%     
==========================================
  Files         427      428       +1     
  Lines      117263   119644    +2381     
  Branches    18903    18962      +59     
==========================================
+ Hits        82905    84819    +1914     
- Misses      23102    23556     +454     
- Partials    11256    11269      +13

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

gpanders · 2026-03-27T16:43:58Z

Split out the local dev (container-client.c++) implementation, so this PR only adds the API. Will open a separate PR for the local dev implementation for when the Windows compile errors are resolved.

types/generated-snapshot/experimental/index.d.ts

src/workerd/io/container.capnp

github-actions · 2026-03-30T14:45:40Z

The generated output of @cloudflare/workers-types matches the snapshot in types/generated-snapshot 🎉

snapshotContainer creates a "full container" snapshot, which includes the entire disk/filesystem and (optionally) the state of the container memory when the snapshot is created. Unlike directory snapshots, only a single container snapshot can be restored (but multiple directory snapshots can be restored alongside a container snapshot).

This uses the "docker commit" feature to create a new image from a running container. Restoring a full container snapshot is then as simple as using the new image. By design, local dev cannot support memory snapshots, so we explicitly forbid those with an error.

gpanders · 2026-03-30T18:06:06Z

Split out the local dev (container-client.c++) implementation, so this PR only adds the API. Will open a separate PR for the local dev implementation for when the Windows compile errors are resolved.

Since @fhanau resolved the Windows release build issues, I've added the container-client.c++ modifications back into this PR so that we have the local dev implementation now.

kentonv

API looks good.

gpanders requested review from a team as code owners March 26, 2026 16:40

ask-bonk bot reviewed Mar 26, 2026

View reviewed changes

src/workerd/server/container-client.c++ Show resolved Hide resolved

src/workerd/server/container-client.c++ Show resolved Hide resolved

gpanders mentioned this pull request Mar 26, 2026

Add docs and changelog for containers snapshots cloudflare/cloudflare-docs#29385

Open

2 tasks

gpanders force-pushed the ganders/container-snapshots branch 2 times, most recently from 20eadae to 60182d2 Compare March 27, 2026 16:42

gpanders changed the title ~~Add API and local dev implementation for "full" container snapshots~~ Add API for "full" container snapshots Mar 27, 2026

gpanders force-pushed the ganders/container-snapshots branch from 60182d2 to 564d7dd Compare March 27, 2026 16:44

anonrig approved these changes Mar 27, 2026

View reviewed changes

kentonv reviewed Mar 27, 2026

View reviewed changes

types/generated-snapshot/experimental/index.d.ts Show resolved Hide resolved

gpanders force-pushed the ganders/container-snapshots branch from 564d7dd to 83a16ed Compare March 27, 2026 18:03

kentonv reviewed Mar 27, 2026

View reviewed changes

src/workerd/io/container.capnp Outdated Show resolved Hide resolved

gpanders force-pushed the ganders/container-snapshots branch from 83a16ed to e7f24df Compare March 30, 2026 14:37

gpanders added 2 commits March 30, 2026 09:47

gpanders force-pushed the ganders/container-snapshots branch from e7f24df to d1c04ba Compare March 30, 2026 14:48

gpanders requested a review from kentonv March 30, 2026 16:04

kentonv approved these changes Mar 30, 2026

View reviewed changes

anonrig approved these changes Mar 30, 2026

View reviewed changes

gpanders merged commit 40308bc into main Mar 30, 2026
37 of 38 checks passed

gpanders deleted the ganders/container-snapshots branch March 30, 2026 21:48

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add API for "full" container snapshots#6430

Add API for "full" container snapshots#6430
gpanders merged 2 commits intomainfrom
ganders/container-snapshots

gpanders commented Mar 26, 2026 •

edited

Loading

Uh oh!

ask-bonk bot left a comment

Uh oh!

Uh oh!

Uh oh!

ask-bonk bot commented Mar 26, 2026

Uh oh!

codecov-commenter commented Mar 26, 2026 •

edited

Loading

Uh oh!

gpanders commented Mar 27, 2026

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Mar 30, 2026 •

edited

Loading

Uh oh!

gpanders commented Mar 30, 2026

Uh oh!

kentonv left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

gpanders commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ask-bonk bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ask-bonk bot commented Mar 26, 2026

Uh oh!

codecov-commenter commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

gpanders commented Mar 27, 2026

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gpanders commented Mar 30, 2026

Uh oh!

kentonv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

gpanders commented Mar 26, 2026 •

edited

Loading

codecov-commenter commented Mar 26, 2026 •

edited

Loading

github-actions bot commented Mar 30, 2026 •

edited

Loading