github/kata-containers
1
0
Fork 1
mirror of https://github.com/kata-containers/kata-containers.git synced 2025-06-23 14:08:31 +00:00
Code Issues Projects Releases Wiki Activity

docs: Add agent-ctl examples section

Browse Source 
Add a new `Examples` section to the `agent-ctl` docs giving some
examples of how to use the tool with QEMU and stand-alone.

Fixes: #4414.

Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>
This commit is contained in:
James O. D. Hunt 2022-06-07 14:56:22 +01:00
parent 815157bf02
commit 34bcef8846
1 changed files with 122 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

125
src/tools/agent-ctl/README.md
View File

@ -97,10 +97,11 @@ An example showing how to specify the messages fields for an API call
$ cargo run -- -l debug connect --server-address "unix://@/tmp/foo.socket" --bundle-dir "$bundle_dir" -c Check -c 'GetGuestDetails json://{"mem_block_size": true, "mem_hotplug_probe": true}'
```
> **Note:**
> **Notes:**
>
> For details of the names of the APIs to call and the available fields
> in each API, see the [Code Summary](#code-summary) section.
> - For details of the names of the APIs to call and the available fields
> in each API, see the [Code Summary](#code-summary) section.
> - For further examples, see the [Examples](#examples) section.
### Connect to a real Kata Container
@ -262,3 +263,121 @@ running.
$ cargo run -- -l debug connect --server-address "vsock://${vsock_loopback_cid}:${agent_vsock_port}" --bundle-dir "$bundle_dir" -c Check -c GetGuestDetails
```
## Examples
### QEMU examples
The following examples assume you have:
- Configure Kata Containers to use QEMU.
- Created a container using a command such as this:
```bash
$ container_id="foo"
$ sudo ctr --debug run --runtime "io.containerd.kata.v2" --rm -t "quay.io/prometheus/busybox:latest" "$container_id" sh
```
#### Check the agent is running with QEMU
```bash
$ cargo run -- -l trace connect --no-auto-values --bundle-dir "${bundle_dir}" --server-address "vsock://${guest_cid}:${agent_vsock_port}" -c Check
```
#### Show guest environment details with QEMU
```bash
$ cargo run -- -l trace connect --no-auto-values --bundle-dir "${bundle_dir}" --server-address "vsock://${guest_cid}:${agent_vsock_port}" -c GetGuestDetails
```
#### Show sandbox metrics with QEMU
```bash
$ cargo run -- -l trace connect --no-auto-values --bundle-dir "${bundle_dir}" --server-address "vsock://${guest_cid}:${agent_vsock_port}" -c GetMetrics
```
#### Show container statistics with QEMU
```bash
$ cargo run -- -l trace connect --no-auto-values --bundle-dir "${bundle_dir}" --server-address "vsock://${guest_cid}:${agent_vsock_port}" -c "StatsContainer json://{\"container_id\": \"${container_id}\"}"
```
#### Pause a running container with QEMU
```bash
$ cargo run -- -l trace connect --no-auto-values --bundle-dir "${bundle_dir}" --server-address "vsock://${guest_cid}:${agent_vsock_port}" -c "PauseContainer json://{\"container_id\": \"$container_id\"}"
```
#### Resume a paused container with QEMU
```bash
$ cargo run -- -l trace connect --no-auto-values --bundle-dir "${bundle_dir}" --server-address "vsock://${guest_cid}:${agent_vsock_port}" -c "ResumeContainer json://{\"container_id\": \"$container_id\"}"
```
#### Destroy a running container with QEMU
```bash
$ cargo run -- -l trace connect --no-auto-values --bundle-dir "${bundle_dir}" --server-address "vsock://${guest_cid}:${agent_vsock_port}" -c "RemoveContainer json://{\"container_id\": \"$container_id\"}"
```
> **Note:**
>
> Only run this on a test or development system!
#### Destroy a running sandbox with QEMU
```bash
$ cargo run -- -l trace connect --no-auto-values --bundle-dir "${bundle_dir}" --server-address "vsock://${guest_cid}:${agent_vsock_port}" -c 'DestroySandbox'
```
> **Notes:**
>
> - Only run this on a test or development system!
> - This will destroy the sandbox and all resources associated with it
> (including all containers and the VM that hosts the agent).
> - You cannot create a sandbox this way since the Kata Containers
> runtime and agent will already have created one inside the QEMU
> VM.
>
> See [Create a sandbox manually](#create-a-sandbox-manually).
### Local examples
> **Note:**
>
> These examples assume you have
> [already started the agent manually](#use-a-unix-abstract-domain-socket).
#### Create a sandbox manually
```bash
$ sandbox_id="foo"
# Critical to clear up from any previous run
$ sudo umount /run/sandbox-ns/*
$ server_addr='unix://@/tmp/foo.socket'
$ cargo run -- -l trace connect --no-auto-values --bundle-dir "${bundle_dir}" --server-address "${server_addr}" -c "CreateSandbox json://{\"sandbox_id\": \"$sandbox_id\"}"
```
> **Note:**
>
> Although it should be possible to create a container inside the
> sandbox, this is difficult since the JSON `CreateContainer` request
> must include an OCI configuration file specification in (quoted)
> JSON format.
#### Delete a sandbox manually
```bash
$ sandbox_id="foo"
$ server_addr='unix://@/tmp/foo.socket'
$ cargo run -- -l trace connect --no-auto-values --bundle-dir "${bundle_dir}" --server-address "${server_addr}" -c DestroySandbox
```
> **Note:**
>
> No parameters are required for the `DestroySandbox` API call
> (since only a single sandbox can be created).