Skip to content

Core Concepts & Glossary

Shared terminology for the Dory platform. Both operators and developers should be familiar with these terms; they are used throughout the System Architecture, Processor SDK getting started, and Orchestrator architecture sections.

Processors and configuration

Term Definition
Processor A long-running, stateful workload built with the Dory SDK. It maintains in-memory state across iterations, runs an async run() loop, and publishes output. Realized as exactly one Kubernetes pod.
Processor template A reusable definition of a processor type, stored in the processor_templates table. References the container image and default runtime configuration.
Processor template version A specific, immutable version of a template, stored in processor_template_versions. Carries the runtime_config_template used to render a pod's env vars and runtime settings.
Processor config (DB row) A row in the processors table — the desired-state record for one processor. Joined to processor_templates and processor_template_versions to produce a pod spec. The Orchestrator reconciles this row into a running pod keyed by the processor-id label.
SDK version header X-Dory-SDK-Version, sent by the pod on its /health response. The Orchestrator uses it to detect that a pod is running the Dory SDK.

Control plane

Term Definition
Orchestrator The Go control plane (v0.1.0). Reads desired processors from PostgreSQL and reconciles Kubernetes pods. Serves a single HTTP server on :8080.
Reconciler The component that compares desired state (DB rows) against actual state (pods) and drives them together. Because pods are immutable, a config change is applied as delete + recreate. Runs on every config-watcher poll (default 30s), even with no DB change.
Scheduler The placement component. Bin-packs with first-fit on the most-utilized healthy node (10% resource buffer). When nothing fits, emits a provision_node decision that creates a Pending pod for Karpenter to satisfy.
Karpenter The Kubernetes node autoscaler that provisions app nodes on demand. App nodes use NodePool dory-app-pool (label workload-type=application, no taint) and EC2NodeClass dory-app-nodeclass.
Sentinel ConfigMap dory-controller-ref, attached to processor pods as an owner reference so that bare pods are eligible for kubectl drain without --force.

Nodes and placement

Term Definition
Managed (cloud) node A standard application node in the cluster. Managed pods get nodeSelector{workload-type: application}.
Edge node A node at the edge, registered via POST /api/v1/edge/nodes. Edge pods get toleration edge-node=true:NoSchedule and nodeSelector{node-type: edge}.
Workload location Where a processor is currently running. The workload-location label records this; after an edge→cloud migration a pod carries workload-location=edge along with migrated-from-edge=true and original-edge-node=<node>.

Note

All processor pods, regardless of location, get node affinity node-role NotIn [system], ServiceAccount dory-processor, and ImagePullSecret ecr-registry-secret.

State and migration

Term Definition
State / stateful var A processor's persisted data. In the SDK, a variable declared with stateful(...) is automatically saved on shutdown/prestop and restored on restart.
State backend Where the SDK persists state: ConfigMap, S3, PVC, or Local. The active edge restore path is provided via env DORY_STATE_RESTORE_PATH.
State transfer / migration Moving a processor's state from an old pod to a new one. The Orchestrator captures with GET /state and restores with POST /state (both on pod port 8080), authenticated with Authorization: Bearer <DORY_STATE_TOKEN>. Limits: 30s HTTP timeout, 10 MB max (SDK targets ≤25s and ≤8 MB). Retries use exponential backoff (1s base ×2, cap 30s).
Drain Removing pods from a node being cordoned. With --enable-monitor, the Orchestrator captures state, creates an <app>-drain-<ts> replacement, restores state, then allows kubectl drain to evict the old pod.
Consolidation Reclaiming under-utilized nodes by repacking processors. The reconcile loop fires every interval (even with no DB change) so the scheduler can act on consolidation opportunities.

Edge resilience

Term Definition
Heartbeat A periodic POST /api/v1/edge/heartbeat from an edge pod. The response directive is continue or shutdown.
Failover Recreating an edge app as a managed (cloud) pod when its edge node fails — triggered by K8s NotReady > 30s grace OR DB heartbeat stale > 60s. The cloud pod restores state from the SDK's ConfigMap-backed store.
Failback Recreating the edge pod once the edge node returns.
Fencing / epoch Split-brain prevention. Each processor has a monotonically increasing epoch. A new instance increments the epoch, making the previous instance's token stale so it must stop writing.
Primary / Standby role Instance roles under fencing. PRIMARY actively processes; STANDBY does not. Only one instance holds the current (highest) epoch and acts as PRIMARY.

Warning

Fencing prevents two instances of the same processor from writing concurrently during an edge↔cloud transition. An instance whose epoch token has been superseded must stop processing immediately.

Output

Term Definition
Message envelope The versioned JSON wrapper a processor publishes: { schema_version: "0.1", message_id: <uuid4>, timestamp: <ISO8601 UTC>, payload: {...} }. Subscribers match on its major version.
Routing key The RabbitMQ topic routing key <processor_id>.<event_type>.<geohash-segments>, used to publish to the topic exchange dory.output.