Skip to content

podman: add opt-in local tfork API - #14

Open
yiying-zhang wants to merge 70 commits into
mainfrom
perf/tfork-local-api
Open

podman: add opt-in local tfork API#14
yiying-zhang wants to merge 70 commits into
mainfrom
perf/tfork-local-api

Conversation

@yiying-zhang

Copy link
Copy Markdown
Collaborator

Summary

  • add POST /libpod/containers/{name}/tfork for a resident local Podman
    service;
  • keep the endpoint disabled unless PODMAN_TFORK_LOCAL_API=1;
  • reject non-Unix listeners, cap request bodies at 1 MiB, and reject unknown
    JSON fields;
  • call the existing transactional live-clone ABI and return its clone metadata.

Why

Every direct TClone starts a new Podman CLI and reinitializes libpod, storage,
runtime, and client state. Keeping only CRIU's service warm saved effectively
nothing (0.014 ms paired median), so this branch tests the useful worker
boundary: a resident Podman/libpod process plus a persistent local client.

Performance

On 137.110.161.221, a controlled four-process Alpine source measured:

Variant Median Mean
Fresh Podman CLI 486.721 ms 484.534 ms
Resident local API 405.789 ms 398.118 ms

The paired median saving was 86.338 ms, with 30/30 resident wins. Ten-pair
process scaling saved 91.5 ms at 1 process, 107.4 ms at 4, 84.9 ms at 25, and
86.6 ms at 100. This reduces fixed overhead but does not flatten CRIU's
per-process slope.

Validation

  • built the full candidate Podman binary;
  • go test ./pkg/api/handlers/libpod ./pkg/api/server passes;
  • every recorded child had the exact expected process count and sentinel;
  • the source remained running after every fork;
  • 30-pair four-process A/B and 1/4/25/100 process scaling completed.

Security and deployment notes

This endpoint is intentionally local and opt-in. Production deployment must
place the socket in a root-owned directory, restrict its mode/group, validate
peer credentials and container authorization, and run one authoritative
libpod service per state store. A source must be addressed by immutable ID plus
generation; running two long-lived services against the same database exposed
a stale-name-generation failure during prototype testing.

This branch does not yet cache source pidfds, namespaces, mount handles, task
graphs, or mutation manifests. Those are later optimizations with separate
correctness and performance gates.

yiying-zhang and others added 30 commits July 10, 2026 23:44
Stabilize live tfork source freezing
yiying-zhang and others added 28 commits July 20, 2026 08:24
…-main

Stabilize single-copy tfork clone path
Rewrite tclone setup for Gensee Crate
@yiying-zhang yiying-zhang changed the title podman: add opt-in local tfork API- #18 podman: add opt-in local tfork API Aug 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants