[PR #87] [MERGED] feat: support PVM-backed deployment #170

New issue

Closed

opened 2026-10-29 14:20:36 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 14:20:36 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/87
Author: @LSX-s-Software
Created: 7/30/2026
Status: ✅ Merged
Merged: 8/4/2026
Merged by: @yingdi-shan

Base: main ← Head: feat/pvm

📝 Commits (3)

c6c515c feat: support pvm-backed deployment
5df1073 docs(deploy): add warning for PVM deployment
e9e0a2b ci: deploy multi-version documentation

📊 Changes

54 files changed (+1393 additions, -118 deletions)

View changed files

📝 .github/workflows/docs.yml (+149 -20)
📝 .github/workflows/release.yml (+64 -33)
📝 CLAUDE.md (+4 -4)
📝 README.md (+4 -0)
📝 config/default.toml (+5 -1)
📝 config/deps_manifest.toml (+10 -3)
📝 config/oss_default.toml (+4 -1)
📝 crates/e2e-tests/tests/snapshot_oss_e2e_test.rs (+4 -0)
📝 deploy/docker-compose.yml (+1 -0)
📝 deploy/docker/Dockerfile.agentenv (+6 -0)
📝 deploy/k8s/base/agentenv-daemonset.yaml (+2 -0)
📝 docs/book.toml (+2 -0)
➕ docs/redirects/index.html (+15 -0)
📝 docs/src/SUMMARY.md (+1 -0)
📝 docs/src/configuration/env-vars.md (+1 -0)
📝 docs/src/configuration/reference.md (+7 -2)
📝 docs/src/deployment/docker-compose.md (+4 -0)
📝 docs/src/deployment/docker.md (+4 -0)
📝 docs/src/deployment/kubernetes.md (+5 -1)
📝 docs/src/deployment/manual-compile.md (+3 -0)

...and 34 more files

📄 Description

What

Add an opt-in PVM virtualization mode alongside the existing KVM deployment path.

Add virtualization_mode = "kvm" | "pvm" with AENV_VIRTUALIZATION_MODE override.
Select mode-specific Firecracker and guest-kernel dependencies during provisioning.
Validate the host mode and /dev/kvm prerequisites at startup.
Persist the virtualization mode in snapshots and paused-sandbox records and reject cross-mode restore.
Publish separate PVM Docker and server-bundle variants while retaining the existing KVM names.
Add installer support and a dedicated PVM deployment guide, including matching host-kernel DEB/RPM packages.
Deploy multiple versions of the documentation so that the documentation for each release version and the main branch can coexist.

Why

Cloud VMs often do not expose nested virtualization, which prevents the standard KVM deployment from running. PVM provides an alternative deployment path for those environments while keeping standard KVM as the default and recommended mode.

Closes #7

Scope and non-goals

Included:

Node-level KVM/PVM mode selection.
Mode-aware dependency provisioning, host checks, persistence compatibility, release assets, installer behavior, and documentation.
Initial PVM support for x86_64.

Not included:

Installing or automatically loading the PVM host kernel/module.
Cross-mode snapshot or paused-sandbox conversion.
Mixing KVM and PVM nodes for the same persisted workload.

Design and behavior changes

VirtualizationMode is a shared domain type used by configuration, setup, snapshots, and persistence.
The dependency manifest now has symmetric firecracker.{kvm,pvm} and kernel.{kvm,pvm} entries; only the active variant is provisioned.
KVM startup rejects a loaded kvm_pvm module. PVM startup requires x86_64, kvm_pvm, and read/write access to /dev/kvm.
--setup-only remains host-module independent so release artifacts can be assembled on ordinary CI runners.
Legacy snapshots and paused records deserialize as KVM; new records persist their explicit mode.
Release artifacts are:
- aenv-server-linux-x86_64.tar.gz for KVM
- aenv-server-linux-x86_64-pvm.tar.gz for PVM
- latest / version tags for KVM images
- latest-pvm / version-pvm tags for PVM images

Compatibility and operations

Public API or generated protocol: No API or generated protocol changes.
Configuration or defaults: Adds virtualization_mode; default remains kvm.
Snapshot manifest, artifact layout, or storage format: Adds virtualization_mode to committed snapshot metadata and paused-sandbox records. Legacy records default to KVM.
Upgrade and rollback: Existing KVM state remains readable in KVM mode. KVM and PVM state is intentionally not interchangeable.
Host requirements, permissions, ports, or dependencies: PVM is x86_64-only and requires a compatible PVM host kernel with CONFIG_KVM_PVM, plus an ABI-compatible guest kernel with CONFIG_PVM_GUEST. AgentENV does not install the host kernel automatically.

Validation

make fmt
make clippy
make test-unit
Relevant Rust integration tests
make -C services test (required when services/ changes)
Generated clients/server regenerated with the documented make target
Documentation updated
Benchmarks or performance comparison completed

Commands and results:

make fmt
make clippy
make test-unit
cargo test -p agentenv --lib setup::kvm::tests -- --nocapture
cargo test -p agentenv --lib setup::deps::tests::pvm_placeholders_fail_before_download -- --nocapture
bash scripts/tests/verify-install-service.sh

All completed successfully. Release, Compose, and Kubernetes YAML files were also parsed successfully, and local Markdown links were checked.

Skipped checks and reasons:

make -C services test was not required because no Go service code changed.
Generated clients/server were not regenerated because no OpenAPI or generated protocol source changed.
Benchmarks were not run because this change does not target runtime performance.

Risks and reviewer notes

PVM depends on a non-mainline host kernel and requires explicit operator setup.
Host and guest PVM kernels must be ABI-compatible. The packaged guest is based on Linux 6.12.33; matching host-kernel DEB/RPM packages are published from kvcache-ai/linux.
Reviewers should focus on mode selection in src/cfg.rs and src/setup/, compatibility checks in snapshot/persistence code, release packaging, and the deployment guide.

Checklist

The PR contains one coherent change and no unrelated formatting or refactoring.
New behavior is covered by tests, or I explained why testing is impractical.
Logs and examples contain no credentials, tokens, or private registry information.
I did not manually edit generated code without updating its source and regenerating it.

_{🔄 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/87 **Author:** [@LSX-s-Software](https://github.com/LSX-s-Software) **Created:** 7/30/2026 **Status:** ✅ Merged **Merged:** 8/4/2026 **Merged by:** [@yingdi-shan](https://github.com/yingdi-shan) **Base:** `main` ← **Head:** `feat/pvm` --- ### 📝 Commits (3) - [`c6c515c`](https://github.com/kvcache-ai/AgentENV/commit/c6c515c0f9690cb5f6e61afc0de617c225bee335) feat: support pvm-backed deployment - [`5df1073`](https://github.com/kvcache-ai/AgentENV/commit/5df1073bc078d01b597ef26c051c043a9d24f1a9) docs(deploy): add warning for PVM deployment - [`e9e0a2b`](https://github.com/kvcache-ai/AgentENV/commit/e9e0a2b8b9ef939912f6671ccf2503eabd3341e3) ci: deploy multi-version documentation ### 📊 Changes **54 files changed** (+1393 additions, -118 deletions) <details> <summary>View changed files</summary> 📝 `.github/workflows/docs.yml` (+149 -20) 📝 `.github/workflows/release.yml` (+64 -33) 📝 `CLAUDE.md` (+4 -4) 📝 `README.md` (+4 -0) 📝 `config/default.toml` (+5 -1) 📝 `config/deps_manifest.toml` (+10 -3) 📝 `config/oss_default.toml` (+4 -1) 📝 `crates/e2e-tests/tests/snapshot_oss_e2e_test.rs` (+4 -0) 📝 `deploy/docker-compose.yml` (+1 -0) 📝 `deploy/docker/Dockerfile.agentenv` (+6 -0) 📝 `deploy/k8s/base/agentenv-daemonset.yaml` (+2 -0) 📝 `docs/book.toml` (+2 -0) ➕ `docs/redirects/index.html` (+15 -0) 📝 `docs/src/SUMMARY.md` (+1 -0) 📝 `docs/src/configuration/env-vars.md` (+1 -0) 📝 `docs/src/configuration/reference.md` (+7 -2) 📝 `docs/src/deployment/docker-compose.md` (+4 -0) 📝 `docs/src/deployment/docker.md` (+4 -0) 📝 `docs/src/deployment/kubernetes.md` (+5 -1) 📝 `docs/src/deployment/manual-compile.md` (+3 -0) _...and 34 more files_ </details> ### 📄 Description ## What Add an opt-in PVM virtualization mode alongside the existing KVM deployment path. - Add `virtualization_mode = "kvm" | "pvm"` with `AENV_VIRTUALIZATION_MODE` override. - Select mode-specific Firecracker and guest-kernel dependencies during provisioning. - Validate the host mode and `/dev/kvm` prerequisites at startup. - Persist the virtualization mode in snapshots and paused-sandbox records and reject cross-mode restore. - Publish separate PVM Docker and server-bundle variants while retaining the existing KVM names. - Add installer support and a dedicated PVM deployment guide, including matching host-kernel DEB/RPM packages. - Deploy multiple versions of the documentation so that the documentation for each release version and the main branch can coexist. ## Why Cloud VMs often do not expose nested virtualization, which prevents the standard KVM deployment from running. PVM provides an alternative deployment path for those environments while keeping standard KVM as the default and recommended mode. ## Related issue Closes #7 ## Scope and non-goals Included: - Node-level KVM/PVM mode selection. - Mode-aware dependency provisioning, host checks, persistence compatibility, release assets, installer behavior, and documentation. - Initial PVM support for x86_64. Not included: - Installing or automatically loading the PVM host kernel/module. - Cross-mode snapshot or paused-sandbox conversion. - Mixing KVM and PVM nodes for the same persisted workload. ## Design and behavior changes - `VirtualizationMode` is a shared domain type used by configuration, setup, snapshots, and persistence. - The dependency manifest now has symmetric `firecracker.{kvm,pvm}` and `kernel.{kvm,pvm}` entries; only the active variant is provisioned. - KVM startup rejects a loaded `kvm_pvm` module. PVM startup requires x86_64, `kvm_pvm`, and read/write access to `/dev/kvm`. - `--setup-only` remains host-module independent so release artifacts can be assembled on ordinary CI runners. - Legacy snapshots and paused records deserialize as KVM; new records persist their explicit mode. - Release artifacts are: - `aenv-server-linux-x86_64.tar.gz` for KVM - `aenv-server-linux-x86_64-pvm.tar.gz` for PVM - `latest` / version tags for KVM images - `latest-pvm` / version-`pvm` tags for PVM images ## Compatibility and operations - Public API or generated protocol: No API or generated protocol changes. - Configuration or defaults: Adds `virtualization_mode`; default remains `kvm`. - Snapshot manifest, artifact layout, or storage format: Adds `virtualization_mode` to committed snapshot metadata and paused-sandbox records. Legacy records default to KVM. - Upgrade and rollback: Existing KVM state remains readable in KVM mode. KVM and PVM state is intentionally not interchangeable. - Host requirements, permissions, ports, or dependencies: PVM is x86_64-only and requires a compatible PVM host kernel with `CONFIG_KVM_PVM`, plus an ABI-compatible guest kernel with `CONFIG_PVM_GUEST`. AgentENV does not install the host kernel automatically. ## Validation - [x] `make fmt` - [x] `make clippy` - [x] `make test-unit` - [x] Relevant Rust integration tests - [ ] `make -C services test` (required when `services/` changes) - [ ] Generated clients/server regenerated with the documented `make` target - [x] Documentation updated - [ ] Benchmarks or performance comparison completed Commands and results: ```text make fmt make clippy make test-unit cargo test -p agentenv --lib setup::kvm::tests -- --nocapture cargo test -p agentenv --lib setup::deps::tests::pvm_placeholders_fail_before_download -- --nocapture bash scripts/tests/verify-install-service.sh ``` All completed successfully. Release, Compose, and Kubernetes YAML files were also parsed successfully, and local Markdown links were checked. Skipped checks and reasons: - `make -C services test` was not required because no Go service code changed. - Generated clients/server were not regenerated because no OpenAPI or generated protocol source changed. - Benchmarks were not run because this change does not target runtime performance. ## Risks and reviewer notes - PVM depends on a non-mainline host kernel and requires explicit operator setup. - Host and guest PVM kernels must be ABI-compatible. The packaged guest is based on Linux 6.12.33; matching host-kernel DEB/RPM packages are published from `kvcache-ai/linux`. - Reviewers should focus on mode selection in `src/cfg.rs` and `src/setup/`, compatibility checks in snapshot/persistence code, release packaging, and the deployment guide. ## Checklist - [x] The PR contains one coherent change and no unrelated formatting or refactoring. - [x] New behavior is covered by tests, or I explained why testing is impractical. - [x] Logs and examples contain no credentials, tokens, or private registry information. - [x] I did not manually edit generated code without updating its source and regenerating it. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-29 14:20:36 +00:00