[PR #253] [MERGED] fix(sandbox): start OCI images with explicit UID or GID #294

New issue

Closed

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

bsakaguchi commented

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

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/253
Author: @yingdi-shan
Created: 9/7/2026
Status: ✅ Merged
Merged: 9/9/2026
Merged by: @yingdi-shan

Base: main ← Head: fix/oci-numeric-user-startup

📝 Commits (1)

578a854 fix(sandbox): preserve OCI image UID and GID at startup

📊 Changes

4 files changed (+463 additions, -4 deletions)

View changed files

📝 src/sandbox/envd.rs (+64 -2)
➕ src/sandbox/envd/user.rs (+326 -0)
📝 src/template/runner.rs (+2 -2)
📝 tests/integration/process.rs (+71 -0)

📄 Description

What

Start and resume OCI images whose User config specifies a numeric UID or an explicit user/group pair. Resolve the identity to an envd account while preserving the requested UID/GID, image environment, and working directory.

Why

OCI permits numeric identities without a passwd entry, but envd requires an account name. Passing 12345 or 12345:23456 directly to envd can prevent image startup.

Extracted from #247 alongside #252 (volume deletion) and #254 (BuildKit).

Scope and non-goals

Guest identity resolution, privileged internal filesystem maintenance, and regression tests. BuildKit integration and volume-deletion optimization are separate PRs.

Design and behavior changes

Bootstrap authenticated envd as root before account resolution, then apply the final image configuration.
Reuse existing accounts for UID-only identities. Explicit groups and missing numeric users get a separate account preserving UID, GID, and home, reused after snapshot restore without rewriting existing accounts.
Resolve named groups, reject invalid IDs or missing named identities, cap account-file reads at 1 MiB, and bound account setup. Parse account files as bytes and report malformed passwd records with line numbers.
Use the provided BusyBox and explicitly select root for internal filesystem operations independently of the image's default user.

Compatibility and operations

Public API or generated protocol: unchanged.
Configuration or defaults: unchanged; an unknown numeric UID without an explicit group uses GID 0.
Snapshot manifest, artifact layout, or storage format: unchanged. Added guest passwd entries are captured normally.
Upgrade and rollback: no host-state migration; existing guest accounts are preserved.
Host requirements, permissions, ports, or dependencies: unchanged; uses the existing tools drive.

Validation

make fmt
make clippy
make test-unit
Relevant Rust integration tests
Documentation updated (no documentation changes included)

Commands and results:

make fmt clippy: passed
RUST_TEST_THREADS=2 make test-unit: passed, including capability and ublk checks
cargo test -p agentenv --test integration numeric_image_users_preserve_identity_after_start_and_resume -- --nocapture: passed
git diff --check: passed

The VM test ran through the repository capability runner as a non-root user with isolated test state and dependency copies. Unit coverage includes existing and missing UIDs, explicit numeric and named groups, account-name collisions, invalid IDs, non-UTF-8 fields, malformed passwd records, authenticated initialization, and image environment preservation. The VM test discovers named-account IDs from the guest fixture. Validation used CARGO_TARGET_DIR=/tmp/aenv-target. The initial parallel unit run encountered transient ETXTBSY failures in two helper-script tests; both passed individually. A single-thread retry exposed an existing output-marker parsing issue in the network panic-cleanup test; two-thread execution passed that test. Go, code generation, and performance benchmarks do not apply.

Risks and reviewer notes

Review src/sandbox/envd/user.rs. The fix adds passwd entries only when needed and leaves existing accounts intact. The new VM test checks six identities across cold startup and resume without depending on BuildKit.

Checklist

The PR contains one coherent change and no unrelated formatting or refactoring.
New behavior is covered by focused regression tests.
Logs and examples contain no credentials, tokens, or private registry information.
No generated code was manually edited.

_{🔄 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/253 **Author:** [@yingdi-shan](https://github.com/yingdi-shan) **Created:** 9/7/2026 **Status:** ✅ Merged **Merged:** 9/9/2026 **Merged by:** [@yingdi-shan](https://github.com/yingdi-shan) **Base:** `main` ← **Head:** `fix/oci-numeric-user-startup` --- ### 📝 Commits (1) - [`578a854`](https://github.com/kvcache-ai/AgentENV/commit/578a8541b8722622261cdda72964fed9fa89525b) fix(sandbox): preserve OCI image UID and GID at startup ### 📊 Changes **4 files changed** (+463 additions, -4 deletions) <details> <summary>View changed files</summary> 📝 `src/sandbox/envd.rs` (+64 -2) ➕ `src/sandbox/envd/user.rs` (+326 -0) 📝 `src/template/runner.rs` (+2 -2) 📝 `tests/integration/process.rs` (+71 -0) </details> ### 📄 Description ## What Start and resume OCI images whose `User` config specifies a numeric UID or an explicit user/group pair. Resolve the identity to an envd account while preserving the requested UID/GID, image environment, and working directory. ## Why OCI permits numeric identities without a passwd entry, but envd requires an account name. Passing `12345` or `12345:23456` directly to envd can prevent image startup. ## Related issue Extracted from #247 alongside #252 (volume deletion) and #254 (BuildKit). ## Scope and non-goals Guest identity resolution, privileged internal filesystem maintenance, and regression tests. BuildKit integration and volume-deletion optimization are separate PRs. ## Design and behavior changes - Bootstrap authenticated envd as root before account resolution, then apply the final image configuration. - Reuse existing accounts for UID-only identities. Explicit groups and missing numeric users get a separate account preserving UID, GID, and home, reused after snapshot restore without rewriting existing accounts. - Resolve named groups, reject invalid IDs or missing named identities, cap account-file reads at 1 MiB, and bound account setup. Parse account files as bytes and report malformed passwd records with line numbers. - Use the provided BusyBox and explicitly select root for internal filesystem operations independently of the image's default user. ## Compatibility and operations - Public API or generated protocol: unchanged. - Configuration or defaults: unchanged; an unknown numeric UID without an explicit group uses GID 0. - Snapshot manifest, artifact layout, or storage format: unchanged. Added guest passwd entries are captured normally. - Upgrade and rollback: no host-state migration; existing guest accounts are preserved. - Host requirements, permissions, ports, or dependencies: unchanged; uses the existing tools drive. ## Validation - [x] `make fmt` - [x] `make clippy` - [x] `make test-unit` - [x] Relevant Rust integration tests - [ ] Documentation updated (no documentation changes included) Commands and results: ```text make fmt clippy: passed RUST_TEST_THREADS=2 make test-unit: passed, including capability and ublk checks cargo test -p agentenv --test integration numeric_image_users_preserve_identity_after_start_and_resume -- --nocapture: passed git diff --check: passed ``` The VM test ran through the repository capability runner as a non-root user with isolated test state and dependency copies. Unit coverage includes existing and missing UIDs, explicit numeric and named groups, account-name collisions, invalid IDs, non-UTF-8 fields, malformed passwd records, authenticated initialization, and image environment preservation. The VM test discovers named-account IDs from the guest fixture. Validation used `CARGO_TARGET_DIR=/tmp/aenv-target`. The initial parallel unit run encountered transient `ETXTBSY` failures in two helper-script tests; both passed individually. A single-thread retry exposed an existing output-marker parsing issue in the network panic-cleanup test; two-thread execution passed that test. Go, code generation, and performance benchmarks do not apply. ## Risks and reviewer notes Review `src/sandbox/envd/user.rs`. The fix adds passwd entries only when needed and leaves existing accounts intact. The new VM test checks six identities across cold startup and resume without depending on BuildKit. ## Checklist - [x] The PR contains one coherent change and no unrelated formatting or refactoring. - [x] New behavior is covered by focused regression tests. - [x] Logs and examples contain no credentials, tokens, or private registry information. - [x] No generated code was manually edited. --- <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:54 +00:00