feat(examples): add tiny smoke assets and validation

Author: syscod3

.github/workflows/test.yml

@@ -5,9 +5,20 @@ on:
   pull_request:
 
 jobs:
+  tiny-smoke-assets:
+    name: Validate tiny smoke assets
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone the code
+        uses: actions/checkout@v6
+
+      - name: Verify tiny smoke example
+        run: ./hack/verify-tiny-smoke.sh
+
   test:
     name: Run on Ubuntu
     runs-on: ubuntu-latest
+    needs: tiny-smoke-assets
     steps:
       - name: Clone the code
         uses: actions/checkout@v6

examples/README.md

@@ -29,9 +29,11 @@ Each example is designed to be:
 - `isolated-untrusted-builds`: Disposable VM isolation boundary for risky builds
 - `compliance-segmented-workloads`: Sensitive workloads pinned to dedicated nodes
 - `cost-optimized-night-jobs`: Scale-from-zero capacity for periodic spikes
+- `tiny-smoke`: Tiny-footprint classRef boot + two-VM connectivity validation
 
 ## Notes
 
 - These examples intentionally use `ghcr.io/syscode-labs/test:latest` as a neutral placeholder image.
+- `tiny-smoke` uses pinned Docker Hub images so it can run unchanged in public environments.
 - Secrets referenced by runner pool examples must be created separately.
 - GPU passthrough is not supported in `imp`/Firecracker here; examples focus on CPU/memory/storage-isolated workloads.

examples/tiny-smoke/README.md

@@ -0,0 +1,43 @@
+# tiny-smoke
+
+## What This Demonstrates
+
+A constrained-footprint smoke path for validating:
+- classRef-based VM boot
+- VM-to-VM east-west traffic on one `ImpNetwork`
+
+This is intended for tiny nodes and one-off validation, not production sizing.
+
+## Manifests
+
+- `impvmclass.yaml`: tiny compute profile
+- `impnetwork.yaml`: isolated smoke network
+- `vm-server.yaml`: long-running server VM
+- `vm-client.yaml`: long-running client VM
+
+## Prerequisites
+
+- `imp` is installed and healthy.
+- Guest agent is enabled (default).
+- Agent can run Firecracker on at least one node.
+- `kubectl` and `curl` are installed on your workstation.
+
+## Run Smoke Validation
+
+```sh
+bash examples/tiny-smoke/run.sh
+```
+
+What `run.sh` does:
+1. Applies class, network, and two VMs.
+2. Waits for both VMs to reach `Running`.
+3. Finds the `imp-agent` pod on the client VM node.
+4. Port-forwards the agent API.
+5. Executes an HTTP request from client VM to server VM over the ImpNetwork.
+6. Fails unless guest-exec returns exit code `0`.
+
+## Cleanup
+
+```sh
+kubectl delete -f examples/tiny-smoke/
+```

examples/tiny-smoke/impnetwork.yaml

@@ -0,0 +1,8 @@
+apiVersion: imp.dev/v1alpha1
+kind: ImpNetwork
+metadata:
+  name: tiny-smoke-net
+  namespace: default
+spec:
+  subnet: 10.251.0.0/24
+  gateway: 10.251.0.1

examples/tiny-smoke/impvmclass.yaml

@@ -0,0 +1,7 @@
+apiVersion: imp.dev/v1alpha1
+kind: ImpVMClass
+metadata:
+  name: tiny-smoke
+spec:
+  vcpu: 1
+  memoryMiB: 192

examples/tiny-smoke/run.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+EXAMPLE_DIR="${ROOT_DIR}/examples/tiny-smoke"
+NS="${NS:-default}"
+IMP_NS="${IMP_NS:-imp-system}"
+SERVER_VM="${SERVER_VM:-tiny-server}"
+CLIENT_VM="${CLIENT_VM:-tiny-client}"
+LOCAL_AGENT_PORT="${LOCAL_AGENT_PORT:-19091}"
+
+require() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "missing required command: $1" >&2
+    exit 1
+  }
+}
+
+require kubectl
+require curl
+
+echo "[1/6] apply tiny smoke manifests"
+kubectl apply -f "${EXAMPLE_DIR}/impvmclass.yaml"
+kubectl apply -f "${EXAMPLE_DIR}/impnetwork.yaml" -n "${NS}"
+kubectl apply -f "${EXAMPLE_DIR}/vm-server.yaml" -n "${NS}"
+kubectl apply -f "${EXAMPLE_DIR}/vm-client.yaml" -n "${NS}"
+
+echo "[2/6] wait for both VMs to be Running"
+kubectl wait --for=jsonpath='{.status.phase}'=Running "impvm/${SERVER_VM}" -n "${NS}" --timeout=8m
+kubectl wait --for=jsonpath='{.status.phase}'=Running "impvm/${CLIENT_VM}" -n "${NS}" --timeout=8m
+
+SERVER_IP="$(kubectl get impvm "${SERVER_VM}" -n "${NS}" -o jsonpath='{.status.ip}')"
+CLIENT_NODE="$(kubectl get impvm "${CLIENT_VM}" -n "${NS}" -o jsonpath='{.spec.nodeName}')"
+
+if [[ -z "${SERVER_IP}" || -z "${CLIENT_NODE}" ]]; then
+  echo "failed to resolve server IP or client node" >&2
+  exit 1
+fi
+
+echo "[3/6] locate imp-agent pod on client node ${CLIENT_NODE}"
+AGENT_POD="$(
+  kubectl get pods -n "${IMP_NS}" -l app.kubernetes.io/component=agent \
+    -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.nodeName}{"\n"}{end}' \
+  | awk -v node="${CLIENT_NODE}" '$2==node {print $1; exit}'
+)"
+
+if [[ -z "${AGENT_POD}" ]]; then
+  echo "no imp-agent pod found on node ${CLIENT_NODE} in namespace ${IMP_NS}" >&2
+  exit 1
+fi
+
+cleanup() {
+  if [[ -n "${PF_PID:-}" ]]; then
+    kill "${PF_PID}" >/dev/null 2>&1 || true
+  fi
+}
+trap cleanup EXIT
+
+echo "[4/6] port-forward agent API via pod/${AGENT_POD}"
+kubectl -n "${IMP_NS}" port-forward "pod/${AGENT_POD}" "${LOCAL_AGENT_PORT}:9091" >/tmp/imp-tiny-smoke-portforward.log 2>&1 &
+PF_PID=$!
+sleep 2
+
+echo "[5/6] execute connectivity check from ${CLIENT_VM} -> ${SERVER_IP}"
+REQ_BODY="$(
+  cat <<EOF
+{"command":["/bin/sh","-lc","wget -qO- http://${SERVER_IP} | grep -qi nginx"]}
+EOF
+)"
+RESP="$(
+  curl -fsS -X POST \
+    -H "Content-Type: application/json" \
+    --data "${REQ_BODY}" \
+    "http://127.0.0.1:${LOCAL_AGENT_PORT}/v1/exec/${NS}/${CLIENT_VM}"
+)"
+
+echo "${RESP}" | grep -q '"stream":"exit","code":0' || {
+  echo "connectivity check failed; agent exec response:" >&2
+  echo "${RESP}" >&2
+  exit 1
+}
+
+echo "[6/6] smoke PASS: classRef boot + VM-to-VM HTTP connectivity validated"

examples/tiny-smoke/vm-client.yaml

@@ -0,0 +1,12 @@
+apiVersion: imp.dev/v1alpha1
+kind: ImpVM
+metadata:
+  name: tiny-client
+  namespace: default
+spec:
+  classRef:
+    name: tiny-smoke
+  networkRef:
+    name: tiny-smoke-net
+  image: docker.io/library/nginx:1.27.4-alpine
+  lifecycle: persistent

examples/tiny-smoke/vm-server.yaml

@@ -0,0 +1,12 @@
+apiVersion: imp.dev/v1alpha1
+kind: ImpVM
+metadata:
+  name: tiny-server
+  namespace: default
+spec:
+  classRef:
+    name: tiny-smoke
+  networkRef:
+    name: tiny-smoke-net
+  image: docker.io/library/nginx:1.27.4-alpine
+  lifecycle: persistent

hack/verify-tiny-smoke.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+EXAMPLE_DIR="${ROOT_DIR}/examples/tiny-smoke"
+
+required_files=(
+  "${EXAMPLE_DIR}/README.md"
+  "${EXAMPLE_DIR}/impvmclass.yaml"
+  "${EXAMPLE_DIR}/impnetwork.yaml"
+  "${EXAMPLE_DIR}/vm-server.yaml"
+  "${EXAMPLE_DIR}/vm-client.yaml"
+  "${EXAMPLE_DIR}/run.sh"
+)
+
+for f in "${required_files[@]}"; do
+  [[ -f "${f}" ]] || {
+    echo "missing tiny-smoke asset: ${f}" >&2
+    exit 1
+  }
+done
+
+grep -q '^kind: ImpVMClass$' "${EXAMPLE_DIR}/impvmclass.yaml"
+grep -q '^kind: ImpNetwork$' "${EXAMPLE_DIR}/impnetwork.yaml"
+grep -q '^kind: ImpVM$' "${EXAMPLE_DIR}/vm-server.yaml"
+grep -q '^kind: ImpVM$' "${EXAMPLE_DIR}/vm-client.yaml"
+grep -q 'classRef:' "${EXAMPLE_DIR}/vm-server.yaml"
+grep -q 'classRef:' "${EXAMPLE_DIR}/vm-client.yaml"
+grep -q 'networkRef:' "${EXAMPLE_DIR}/vm-server.yaml"
+grep -q 'networkRef:' "${EXAMPLE_DIR}/vm-client.yaml"
+
+# Require pinned image tags (reject :latest) for this tiny smoke path.
+if grep -R --line-number 'image: .*:latest' "${EXAMPLE_DIR}"/*.yaml; then
+  echo "tiny-smoke manifests must not use :latest tags" >&2
+  exit 1
+fi
+
+bash -n "${EXAMPLE_DIR}/run.sh"
+echo "tiny-smoke assets verified"