mirror of
https://github.com/kata-containers/kata-containers.git
synced 2025-06-26 15:32:30 +00:00
agent: Update README
Update the agent README by removing the historical details about the conversion from golang to rust which (occurred at the start of Kata 2.x development) and replacing it with information that developers and testers should find more useful. Fixes: #3056. Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>
This commit is contained in:
James O. D. Hunt
parent
e34893a0c4
commit
599bc0c2a9
@ -1,48 +1,38 @@
|
|||||||
# Kata Agent in Rust
|
# Kata Agent
|
||||||
|
|
||||||
This is a rust version of the [`kata-agent`](https://github.com/kata-containers/agent).
|
## Overview
|
||||||
|
|
||||||
In Denver PTG, [we discussed about re-writing agent in rust](https://etherpad.openstack.org/p/katacontainers-2019-ptg-denver-agenda):
|
The Kata agent is a long running process that runs inside the Virtual Machine
|
||||||
|
(VM) (also known as the "pod" or "sandbox").
|
||||||
|
|
||||||
> In general, we all think about re-write agent in rust to reduce the footprint of agent. Moreover, Eric mentioned the possibility to stop using gRPC, which may have some impact on footprint. We may begin to do some POC to show how much we could save by re-writing agent in rust.
|
The agent is packaged inside the Kata Containers
|
||||||
|
[guest image](../../docs/design/architecture.md#guest-image)
|
||||||
|
which is used to boot the VM. Once the runtime has launched the configured
|
||||||
|
[hypervisor](../../docs/hypervisors.md) 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.
|
||||||
|
|
||||||
After that, we drafted the initial code here, and any contributions are welcome.
|
For further details, see the
|
||||||
|
[architecture document](../../docs/design/architecture.md).
|
||||||
|
|
||||||
## Features
|
## Audience
|
||||||
|
|
||||||
| Feature | Status |
|
If you simply wish to use Kata Containers, it is not necessary to understand
|
||||||
| :--|:--:|
|
the details of how the agent operates. Please see the
|
||||||
| **OCI Behaviors** |
|
[installation documentation](../../docs/install) for details of how deploy
|
||||||
| create/start containers | :white_check_mark: |
|
Kata Containers (which will include the Kata agent).
|
||||||
| signal/wait process | :white_check_mark: |
|
|
||||||
| exec/list process | :white_check_mark: |
|
|
||||||
| I/O stream | :white_check_mark: |
|
|
||||||
| Cgroups | :white_check_mark: |
|
|
||||||
| Capabilities, `rlimit`, readonly path, masked path, users | :white_check_mark: |
|
|
||||||
| Seccomp | :white_check_mark: |
|
|
||||||
| container stats (`stats_container`) | :white_check_mark: |
|
|
||||||
| Hooks | :white_check_mark: |
|
|
||||||
| **Agent Features & APIs** |
|
|
||||||
| run agent as `init` (mount fs, udev, setup `lo`) | :white_check_mark: |
|
|
||||||
| block device as root device | :white_check_mark: |
|
|
||||||
| Health API | :white_check_mark: |
|
|
||||||
| network, interface/routes (`update_container`) | :white_check_mark: |
|
|
||||||
| File transfer API (`copy_file`) | :white_check_mark: |
|
|
||||||
| Device APIs (`reseed_random_device`, , `online_cpu_memory`, `mem_hotplug_probe`, `set_guet_data_time`) | :white_check_mark: |
|
|
||||||
| VSOCK support | :white_check_mark: |
|
|
||||||
| virtio-serial support | :heavy_multiplication_x: |
|
|
||||||
| OCI Spec validator | :white_check_mark: |
|
|
||||||
| **Infrastructures**|
|
|
||||||
| Debug Console | :white_check_mark: |
|
|
||||||
| Command line | :white_check_mark: |
|
|
||||||
| Tracing | :heavy_multiplication_x: |
|
|
||||||
|
|
||||||
## Getting Started
|
The remainder of this document is only useful for developers and testers.
|
||||||
|
|
||||||
### Build from Source
|
## Build from Source
|
||||||
The rust-agent needs to be built statically and linked with `musl`
|
|
||||||
|
|
||||||
> **Note:** skip this step for ppc64le, the build scripts explicitly use gnu for ppc64le.
|
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:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
$ arch=$(uname -m)
|
$ arch=$(uname -m)
|
||||||
@ -50,12 +40,15 @@ $ rustup target add "${arch}-unknown-linux-musl"
|
|||||||
$ sudo ln -s /usr/bin/g++ /bin/musl-g++
|
$ sudo ln -s /usr/bin/g++ /bin/musl-g++
|
||||||
```
|
```
|
||||||
|
|
||||||
ppc64le-only: Manually install `protoc`, e.g.
|
> **Note:**
|
||||||
```bash
|
>
|
||||||
$ sudo dnf install protobuf-compiler
|
> 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:
|
||||||
|
|
||||||
Download the source files in the Kata containers repository and build the agent:
|
|
||||||
```bash
|
```bash
|
||||||
$ GOPATH="${GOPATH:-$HOME/go}"
|
$ GOPATH="${GOPATH:-$HOME/go}"
|
||||||
$ dir="$GOPATH/src/github.com/kata-containers"
|
$ dir="$GOPATH/src/github.com/kata-containers"
|
||||||
@ -63,17 +56,56 @@ $ git -C ${dir} clone --depth 1 https://github.com/kata-containers/kata-containe
|
|||||||
$ make -C ${dir}/kata-containers/src/agent
|
$ make -C ${dir}/kata-containers/src/agent
|
||||||
```
|
```
|
||||||
|
|
||||||
## Run Kata CI with rust-agent
|
## Change the agent API
|
||||||
* Firstly, install Kata as noted by ["how to install Kata"](../../docs/install/README.md)
|
|
||||||
* Secondly, build your own Kata initrd/image following the steps in ["how to build your own initrd/image"](../../docs/Developer-Guide.md#create-and-install-rootfs-and-initrd-image).
|
The Kata runtime communicates with the Kata agent using a ttRPC based API protocol.
|
||||||
notes: Please use your rust agent instead of the go agent when building your initrd/image.
|
|
||||||
* Clone the Kata CI test cases from: https://github.com/kata-containers/tests.git, and then run the CRI test with:
|
This ttRPC API is defined by a set of [protocol buffers files](protocols/protos).
|
||||||
|
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` | |
|
||||||
|
|
||||||
|
If you wish to change the API, these files must be regenerated. Although the
|
||||||
|
rust code will be automatically generated by the
|
||||||
|
[build script](protocols/build.rs),
|
||||||
|
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:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
$sudo -E PATH=$PATH -E GOPATH=$GOPATH integration/containerd/shimv2/shimv2-tests.sh
|
$ sudo dnf install -y protobuf-compiler
|
||||||
```
|
```
|
||||||
|
|
||||||
## Mini Benchmark
|
## Custom guest image and kernel assets
|
||||||
The memory of `RssAnon` consumed by the go-agent and rust-agent as below:
|
|
||||||
go-agent: about 11M
|
If you wish to develop or test changes to the agent, you will need to create a
|
||||||
rust-agent: about 1.1M
|
custom guest image using the [osbuilder tool](../../tools/osbuilder). You
|
||||||
|
may also wish to create a custom [guest kernel](../../tools/packaging/kernel).
|
||||||
|
|
||||||
|
Once created, [configure](../runtime/README.md#configuration) 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](#run-the-agent-stand-alone) initially.
|
||||||
|
|
||||||
|
## Tracing
|
||||||
|
|
||||||
|
For details of tracing the operation of the agent, see the
|
||||||
|
[tracing documentation](../../docs/tracing.md).
|
||||||
|
|
||||||
|
## 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](../../tools/agent-ctl/README.md#run-the-tool-and-the-agent-in-the-same-environment).
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user