Imp Kubernetes E2E Sequence (Technical)

Primary diagram (Excalidraw export):

Mermaid fallback/source-friendly variant:

sequenceDiagram
    autonumber
    actor U as User/kubectl
    participant APIServer as Kubernetes API Server
    participant Etcd as etcd
    participant Op as Imp Operator
    participant Agent as Imp Agent
    participant FC as Firecracker Runtime
    participant Net as ImpNetwork/IPAM
    participant Ev as events.k8s.io
    participant Prom as Prometheus

    U->>APIServer: POST /apis/imp.dev/v1alpha1/namespaces/{ns}/impvms
    U->>APIServer: POST /apis/imp.dev/v1alpha1/namespaces/{ns}/impnetworks
    APIServer->>Etcd: Persist CR specs + defaults
    APIServer-->>U: 201 Created

    Op->>APIServer: LIST/WATCH impvms, impnetworks, pools
    APIServer-->>Op: ADDED/MODIFIED events

    Op->>APIServer: GET ImpVM + dependencies (Class/Template/Network/ClusterImp*)
    APIServer-->>Op: Current resource state

    Op->>APIServer: PATCH ImpVM status.conditions=Reconciling
    APIServer->>Etcd: Persist status update

    Op->>Agent: Desired assignment (node/runtime/network intent)
    Agent->>FC: Create VM (kernel/rootfs/boot)
    FC-->>Agent: VM runtime state

    Agent->>Net: Allocate + wire network (Cilium IPAM or internal)
    Net-->>Agent: IP/route/NAT/DNS result

    Agent->>Op: Runtime + networking result

    Op->>APIServer: PATCH ImpVM status.conditions=Ready|Failed
    Op->>Ev: Create/patch Kubernetes Events
    Op->>Prom: Emit metrics (state, latency, health)

    APIServer->>Etcd: Persist final status

Notes

• API verbs shown are representative for the dominant happy-path writes/reads.
• Actual reconciles may include retries, conflict retries, and additional PATCH calls.
• Migration/snapshot/runner-pool flows are extensions on top of this base sequence.
• See also: failure-path sequence in docs/architecture/k8s-e2e-failure-sequence.md.