github/kata-containers
1
0
Fork 1
mirror of https://github.com/kata-containers/kata-containers.git synced 2025-06-26 15:32:30 +00:00
Code Issues Projects Releases Wiki Activity

tools: Improve agent-ctl README

Browse Source 
Add a summary to help understand how to use the `agent-ctl` tool.

Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>
This commit is contained in:
James O. D. Hunt 2020-10-15 17:17:23 +01:00
parent edf02af1d4
commit e2221d34bf
1 changed files with 82 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

82
tools/agent-ctl/README.md
View File

@ -3,6 +3,11 @@
* [Overview](#overview)
* [Audience and environment](#audience-and-environment)
* [Full details](#full-details)
* [Code summary](#code-summary)
* [Running the tool](#running-the-tool)
* [Prerequisites](#prerequisites)
* [Connect to a real Kata Container](#connect-to-a-real-kata-container)
* [Run the tool and the agent in the same environment](#run-the-tool-and-the-agent-in-the-same-environment)
## Overview
@ -37,3 +42,80 @@ To see some examples, run:
```sh
$ cargo run -- examples
```
## Code summary
The table below summarises where to look to learn more about both this tool,
the agent protocol and the client and server implementations.
| Description | File | Example RPC or function | Example summary |
|-|-|-|-|
| Protocol buffers definition of the Kata Containers Agent API protocol | [`agent.proto`](../../src/agent/protocols/protos/agent.proto) | `CreateContainer` | API to create a Kata container. |
| Agent Control (client) API calls | [`src/client.rs`](src/client.rs) | `agent_cmd_container_create()` | Agent Control tool function that calls the `CreateContainer` API. |
| Agent (server) API implementations | [`rpc.rs`](../../src/agent/src/rpc.rs) | `create_container()` | Server function that implements the `CreateContainers` API. |
## Running the tool
### Prerequisites
It is necessary to create an OCI bundle to use the tool. The simplest method
is:
```sh
$ bundle_dir="bundle"
$ rootfs_dir="$bundle_dir/rootfs"
$ image="busybox"
$ mkdir -p "$rootfs_dir" && (cd "$bundle_dir" && runc spec)
$ sudo docker export $(sudo docker create "$image") | tar -C "$rootfs_dir" -xvf -
```
### Connect to a real Kata Container
1. Start a Kata Container
1. Establish the VSOCK guest CID number for the virtual machine:
Assuming you are running a single QEMU based Kata Container, you can look
at the program arguments to find the (randomly-generated) `guest-cid=` option
value:
```sh
$ guest_cid=$(ps -ef | grep qemu-system-x86_64 | egrep -o "guest-cid=[^,][^,]*" | cut -d= -f2)
```
1. Run the tool to connect to the agent:
```sh
$ cargo run -- -l debug connect --bundle-dir "${bundle_dir}" --server-address "vsock://${guest_cid}:1024" -c Check -c GetGuestDetails
```
This examples makes two API calls:
- It runs `Check` to see if the agent's RPC server is serving.
- It then runs `GetGuestDetails` to establish some details of the
environment the agent is running in.
### Run the tool and the agent in the same environment
> **Warnings:**
>
> - This method is **only** for testing and development!
> - Only continue if you are using a non-critical system
> (such as a freshly installed VM environment).
1. Start the agent, specifying a local socket for it to communicate on:
```sh
$ sudo KATA_AGENT_SERVER_ADDR=unix:///tmp/foo.socket target/x86_64-unknown-linux-musl/release/kata-agent
```
1. Run the tool in the same environment:
```sh
$ cargo run -- -l debug connect --server-address "unix://@/tmp/foo.socket" --bundle-dir "$bundle_dir" -c Check -c GetGuestDetails
```
> **Note:**
>
> The `@` in the server address is required - it denotes an abstract
> socket which the agent requires (see `unix(7)`).