Expand description
kata-agent ttrpc/vsock client — T1-C (#344) of the Worker GA epic (#341)
Implements a real client for the kata-agent running inside a Kata
guest VM, so KataBackend::exec_sync
can create/start/exec a container inside the VM instead of returning the
historical “not supported” error.
§Wire protocol: REAL, not hand-rolled
The ttrpc request/response message types ([protocols::agent],
[protocols::oci]) and the generated async ttrpc client
([protocols::agent_ttrpc_async::AgentServiceClient]) come from the
protocols crate, which is vendored verbatim from the upstream
kata-containers Rust workspace (src/libs/protocols, tag matching our
kata-hypervisor dependency). It is already present in our dependency
graph transitively (kata-hypervisor depends on protocols with the
async ttrpc feature enabled) — this module simply adds it as a direct
dependency and uses it, rather than reimplementing the kata-agent
protobuf/ttrpc wire format by hand. The CreateContainer / StartContainer
/ ExecProcess / WaitProcess RPCs used below are the real generated
client methods (agent_ttrpc_async.rs), framed and (de)serialized by the
real ttrpc crate (ttrpc::r#async::Client).
What IS hand-written here: the hybrid-vsock transport dialer
(connecting to the guest’s kata-agent listen socket and handing the
connected stream to ttrpc::r#async::Client::new), and the mapping from our
SandboxBackend::exec_sync shape to the agent RPC sequence. This mirrors
(does not vendor) the dialer in upstream
runtime-rs/crates/agent/src/sock/{vsock,hybrid_vsock}.rs.
§Connection convention (verified against upstream kata-containers source,
tag 4.0.0, fetched into the local cargo git checkout cache — see
~/.cargo/git/checkouts/kata-containers-*/*/src/runtime-rs/crates/agent/src/sock/)
- Cloud Hypervisor (the only hypervisor this crate wires up — see
kata_backend.rs) exposes the kata-agent over hybrid vsock: a Unix domain socket at<sandbox_dir>/ch-vm.sock(hypervisor::ch::utils::get_vsock_path), where the host writes"connect <port>\n"and expects a response line containing"OK"before the same stream becomes the ttrpc transport (runtime-rs/crates/agent/src/sock/hybrid_vsock.rs::connect_helper).kata_hypervisor::Hypervisor::get_agent_socket()returns this address ashvsock://<path>, matching theHypervisortrait already used byKataBackend. - Firecracker/Dragonball use real
AF_VSOCK(vsock://<cid>:<port>), dialed viasocket(AF_VSOCK) + connect(VsockAddr{cid, port})(runtime-rs/crates/agent/src/sock/vsock.rs). We don’t boot these hypervisors yet, but the dialer below supports the scheme for parity. - The kata-agent’s default ttrpc listen port is 1024
(
src/runtime/virtcontainers/hypervisor.go: vSockPort = 1024), used whenever a caller doesn’t override it.
§What’s REAL vs what’s UNVALIDATED in this pass
REAL: the message types, the ttrpc client/wire framing, the hybrid-vsock
handshake implementation, and the RPC sequencing
(CreateContainer → StartContainer → ExecProcess → WaitProcess (→
ReadStdout/ReadStderr)). Unit tests in this module run a real
ttrpc::r#async::Server (the same crate a real kata-agent links against)
bound to a Unix socket, with a minimal AgentService impl that returns
canned responses — so the request encoding / response decoding is
exercised through the genuine ttrpc+protobuf wire path, not mocked at the
byte level.
UNVALIDATED (this sandbox has no bootable kata-agent guest image): that a
real kata-agent’s CreateContainer/ExecProcess semantics (OCI bundle
layout expectations, namespace/cgroup setup it performs) are satisfied by
the minimal oci::Spec this module constructs. The CreateContainerRequest.OCI
field needs a real OCI runtime spec (rootfs, mounts, namespaces) wired up
from PodSandbox/container config — this module supplies a minimal
placeholder Spec sufficient to exercise the RPC, not a complete OCI bundle
translation (that’s a larger follow-up, see build_minimal_spec).
§Exit-value structuring (issue #608 / future #610)
exec_sync’s return shape (exit_code, stdout, stderr) is built from
WaitProcessResponse.status (a real terminal exit code from the guest
agent) plus drained ReadStdout/ReadStderr output — i.e. the exit code
is already a true terminal value by construction, not synthesized. A
future /exec/instances/<id>/exit projection (#610) can latch directly
onto the (i32, Vec<u8>, Vec<u8>) returned by KataAgentClient::exec
without restructuring this client.
Structs§
- Container
Rootfs - How the container’s rootfs is provided to the guest.
- Kata
Agent Client - A connected kata-agent ttrpc client.
Enums§
- Agent
Address - A parsed kata-agent connection address.
Constants§
- KATA_
AGENT_ VSOCK_ PORT - Default kata-agent ttrpc vsock port.
Functions§
- dial
- Dial the kata-agent’s ttrpc socket and wrap its connected stream.