[PR #247] [CLOSED] feat: build templates with managed BuildKit workers #290

New issue

Closed

opened 2026-10-29 14:21:52 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 14:21:52 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/247
Author: @yingdi-shan
Created: 9/5/2026
Status: ❌ Closed

Base: main ← Head: feat/template-buildkit

📝 Commits (3)

60b6da8 feat(image): import BuildKit content into OverlayBD cache
928cdb3 feat(templates): manage reusable BuildKit workers and volume publication
2dcf04f feat(cli): build Dockerfiles with bundled BuildKit and document lifecycle

📊 Changes

80 files changed (+6733 additions, -813 deletions)

View changed files

📝 .github/workflows/integration-tests.yml (+21 -0)
📝 .github/workflows/release.yml (+1 -0)
📝 Cargo.lock (+7 -10)
📝 Makefile (+10 -1)
📝 build.rs (+6 -0)
➕ config/buildkit-version (+1 -0)
📝 config/default.toml (+7 -0)
📝 crates/aenv/Cargo.toml (+2 -2)
➕ crates/aenv/src/client/buildkit.rs (+199 -0)
📝 crates/aenv/src/client/mod.rs (+6 -0)
📝 crates/aenv/src/commands/build.rs (+377 -515)
📝 crates/aenv/src/main.rs (+2 -2)
📝 crates/aenv/src/progress.rs (+60 -0)
📝 deploy/docker-compose.yml (+6 -0)
📝 docs/src/concepts/templates.md (+141 -21)
📝 docs/src/concepts/volumes.md (+7 -0)
📝 docs/src/configuration/reference.md (+16 -8)
📝 docs/src/deployment/docker-compose.md (+9 -0)
📝 docs/src/getting-started/aenv-cli.md (+35 -8)
➕ scripts/buildkit/README.md (+45 -0)

...and 60 more files

📄 Description

Superseded by three focused PRs:

#252: optimize mounted-volume deletion.
#253: fix OCI image startup with explicit UID or GID.
#254: BuildKit integration.

All three target main. The tested integration commit preserves this PR's combined runtime implementation on current main and records the shared-file reconciliation. Validation and merge-order notes are in the replacement PRs. This branch is retained for the original commits and review history.

What

Replace the limited Dockerfile interpreter with BuildKit in managed microVMs. aenv build <context> --name <name> transfers the context, imports the final image into OverlayBD, and publishes a runnable template. Ordinary sandboxes and builders preserve mounted volumes during deletion by freezing and sealing them without capturing VM state.

Why

Support Dockerfile semantics and persistent instruction/cache-mount reuse, while avoiding disposable VM snapshots and filesystem journal replay during volume reuse.

Close #147. The volume-layer hashing optimization remains separate in #249.

Scope and non-goals

CLI, node/gateway APIs, image import, worker/cache lifecycle, mounted-volume deletion, installation, tests, and documentation. Stage selection, SSH forwarding, remote/stdin contexts, and cross-platform emulation are outside this flow.

Design and behavior changes

flowchart LR
  CLI["aenv + private buildctl"] -->|"authenticated WebSocket"| Worker["Per-build microVM"]
  Seed["Immutable cache seed"] -->|"writable clone"| Worker
  Worker -->|"verified OCI content"| Image["OverlayBD cache"]
  Image --> Template["Boot and publish template"]
  Worker -->|"freeze, seal, stop"| Cache["Publish next cache seed"]

Reuse builder snapshots keyed by image, resources, virtualization mode, and readiness setup. Each build gets a separate cache child; concurrent branches run independently, with the last published seed used by subsequent builds.
Commit the cache head and pending retirements in one atomic repository record. Retirements run independently of build finalization and respect active leases.
Bound preparation and startup by the build deadline. Catch worker panics, retain failed cleanup for periodic retry, cancel abandoned allocation handlers, and reject deletion of active build records. Cleanup waits for in-flight resource creation before releasing its volumes.
Freeze and publish mounted volumes, stop the VM, then release ownership. Recoverable capture/publication failures thaw the original runtime; terminal failures share normal persisted-state cleanup. Freeze/thaw RPCs have an overall 30-second timeout.
Use cancellable CLI HTTP requests, including allocation and polling. Require a routable gateway assignment before acknowledging build allocation. Use a private Unix socket on Linux/macOS.
Preserve image startup, health checks, and numeric UID/GID values. Bound account-file reads and use the provided BusyBox for account maintenance.

Compatibility and operations

Additive API and regenerated bindings; the new CLI requires the matching server/gateway. Existing declarative template APIs remain available.
Builder defaults: moby/buildkit:v0.33.0, 16 vCPUs, 32768 MiB memory, 262144 MiB cache. Build allocation validates cache capacity against the volume limit; ordinary APIs still work with smaller volume limits.
Install one private aenv-buildctl beside aenv, preserving system buildctl. Both installers read the client pin from the same AgentENV release. No previous BuildKit/cache-format compatibility layer is included.
Normal pause and graceful shutdown retain resumable state. Internal workers are disposable. Snapshot and OverlayBD artifact formats are unchanged.

Validation

make fmt and make clippy
make test-unit: 843 AgentENV tests, 4 capability-gated tests, 55 CLI tests, 3 Linux capability tests, 8 ublk tests, 46 daemon tests, and installer checks.
make -C services test
make agentenv-server; generated bindings were regenerated, not manually edited.
Regression coverage for panic cleanup, active-template deletion, atomic cache retirement, terminal persistence cleanup, ownership ordering, and invalid inputs.
Stalled HTTP allocation/polling checks: Ctrl+C exits within one second; an allocated build receives cancellation.
Live volume E2E suite: all 52 checks pass, including exact file preservation after deletion and reattachment.
Live BuildKit fixture and numeric-user suites: cache reuse, concurrent builds, failure, cancellation, startup overrides, terminal progress, and four UID/GID cases passed. Cleanup left one current seed, no pending retirements, and no sandboxes.
ShellCheck and installer collision/failure-injection checks; documentation updated.

The single-node E2E CI job runs both BuildKit suites with a 2-vCPU, 2048-MiB builder and an 8192-MiB cache. The full Rust integration suite was not rerun during this revision.

Risks and reviewer notes

Concurrent builders multiply resource use. Shared cache access follows the repository's API-key trust boundary. Publication depends on storage throughput; freezing flushes filesystem data but cannot capture application buffers. Review deletion ordering in src/orchestrator/service.rs and cache transactions in src/snapshot/repository/.

Checklist

Changes stay within managed builds and their persistent-volume lifecycle.
New behavior has focused regression coverage.
Logs and examples contain no credentials or private registry information.
Schema changes include regenerated bindings.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/AgentENV/pull/247 **Author:** [@yingdi-shan](https://github.com/yingdi-shan) **Created:** 9/5/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `feat/template-buildkit` --- ### 📝 Commits (3) - [`60b6da8`](https://github.com/kvcache-ai/AgentENV/commit/60b6da8d103667197bf6f2c8e7f6fed4b6886bfb) feat(image): import BuildKit content into OverlayBD cache - [`928cdb3`](https://github.com/kvcache-ai/AgentENV/commit/928cdb3da4e2483b89e4360a51a90b54c06e115b) feat(templates): manage reusable BuildKit workers and volume publication - [`2dcf04f`](https://github.com/kvcache-ai/AgentENV/commit/2dcf04f01432134fb68c55d06555ea856e0b69dc) feat(cli): build Dockerfiles with bundled BuildKit and document lifecycle ### 📊 Changes **80 files changed** (+6733 additions, -813 deletions) <details> <summary>View changed files</summary> 📝 `.github/workflows/integration-tests.yml` (+21 -0) 📝 `.github/workflows/release.yml` (+1 -0) 📝 `Cargo.lock` (+7 -10) 📝 `Makefile` (+10 -1) 📝 `build.rs` (+6 -0) ➕ `config/buildkit-version` (+1 -0) 📝 `config/default.toml` (+7 -0) 📝 `crates/aenv/Cargo.toml` (+2 -2) ➕ `crates/aenv/src/client/buildkit.rs` (+199 -0) 📝 `crates/aenv/src/client/mod.rs` (+6 -0) 📝 `crates/aenv/src/commands/build.rs` (+377 -515) 📝 `crates/aenv/src/main.rs` (+2 -2) 📝 `crates/aenv/src/progress.rs` (+60 -0) 📝 `deploy/docker-compose.yml` (+6 -0) 📝 `docs/src/concepts/templates.md` (+141 -21) 📝 `docs/src/concepts/volumes.md` (+7 -0) 📝 `docs/src/configuration/reference.md` (+16 -8) 📝 `docs/src/deployment/docker-compose.md` (+9 -0) 📝 `docs/src/getting-started/aenv-cli.md` (+35 -8) ➕ `scripts/buildkit/README.md` (+45 -0) _...and 60 more files_ </details> ### 📄 Description Superseded by three focused PRs: 1. #252: optimize mounted-volume deletion. 2. #253: fix OCI image startup with explicit UID or GID. 3. #254: BuildKit integration. All three target `main`. The tested [integration commit](https://github.com/yingdi-shan/AgentENV/commit/3d654ef) preserves this PR's combined runtime implementation on current `main` and records the shared-file reconciliation. Validation and merge-order notes are in the replacement PRs. This branch is retained for the original commits and review history. --- ## What Replace the limited Dockerfile interpreter with BuildKit in managed microVMs. `aenv build <context> --name <name>` transfers the context, imports the final image into OverlayBD, and publishes a runnable template. Ordinary sandboxes and builders preserve mounted volumes during deletion by freezing and sealing them without capturing VM state. ## Why Support Dockerfile semantics and persistent instruction/cache-mount reuse, while avoiding disposable VM snapshots and filesystem journal replay during volume reuse. ## Related issue Close #147. The volume-layer hashing optimization remains separate in #249. ## Scope and non-goals CLI, node/gateway APIs, image import, worker/cache lifecycle, mounted-volume deletion, installation, tests, and documentation. Stage selection, SSH forwarding, remote/stdin contexts, and cross-platform emulation are outside this flow. ## Design and behavior changes ```mermaid flowchart LR CLI["aenv + private buildctl"] -->|"authenticated WebSocket"| Worker["Per-build microVM"] Seed["Immutable cache seed"] -->|"writable clone"| Worker Worker -->|"verified OCI content"| Image["OverlayBD cache"] Image --> Template["Boot and publish template"] Worker -->|"freeze, seal, stop"| Cache["Publish next cache seed"] ``` - Reuse builder snapshots keyed by image, resources, virtualization mode, and readiness setup. Each build gets a separate cache child; concurrent branches run independently, with the last published seed used by subsequent builds. - Commit the cache head and pending retirements in one atomic repository record. Retirements run independently of build finalization and respect active leases. - Bound preparation and startup by the build deadline. Catch worker panics, retain failed cleanup for periodic retry, cancel abandoned allocation handlers, and reject deletion of active build records. Cleanup waits for in-flight resource creation before releasing its volumes. - Freeze and publish mounted volumes, stop the VM, then release ownership. Recoverable capture/publication failures thaw the original runtime; terminal failures share normal persisted-state cleanup. Freeze/thaw RPCs have an overall 30-second timeout. - Use cancellable CLI HTTP requests, including allocation and polling. Require a routable gateway assignment before acknowledging build allocation. Use a private Unix socket on Linux/macOS. - Preserve image startup, health checks, and numeric UID/GID values. Bound account-file reads and use the provided BusyBox for account maintenance. ## Compatibility and operations - Additive API and regenerated bindings; the new CLI requires the matching server/gateway. Existing declarative template APIs remain available. - Builder defaults: `moby/buildkit:v0.33.0`, 16 vCPUs, 32768 MiB memory, 262144 MiB cache. Build allocation validates cache capacity against the volume limit; ordinary APIs still work with smaller volume limits. - Install one private `aenv-buildctl` beside `aenv`, preserving system `buildctl`. Both installers read the client pin from the same AgentENV release. No previous BuildKit/cache-format compatibility layer is included. - Normal pause and graceful shutdown retain resumable state. Internal workers are disposable. Snapshot and OverlayBD artifact formats are unchanged. ## Validation - [x] `make fmt` and `make clippy` - [x] `make test-unit`: 843 AgentENV tests, 4 capability-gated tests, 55 CLI tests, 3 Linux capability tests, 8 ublk tests, 46 daemon tests, and installer checks. - [x] `make -C services test` - [x] `make agentenv-server`; generated bindings were regenerated, not manually edited. - [x] Regression coverage for panic cleanup, active-template deletion, atomic cache retirement, terminal persistence cleanup, ownership ordering, and invalid inputs. - [x] Stalled HTTP allocation/polling checks: Ctrl+C exits within one second; an allocated build receives cancellation. - [x] Live volume E2E suite: all 52 checks pass, including exact file preservation after deletion and reattachment. - [x] Live BuildKit fixture and numeric-user suites: cache reuse, concurrent builds, failure, cancellation, startup overrides, terminal progress, and four UID/GID cases passed. Cleanup left one current seed, no pending retirements, and no sandboxes. - [x] ShellCheck and installer collision/failure-injection checks; documentation updated. The single-node E2E CI job runs both BuildKit suites with a 2-vCPU, 2048-MiB builder and an 8192-MiB cache. The full Rust integration suite was not rerun during this revision. ## Risks and reviewer notes Concurrent builders multiply resource use. Shared cache access follows the repository's API-key trust boundary. Publication depends on storage throughput; freezing flushes filesystem data but cannot capture application buffers. Review deletion ordering in `src/orchestrator/service.rs` and cache transactions in `src/snapshot/repository/`. ## Checklist - [x] Changes stay within managed builds and their persistent-volume lifecycle. - [x] New behavior has focused regression coverage. - [x] Logs and examples contain no credentials or private registry information. - [x] Schema changes include regenerated bindings. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-29 14:21:52 +00:00