ci: Add workflow to run kata-agent api tests using kata-agent-ctl

enable CI to add test cases for testing kata-agent APIs. This commit
introduces:
- a workflow to run tests
- setup scripts to prepare the test environment

Fixes #10262

Signed-off-by: Sumedh Alok Sharma <sumsharma@microsoft.com>

.github/workflows/basic-ci-amd64.yaml

@@ -345,3 +345,34 @@ jobs:
           name: nerdctl-tests-garm-${{ matrix.vmm }}
           path: /tmp/artifacts
           retention-days: 1
+
+  run-kata-agent-apis:
+    strategy:
+      fail-fast: false
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.commit-hash }}
+          fetch-depth: 0
+
+      - name: Rebase atop of the latest target branch
+        run: |
+          ./tests/git-helper.sh "rebase-atop-of-the-latest-target-branch"
+        env:
+          TARGET_BRANCH: ${{ inputs.target-branch }}
+
+      - name: Install dependencies
+        run: bash tests/functional/kata-agent-apis/gha-run.sh install-dependencies
+
+      - name: get-kata-tarball
+        uses: actions/download-artifact@v3
+        with:
+          name: kata-static-tarball-amd64${{ inputs.tarball-suffix }}
+          path: kata-artifacts
+
+      - name: Install kata
+        run: bash tests/functional/kata-agent-apis/gha-run.sh install-kata kata-artifacts
+
+      - name: Run kata agent api tests with agent-ctl
+        run: bash tests/functional/kata-agent-apis/gha-run.sh run

tests/functional/kata-agent-apis/gha-run.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+
+# Copyright (c) 2024 Microsoft Corporation
+#
+# SPDX-License-Identifier: Apache-2.0
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+kata_tarball_dir="${2:-kata-artifacts}"
+kata_agent_apis_dir="$(dirname "$(readlink -f "$0")")"
+source "${kata_agent_apis_dir}/../../common.bash"
+
+function install_dependencies() {
+	info "Installing dependencies needed for testing individual agent apis using agent-ctl"
+
+	# Dependency list of projects that we can rely on the system packages
+	# - jq
+	declare -a deps=(
+		jq
+	)
+
+	sudo apt-get update
+	sudo apt-get -y install "${deps[@]}"
+}
+
+function run() {
+	exit 0
+}
+
+function main() {
+	action="${1:-}"
+	case "${action}" in
+		install-dependencies) install_dependencies ;;
+		install-kata) install_kata ;;
+		run) run ;;
+		*) >&2 die "Invalid argument" ;;
+	esac
+}
+
+main "$@"

tests/functional/kata-agent-apis/run-agent-api-tests.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+
+# Copyright (c) 2024 Microsoft Corporation
+#
+# SPDX-License-Identifier: Apache-2.0
+
+set -e
+
+kata_agent_apis_dir="$(dirname "$(readlink -f "$0")")"
+source "${kata_agent_apis_dir}/../../common.bash"
+source "${kata_agent_apis_dir}/setup_common.sh"
+
+usage()
+{
+	cat <<EOF
+
+Usage: $script_name [<command>]
+
+Summary: Test agent ttrpc apis using agent-ctl tool.
+
+Description: Test agent exposed ttrpc api endpoints using agent-ctl tool.
+A number of variations of the inputs are used to test an inidividual api
+to validate success & failure code paths.
+
+Commands:
+
+  help   - Show usage.
+
+Notes:
+  - Currently, the script *does not support* running individual agent api tests.
+
+EOF
+}
+
+run_tests() {
+    info "placeholder: no tests"
+}
+
+main()
+{
+	local cmd="${1:-}"
+
+	case "$cmd" in
+		help|-h|-help|--help) usage; exit 0;;
+	esac
+
+	trap cleanup EXIT
+
+	setup_agent
+
+	run_tests
+}
+
+main "$@"

tests/functional/kata-agent-apis/setup_common.sh

@@ -0,0 +1,175 @@
+#!/bin/bash
+
+# Copyright (c) 2024 Microsoft Corporation
+#
+# SPDX-License-Identifier: Apache-2.0
+
+set -o errexit
+set -o nounset
+set -o pipefail
+set -o errtrace
+
+# 1. Setup: start kata-agent as an individual process listening on the default port
+# 2. Use a bats script to run all tests
+# 3. Collect logs if possible (look into this to validate success/failures)
+# 4. handle errors/exit in cleanup to remove all mounts, etc.
+# The agent process runs locally as a standalone process for now.
+
+agent_binary="/usr/bin/kata-agent"
+agent_ctl_path="/opt/kata/bin/kata-agent-ctl"
+
+# Name of socket file used by a local agent.
+agent_socket_file="/tmp/kata-agent.socket"
+
+# Kata Agent socket URI.
+local_agent_server_addr="unix://@${agent_socket_file}"
+
+# Log file that contains agent ctl output
+ctl_log_file="${PWD}/agent-ctl.log"
+# Log file that contains agent output.
+agent_log_file="${PWD}/kata-agent.log"
+
+agent_log_level="debug"
+keep_logs=false
+
+cleanup()
+{
+	info "cleaning resources..."
+
+	local failure_ret="$?"
+
+	stop_agent
+
+	local sandbox_dir="/run/sandbox-ns/"
+	sudo umount -f "${sandbox_dir}/uts" "${sandbox_dir}/ipc" &>/dev/null || true
+	sudo rm -rf "${sandbox_dir}" &>/dev/null || true
+
+	if [ "$failure_ret" -eq 0 ] && [ "$keep_logs" = 'true' ]
+	then
+		info "SUCCESS: Test passed, but leaving logs:"
+		info ""
+		info "agent log file       : ${agent_log_file}"
+		info "agent-ctl log file   : ${ctl_log_file}"
+		return 0
+	fi
+
+	if [ $failure_ret -ne 0 ]; then
+		warn "ERROR: Test failed"
+		warn ""
+		warn "Not cleaning up to help debug failure:"
+		warn ""
+
+		info "agent-ctl log file   : ${ctl_log_file}"
+		info "agent log file       : ${agent_log_file}"
+		return 0
+	fi
+
+	sudo rm -f \
+		"$agent_log_file" \
+		"$ctl_log_file"
+}
+
+run_agent_ctl()
+{
+	local cmds="${1:-}"
+
+	[ -n "$cmds" ] || die "need commands for agent control tool"
+
+	local redirect="&>\"${ctl_log_file}\""
+
+	local server_address="--server-address ${local_agent_server_addr}"
+
+	eval \
+		sudo \
+		RUST_BACKTRACE=full \
+		"${agent_ctl_path}" \
+		-l debug \
+		connect \
+		${server_address} \
+		${cmds} \
+		${redirect}
+}
+
+get_agent_pid()
+{
+	local pids
+
+	local name
+	name=$(basename "$agent_binary")
+
+	pids=$(pgrep "$name" || true)
+	[ -z "$pids" ] && return 0
+
+	local count
+	count=$(echo "$pids"|wc -l)
+
+	[ "$count" -gt 1 ] && \
+		die "too many agent processes running ($count, '$pids')"
+
+	echo $pids
+}
+
+check_agent_alive()
+{
+	local cmds=()
+
+	cmds+=("-c Check")
+
+	run_agent_ctl \
+		"${cmds[@]}"
+}
+
+wait_for_agent_to_start()
+{
+	local cmd="check_agent_alive"
+
+	local wait_time_secs=20
+	local sleep_time_secs=1
+
+	info "Waiting for agent process to start.."
+
+	waitForProcess \
+		"$wait_time_secs" \
+		"$sleep_time_secs" \
+		"$cmd"
+
+	info "Kata agent process running."
+}
+
+stop_agent() {
+	info "Stopping agent"
+	local cmds=()
+	cmds+=("-c DestroySandbox")
+	run_agent_ctl \
+		"${cmds[@]}"
+}
+
+start_agent()
+{
+	local log_file="${1:-}"
+	[ -z "$log_file" ] && die "need agent log file"
+
+	local running
+	running=$(get_agent_pid || true)
+
+	[ -n "$running" ] && die "agent already running: '$running'"
+
+	eval \
+		sudo \
+			RUST_BACKTRACE=full \
+			KATA_AGENT_LOG_LEVEL=${agent_log_level} \
+			KATA_AGENT_SERVER_ADDR=${local_agent_server_addr} \
+			${agent_binary} \
+			&> ${log_file} \
+			&
+
+    wait_for_agent_to_start
+}
+
+setup_agent() {
+	info "Starting a single kata agent process."
+
+	start_agent $agent_log_file
+
+	info "Setup done."
+}