Kontinue Architecture

Kontinue is a Kubernetes-native durable execution platform. Workflows are written in Go and execute as Kubernetes custom resources, with all state stored in etcd.

Core Concepts

Durable Execution Model

Kontinue stores execution state in Kubernetes resources (primarily Execution and Suspension resources). This state serves as checkpoints of progress in the execution of a workflow, allowing it to be resumed if anything fails.

When a workflow runs, each step’s results are saved to the Execution resource in Kubernetes. If a worker crashes mid-execution, another worker can pick up the Execution and resume from the last checkpoint without re-executing completed steps.

Kubernetes Custom Resources

Kontinue extends the Kubernetes API with custom resource types like Execution, Suspension, ScheduledExecution, and Function. These are extensions to the Kubernetes API which allow storing and watching state in a schematized way.

Custom resources can be:

  • Queried using the Kubernetes API and tools like kubectl
  • Stored in Kubernetes’ backing database (etcd)
  • Watched for changes using the standard Kubernetes watch API
  • Protected with Kubernetes RBAC and namespace isolation

Example Execution resource:

apiVersion: kontinue.cloud/v1alpha1
kind: Execution
metadata:
  name: process-order-abc123
spec:
  function: processOrder
  arguments: {"orderId": "12345"}
status:
  phase: Executing
  state: {"fetchedOrder": {...}, "paymentProcessed": true}
  result: null

Kontinue SDK

Workflows are written in Go using the Kontinue SDK (pkg/kontinue). The SDK provides functions like:

  • kontinue.Execute(ktx, function, args, opts) - Start a child workflow execution
  • kontinue.Sleep(duration) - Pause execution for a duration
  • kontinue.Store(fn) - Save the result of a function call as a checkpoint
  • kontinue.Poll(condition) - Wait for an external condition

The SDK handles interaction with the Kubernetes API to ensure durability of individual steps and provides ergonomic workflow authoring. When you call these functions, the SDK creates/updates Kubernetes resources and manages the execution lifecycle.

Kontinue Worker

All workflows are run via a Kontinue worker process. Workers can run anywhere with access to Kubernetes, but are typically deployed as a regular Deployment in the same Kubernetes cluster.

The worker:

  • Watches the Kubernetes API for new Executions
  • Picks up Pending Executions and runs the registered workflow functions
  • Uses the Kontinue SDK internally to manage Execution state
  • Updates Execution resources as workflows progress

Execution Model

Here’s how a workflow executes from start to finish:

architecture

Step-by-Step Flow

  1. Execution Created: An Execution resource is created to start a workflow of a particular Function. This can be done via:
    • CLI: kontinue execute processOrder '{"orderId": "12345"}'
    • UI: Web interface for triggering workflows
    • YAML: kubectl apply -f execution.yaml
    • Go client library: client.CreateExecution(...)
  2. Worker Picks Up Execution: The Kontinue worker watches the Kubernetes API and picks up the Pending Execution, marking it as Executing.
  3. Dispatch Workflow Code: The Kontinue worker dispatches the Execution and starts running the associated Go code (the registered workflow function).
  4. SDK Interactions: The Go code calls into the Kontinue SDK to:
    • Run sub-Executions via kontinue.Execute(ktx, function, args, opts)
    • Suspend execution via kontinue.Sleep() or kontinue.Poll()
    • Store intermediate state via kontinue.Store() Each SDK call updates Kubernetes resources, creating checkpoints.
  5. Completion: The Go code terminates (returns), and the Kontinue worker updates the Execution status in the Kubernetes API to Completed with the final result.