Skip to main content

Module kata_agent

Module kata_agent 

Source
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 as hvsock://<path>, matching the Hypervisor trait already used by KataBackend.
  • Firecracker/Dragonball use real AF_VSOCK (vsock://<cid>:<port>), dialed via socket(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§

ContainerRootfs
How the container’s rootfs is provided to the guest.
KataAgentClient
A connected kata-agent ttrpc client.

Enums§

AgentAddress
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.