kata-containers/src/agent

Kata Agent

Overview

The Kata agent is a long running process that runs inside the Virtual Machine (VM) (also known as the "pod" or "sandbox").

The agent is packaged inside the Kata Containers guest image which is used to boot the VM. Once the runtime has launched the configured hypervisor to create a new VM, the agent is started. From this point on, the agent is responsible for creating and managing the life cycle of the containers inside the VM.

For further details, see the architecture document.

Audience

If you simply wish to use Kata Containers, it is not necessary to understand the details of how the agent operates. Please see the installation documentation for details of how deploy Kata Containers (which will include the Kata agent).

The remainder of this document is only useful for developers and testers.

Build from Source

Since the agent is written in the Rust language this section assumes the tool chain has been installed using standard Rust rustup tool.

Build with musl

If you wish to build the agent with the musl C library, you need to run the following commands:

$ arch=$(uname -m)
$ rustup target add "${arch}-unknown-linux-musl"
$ sudo ln -s /usr/bin/g++ /bin/musl-g++

Note:

It is not currently possible to build using musl on ppc64le and s390x since both platforms lack the musl target.

Build the agent binary

The following steps download the Kata Containers source files and build the agent:

$ GOPATH="${GOPATH:-$HOME/go}"
$ dir="$GOPATH/src/github.com/kata-containers"
$ git -C ${dir} clone --depth 1 https://github.com/kata-containers/kata-containers
$ make -C ${dir}/kata-containers/src/agent

Change the agent API

The Kata runtime communicates with the Kata agent using a ttRPC based API protocol.

This ttRPC API is defined by a set of protocol buffers files. The protocol files are used to generate the bindings for the following components:

Component	Language	Generation method [*]	Tooling required
runtime	Golang	Run, make generate-protocols	protoc
agent	Rust	Run, make

Key:

[*] - All commands must be run in the agent repository.

If you wish to change the API, these files must be regenerated. Although the rust code will be automatically generated by the build script, the Golang code generation requires the external protoc command to be available in $PATH.

To install the protoc command on a Fedora/CentOS/RHEL system:

$ sudo dnf install -y protobuf-compiler

Custom guest image and kernel assets

If you wish to develop or test changes to the agent, you will need to create a custom guest image using the osbuilder tool. You may also wish to create a custom guest kernel.

Once created, configure Kata Containers to use these custom assets to allow you to test your changes.

Note:

To simplify development and testing, you may wish to run the agent stand alone initially.

Tracing

For details of tracing the operation of the agent, see the tracing documentation.

Run the agent stand alone

Although the agent is designed to run in a VM environment, for development and testing purposes it is possible to run it as a normal application.

When run in this way, the agent can be controlled using the low-level Kata agent control tool, rather than the Kata runtime.

For further details, see the agent control tool documentation.

Agent options

The kata agent has the ability to configure agent options in guest kernel command line at runtime. Currently, the following agent options can be configured:

Option	Name	Description	Type	Default
agent.config_file	Configuration file	Allow to configure options through a configuration file from the root filesystem	string	""
agent.container_pipe_size	Container pipe sizes	Allow to configure the stdout or stderr pipe sizes	integer	0
agent.debug_console	Debug console flag	Allow to connect guest OS running inside hypervisor Connect using kata-runtime exec <sandbox-id>	boolean	false
agent.debug_console_vport	Debug console port	Allow to specify the vsock port to connect the debugging console	integer	0
agent.devmode	Developer mode	Allow the agent process to coredump	boolean	false
agent.hotplug_timeout	Hotplug timeout	Allow to configure hotplug timeout(seconds) of block devices	integer	3
agent.https_proxy	HTTPS proxy	Allow to configure https_proxy in the guest	string	""
agent.log	Log level	Allow the agent log level to be changed (produces more or less output)	string	"info"
agent.log_vport	Log port	Allow to specify the vsock port to read logs	integer	0
agent.no_proxy	NO proxy	Allow to configure no_proxy in the guest	string	""
agent.passfd_listener_port	File descriptor passthrough IO listener port	Allow to set the file descriptor passthrough IO listener port	integer	0
agent.server_addr	Server address	Allow the ttRPC server address to be specified	string	"vsock://-1:1024"
agent.trace	Trace mode	Allow to static tracing	boolean	false
agent.unified_cgroup_hierarchy	Cgroup hierarchy	Allow to setup v2 cgroups	boolean	false

Note: Accepted values for some agent options

• agent.config_file: If we enable agent.config_file in guest kernel command line, we will generate the agent config from it. The agent will fail to start if the configuration file is not present, or if it can't be parsed properly.
• agent.devmode: true | false
• agent.hotplug_timeout: a whole number of seconds
• agent.log: "critical"("fatal" | "panic") | "error" | "warn"("warning") | "info" | "debug"
• agent.server_addr: "{VSOCK_ADDR}:{VSOCK_PORT}"
• agent.trace: true | false
• agent.unified_cgroup_hierarchy: true | false

For instance, you can enable the debug console and set the agent log level to debug by configuring the guest kernel command line in the configuration file:

kernel_params = "agent.debug_console agent.log=debug agent.hotplug_timeout=10" 

results in:

{"msg":"announce","level":"INFO","subsystem":"root","version":"0.1.0","pid":"214","source":"agent","name":"kata-agent","config":"AgentConfig { debug_console: true, dev_mode: false, log_level: Debug, hotplug_timeout: 10s, debug_console_vport: 0, log_vport: 0, container_pipe_size: 0, server_addr: "vsock://-1:1024", passfd_listener_port: 0, unified_cgroup_hierarchy: false, tracing: false, supports_seccomp: true }","agent-version":"3.3.0-alpha0"}