~/DOCS/

How It Works

How It Works

On this page:

──

Components

──

Pod Startup

──

Scale-Down

──

Scale-Up

──

Migration

Components

Architect deploys four components into your cluster:

  • Admission controller: configures managed containers on pod creation
  • Control plane: coordinates checkpoint transfers during migrations
  • Daemon: per-node agent that orchestrates hibernation and wake
  • Shim: performs checkpoint/restore via CRIU (runc-architect) or gVisor (runsc-architect)
graph TB
    subgraph "Each Node"
        Pod[Your Pods]
        D[Architect Daemon]
    end

    subgraph "Cluster"
        API[Kubernetes API]
        AC[Admission Controller]
        CP[Control Plane]
    end

    Pod <--> D
    D --> API
    D --> CP
    API --> AC

View the above diagram in mermaid.live

Pod Startup

When a pod starts, Architect checks for an available checkpoint:

graph TD
    A[Pod starts] --> R{Runtime class?}
    R -->|runc-architect| B{Checkpoint<br/>available?}
    B -->|Yes| C[Restore from checkpoint]
    B -->|No| D[Start fresh]
    C -->|Fails| D
    R -->|runsc-architect| E{PersistentCheckpoint<br/>configured?}
    E -->|Yes| F[Restore from PersistentCheckpoint]
    E -->|No| G[Start fresh]
    F -->|Fails| G

View the above diagram in mermaid.live

With runc-architect, pods automatically find checkpoints from other pods with the same template hash. This is how migration works. With runsc-architect, start-from-persistent-checkpoint is the only restore path.

Scale-Down

When a container has been idle for the configured duration:

sequenceDiagram
    participant Pod as Your Pod
    participant A as Architect

    Note over Pod: Idle threshold reached
    A->>Pod: Checkpoint and stop container
    A->>A: Buffer incoming packets
    A->>A: Reduce pod resources to zero
    Note over Pod: Status: SCALED_DOWN

View the above diagram in mermaid.live

Scale-Up

When a wake trigger arrives (kubectl exec or network packet):

sequenceDiagram
    participant U as User / Traffic
    participant A as Architect
    participant Pod as Your Pod

    U->>A: Request arrives
    A->>Pod: Restore from checkpoint
    A->>A: Release buffered packets
    A->>A: Restore original resources
    Note over Pod: Status: RUNNING
    A->>U: Ready

View the above diagram in mermaid.live

Migration

When a pod is deleted (e.g., node drain), Architect transfers state to the replacement pod:

sequenceDiagram
    participant N1 as Node 1
    participant API as Kubernetes API
    participant N2 as Node 2

    Note over N1: Pod deleted
    N1->>API: Store checkpoint
    Note over N2: Replacement pod scheduled
    N2->>API: Find checkpoint
    API->>N2: Transfer checkpoint
    N2->>N2: Restore container

View the above diagram in mermaid.live

Typically completes faster than a cold start.