Data Plane (L3)

This view focuses on node-level execution performed by IMP agents.

Responsibilities

• Prepare and start Firecracker microVM runtime.
• Configure and attach VM networking.
• Report runtime/network outcomes back to operator.
• Expose node-level health and telemetry.

Runtime Path

1. Agent receives desired assignment from control plane.
2. Agent validates node capability and required artifacts.
3. Agent starts VM process and performs runtime checks.
4. Agent returns success/failure details for status updates.

Select VM nodes and runtime paths

The agent chart runs only on selected nodes. Point the required kernel and Firecracker paths at artifacts already present on every selected node; keep the socket directory host-backed so the agent can reattach after a pod restart.

# values.yaml
agent:
  nodeSelector:
    imp/enabled: "true"
  env:
    kernelPath: /var/lib/imp/vmlinux
    fcBinPath: /usr/local/bin/firecracker
  hostPaths:
    socketDir:
      enabled: true
      path: /run/imp

agent.env.kernelPath and agent.env.fcBinPath are required chart values. With socketDir.enabled: true, the chart mounts socketDir.path as a hostPath; set it to a writable node-local directory shared by the agent lifecycle.

Networking Path

• Preferred: Cilium-based integration for policy and observability.
• Fallback: non-Cilium path with equivalent connectivity goals.
• Typical tasks: IP allocation, routing/NAT wiring, DNS setup.

Define an internal network

Use an ImpNetwork to give its VMs a subnet, default gateway, outbound NAT, and guest DNS. This example relies on the built-in IPAM default and leaves the NAT egress interface unset for node-side default-route detection.

apiVersion: imp.dev/v1alpha1
kind: ImpNetwork
metadata:
  name: app-network
  namespace: default
spec:
  subnet: 10.44.0.0/24
  gateway: 10.44.0.1
  nat:
    enabled: true
  dns:
    - 1.1.1.1
    - 8.8.8.8

Failure Handling

• Runtime start errors are reported with precise reason/category.
• Networking setup errors trigger retry-safe failure paths.
• Heartbeat or communication gaps are surfaced as availability issues.

Make readiness visible

Set a readiness probe on an ImpVMClass when the guest agent can answer the HTTP endpoint. The agent polls it through VSOCK and updates the VM Ready condition after the configured number of consecutive failures.

apiVersion: imp.dev/v1alpha1
kind: ImpVMClass
metadata:
  name: web-small
spec:
  vcpu: 1
  memoryMiB: 512
  diskGiB: 4
  probes:
    readinessProbe:
      http:
        path: /readyz
        port: 8080
      periodSeconds: 10
      failureThreshold: 3

Restart persistent workloads deliberately

Restart policy applies to persistent VMs. The following policy reschedules a failed VM, retries with exponential backoff, and resets the retry budget after a cool-down period instead of requiring manual intervention.

# Add to an ImpVM spec, or set on an ImpVMClass for inheriting VMs.
spec:
  lifecycle: persistent
  restartPolicy:
    mode: reschedule
    backoff:
      maxRetries: 5
      initialDelay: 10s
      maxDelay: 5m
    onExhaustion: cool-down
    coolDownPeriod: 1h

What to Monitor

• VM boot latency and start failure rate.
• Network allocation/setup failure rate.
• Agent heartbeat freshness and node-level execution backlog.

Chart-managed Prometheus discovery

The chart renders a ServiceMonitor for the operator and PodMonitor resources for the agent and runtime by default. These resources require Prometheus Operator CRDs. On clusters without those CRDs, disable both monitors explicitly:

# values.yaml
metrics:
  serviceMonitor:
    enabled: false
  podMonitor:
    enabled: false

For Prometheus Operator users, keep the monitors enabled and optionally configure the scrape interval. These values only configure discovery; use metrics exposed by the v0.10.1 components, such as imp_vm_scheduling_latency_seconds, imp_vm_boot_latency_seconds, imp_vm_guest_memory_used_bytes, imp_vm_guest_disk_used_bytes, and imp_runtime_ready.

# values.yaml — Prometheus Operator CRDs installed
metrics:
  serviceMonitor:
    enabled: true
    interval: 30s
  podMonitor:
    enabled: true
    interval: 30s

v0.10.1 ScaleToZero (experimental)

desiredState: ScaleToZero is an opt-in mode, enabled only when the agent is started with IMP_SCALE_TO_ZERO=true. While a VM is running, the agent asks imp-runtime for cumulative TAP link statistics through the node-local Unix socket and its Runtime.LinkStats RPC. The agent does not inspect the runtime's TAP namespace directly; the runtime owns that host-local operation.

# values.yaml — opt in the Imp agent.
agent:
  extraEnv:
    - name: IMP_SCALE_TO_ZERO
      value: "true"
---
# Add to the spec of an existing ImpVM.
spec:
  desiredState: ScaleToZero

Apply the Helm values and set desiredState: ScaleToZero on each intended ImpVM; optional idleTimeout defaults to 5m and, when set, must be at least 10s.

When the configured idle window elapses without TAP byte-counter movement, the agent snapshots the VM, stops its runtime, and retains the VTEP mapping so the overlay can deliver a possible wake frame. A per-node packet-capture hook maps an inbound IPv4 destination to a suspended VM and queues reconciliation. The agent then restores the snapshot, brings the VM back to Running, and re-establishes its network state. The implementation and ownership split are described in the v0.10.1 agent source and runtime RPC source.

This feature remains experimental. The admission warning and source comments state that wake-on-traffic has not been hardware-validated. TAP byte-idle can also suspend a VM with an idle-but-open connection, so connection behavior must be validated for the workload; the wake hook is not evidence of a production-grade hardware datapath.