diff --git a/src/tools/agent-ctl/README.md b/src/tools/agent-ctl/README.md index 8b0369a7c..d9b53ac35 100644 --- a/src/tools/agent-ctl/README.md +++ b/src/tools/agent-ctl/README.md @@ -60,7 +60,6 @@ $ mkdir -p "$rootfs_dir" && (cd "$bundle_dir" && runc spec) $ sudo docker export $(sudo docker create "$image") | tar -C "$rootfs_dir" -xvf - ``` - ### Specify API commands to run The tool allows one or more API commands to be specified using the `-c` or @@ -98,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 @@ -263,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).