Lev Zemlyanov
08/22/2025, 9:42 PMMarvin
08/22/2025, 9:42 PMMarvin
08/22/2025, 9:48 PMget_scheduled_flow_runs
)
- DB/model logic used by the route: prefect/server/models/workers.py (function get_scheduled_flow_runs
)
- Work queue selection helper: prefect/server/models/work_queues.py (function get_runs_in_work_queue
)
2) Claim by setting state
- After a worker decides to run a flow, it “claims” it by proposing a state transition via the flow run state endpoint. The Prefect server arbitrates this atomically so only one worker succeeds.
- API route: Set flow run state (API docs)
- Server route implementation: prefect/server/api/flow_runs.py (function set_flow_run_state
)
- Orchestration rule that prevents double-transitions: prefect/server/orchestration/core_policy.py (class PreventDuplicateTransitions
)
3) Result
- The first worker whose state proposal is accepted proceeds to create the Kubernetes Job. Any other worker that fetched the same run will have its state proposal rejected/aborted and will not submit a duplicate Job.
Additional references
- Concept docs: Workers and Work pools
- Worker heartbeat/liveness route (workers register/heartbeat with the server): prefect/server/api/workers.py (worker_heartbeat
)
- Response types showing accept/reject semantics for state proposals: prefect/server/schemas/responses.py (e.g., SetStateStatus
, OrchestrationResult
)
Notes
- This claiming/dedup mechanism is infrastructure-agnostic — it’s the same whether the worker is Process, Docker, Kubernetes, etc. Kubernetes workers simply use this server-side arbitration before creating Jobs in your cluster.
- Running multiple Kubernetes workers in the same pool is safe and recommended for horizontal scaling. There’s no shared lock in the cluster; concurrency control and deduplication are enforced by Prefect’s orchestration API.