Deployments and Work Pools

## The problem a deployment solves In Prefect you write ordinary Python and decorate it: ```python from prefect import flow, task @task def extract(day: str) -> list[dict]: ... @flow def etl_flow(day: str = "today"): return extract(day) if __name__ == "__main__": etl_flow("2026-08-20") ``` Running `python flows/etl.py` executes the flow immediately in that process. Prefect still observes it — a flow run appears in the UI with states, task runs and logs — but the *trigger* was you, and the *infrastructure* was whatever machine you were sitting at. Nothing here is scheduled, nothing is reproducible on a server, and there is no way for a teammate or an event to start it. A **deployment** closes that gap. It is a record stored by the Prefect API that says: this flow, found at this entrypoint, fetched from this location, with these default parameters, on these schedules, should run in this work pool with these infrastructure settings. ## What a deployment actually stores - **Entrypoint** — `path/to/file.py:flow_function_name`. Prefect imports the module and calls that flow object. - **Code source** — how the executing process obtains the code: pull steps in `prefect.yaml` (for example `prefect.deployments.steps.git_clone`), a `flow.from_source(...)` reference to a git URL or storage bucket, or code baked into a Docker image. - **Parameters** — defaults for the flow's arguments, overridable per run. Prefect validates them against the function's type annotations (pydantic under the hood), so a bad parameter fails fast at run creation. - **Schedules** — a list; each may be `cron`, `interval` (seconds, with an optional anchor date), or `rrule`, each with a timezone and an active flag. - **Work pool (and optional work queue)** — the queue of pending runs a worker polls. - **Job variables** — per-deployment overrides of the work pool's infrastructure defaults (image, env vars, CPU/memory, namespace). - **Metadata** — name, version, description, tags, concurrency-related settings. A deployment is identified as `flow-name/deployment-name`, which is what you pass to `prefect deployment run`. ## How you create one The file-driven route is `prefect.yaml` at the project root plus `prefect deploy`: ```yaml deployments: - name: nightly entrypoint: flows/etl.py:etl_flow parameters: day: "yesterday" schedules: - cron: "0 4 * * *" timezone: "UTC" work_pool: name: k8s-prod ``` The Python route is equivalent and often nicer in CI: ```python flow.from_source( source="https://github.com/acme/pipelines.git", entrypoint="flows/etl.py:etl_flow", ).deploy(name="nightly", work_pool_name="k8s-prod") ``` There is also `flow.serve(name="nightly", cron="0 4 * * *")`, which creates a deployment *and* runs a long-lived process that executes its runs as subprocesses. It is the fastest way to get something scheduled, but that process is your only execution capacity — no work pool, no remote infrastructure, no horizontal scaling. Teams graduate from `serve` to a work pool when they need runs on containers or Kubernetes. ## The mental model to say out loud Deploying does **not** upload your flow code to Prefect and does not "run" anything. It registers a pointer plus a configuration. Execution stays in your infrastructure: the API creates a flow run in `Scheduled` state, a worker polling the deployment's work pool claims it, materializes the configured infrastructure, fetches the code, and runs the flow there. If no worker is polling that pool, the run simply sits and eventually shows as `Late` — a deployment by itself is not execution capacity. This is also the piece with no direct Airflow equivalent. In Airflow, a DAG file placed in the DAGs folder is simultaneously the definition, the schedule and the thing the scheduler executes. In Prefect the flow is plain Python that runs anywhere, and the deployment is a separate, explicitly created object that adds remote triggering, scheduling and infrastructure to it. ## Version note This describes Prefect 3.x, where `prefect deploy` / `flow.deploy()` and workers with work pools are the model. Prefect 2 originally used `prefect deployment build`, agents, and infrastructure/storage blocks attached to the deployment; agents were removed in 3.x in favour of workers.